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 List
6711 \labelwidthstring 00.00.0000
6712
6713
6714 \series bold
6715 -
6716 \begin_inset ERT
6717 status Collapsed
6718
6719 \layout Standard
6720
6721 \backslash
6722 /
6723 \end_inset
6724
6725 -opt-code-speed
6726 \begin_inset LatexCommand \index{-\/-opt-code-speed}
6727
6728 \end_inset
6729
6730
6731 \series default
6732  The compiler will optimize code generation towards fast code, possibly
6733  at the expense of code size.
6734 \layout List
6735 \labelwidthstring 00.00.0000
6736
6737
6738 \series bold
6739 -
6740 \begin_inset ERT
6741 status Collapsed
6742
6743 \layout Standard
6744
6745 \backslash
6746 /
6747 \end_inset
6748
6749 -opt-code-size
6750 \begin_inset LatexCommand \index{-\/-opt-code-size}
6751
6752 \end_inset
6753
6754
6755 \series default
6756  The compiler will optimize code generation towards compact code, possibly
6757  at the expense of code speed.
6758 \layout Subsection
6759
6760 Other Options
6761 \begin_inset LatexCommand \index{Options other}
6762
6763 \end_inset
6764
6765
6766 \layout List
6767 \labelwidthstring 00.00.0000
6768
6769
6770 \series bold
6771 -c\SpecialChar ~
6772 -
6773 \begin_inset ERT
6774 status Collapsed
6775
6776 \layout Standard
6777
6778 \backslash
6779 /
6780 \end_inset
6781
6782 -compile-only
6783 \begin_inset LatexCommand \index{-\/-compile-only}
6784
6785 \end_inset
6786
6787
6788 \begin_inset LatexCommand \index{-c -\/-compile-only}
6789
6790 \end_inset
6791
6792
6793 \series default
6794  will compile and assemble the source, but will not call the linkage editor.
6795 \layout List
6796 \labelwidthstring 00.00.0000
6797
6798
6799 \series bold
6800 -
6801 \series default
6802
6803 \begin_inset ERT
6804 status Collapsed
6805
6806 \layout Standard
6807
6808 \backslash
6809 /
6810 \end_inset
6811
6812
6813 \series bold
6814 -c1mode
6815 \begin_inset LatexCommand \index{-\/-c1mode}
6816
6817 \end_inset
6818
6819
6820 \series default
6821  reads the preprocessed source from standard input and compiles it.
6822  The file name for the assembler output must be specified using the -o option.
6823 \layout List
6824 \labelwidthstring 00.00.0000
6825
6826
6827 \series bold
6828 -E
6829 \begin_inset LatexCommand \index{-E}
6830
6831 \end_inset
6832
6833
6834 \series default
6835  Run only the C preprocessor.
6836  Preprocess all the C source files specified and output the results to standard
6837  output.
6838 \layout List
6839 \labelwidthstring 00.00.0000
6840
6841
6842 \series bold
6843 -o\SpecialChar ~
6844 <path/file>
6845 \begin_inset LatexCommand \index{-o <path/file>}
6846
6847 \end_inset
6848
6849
6850 \series default
6851 The output path resp.
6852  file where everything will be placed.
6853  If the parameter is a path, it must have a trailing slash (or backslash
6854  for the Windows binaries) to be recognized as a path.
6855
6856 \layout List
6857 \labelwidthstring 00.00.0000
6858
6859
6860 \series bold
6861 -
6862 \begin_inset ERT
6863 status Collapsed
6864
6865 \layout Standard
6866
6867 \backslash
6868 /
6869 \end_inset
6870
6871 -stack-auto
6872 \begin_inset LatexCommand \index{-\/-stack-auto}
6873
6874 \end_inset
6875
6876
6877 \series default
6878 \size large
6879 \emph on
6880
6881 \size default
6882 \emph default
6883 All functions in the source file will be compiled as
6884 \emph on
6885 reentrant
6886 \emph default
6887
6888 \begin_inset LatexCommand \index{reentrant}
6889
6890 \end_inset
6891
6892 , i.e.
6893  the parameters and local variables will be allocated on the stack
6894 \begin_inset LatexCommand \index{stack}
6895
6896 \end_inset
6897
6898 .
6899  See section
6900 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
6901
6902 \end_inset
6903
6904  Parameters and Local Variables for more details.
6905  If this option is used all source files in the project should be compiled
6906  with this option.
6907
6908 \layout List
6909 \labelwidthstring 00.00.0000
6910
6911
6912 \series bold
6913 -
6914 \begin_inset ERT
6915 status Collapsed
6916
6917 \layout Standard
6918
6919 \backslash
6920 /
6921 \end_inset
6922
6923 -callee-saves
6924 \begin_inset LatexCommand \index{-\/-callee-saves}
6925
6926 \end_inset
6927
6928  function1[,function2][,function3]....
6929
6930 \series default
6931  The compiler by default uses a caller saves convention for register saving
6932  across function calls, however this can cause unnecessary register pushing
6933  & popping when calling small functions from larger functions.
6934  This option can be used to switch the register saving convention for the
6935  function names specified.
6936  The compiler will not save registers when calling these functions, no extra
6937  code will be generated at the entry & exit (function prologue
6938 \series bold
6939
6940 \begin_inset LatexCommand \index{function prologue}
6941
6942 \end_inset
6943
6944
6945 \series default
6946  & epilogue
6947 \series bold
6948
6949 \begin_inset LatexCommand \index{function epilogue}
6950
6951 \end_inset
6952
6953
6954 \series default
6955 ) for these functions to save & restore the registers used by these functions,
6956  this can SUBSTANTIALLY reduce code & improve run time performance of the
6957  generated code.
6958  In the future the compiler (with inter procedural analysis) will be able
6959  to determine the appropriate scheme to use for each function call.
6960  DO NOT use this option for built-in functions such as _mulint..., if this
6961  option is used for a library function the appropriate library function
6962  needs to be recompiled with the same option.
6963  If the project consists of multiple source files then all the source file
6964  should be compiled with the same -
6965 \begin_inset ERT
6966 status Collapsed
6967
6968 \layout Standard
6969
6970 \backslash
6971 /
6972 \end_inset
6973
6974 -callee-saves option string.
6975  Also see #pragma\SpecialChar ~
6976 callee_saves
6977 \begin_inset LatexCommand \index{\#pragma callee\_saves}
6978
6979 \end_inset
6980
6981 .
6982 \layout List
6983 \labelwidthstring 00.00.0000
6984
6985
6986 \series bold
6987 -
6988 \begin_inset ERT
6989 status Collapsed
6990
6991 \layout Standard
6992
6993 \backslash
6994 /
6995 \end_inset
6996
6997 -debug
6998 \begin_inset LatexCommand \index{-\/-debug}
6999
7000 \end_inset
7001
7002
7003 \bar under
7004
7005 \series default
7006 \bar default
7007 When this option is used the compiler will generate debug information.
7008  The debug information collected in a file with .cdb extension can be used
7009  with the SDCDB.
7010  For more information see documentation for SDCDB.
7011  Another file with no extension contains debug information in AOMF or AOMF51
7012 \begin_inset LatexCommand \index{AOMF, AOMF51}
7013
7014 \end_inset
7015
7016  format which is commonly used by third party tools.
7017 \layout List
7018 \labelwidthstring 00.00.0000
7019
7020
7021 \series bold
7022 -S
7023 \begin_inset LatexCommand \index{-S}
7024
7025 \end_inset
7026
7027
7028 \size large
7029 \bar under
7030
7031 \series default
7032 \size default
7033 \bar default
7034 Stop after the stage of compilation proper; do not assemble.
7035  The output is an assembler code file for the input file specified.
7036 \layout List
7037 \labelwidthstring 00.00.0000
7038
7039
7040 \series bold
7041 -
7042 \begin_inset ERT
7043 status Collapsed
7044
7045 \layout Standard
7046
7047 \backslash
7048 /
7049 \end_inset
7050
7051 -int-long-reent
7052 \begin_inset LatexCommand \index{-\/-int-long-reent}
7053
7054 \end_inset
7055
7056
7057 \series default
7058  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7059  Note by default these libraries are compiled as non-reentrant.
7060  See section Installation for more details.
7061 \layout List
7062 \labelwidthstring 00.00.0000
7063
7064
7065 \series bold
7066 -
7067 \begin_inset ERT
7068 status Collapsed
7069
7070 \layout Standard
7071
7072 \backslash
7073 /
7074 \end_inset
7075
7076 -cyclomatic
7077 \begin_inset LatexCommand \index{-\/-cyclomatic}
7078
7079 \end_inset
7080
7081
7082 \bar under
7083
7084 \series default
7085 \bar default
7086 This option will cause the compiler to generate an information message for
7087  each function in the source file.
7088  The message contains some
7089 \emph on
7090 important
7091 \emph default
7092  information about the function.
7093  The number of edges and nodes the compiler detected in the control flow
7094  graph of the function, and most importantly the
7095 \emph on
7096 cyclomatic complexity
7097 \begin_inset LatexCommand \index{Cyclomatic complexity}
7098
7099 \end_inset
7100
7101
7102 \emph default
7103  see section on Cyclomatic Complexity for more details.
7104 \layout List
7105 \labelwidthstring 00.00.0000
7106
7107
7108 \series bold
7109 -
7110 \begin_inset ERT
7111 status Collapsed
7112
7113 \layout Standard
7114
7115 \backslash
7116 /
7117 \end_inset
7118
7119 -float-reent
7120 \begin_inset LatexCommand \index{-\/-float-reent}
7121
7122 \end_inset
7123
7124
7125 \series default
7126  Floating point library is compiled as reentrant
7127 \begin_inset LatexCommand \index{reentrant}
7128
7129 \end_inset
7130
7131 .
7132  See section Installation for more details.
7133 \layout List
7134 \labelwidthstring 00.00.0000
7135
7136
7137 \series bold
7138 -
7139 \begin_inset ERT
7140 status Collapsed
7141
7142 \layout Standard
7143
7144 \backslash
7145 /
7146 \end_inset
7147
7148 -main-return
7149 \begin_inset LatexCommand \index{-\/-main-return}
7150
7151 \end_inset
7152
7153
7154 \series default
7155  This option can be used if the code generated is called by a monitor program
7156  or if the main routine includes an endless loop.
7157  This option might result in slightly smaller code and save two bytes of
7158  stack space.
7159  The return from the 'main'
7160 \begin_inset LatexCommand \index{main return}
7161
7162 \end_inset
7163
7164  function will return to the function calling main.
7165  The default setting is to lock up i.e.
7166  generate a '
7167 \family typewriter
7168 sjmp .
7169 \family default
7170 '.
7171 \layout List
7172 \labelwidthstring 00.00.0000
7173
7174
7175 \series bold
7176 -
7177 \begin_inset ERT
7178 status Collapsed
7179
7180 \layout Standard
7181
7182 \backslash
7183 /
7184 \end_inset
7185
7186 -nostdincl
7187 \begin_inset LatexCommand \index{-\/-nostdincl}
7188
7189 \end_inset
7190
7191
7192 \series default
7193  This will prevent the compiler from passing on the default include path
7194  to the preprocessor.
7195 \layout List
7196 \labelwidthstring 00.00.0000
7197
7198
7199 \series bold
7200 -
7201 \begin_inset ERT
7202 status Collapsed
7203
7204 \layout Standard
7205
7206 \backslash
7207 /
7208 \end_inset
7209
7210 -nostdlib
7211 \begin_inset LatexCommand \index{-\/-nostdlib}
7212
7213 \end_inset
7214
7215
7216 \series default
7217  This will prevent the compiler from passing on the default library
7218 \begin_inset LatexCommand \index{Libraries}
7219
7220 \end_inset
7221
7222  path to the linker.
7223 \layout List
7224 \labelwidthstring 00.00.0000
7225
7226
7227 \series bold
7228 -
7229 \begin_inset ERT
7230 status Collapsed
7231
7232 \layout Standard
7233
7234 \backslash
7235 /
7236 \end_inset
7237
7238 -verbose
7239 \begin_inset LatexCommand \index{-\/-verbose}
7240
7241 \end_inset
7242
7243
7244 \series default
7245  Shows the various actions the compiler is performing.
7246 \layout List
7247 \labelwidthstring 00.00.0000
7248
7249
7250 \series bold
7251 -V
7252 \begin_inset LatexCommand \index{-V}
7253
7254 \end_inset
7255
7256
7257 \series default
7258  Shows the actual commands the compiler is executing.
7259 \layout List
7260 \labelwidthstring 00.00.0000
7261
7262
7263 \series bold
7264 -
7265 \begin_inset ERT
7266 status Collapsed
7267
7268 \layout Standard
7269
7270 \backslash
7271 /
7272 \end_inset
7273
7274 -no-c-code-in-asm
7275 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7276
7277 \end_inset
7278
7279
7280 \series default
7281  Hides your ugly and inefficient c-code from the asm file, so you can always
7282  blame the compiler :)
7283 \layout List
7284 \labelwidthstring 00.00.0000
7285
7286
7287 \series bold
7288 -
7289 \begin_inset ERT
7290 status Collapsed
7291
7292 \layout Standard
7293
7294 \backslash
7295 /
7296 \end_inset
7297
7298 -no-peep-comments
7299 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7300
7301 \end_inset
7302
7303
7304 \series default
7305  Will not include peep-hole comments in the generated files.
7306 \layout List
7307 \labelwidthstring 00.00.0000
7308
7309
7310 \series bold
7311 -
7312 \begin_inset ERT
7313 status Collapsed
7314
7315 \layout Standard
7316
7317 \backslash
7318 /
7319 \end_inset
7320
7321 -i-code-in-asm
7322 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7323
7324 \end_inset
7325
7326
7327 \series default
7328  Include i-codes in the asm file.
7329  Sounds like noise but is most helpful for debugging the compiler itself.
7330 \layout List
7331 \labelwidthstring 00.00.0000
7332
7333
7334 \series bold
7335 -
7336 \begin_inset ERT
7337 status Collapsed
7338
7339 \layout Standard
7340
7341 \backslash
7342 /
7343 \end_inset
7344
7345 -less-pedantic
7346 \begin_inset LatexCommand \index{-\/-less-pedantic}
7347
7348 \end_inset
7349
7350
7351 \series default
7352  Disable some of the more pedantic warnings
7353 \begin_inset LatexCommand \index{Warnings}
7354
7355 \end_inset
7356
7357  (jwk burps: please be more specific here, please!).
7358  If you want rather more than less warnings you should consider using a
7359  separate tool dedicated to syntax checking like splint
7360 \begin_inset LatexCommand \url{www.splint.org}
7361
7362 \end_inset
7363
7364 .
7365 \layout List
7366 \labelwidthstring 00.00.0000
7367
7368
7369 \series bold
7370 -
7371 \begin_inset ERT
7372 status Collapsed
7373
7374 \layout Standard
7375
7376 \backslash
7377 /
7378 \end_inset
7379
7380 -print-search-dirs
7381 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7382
7383 \end_inset
7384
7385
7386 \series default
7387  Display the directories in the compiler's search path
7388 \layout List
7389 \labelwidthstring 00.00.0000
7390
7391
7392 \series bold
7393 -
7394 \begin_inset ERT
7395 status Collapsed
7396
7397 \layout Standard
7398
7399 \backslash
7400 /
7401 \end_inset
7402
7403 -vc
7404 \begin_inset LatexCommand \index{-\/-vc}
7405
7406 \end_inset
7407
7408
7409 \series default
7410  Display errors and warnings using MSVC style, so you can use SDCC with
7411  visual studio.
7412 \layout List
7413 \labelwidthstring 00.00.0000
7414
7415
7416 \series bold
7417 -
7418 \begin_inset ERT
7419 status Collapsed
7420
7421 \layout Standard
7422
7423 \backslash
7424 /
7425 \end_inset
7426
7427 -use-stdout
7428 \begin_inset LatexCommand \index{-\/-use-stdout}
7429
7430 \end_inset
7431
7432
7433 \series default
7434  Send errors and warnings to stdout instead of stderr.
7435 \layout List
7436 \labelwidthstring 00.00.0000
7437
7438
7439 \series bold
7440 -Wa\SpecialChar ~
7441 asmOption[,asmOption]
7442 \series default
7443
7444 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7445
7446 \end_inset
7447
7448 ...
7449  Pass the asmOption to the assembler
7450 \begin_inset LatexCommand \index{Options assembler}
7451
7452 \end_inset
7453
7454
7455 \begin_inset LatexCommand \index{Assembler options}
7456
7457 \end_inset
7458
7459 .
7460  See file sdcc/as/doc/asxhtm.html for assembler options.
7461 \layout Subsection
7462
7463 Intermediate Dump Options
7464 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7465
7466 \end_inset
7467
7468
7469 \begin_inset LatexCommand \index{Options intermediate dump}
7470
7471 \end_inset
7472
7473
7474 \begin_inset LatexCommand \index{Intermediate dump options}
7475
7476 \end_inset
7477
7478
7479 \layout Standard
7480
7481 The following options are provided for the purpose of retargetting and debugging
7482  the compiler.
7483  These provided a means to dump the intermediate code (iCode
7484 \begin_inset LatexCommand \index{iCode}
7485
7486 \end_inset
7487
7488 ) generated by the compiler in human readable form at various stages of
7489  the compilation process.
7490  More on iCodes see chapter
7491 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7492
7493 \end_inset
7494
7495
7496 \begin_inset Quotes srd
7497 \end_inset
7498
7499 The anatomy of the compiler
7500 \begin_inset Quotes srd
7501 \end_inset
7502
7503 .
7504 \layout List
7505 \labelwidthstring 00.00.0000
7506
7507
7508 \series bold
7509 -
7510 \begin_inset ERT
7511 status Collapsed
7512
7513 \layout Standard
7514
7515 \backslash
7516 /
7517 \end_inset
7518
7519 -dumpraw
7520 \begin_inset LatexCommand \index{-\/-dumpraw}
7521
7522 \end_inset
7523
7524
7525 \series default
7526  This option will cause the compiler to dump the intermediate code into
7527  a file of named
7528 \emph on
7529 <source filename>.dumpraw
7530 \emph default
7531  just after the intermediate code has been generated for a function, i.e.
7532  before any optimizations are done.
7533  The basic blocks
7534 \begin_inset LatexCommand \index{Basic blocks}
7535
7536 \end_inset
7537
7538  at this stage ordered in the depth first number, so they may not be in
7539  sequence of execution.
7540 \layout List
7541 \labelwidthstring 00.00.0000
7542
7543
7544 \series bold
7545 -
7546 \begin_inset ERT
7547 status Collapsed
7548
7549 \layout Standard
7550
7551 \backslash
7552 /
7553 \end_inset
7554
7555 -dumpgcse
7556 \begin_inset LatexCommand \index{-\/-dumpgcse}
7557
7558 \end_inset
7559
7560
7561 \series default
7562  Will create a dump of iCode's, after global subexpression elimination
7563 \begin_inset LatexCommand \index{Global subexpression elimination}
7564
7565 \end_inset
7566
7567 , into a file named
7568 \emph on
7569 <source filename>.dumpgcse.
7570 \layout List
7571 \labelwidthstring 00.00.0000
7572
7573
7574 \series bold
7575 -
7576 \begin_inset ERT
7577 status Collapsed
7578
7579 \layout Standard
7580
7581 \backslash
7582 /
7583 \end_inset
7584
7585 -dumpdeadcode
7586 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
7587
7588 \end_inset
7589
7590
7591 \series default
7592  Will create a dump of iCode's, after deadcode elimination
7593 \begin_inset LatexCommand \index{Dead-code elimination}
7594
7595 \end_inset
7596
7597 , into a file named
7598 \emph on
7599 <source filename>.dumpdeadcode.
7600 \layout List
7601 \labelwidthstring 00.00.0000
7602
7603
7604 \series bold
7605 -
7606 \begin_inset ERT
7607 status Collapsed
7608
7609 \layout Standard
7610
7611 \backslash
7612 /
7613 \end_inset
7614
7615 -dumploop
7616 \begin_inset LatexCommand \index{-\/-dumploop}
7617
7618 \end_inset
7619
7620
7621 \series default
7622 \size large
7623
7624 \size default
7625 Will create a dump of iCode's, after loop optimizations
7626 \begin_inset LatexCommand \index{Loop optimization}
7627
7628 \end_inset
7629
7630 , into a file named
7631 \emph on
7632 <source filename>.dumploop.
7633 \layout List
7634 \labelwidthstring 00.00.0000
7635
7636
7637 \series bold
7638 -
7639 \begin_inset ERT
7640 status Collapsed
7641
7642 \layout Standard
7643
7644 \backslash
7645 /
7646 \end_inset
7647
7648 -dumprange
7649 \begin_inset LatexCommand \index{-\/-dumprange}
7650
7651 \end_inset
7652
7653
7654 \series default
7655 \size large
7656
7657 \size default
7658 Will create a dump of iCode's, after live range analysis
7659 \begin_inset LatexCommand \index{Live range analysis}
7660
7661 \end_inset
7662
7663 , into a file named
7664 \emph on
7665 <source filename>.dumprange.
7666 \layout List
7667 \labelwidthstring 00.00.0000
7668
7669
7670 \series bold
7671 -
7672 \begin_inset ERT
7673 status Collapsed
7674
7675 \layout Standard
7676
7677 \backslash
7678 /
7679 \end_inset
7680
7681 -dumlrange
7682 \begin_inset LatexCommand \index{-\/-dumlrange}
7683
7684 \end_inset
7685
7686
7687 \series default
7688  Will dump the life ranges
7689 \begin_inset LatexCommand \index{Live range analysis}
7690
7691 \end_inset
7692
7693  for all symbols.
7694 \layout List
7695 \labelwidthstring 00.00.0000
7696
7697
7698 \series bold
7699 -
7700 \begin_inset ERT
7701 status Collapsed
7702
7703 \layout Standard
7704
7705 \backslash
7706 /
7707 \end_inset
7708
7709 -dumpregassign
7710 \begin_inset LatexCommand \index{-\/-dumpregassign}
7711
7712 \end_inset
7713
7714
7715 \bar under
7716
7717 \series default
7718 \bar default
7719 Will create a dump of iCode's, after register assignment
7720 \begin_inset LatexCommand \index{Register assignment}
7721
7722 \end_inset
7723
7724 , into a file named
7725 \emph on
7726 <source filename>.dumprassgn.
7727 \layout List
7728 \labelwidthstring 00.00.0000
7729
7730
7731 \series bold
7732 -
7733 \begin_inset ERT
7734 status Collapsed
7735
7736 \layout Standard
7737
7738 \backslash
7739 /
7740 \end_inset
7741
7742 -dumplrange
7743 \begin_inset LatexCommand \index{-\/-dumplrange}
7744
7745 \end_inset
7746
7747
7748 \series default
7749  Will create a dump of the live ranges of iTemp's
7750 \layout List
7751 \labelwidthstring 00.00.0000
7752
7753
7754 \series bold
7755 -
7756 \begin_inset ERT
7757 status Collapsed
7758
7759 \layout Standard
7760
7761 \backslash
7762 /
7763 \end_inset
7764
7765 -dumpall
7766 \begin_inset LatexCommand \index{-\/-dumpall}
7767
7768 \end_inset
7769
7770
7771 \size large
7772 \bar under
7773
7774 \series default
7775 \size default
7776 \bar default
7777 Will cause all the above mentioned dumps to be created.
7778 \layout Subsection
7779
7780 Redirecting output on Windows Shells
7781 \layout Standard
7782
7783 By default SDCC writes it's error messages to
7784 \begin_inset Quotes sld
7785 \end_inset
7786
7787 standard error
7788 \begin_inset Quotes srd
7789 \end_inset
7790
7791 .
7792  To force all messages to
7793 \begin_inset Quotes sld
7794 \end_inset
7795
7796 standard output
7797 \begin_inset Quotes srd
7798 \end_inset
7799
7800  use
7801 \series bold
7802 -
7803 \series default
7804 \emph on
7805
7806 \begin_inset ERT
7807 status Collapsed
7808
7809 \layout Standard
7810
7811 \backslash
7812 /
7813 \end_inset
7814
7815
7816 \series bold
7817 \emph default
7818 -
7819 \series default
7820 use-stdout
7821 \begin_inset LatexCommand \index{-\/-use-stdout}
7822
7823 \end_inset
7824
7825 .
7826  Additionally, if you happen to have visual studio installed in your windows
7827  machine, you can use it to compile your sources using a custom build and
7828  the SDCC -
7829 \emph on
7830
7831 \begin_inset ERT
7832 status Collapsed
7833
7834 \layout Standard
7835
7836 \backslash
7837 /
7838 \end_inset
7839
7840
7841 \emph default
7842 -vc
7843 \begin_inset LatexCommand \index{-\/-vc}
7844
7845 \end_inset
7846
7847  option.
7848  Something like this should work:
7849 \newline
7850
7851 \newline
7852
7853 \series bold
7854 c:
7855 \backslash
7856 sdcc
7857 \backslash
7858 bin
7859 \backslash
7860 sdcc.exe -
7861 \series default
7862 \emph on
7863
7864 \begin_inset ERT
7865 status Collapsed
7866
7867 \layout Standard
7868
7869 \backslash
7870 /
7871 \end_inset
7872
7873
7874 \series bold
7875 \emph default
7876 -vc -
7877 \series default
7878 \emph on
7879
7880 \begin_inset ERT
7881 status Collapsed
7882
7883 \layout Standard
7884
7885 \backslash
7886 /
7887 \end_inset
7888
7889
7890 \series bold
7891 \emph default
7892 -model-large -c $(InputPath)
7893 \layout Section
7894
7895 Environment variables
7896 \begin_inset LatexCommand \index{Environment variables}
7897
7898 \end_inset
7899
7900
7901 \layout Standard
7902
7903 SDCC recognizes the following environment variables:
7904 \layout List
7905 \labelwidthstring 00.00.0000
7906
7907
7908 \series bold
7909 SDCC_LEAVE_SIGNALS
7910 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
7911
7912 \end_inset
7913
7914
7915 \series default
7916  SDCC installs a signal handler
7917 \begin_inset LatexCommand \index{signal handler}
7918
7919 \end_inset
7920
7921  to be able to delete temporary files after an user break (^C) or an exception.
7922  If this environment variable is set, SDCC won't install the signal handler
7923  in order to be able to debug SDCC.
7924 \layout List
7925 \labelwidthstring 00.00.0000
7926
7927
7928 \series bold
7929 TMP,\SpecialChar ~
7930 TEMP,\SpecialChar ~
7931 TMPDIR
7932 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
7933
7934 \end_inset
7935
7936
7937 \series default
7938  Path, where temporary files will be created.
7939  The order of the variables is the search order.
7940  In a standard *nix environment these variables are not set, and there's
7941  no need to set them.
7942  On Windows it's recommended to set one of them.
7943 \layout List
7944 \labelwidthstring 00.00.0000
7945
7946
7947 \series bold
7948 SDCC_HOME
7949 \begin_inset LatexCommand \index{SDCC\_HOME}
7950
7951 \end_inset
7952
7953
7954 \series default
7955  Path, see section
7956 \begin_inset LatexCommand \ref{sub:Install-paths}
7957
7958 \end_inset
7959
7960 \SpecialChar ~
7961
7962 \begin_inset Quotes sld
7963 \end_inset
7964
7965  Install Paths
7966 \begin_inset Quotes srd
7967 \end_inset
7968
7969 .
7970 \layout List
7971 \labelwidthstring 00.00.0000
7972
7973
7974 \series bold
7975 SDCC_INCLUDE
7976 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
7977
7978 \end_inset
7979
7980
7981 \series default
7982  Path, see section
7983 \begin_inset LatexCommand \ref{sub:Search-Paths}
7984
7985 \end_inset
7986
7987 \SpecialChar ~
7988
7989 \begin_inset Quotes sld
7990 \end_inset
7991
7992 Search Paths
7993 \begin_inset Quotes srd
7994 \end_inset
7995
7996 .
7997 \layout List
7998 \labelwidthstring 00.00.0000
7999
8000
8001 \series bold
8002 SDCC_LIB
8003 \begin_inset LatexCommand \index{SDCC\_LIB}
8004
8005 \end_inset
8006
8007
8008 \series default
8009  Path, see section
8010 \begin_inset LatexCommand \ref{sub:Search-Paths}
8011
8012 \end_inset
8013
8014 \SpecialChar ~
8015
8016 \begin_inset Quotes sld
8017 \end_inset
8018
8019 Search Paths
8020 \begin_inset Quotes srd
8021 \end_inset
8022
8023 ..
8024 \layout Standard
8025
8026 There are some more environment variables recognized by SDCC, but these
8027  are solely used for debugging purposes.
8028  They can change or disappear very quickly, and will never be documented.
8029 \layout Section
8030
8031 Storage Class Language Extensions
8032 \layout Subsection
8033
8034 MCS51/DS390 Storage Class
8035 \begin_inset LatexCommand \index{Storage class}
8036
8037 \end_inset
8038
8039  Language Extensions
8040 \layout Standard
8041
8042 In addition to the ANSI storage classes SDCC allows the following MCS51
8043  specific storage classes:
8044 \layout Subsubsection
8045
8046 data
8047 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8048
8049 \end_inset
8050
8051  / near
8052 \begin_inset LatexCommand \index{near (storage class)}
8053
8054 \end_inset
8055
8056
8057 \layout Standard
8058
8059 This is the
8060 \series bold
8061 default
8062 \series default
8063  storage class for the Small Memory model (
8064 \emph on
8065 data
8066 \emph default
8067  and
8068 \emph on
8069 near
8070 \emph default
8071  can be used synonymously).
8072  Variables declared with this storage class will be allocated in the directly
8073  addressable portion of the internal RAM of a 8051, e.g.:
8074 \layout Verse
8075
8076
8077 \family typewriter
8078 data unsigned char test_data;
8079 \layout Standard
8080
8081 Writing 0x01 to this variable generates the assembly code:
8082 \layout Verse
8083
8084
8085 \family typewriter
8086 75*00 01\SpecialChar ~
8087 \SpecialChar ~
8088 \SpecialChar ~
8089 mov\SpecialChar ~
8090 \SpecialChar ~
8091 _test_data,#0x01
8092 \layout Subsubsection
8093
8094 xdata
8095 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8096
8097 \end_inset
8098
8099  / far
8100 \begin_inset LatexCommand \index{far (storage class)}
8101
8102 \end_inset
8103
8104
8105 \layout Standard
8106
8107 Variables declared with this storage class will be placed in the external
8108  RAM.
8109  This is the
8110 \series bold
8111 default
8112 \series default
8113  storage class for the Large Memory model, e.g.:
8114 \layout Verse
8115
8116
8117 \family typewriter
8118 xdata unsigned char test_xdata;
8119 \layout Standard
8120
8121 Writing 0x01 to this variable generates the assembly code:
8122 \layout Verse
8123
8124
8125 \family typewriter
8126 90s00r00\SpecialChar ~
8127 \SpecialChar ~
8128 \SpecialChar ~
8129 mov\SpecialChar ~
8130 \SpecialChar ~
8131 dptr,#_test_xdata
8132 \newline
8133 74\SpecialChar ~
8134 01\SpecialChar ~
8135 \SpecialChar ~
8136 \SpecialChar ~
8137 \SpecialChar ~
8138 \SpecialChar ~
8139 \SpecialChar ~
8140 mov\SpecialChar ~
8141 \SpecialChar ~
8142 a,#0x01
8143 \newline
8144 F0\SpecialChar ~
8145 \SpecialChar ~
8146 \SpecialChar ~
8147 \SpecialChar ~
8148 \SpecialChar ~
8149 \SpecialChar ~
8150 \SpecialChar ~
8151 \SpecialChar ~
8152 \SpecialChar ~
8153 movx\SpecialChar ~
8154 @dptr,a
8155 \layout Subsubsection
8156
8157 idata
8158 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8159
8160 \end_inset
8161
8162
8163 \layout Standard
8164
8165 Variables declared with this storage class will be allocated into the indirectly
8166  addressable portion of the internal ram of a 8051, e.g.:
8167 \layout Verse
8168
8169
8170 \family typewriter
8171 idata unsigned char test_idata;
8172 \layout Standard
8173
8174 Writing 0x01 to this variable generates the assembly code:
8175 \layout Verse
8176
8177
8178 \family typewriter
8179 78r00\SpecialChar ~
8180 \SpecialChar ~
8181 \SpecialChar ~
8182 \SpecialChar ~
8183 \SpecialChar ~
8184 \SpecialChar ~
8185 \SpecialChar ~
8186 mov\SpecialChar ~
8187 \SpecialChar ~
8188 r0,#_test_idata
8189 \newline
8190 76\SpecialChar ~
8191 01\SpecialChar ~
8192 \SpecialChar ~
8193 \SpecialChar ~
8194 \SpecialChar ~
8195 \SpecialChar ~
8196 \SpecialChar ~
8197 \SpecialChar ~
8198 mov\SpecialChar ~
8199 \SpecialChar ~
8200 @r0,#0x01
8201 \layout Standard
8202
8203 Please note, the first 128 byte of idata physically access the same RAM
8204  as the data memory.
8205  The original 8051 had 128 byte idata memory, nowadays most devices have
8206  256 byte idata memory.
8207  The stack
8208 \begin_inset LatexCommand \index{stack}
8209
8210 \end_inset
8211
8212  is located in idata memory.
8213 \layout Subsubsection
8214
8215 pdata
8216 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8217
8218 \end_inset
8219
8220
8221 \layout Standard
8222
8223 Paged xdata access is currently not as straightforward as using the other
8224  addressing modes of a 8051.
8225  The following example writes 0x01 to the address pointed to.
8226  Please note, pdata access physically accesses xdata memory.
8227  The high byte of the address is determined by port P2
8228 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8229
8230 \end_inset
8231
8232 (or in case of some 8051 variants by a separate Special Function Register,
8233  see section
8234 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8235
8236 \end_inset
8237
8238 ).
8239 \layout Verse
8240
8241
8242 \family typewriter
8243 pdata unsigned char *test_pdata_ptr;
8244 \newline
8245
8246 \newline
8247 void main()
8248 \newline
8249 {
8250 \newline
8251 \SpecialChar ~
8252 \SpecialChar ~
8253 \SpecialChar ~
8254 \SpecialChar ~
8255 test_pdata_ptr = (pdata *)0xfe;
8256 \newline
8257 \SpecialChar ~
8258 \SpecialChar ~
8259 \SpecialChar ~
8260 \SpecialChar ~
8261 *test_pdata_ptr = 1;
8262 \newline
8263 }
8264 \layout Standard
8265
8266 Generates the assembly code:
8267 \layout Verse
8268
8269
8270 \family typewriter
8271 75*01 FE\SpecialChar ~
8272 \SpecialChar ~
8273 \SpecialChar ~
8274 mov\SpecialChar ~
8275  _test_pdata_ptr,#0xFE
8276 \newline
8277 78 FE\SpecialChar ~
8278 \SpecialChar ~
8279 \SpecialChar ~
8280 \SpecialChar ~
8281 \SpecialChar ~
8282 \SpecialChar ~
8283 mov\SpecialChar ~
8284  r0,#0xFE
8285 \newline
8286 74 01\SpecialChar ~
8287 \SpecialChar ~
8288 \SpecialChar ~
8289 \SpecialChar ~
8290 \SpecialChar ~
8291 \SpecialChar ~
8292 mov\SpecialChar ~
8293  a,#0x01
8294 \newline
8295 F2\SpecialChar ~
8296 \SpecialChar ~
8297 \SpecialChar ~
8298 \SpecialChar ~
8299 \SpecialChar ~
8300 \SpecialChar ~
8301 \SpecialChar ~
8302 \SpecialChar ~
8303 \SpecialChar ~
8304 movx @r0,a
8305 \layout Standard
8306
8307 Be extremely carefull if you use pdata together with the -
8308 \begin_inset ERT
8309 status Collapsed
8310
8311 \layout Standard
8312
8313 \backslash
8314 /
8315 \end_inset
8316
8317 -xstack
8318 \begin_inset LatexCommand \index{-\/-xstack}
8319
8320 \end_inset
8321
8322  option.
8323 \layout Subsubsection
8324
8325 code
8326 \begin_inset LatexCommand \index{code}
8327
8328 \end_inset
8329
8330
8331 \layout Standard
8332
8333 'Variables' declared with this storage class will be placed in the code
8334  memory:
8335 \layout Verse
8336
8337
8338 \family typewriter
8339 code unsigned char test_code;
8340 \layout Standard
8341
8342 Read access to this variable generates the assembly code:
8343 \layout Verse
8344
8345
8346 \family typewriter
8347 90s00r6F\SpecialChar ~
8348 \SpecialChar ~
8349 \SpecialChar ~
8350 mov dptr,#_test_code
8351 \newline
8352 E4\SpecialChar ~
8353 \SpecialChar ~
8354 \SpecialChar ~
8355 \SpecialChar ~
8356 \SpecialChar ~
8357 \SpecialChar ~
8358 \SpecialChar ~
8359 \SpecialChar ~
8360 \SpecialChar ~
8361 clr a
8362 \newline
8363 93\SpecialChar ~
8364 \SpecialChar ~
8365 \SpecialChar ~
8366 \SpecialChar ~
8367 \SpecialChar ~
8368 \SpecialChar ~
8369 \SpecialChar ~
8370 \SpecialChar ~
8371 \SpecialChar ~
8372 movc a,@a+dptr
8373 \layout Standard
8374
8375
8376 \family typewriter
8377 char
8378 \family default
8379  indexed arrays of characters in code memory can be accessed efficiently:
8380 \layout Verse
8381
8382
8383 \family typewriter
8384 code char test_array[] = {'c','h','e','a','p'};
8385 \layout Standard
8386
8387 Read access to this array using an 8-bit unsigned index generates the assembly
8388  code:
8389 \layout Verse
8390
8391
8392 \family typewriter
8393 E5*00\SpecialChar ~
8394 \SpecialChar ~
8395 \SpecialChar ~
8396 \SpecialChar ~
8397 \SpecialChar ~
8398 \SpecialChar ~
8399 mov a,_index
8400 \layout Verse
8401
8402
8403 \family typewriter
8404 90s00r41\SpecialChar ~
8405 \SpecialChar ~
8406 \SpecialChar ~
8407 mov dptr,#_test_array
8408 \layout Verse
8409
8410
8411 \family typewriter
8412 93\SpecialChar ~
8413 \SpecialChar ~
8414 \SpecialChar ~
8415 \SpecialChar ~
8416 \SpecialChar ~
8417 \SpecialChar ~
8418 \SpecialChar ~
8419 \SpecialChar ~
8420 \SpecialChar ~
8421 movc a,@a+dptr
8422 \layout Subsubsection
8423
8424 bit
8425 \begin_inset LatexCommand \index{bit}
8426
8427 \end_inset
8428
8429
8430 \layout Standard
8431
8432 This is a data-type and a storage class specifier.
8433  When a variable is declared as a bit, it is allocated into the bit addressable
8434  memory of 8051, e.g.:
8435 \layout Verse
8436
8437
8438 \family typewriter
8439 bit test_bit;
8440 \layout Standard
8441
8442 Writing 1 to this variable generates the assembly code:
8443 \layout Verse
8444
8445
8446 \family typewriter
8447 D2*00\SpecialChar ~
8448 \SpecialChar ~
8449 \SpecialChar ~
8450 \SpecialChar ~
8451 \SpecialChar ~
8452 \SpecialChar ~
8453 \SpecialChar ~
8454 setb\SpecialChar ~
8455 _test_bit
8456 \layout Standard
8457
8458 The bit addressable memory consists of 128 bits which are located from 0x20
8459  to 0x2f in data memory.
8460
8461 \newline
8462 Apart from this 8051 specific storage class most architectures support ANSI-C
8463  bitfields
8464 \begin_inset LatexCommand \index{bitfields}
8465
8466 \end_inset
8467
8468
8469 \begin_inset Foot
8470 collapsed false
8471
8472 \layout Standard
8473
8474 Not really meant as examples, but nevertheless showing what bitfields are
8475  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8476 \end_inset
8477
8478 .
8479  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
8480  signed modifier are implemented as unsigned.
8481 \layout Subsubsection
8482
8483 sfr
8484 \begin_inset LatexCommand \index{sfr}
8485
8486 \end_inset
8487
8488  / sbit
8489 \begin_inset LatexCommand \index{sbit}
8490
8491 \end_inset
8492
8493
8494 \layout Standard
8495
8496 Like the bit keyword,
8497 \emph on
8498 sfr / sbit
8499 \emph default
8500 signifies both a data-type and storage class, they are used to describe
8501  the
8502 \emph on
8503 s
8504 \emph default
8505 pecial
8506 \emph on
8507 f
8508 \emph default
8509 unction
8510 \emph on
8511 r
8512 \emph default
8513 egisters and
8514 \emph on
8515 s
8516 \emph default
8517 pecial
8518 \emph on
8519 bit
8520 \emph default
8521  variables of a 8051, eg:
8522 \layout Verse
8523
8524
8525 \family typewriter
8526 sfr at
8527 \begin_inset LatexCommand \index{at}
8528
8529 \end_inset
8530
8531  0x80 P0;\SpecialChar ~
8532  /* special function register P0 at location 0x80 */
8533 \newline
8534 sbit at 0xd7 CY; /* CY (Carry Flag
8535 \begin_inset LatexCommand \index{Flags}
8536
8537 \end_inset
8538
8539
8540 \begin_inset LatexCommand \index{Carry flag}
8541
8542 \end_inset
8543
8544 ) */
8545 \layout Standard
8546
8547 Special function registers which are located on an address dividable by
8548  8 are bit-addressable, an
8549 \emph on
8550  sbit
8551 \emph default
8552  addresses a specific bit within these sfr.
8553 \layout Subsubsection
8554
8555 Pointers
8556 \begin_inset LatexCommand \index{Pointer}
8557
8558 \end_inset
8559
8560  to MCS51/DS390 specific memory spaces
8561 \layout Standard
8562
8563 SDCC allows (via language extensions) pointers to explicitly point to any
8564  of the memory spaces
8565 \begin_inset LatexCommand \index{Memory model}
8566
8567 \end_inset
8568
8569  of the 8051.
8570  In addition to the explicit pointers, the compiler uses (by default) generic
8571  pointers which can be used to point to any of the memory spaces.
8572 \newline
8573
8574 \newline
8575 Pointer declaration examples:
8576 \layout Verse
8577
8578
8579 \family typewriter
8580 /* pointer physically in internal ram pointing to object in external ram
8581  */
8582 \newline
8583 xdata unsigned char * data p;
8584 \newline
8585
8586 \newline
8587 /* pointer physically in external ram pointing to object in internal ram
8588  */
8589 \newline
8590 data unsigned char * xdata p;
8591 \newline
8592
8593 \newline
8594 /* pointer physically in code rom pointing to data in xdata space */
8595 \newline
8596 xdata unsigned char * code p;
8597 \newline
8598
8599 \newline
8600 /* pointer physically in code space pointing to data in code space */
8601 \newline
8602 code unsigned char * code p;
8603 \newline
8604
8605 \newline
8606 /* the following is a generic pointer physically located in xdata space
8607  */
8608 \newline
8609 char * xdata p;
8610 \layout Standard
8611
8612 Well you get the idea.
8613
8614 \newline
8615
8616 \newline
8617 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
8618 \emph on
8619 generic
8620 \emph default
8621  pointers.
8622
8623 \size small
8624
8625 \newline
8626
8627 \newline
8628
8629 \size default
8630 The highest order byte of the
8631 \emph on
8632 generic
8633 \emph default
8634  pointers contains the data space information.
8635  Assembler support routines are called whenever data is stored or retrieved
8636  using
8637 \emph on
8638 generic
8639 \emph default
8640  pointers.
8641  These are useful for developing reusable library
8642 \begin_inset LatexCommand \index{Libraries}
8643
8644 \end_inset
8645
8646  routines.
8647  Explicitly specifying the pointer type will generate the most efficient
8648  code.
8649 \layout Subsubsection
8650
8651 Notes on MCS51 memory
8652 \begin_inset LatexCommand \index{MCS51 memory}
8653
8654 \end_inset
8655
8656  layout
8657 \layout Standard
8658
8659 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
8660  RAM memory which is structured as follows:
8661 \newline
8662
8663 \newline
8664 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
8665
8666 \newline
8667 - Bytes 20-2F - 16 bytes to hold 128 bit
8668 \begin_inset LatexCommand \index{bit}
8669
8670 \end_inset
8671
8672  variables and,
8673 \newline
8674 - Bytes 30-7F - 80 bytes for general purpose use.
8675 \newline
8676
8677 \layout Standard
8678
8679 Additionally some members of the MCS51 family may have up to 128 bytes of
8680  additional, indirectly addressable, internal RAM memory (
8681 \emph on
8682 idata
8683 \emph default
8684
8685 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8686
8687 \end_inset
8688
8689 ).
8690  Furthermore, some chips may have some built in external memory (
8691 \emph on
8692 xdata
8693 \emph default
8694
8695 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8696
8697 \end_inset
8698
8699 ) which should not be confused with the internal, directly addressable RAM
8700  memory (
8701 \emph on
8702 data
8703 \emph default
8704
8705 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8706
8707 \end_inset
8708
8709 ).
8710  Sometimes this built in
8711 \emph on
8712 xdata
8713 \emph default
8714  memory has to be activated before using it (you can probably find this
8715  information on the datasheet of the microcontroller your are using, see
8716  also section
8717 \begin_inset LatexCommand \ref{sub:Startup-Code}
8718
8719 \end_inset
8720
8721 \SpecialChar ~
8722 Startup-Code).
8723 \layout Standard
8724
8725 Normally SDCC will only use the first bank
8726 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
8727
8728 \end_inset
8729
8730  of registers (register bank 0), but it is possible to specify that other
8731  banks of registers should be used in interrupt
8732 \begin_inset LatexCommand \index{interrupt}
8733
8734 \end_inset
8735
8736  routines.
8737  By default, the compiler will place the stack after the last byte of allocated
8738  memory for variables.
8739  For example, if the first 2 banks of registers are used, and only four
8740  bytes are used for
8741 \emph on
8742 data
8743 \emph default
8744  variables, it will position the base of the internal stack at address 20
8745  (0x14).
8746  This implies that as the stack
8747 \begin_inset LatexCommand \index{stack}
8748
8749 \end_inset
8750
8751  grows, it will use up the remaining register banks, and the 16 bytes used
8752  by the 128 bit variables, and 80 bytes for general purpose use.
8753  If any bit variables are used, the data variables will be placed after
8754  the byte holding the last bit variable.
8755  For example, if register banks 0 and 1 are used, and there are 9 bit variables
8756  (two bytes used),
8757 \emph on
8758 data
8759 \emph default
8760  variables will be placed starting at address 0x22.
8761  You can also use -
8762 \begin_inset ERT
8763 status Collapsed
8764
8765 \layout Standard
8766
8767 \backslash
8768 /
8769 \end_inset
8770
8771 -data-loc
8772 \begin_inset LatexCommand \index{-\/-data-loc<Value>}
8773
8774 \end_inset
8775
8776  to specify the start address of the
8777 \emph on
8778 data
8779 \emph default
8780  and -
8781 \begin_inset ERT
8782 status Collapsed
8783
8784 \layout Standard
8785
8786 \backslash
8787 /
8788 \end_inset
8789
8790 -iram-size to specify the size of the total internal RAM (
8791 \emph on
8792 data
8793 \emph default
8794 +
8795 \emph on
8796 idata
8797 \emph default
8798 ).
8799
8800 \layout Standard
8801
8802 By default the 8051 linker will place the stack after the last byte of data
8803  variables.
8804  Option -
8805 \begin_inset ERT
8806 status Collapsed
8807
8808 \layout Standard
8809
8810 \backslash
8811 /
8812 \end_inset
8813
8814 -stack-loc
8815 \begin_inset LatexCommand \index{-\/-stack-loc<Value>}
8816
8817 \end_inset
8818
8819  allows you to specify the start of the stack, i.e.
8820  you could start it after any data in the general purpose area.
8821  If your microcontroller has additional indirectly addressable internal
8822  RAM (
8823 \emph on
8824 idata
8825 \emph default
8826 ) you can place the stack on it.
8827  You may also need to use -
8828 \begin_inset ERT
8829 status Collapsed
8830
8831 \layout Standard
8832
8833 \backslash
8834 /
8835 \end_inset
8836
8837 -xdata-loc
8838 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
8839
8840 \end_inset
8841
8842  to set the start address of the external RAM (
8843 \emph on
8844 xdata
8845 \emph default
8846 ) and -
8847 \begin_inset ERT
8848 status Collapsed
8849
8850 \layout Standard
8851
8852 \backslash
8853 /
8854 \end_inset
8855
8856 -xram-size
8857 \begin_inset LatexCommand \index{-\/-data-loc}
8858
8859 \end_inset
8860
8861  to specify its size.
8862  Same goes for the code memory, using -
8863 \begin_inset ERT
8864 status Collapsed
8865
8866 \layout Standard
8867
8868 \backslash
8869 /
8870 \end_inset
8871
8872 -code-loc
8873 \begin_inset LatexCommand \index{-\/-data-loc}
8874
8875 \end_inset
8876
8877  and -
8878 \begin_inset ERT
8879 status Collapsed
8880
8881 \layout Standard
8882
8883 \backslash
8884 /
8885 \end_inset
8886
8887 -code-size
8888 \begin_inset LatexCommand \index{-\/-data-loc}
8889
8890 \end_inset
8891
8892 .
8893  If in doubt, don't specify any options and see if the resulting memory
8894  layout is appropriate, then you can adjust it.
8895 \layout Standard
8896
8897 The linker generates two files with memory allocation information.
8898  The first, with extension .map
8899 \begin_inset LatexCommand \index{<file>.map}
8900
8901 \end_inset
8902
8903  shows all the variables and segments.
8904  The second with extension .mem
8905 \begin_inset LatexCommand \index{<file>.mem}
8906
8907 \end_inset
8908
8909  shows the final memory layout.
8910  The linker will complain either if memory segments overlap, there is not
8911  enough memory, or there is not enough space for stack.
8912  If you get any linking warnings and/or errors related to stack or segments
8913  allocation, take a look at either the .map or .mem files to find out what
8914  the problem is.
8915  The .mem file may even suggest a solution to the problem.
8916 \layout Subsection
8917
8918 Z80/Z180 Storage Class
8919 \begin_inset LatexCommand \index{Storage class}
8920
8921 \end_inset
8922
8923  Language Extensions
8924 \layout Subsubsection
8925
8926 sfr
8927 \begin_inset LatexCommand \index{sfr}
8928
8929 \end_inset
8930
8931  (in/out to 8-bit addresses)
8932 \layout Standard
8933
8934 The Z80
8935 \begin_inset LatexCommand \index{Z80}
8936
8937 \end_inset
8938
8939  family has separate address spaces for memory and
8940 \emph on
8941 i
8942 \emph default
8943 nput/
8944 \emph on
8945 o
8946 \emph default
8947 utput memory.
8948  I/O memory
8949 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
8950
8951 \end_inset
8952
8953  is accessed with special instructions, e.g.:
8954 \layout Verse
8955
8956
8957 \family typewriter
8958 sfr at 0x78 IoPort;\SpecialChar ~
8959 \SpecialChar ~
8960 /* define a var in I/O space at 78h called IoPort */
8961
8962 \layout Standard
8963
8964 Writing 0x01 to this variable generates the assembly code:
8965 \layout Verse
8966
8967
8968 \family typewriter
8969 3E 01\SpecialChar ~
8970 \SpecialChar ~
8971 \SpecialChar ~
8972 \SpecialChar ~
8973 \SpecialChar ~
8974 \SpecialChar ~
8975 ld a,#0x01
8976 \newline
8977 D3 78\SpecialChar ~
8978 \SpecialChar ~
8979 \SpecialChar ~
8980 \SpecialChar ~
8981 \SpecialChar ~
8982 \SpecialChar ~
8983 out (_IoPort),a
8984 \layout Subsubsection
8985
8986 banked sfr
8987 \begin_inset LatexCommand \index{sfr}
8988
8989 \end_inset
8990
8991  (in/out to 16-bit addresses)
8992 \layout Standard
8993
8994 The keyword
8995 \emph on
8996 banked
8997 \emph default
8998  is used to support 16 bit addresses in I/O memory e.g.:
8999 \layout Verse
9000
9001
9002 \family typewriter
9003 sfr banked at
9004 \begin_inset LatexCommand \index{at}
9005
9006 \end_inset
9007
9008  0x123 IoPort;
9009 \layout Standard
9010
9011 Writing 0x01 to this variable generates the assembly code:
9012 \layout Verse
9013
9014
9015 \family typewriter
9016 01 23 01\SpecialChar ~
9017 \SpecialChar ~
9018 \SpecialChar ~
9019 ld bc,#_IoPort
9020 \newline
9021 3E 01\SpecialChar ~
9022 \SpecialChar ~
9023 \SpecialChar ~
9024 \SpecialChar ~
9025 \SpecialChar ~
9026 \SpecialChar ~
9027 ld a,#0x01
9028 \newline
9029 ED 79\SpecialChar ~
9030 \SpecialChar ~
9031 \SpecialChar ~
9032 \SpecialChar ~
9033 \SpecialChar ~
9034 \SpecialChar ~
9035 out (c),a
9036 \layout Subsubsection
9037
9038 sfr
9039 \begin_inset LatexCommand \index{sfr}
9040
9041 \end_inset
9042
9043  (in0/out0 to 8 bit addresses on Z180
9044 \begin_inset LatexCommand \index{Z180}
9045
9046 \end_inset
9047
9048 /HD64180
9049 \begin_inset LatexCommand \index{HD64180}
9050
9051 \end_inset
9052
9053 )
9054 \layout Standard
9055
9056 The compiler option -
9057 \begin_inset ERT
9058 status Collapsed
9059
9060 \layout Standard
9061
9062 \backslash
9063 /
9064 \end_inset
9065
9066 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9067 portmode
9068 \begin_inset LatexCommand \index{\#pragma portmode}
9069
9070 \end_inset
9071
9072 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9073 ns
9074 \family typewriter
9075 in0/out0
9076 \family default
9077  instead of
9078 \family typewriter
9079 in/out
9080 \family default
9081 .
9082  If you include the file z180.h this will be set automatically.
9083 \layout Subsection
9084
9085 HC08 Storage Class
9086 \begin_inset LatexCommand \index{Storage class}
9087
9088 \end_inset
9089
9090  Language Extensions
9091 \layout Subsubsection
9092
9093 data
9094 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9095
9096 \end_inset
9097
9098
9099 \layout Standard
9100
9101 The data storage class declares a variable that resides in the first 256
9102  bytes of memory (the direct page).
9103  The HC08 is most efficient at accessing variables (especially pointers)
9104  stored here.
9105 \layout Subsubsection
9106
9107 xdata
9108 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9109
9110 \end_inset
9111
9112
9113 \layout Standard
9114
9115 The xdata storage class declares a variable that can reside anywhere in
9116  memory.
9117  This is the default if no storage class is specified.
9118
9119 \layout Section
9120
9121 Absolute Addressing
9122 \begin_inset LatexCommand \index{Absolute addressing}
9123
9124 \end_inset
9125
9126
9127 \layout Standard
9128
9129 Data items can be assigned an absolute address with the
9130 \emph on
9131 at
9132 \begin_inset LatexCommand \index{at}
9133
9134 \end_inset
9135
9136  <address>
9137 \emph default
9138  keyword, in addition to a storage class, e.g.:
9139 \layout Verse
9140
9141
9142 \family typewriter
9143 xdata
9144 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9145
9146 \end_inset
9147
9148  at
9149 \begin_inset LatexCommand \index{at}
9150
9151 \end_inset
9152
9153  0x7ffe unsigned int chksum;
9154 \layout Standard
9155
9156 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9157  of the external ram.
9158  The compiler does
9159 \emph on
9160 not
9161 \emph default
9162  reserve any space for variables declared in this way (they are implemented
9163  with an equate in the assembler).
9164  Thus it is left to the programmer to make sure there are no overlaps with
9165  other variables that are declared without the absolute address.
9166  The assembler listing file (.lst
9167 \begin_inset LatexCommand \index{<file>.lst}
9168
9169 \end_inset
9170
9171 ) and the linker output files (.rst
9172 \begin_inset LatexCommand \index{<file>.rst}
9173
9174 \end_inset
9175
9176 ) and (.map
9177 \begin_inset LatexCommand \index{<file>.map}
9178
9179 \end_inset
9180
9181 ) are good places to look for such overlaps.
9182  Variables with an absolute address are
9183 \emph on
9184 not
9185 \emph default
9186  initialized
9187 \begin_inset LatexCommand \index{Variable initialization}
9188
9189 \end_inset
9190
9191 .
9192 \layout Standard
9193
9194 In case of memory mapped I/O devices the keyword
9195 \emph on
9196 volatile
9197 \emph default
9198  has to be used to tell the compiler that accesses might not be removed:
9199 \layout Verse
9200
9201
9202 \family typewriter
9203 volatile
9204 \begin_inset LatexCommand \index{volatile}
9205
9206 \end_inset
9207
9208  xdata
9209 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9210
9211 \end_inset
9212
9213  at
9214 \begin_inset LatexCommand \index{at}
9215
9216 \end_inset
9217
9218  0x8000 unsigned char PORTA_8255;
9219 \layout Standard
9220
9221 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9222 r) array
9223 \family typewriter
9224 \size footnotesize
9225
9226 \begin_inset LatexCommand \index{Aligned array}
9227
9228 \end_inset
9229
9230
9231 \family default
9232 \size default
9233  starts at a block (256 byte) boundary
9234 \begin_inset LatexCommand \index{block boundary}
9235
9236 \end_inset
9237
9238  (section
9239 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9240
9241 \end_inset
9242
9243  has an example).
9244 \newline
9245 Absolute addresses can be specified for variables in all storage classes,
9246  e.g.:
9247 \layout Verse
9248
9249
9250 \family typewriter
9251 bit
9252 \begin_inset LatexCommand \index{bit}
9253
9254 \end_inset
9255
9256  at
9257 \begin_inset LatexCommand \index{at}
9258
9259 \end_inset
9260
9261  0x02 bvar;
9262 \layout Standard
9263
9264 The above example will allocate the variable at offset 0x02 in the bit-addressab
9265 le space.
9266  There is no real advantage to assigning absolute addresses to variables
9267  in this manner, unless you want strict control over all the variables allocated.
9268  One possible use would be to write hardware portable code.
9269  For example, if you have a routine that uses one or more of the microcontroller
9270  I/O pins, and such pins are different for two different hardwares, you
9271  can declare the I/O pins in your routine using:
9272 \layout Verse
9273
9274
9275 \family typewriter
9276 extern volatile bit MOSI;\SpecialChar ~
9277 \SpecialChar ~
9278 \SpecialChar ~
9279 \SpecialChar ~
9280 /* master out, slave in */
9281 \newline
9282 extern volatile bit MISO;\SpecialChar ~
9283 \SpecialChar ~
9284 \SpecialChar ~
9285 \SpecialChar ~
9286 /* master in, slave out */
9287 \newline
9288 extern volatile bit MCLK;\SpecialChar ~
9289 \SpecialChar ~
9290 \SpecialChar ~
9291 \SpecialChar ~
9292 /* master clock */
9293 \newline
9294
9295 \newline
9296 /* Input and Output of a byte on a 3-wire serial bus.
9297 \newline
9298 \SpecialChar ~
9299 \SpecialChar ~
9300 \SpecialChar ~
9301 If needed adapt polarity of clock, polarity of data and bit order
9302 \newline
9303 \SpecialChar ~
9304 */
9305 \newline
9306 unsigned char spi_io(unsigned char out_byte)
9307 \newline
9308 {
9309 \newline
9310 \SpecialChar ~
9311 \SpecialChar ~
9312 \SpecialChar ~
9313 \SpecialChar ~
9314 unsigned char i=8;
9315 \newline
9316 \SpecialChar ~
9317 \SpecialChar ~
9318 \SpecialChar ~
9319 \SpecialChar ~
9320 do {
9321 \newline
9322 \SpecialChar ~
9323 \SpecialChar ~
9324 \SpecialChar ~
9325 \SpecialChar ~
9326 \SpecialChar ~
9327 \SpecialChar ~
9328 \SpecialChar ~
9329 \SpecialChar ~
9330 MOSI = out_byte & 0x80;
9331 \newline
9332 \SpecialChar ~
9333 \SpecialChar ~
9334 \SpecialChar ~
9335 \SpecialChar ~
9336 \SpecialChar ~
9337 \SpecialChar ~
9338 \SpecialChar ~
9339 \SpecialChar ~
9340 out_byte <<= 1;
9341 \newline
9342 \SpecialChar ~
9343 \SpecialChar ~
9344 \SpecialChar ~
9345 \SpecialChar ~
9346 \SpecialChar ~
9347 \SpecialChar ~
9348 \SpecialChar ~
9349 \SpecialChar ~
9350 MCLK = 1;
9351 \newline
9352 \SpecialChar ~
9353 \SpecialChar ~
9354 \SpecialChar ~
9355 \SpecialChar ~
9356 \SpecialChar ~
9357 \SpecialChar ~
9358 \SpecialChar ~
9359 \SpecialChar ~
9360 /* _asm nop _endasm; */\SpecialChar ~
9361 \SpecialChar ~
9362 \SpecialChar ~
9363 \SpecialChar ~
9364 \SpecialChar ~
9365 \SpecialChar ~
9366 \SpecialChar ~
9367 \SpecialChar ~
9368 /* for slow peripherals */
9369 \newline
9370 \SpecialChar ~
9371 \SpecialChar ~
9372 \SpecialChar ~
9373 \SpecialChar ~
9374 \SpecialChar ~
9375 \SpecialChar ~
9376 \SpecialChar ~
9377 \SpecialChar ~
9378 if(MISO)
9379 \newline
9380 \SpecialChar ~
9381 \SpecialChar ~
9382 \SpecialChar ~
9383 \SpecialChar ~
9384 \SpecialChar ~
9385 \SpecialChar ~
9386 \SpecialChar ~
9387 \SpecialChar ~
9388 \SpecialChar ~
9389 \SpecialChar ~
9390 \SpecialChar ~
9391 \SpecialChar ~
9392 out_byte += 1;
9393 \newline
9394 \SpecialChar ~
9395 \SpecialChar ~
9396 \SpecialChar ~
9397 \SpecialChar ~
9398 \SpecialChar ~
9399 \SpecialChar ~
9400 \SpecialChar ~
9401 \SpecialChar ~
9402 MCLK = 0;
9403 \newline
9404 \SpecialChar ~
9405 \SpecialChar ~
9406 \SpecialChar ~
9407 \SpecialChar ~
9408 } while(--i);
9409 \newline
9410 \SpecialChar ~
9411 \SpecialChar ~
9412 \SpecialChar ~
9413 \SpecialChar ~
9414 return out_byte;
9415 \newline
9416 }
9417 \layout Standard
9418
9419 Then, someplace in the code for the first hardware you would use
9420 \layout Verse
9421
9422
9423 \family typewriter
9424 bit at 0x80 MOSI;\SpecialChar ~
9425 \SpecialChar ~
9426 \SpecialChar ~
9427 \SpecialChar ~
9428 /* I/O port 0, bit 0 */
9429 \newline
9430 bit at 0x81 MISO;\SpecialChar ~
9431 \SpecialChar ~
9432 \SpecialChar ~
9433 \SpecialChar ~
9434 /* I/O port 0, bit 1 */
9435 \newline
9436 bit at 0x82 MCLK;\SpecialChar ~
9437 \SpecialChar ~
9438 \SpecialChar ~
9439 \SpecialChar ~
9440 /* I/O port 0, bit 2 */
9441 \layout Standard
9442
9443 Similarly, for the second hardware you would use
9444 \layout Verse
9445
9446
9447 \family typewriter
9448 bit at 0x83 MOSI;\SpecialChar ~
9449 \SpecialChar ~
9450 \SpecialChar ~
9451 \SpecialChar ~
9452 /* I/O port 0, bit 3 */
9453 \newline
9454 bit at 0x91 MISO;\SpecialChar ~
9455 \SpecialChar ~
9456 \SpecialChar ~
9457 \SpecialChar ~
9458 /* I/O port 1, bit 1 */
9459 \newline
9460 bit
9461 \begin_inset LatexCommand \index{bit}
9462
9463 \end_inset
9464
9465  at 0x92 MCLK;\SpecialChar ~
9466 \SpecialChar ~
9467 \SpecialChar ~
9468 \SpecialChar ~
9469 /* I/O port 1, bit 2 */
9470 \layout Standard
9471
9472 and you can use the same hardware dependent routine without changes, as
9473  for example in a library.
9474  This is somehow similar to sbit, but only one absolute address has to be
9475  specified in the whole project.
9476 \layout Section
9477
9478 Parameters
9479 \begin_inset LatexCommand \index{Parameters}
9480
9481 \end_inset
9482
9483
9484 \begin_inset LatexCommand \index{function parameter}
9485
9486 \end_inset
9487
9488  & Local Variables
9489 \begin_inset LatexCommand \index{local variables}
9490
9491 \end_inset
9492
9493
9494 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
9495
9496 \end_inset
9497
9498
9499 \layout Standard
9500
9501 Automatic (local) variables and parameters to functions can either be placed
9502  on the stack or in data-space.
9503  The default action of the compiler is to place these variables in the internal
9504  RAM (for small model) or external RAM (for large model).
9505  This in fact makes them similar to
9506 \emph on
9507 static
9508 \begin_inset LatexCommand \index{static}
9509
9510 \end_inset
9511
9512
9513 \emph default
9514  so by default functions are non-reentrant
9515 \begin_inset LatexCommand \index{reentrant}
9516
9517 \end_inset
9518
9519 .
9520
9521 \newline
9522
9523 \newline
9524 They can be placed on the stack
9525 \begin_inset LatexCommand \index{stack}
9526
9527 \end_inset
9528
9529  by using the
9530 \emph on
9531  -
9532 \begin_inset ERT
9533 status Collapsed
9534
9535 \layout Standard
9536
9537 \backslash
9538 /
9539 \end_inset
9540
9541 -stack-auto
9542 \begin_inset LatexCommand \index{-\/-stack-auto}
9543
9544 \end_inset
9545
9546
9547 \emph default
9548  option, by using
9549 \emph on
9550 #pragma\SpecialChar ~
9551 stackauto
9552 \emph default
9553
9554 \begin_inset LatexCommand \index{\#pragma stackauto}
9555
9556 \end_inset
9557
9558  or by using the
9559 \emph on
9560 reentrant
9561 \begin_inset LatexCommand \index{reentrant}
9562
9563 \end_inset
9564
9565
9566 \emph default
9567  keyword in the function declaration, e.g.:
9568 \layout Verse
9569
9570
9571 \family typewriter
9572 unsigned char foo(char i) reentrant
9573 \newline
9574 {
9575 \newline
9576 \SpecialChar ~
9577 \SpecialChar ~
9578 \SpecialChar ~
9579 \SpecialChar ~
9580 ...
9581
9582 \newline
9583 }
9584 \layout Standard
9585
9586 Since stack space on 8051 is limited, the
9587 \emph on
9588 reentrant
9589 \emph default
9590 keyword or the
9591 \emph on
9592  -
9593 \begin_inset ERT
9594 status Collapsed
9595
9596 \layout Standard
9597
9598 \backslash
9599 /
9600 \end_inset
9601
9602 -stack-auto
9603 \emph default
9604  option should be used sparingly.
9605  Note that the reentrant keyword just means that the parameters & local
9606  variables will be allocated to the stack, it
9607 \emph on
9608 does not
9609 \emph default
9610  mean that the function is register bank
9611 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9612
9613 \end_inset
9614
9615  independent.
9616 \newline
9617
9618 \newline
9619 Local variables
9620 \begin_inset LatexCommand \index{local variables}
9621
9622 \end_inset
9623
9624  can be assigned storage classes and absolute
9625 \begin_inset LatexCommand \index{Absolute addressing}
9626
9627 \end_inset
9628
9629  addresses, e.g.:
9630 \layout Verse
9631
9632
9633 \family typewriter
9634 unsigned char foo()
9635 \newline
9636 {
9637 \newline
9638 \SpecialChar ~
9639 \SpecialChar ~
9640 \SpecialChar ~
9641 \SpecialChar ~
9642 xdata unsigned char i;
9643 \newline
9644 \SpecialChar ~
9645 \SpecialChar ~
9646 \SpecialChar ~
9647 \SpecialChar ~
9648 bit bvar;
9649 \newline
9650 \SpecialChar ~
9651 \SpecialChar ~
9652 \SpecialChar ~
9653 \SpecialChar ~
9654 data at
9655 \begin_inset LatexCommand \index{at}
9656
9657 \end_inset
9658
9659  0x31 unsigned char j;
9660 \newline
9661 \SpecialChar ~
9662 \SpecialChar ~
9663 \SpecialChar ~
9664 \SpecialChar ~
9665 ...
9666
9667 \newline
9668 }
9669 \layout Standard
9670
9671 In the above example the variable
9672 \emph on
9673 i
9674 \emph default
9675  will be allocated in the external ram,
9676 \emph on
9677 bvar
9678 \emph default
9679  in bit addressable space and
9680 \emph on
9681  j
9682 \emph default
9683  in internal ram.
9684  When compiled with
9685 \emph on
9686 -
9687 \begin_inset ERT
9688 status Collapsed
9689
9690 \layout Standard
9691
9692 \backslash
9693 /
9694 \end_inset
9695
9696 -stack-auto
9697 \emph default
9698  or when a function is declared as
9699 \emph on
9700 reentrant
9701 \emph default
9702  this should only be done for static variables.
9703 \layout Standard
9704
9705 Parameters
9706 \begin_inset LatexCommand \index{function parameter}
9707
9708 \end_inset
9709
9710  however are not allowed any storage class
9711 \begin_inset LatexCommand \index{Storage class}
9712
9713 \end_inset
9714
9715 , (storage classes for parameters will be ignored), their allocation is
9716  governed by the memory model in use, and the reentrancy options.
9717 \layout Section
9718
9719 Overlaying
9720 \begin_inset LatexCommand \label{sub:Overlaying}
9721
9722 \end_inset
9723
9724
9725 \begin_inset LatexCommand \index{Overlaying}
9726
9727 \end_inset
9728
9729
9730 \layout Standard
9731
9732 For non-reentrant
9733 \begin_inset LatexCommand \index{reentrant}
9734
9735 \end_inset
9736
9737  functions SDCC will try to reduce internal ram space usage by overlaying
9738  parameters and local variables of a function (if possible).
9739  Parameters and local variables
9740 \begin_inset LatexCommand \index{local variables}
9741
9742 \end_inset
9743
9744  of a function will be allocated to an overlayable segment if the function
9745  has
9746 \emph on
9747 no other function calls and the function is non-reentrant and the memory
9748  model
9749 \begin_inset LatexCommand \index{Memory model}
9750
9751 \end_inset
9752
9753  is small.
9754
9755 \emph default
9756  If an explicit storage class
9757 \begin_inset LatexCommand \index{Storage class}
9758
9759 \end_inset
9760
9761  is specified for a local variable, it will NOT be overlayed.
9762 \layout Standard
9763
9764 Note that the compiler (not the linkage editor) makes the decision for overlayin
9765 g the data items.
9766  Functions that are called from an interrupt service routine should be preceded
9767  by a #pragma\SpecialChar ~
9768 nooverlay
9769 \begin_inset LatexCommand \index{\#pragma nooverlay}
9770
9771 \end_inset
9772
9773  if they are not reentrant.
9774 \layout Standard
9775
9776 Also note that the compiler does not do any processing of inline assembler
9777  code, so the compiler might incorrectly assign local variables and parameters
9778  of a function into the overlay segment if the inline assembler code calls
9779  other c-functions that might use the overlay.
9780  In that case the #pragma\SpecialChar ~
9781 nooverlay should be used.
9782 \layout Standard
9783
9784 Parameters and local variables of functions that contain 16 or 32 bit multiplica
9785 tion
9786 \begin_inset LatexCommand \index{Multiplication}
9787
9788 \end_inset
9789
9790  or division
9791 \begin_inset LatexCommand \index{Division}
9792
9793 \end_inset
9794
9795  will NOT be overlayed since these are implemented using external functions,
9796  e.g.:
9797 \layout Verse
9798
9799
9800 \family typewriter
9801 #pragma save
9802 \newline
9803 #pragma nooverlay
9804 \begin_inset LatexCommand \index{\#pragma nooverlay}
9805
9806 \end_inset
9807
9808
9809 \newline
9810 void set_error(unsigned char errcd)
9811 \newline
9812 {
9813 \newline
9814 \SpecialChar ~
9815 \SpecialChar ~
9816 \SpecialChar ~
9817 \SpecialChar ~
9818 P3 = errcd;
9819 \newline
9820 }
9821 \newline
9822 #pragma restore
9823 \newline
9824
9825 \newline
9826 void some_isr () interrupt
9827 \begin_inset LatexCommand \index{interrupt}
9828
9829 \end_inset
9830
9831  2
9832 \newline
9833 {
9834 \newline
9835 \SpecialChar ~
9836 \SpecialChar ~
9837 \SpecialChar ~
9838 \SpecialChar ~
9839 ...
9840 \newline
9841 \SpecialChar ~
9842 \SpecialChar ~
9843 \SpecialChar ~
9844 \SpecialChar ~
9845 set_error(10);
9846 \newline
9847 \SpecialChar ~
9848 \SpecialChar ~
9849 \SpecialChar ~
9850 \SpecialChar ~
9851 ...
9852
9853 \newline
9854 }
9855 \layout Standard
9856
9857 In the above example the parameter
9858 \emph on
9859 errcd
9860 \emph default
9861  for the function
9862 \emph on
9863 set_error
9864 \emph default
9865  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
9866 nooverlay was
9867  not present, this could cause unpredictable runtime behavior when called
9868  from an interrupt service routine.
9869  The #pragma\SpecialChar ~
9870 nooverlay ensures that the parameters and local variables for
9871  the function are NOT overlayed.
9872 \layout Section
9873
9874 Interrupt Service Routines
9875 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
9876
9877 \end_inset
9878
9879
9880 \layout Subsection
9881
9882 General Information
9883 \layout Standard
9884
9885 SDCC allows
9886 \emph on
9887 i
9888 \emph default
9889 nterrupt
9890 \emph on
9891 s
9892 \emph default
9893 ervice
9894 \emph on
9895 r
9896 \emph default
9897 outines to be coded in C, with some extended keywords.
9898 \layout Verse
9899
9900
9901 \family typewriter
9902 void timer_isr (void) interrupt 1 using 1
9903 \newline
9904 {
9905 \newline
9906 \SpecialChar ~
9907 \SpecialChar ~
9908 \SpecialChar ~
9909 \SpecialChar ~
9910 ...
9911
9912 \newline
9913 }
9914 \layout Standard
9915
9916 The optional number following the
9917 \emph on
9918 interrupt
9919 \begin_inset LatexCommand \index{interrupt}
9920
9921 \end_inset
9922
9923
9924 \emph default
9925  keyword is the interrupt number this routine will service.
9926  When present, the compiler will insert a call to this routine in the interrupt
9927  vector table for the interrupt number specified.
9928  If you have multiple source files in your project, interrupt service routines
9929  can be present in any of them, but a prototype of the isr MUST be present
9930  or included in the file that contains the function
9931 \emph on
9932 main
9933 \emph default
9934 .
9935  The
9936 \emph on
9937 using
9938 \emph default
9939  keyword can be used to tell the compiler to use the specified register
9940  bank (8051 specific) when generating code for this function.
9941
9942 \newline
9943
9944 \layout Standard
9945
9946 Interrupt service routines open the door for some very interesting bugs:
9947 \newline
9948 If an interrupt service routine changes variables which are accessed by
9949  other functions these variables have to be declared
9950 \emph on
9951 volatile
9952 \emph default
9953
9954 \begin_inset LatexCommand \index{volatile}
9955
9956 \end_inset
9957
9958 .
9959
9960 \layout Standard
9961
9962 If the access to these variables is not
9963 \emph on
9964 atomic
9965 \begin_inset LatexCommand \index{atomic}
9966
9967 \end_inset
9968
9969
9970 \emph default
9971  (i.e.
9972  the processor needs more than one instruction for the access and could
9973  be interrupted while accessing the variable) the interrupt must be disabled
9974  during the access to avoid inconsistent data.
9975  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
9976  and should be protected by disabling interrupts.
9977  You're not automatically on the safe side if you use 8 bit variables though.
9978  We need an example here: f.e.
9979  on the 8051 the harmless looking
9980 \begin_inset Quotes srd
9981 \end_inset
9982
9983
9984 \family typewriter
9985 flags\SpecialChar ~
9986 |=\SpecialChar ~
9987 0x80;
9988 \family default
9989
9990 \begin_inset Quotes sld
9991 \end_inset
9992
9993  is not atomic if
9994 \family typewriter
9995 flags
9996 \family default
9997  resides in xdata.
9998  Setting
9999 \begin_inset Quotes srd
10000 \end_inset
10001
10002
10003 \family typewriter
10004 flags\SpecialChar ~
10005 |=\SpecialChar ~
10006 0x40;
10007 \family default
10008
10009 \begin_inset Quotes sld
10010 \end_inset
10011
10012  from within an interrupt routine might get lost if the interrupt occurs
10013  at the wrong time.
10014
10015 \begin_inset Quotes sld
10016 \end_inset
10017
10018
10019 \family typewriter
10020 counter\SpecialChar ~
10021 +=\SpecialChar ~
10022 8;
10023 \family default
10024
10025 \begin_inset Quotes srd
10026 \end_inset
10027
10028  is not atomic on the 8051 even if
10029 \family typewriter
10030 counter
10031 \family default
10032  is located in data memory.
10033  Bugs like these are hard to reproduce and can cause a lot of trouble.
10034
10035 \layout Standard
10036
10037 The return address and the registers used in the interrupt service routine
10038  are saved on the stack
10039 \begin_inset LatexCommand \index{stack}
10040
10041 \end_inset
10042
10043  so there must be sufficient stack space.
10044  If there isn't variables or registers (or even the return address itself)
10045  will be corrupted.
10046  This
10047 \emph on
10048 stack overflow
10049 \emph default
10050
10051 \begin_inset LatexCommand \index{stack overflow}
10052
10053 \end_inset
10054
10055  is most likely to happen if the interrupt occurs during the
10056 \begin_inset Quotes sld
10057 \end_inset
10058
10059 deepest
10060 \begin_inset Quotes srd
10061 \end_inset
10062
10063  subroutine when the stack is already in use for f.e.
10064  many return addresses.
10065 \layout Standard
10066
10067 A special note here, int (16 bit) and long (32 bit) integer division
10068 \begin_inset LatexCommand \index{Division}
10069
10070 \end_inset
10071
10072 , multiplication
10073 \begin_inset LatexCommand \index{Multiplication}
10074
10075 \end_inset
10076
10077  & modulus
10078 \begin_inset LatexCommand \index{Modulus}
10079
10080 \end_inset
10081
10082  and floating-point
10083 \begin_inset LatexCommand \index{Floating point support}
10084
10085 \end_inset
10086
10087  operations are implemented using external support routines developed in
10088  ANSI-C.
10089  If an interrupt service routine needs to do any of these operations then
10090  the support routines (as mentioned in a following section) will have to
10091  be recompiled using the
10092 \emph on
10093  -
10094 \begin_inset ERT
10095 status Collapsed
10096
10097 \layout Standard
10098
10099 \backslash
10100 /
10101 \end_inset
10102
10103 -stack-auto
10104 \begin_inset LatexCommand \index{-\/-stack-auto}
10105
10106 \end_inset
10107
10108
10109 \emph default
10110  option and the source file will need to be compiled using the
10111 \emph on
10112 -
10113 \begin_inset ERT
10114 status Collapsed
10115
10116 \layout Standard
10117
10118 \backslash
10119 /
10120 \end_inset
10121
10122 -int-long-reent
10123 \emph default
10124
10125 \begin_inset LatexCommand \index{-\/-int-long-reent}
10126
10127 \end_inset
10128
10129  compiler option.
10130 \layout Standard
10131
10132 Calling other functions from an interrupt service routine is not recommended,
10133  avoid it if possible.
10134  Note that when some function is called from an interrupt service routine
10135  it should be preceded by a #pragma\SpecialChar ~
10136 nooverlay
10137 \begin_inset LatexCommand \index{\#pragma nooverlay}
10138
10139 \end_inset
10140
10141  if it is not reentrant.
10142  Furthermore nonreentrant functions should not be called from the main program
10143  while the interrupt service routine might be active.
10144
10145 \newline
10146
10147 \newline
10148 Also see section
10149 \begin_inset LatexCommand \ref{sub:Overlaying}
10150
10151 \end_inset
10152
10153 \SpecialChar ~
10154 about Overlaying and section
10155 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10156
10157 \end_inset
10158
10159 \SpecialChar ~
10160 about Functions using private register banks.
10161 \layout Subsection
10162
10163 MCS51/DS390 Interrupt Service Routines
10164 \layout Standard
10165
10166 Interrupt numbers and the corresponding address & descriptions for the Standard
10167  8051/8052 are listed below.
10168  SDCC will automatically adjust the interrupt vector table to the maximum
10169  interrupt number specified.
10170 \newline
10171
10172 \layout Standard
10173 \align center
10174
10175 \begin_inset  Tabular
10176 <lyxtabular version="3" rows="7" columns="3">
10177 <features>
10178 <column alignment="center" valignment="top" leftline="true" width="0in">
10179 <column alignment="center" valignment="top" leftline="true" width="0in">
10180 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10181 <row topline="true" bottomline="true">
10182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10183 \begin_inset Text
10184
10185 \layout Standard
10186
10187 Interrupt #
10188 \end_inset
10189 </cell>
10190 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10191 \begin_inset Text
10192
10193 \layout Standard
10194
10195 Description
10196 \end_inset
10197 </cell>
10198 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10199 \begin_inset Text
10200
10201 \layout Standard
10202
10203 Vector Address
10204 \end_inset
10205 </cell>
10206 </row>
10207 <row topline="true">
10208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10209 \begin_inset Text
10210
10211 \layout Standard
10212
10213 0
10214 \end_inset
10215 </cell>
10216 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10217 \begin_inset Text
10218
10219 \layout Standard
10220
10221 External 0
10222 \end_inset
10223 </cell>
10224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10225 \begin_inset Text
10226
10227 \layout Standard
10228
10229 0x0003
10230 \end_inset
10231 </cell>
10232 </row>
10233 <row topline="true">
10234 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10235 \begin_inset Text
10236
10237 \layout Standard
10238
10239 1
10240 \end_inset
10241 </cell>
10242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10243 \begin_inset Text
10244
10245 \layout Standard
10246
10247 Timer 0
10248 \end_inset
10249 </cell>
10250 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10251 \begin_inset Text
10252
10253 \layout Standard
10254
10255 0x000B
10256 \end_inset
10257 </cell>
10258 </row>
10259 <row topline="true">
10260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10261 \begin_inset Text
10262
10263 \layout Standard
10264
10265 2
10266 \end_inset
10267 </cell>
10268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10269 \begin_inset Text
10270
10271 \layout Standard
10272
10273 External 1
10274 \end_inset
10275 </cell>
10276 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10277 \begin_inset Text
10278
10279 \layout Standard
10280
10281 0x0013
10282 \end_inset
10283 </cell>
10284 </row>
10285 <row topline="true">
10286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10287 \begin_inset Text
10288
10289 \layout Standard
10290
10291 3
10292 \end_inset
10293 </cell>
10294 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10295 \begin_inset Text
10296
10297 \layout Standard
10298
10299 Timer 1
10300 \end_inset
10301 </cell>
10302 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10303 \begin_inset Text
10304
10305 \layout Standard
10306
10307 0x001B
10308 \end_inset
10309 </cell>
10310 </row>
10311 <row topline="true">
10312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10313 \begin_inset Text
10314
10315 \layout Standard
10316
10317 4
10318 \end_inset
10319 </cell>
10320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10321 \begin_inset Text
10322
10323 \layout Standard
10324
10325 Serial
10326 \end_inset
10327 </cell>
10328 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10329 \begin_inset Text
10330
10331 \layout Standard
10332
10333 0x0023
10334 \end_inset
10335 </cell>
10336 </row>
10337 <row topline="true" bottomline="true">
10338 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10339 \begin_inset Text
10340
10341 \layout Standard
10342
10343 5
10344 \end_inset
10345 </cell>
10346 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10347 \begin_inset Text
10348
10349 \layout Standard
10350
10351 Timer 2 (8052)
10352 \end_inset
10353 </cell>
10354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10355 \begin_inset Text
10356
10357 \layout Standard
10358
10359 0x002B
10360 \end_inset
10361 </cell>
10362 </row>
10363 </lyxtabular>
10364
10365 \end_inset
10366
10367
10368 \newline
10369
10370 \layout Standard
10371
10372 If the interrupt service routine is defined without
10373 \emph on
10374 using
10375 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10376
10377 \end_inset
10378
10379
10380 \emph default
10381  a register bank or with register bank 0 (
10382 \emph on
10383 using
10384 \emph default
10385  0), the compiler will save the registers used by itself on the stack upon
10386  entry and restore them at exit, however if such an interrupt service routine
10387  calls another function then the entire register bank will be saved on the
10388  stack.
10389  This scheme may be advantageous for small interrupt service routines which
10390  have low register usage.
10391 \layout Standard
10392
10393 If the interrupt service routine is defined to be using a specific register
10394  bank then only
10395 \emph on
10396 a, b, dptr
10397 \emph default
10398  & psw are saved and restored, if such an interrupt service routine calls
10399  another function (using another register bank) then the entire register
10400  bank of the called function will be saved on the stack.
10401  This scheme is recommended for larger interrupt service routines.
10402 \layout Subsection
10403
10404 HC08 Interrupt Service Routines
10405 \layout Standard
10406
10407 Since the number of interrupts available is chip specific and the interrupt
10408  vector table always ends at the last byte of memory, the interrupt numbers
10409  corresponds to the interrupt vectors in reverse order of address.
10410  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
10411  2 will use the interrupt vector at 0xfffa, and so on.
10412  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
10413  this way; instead see section
10414 \begin_inset LatexCommand \ref{sub:Startup-Code}
10415
10416 \end_inset
10417
10418  for details on customizing startup.
10419 \layout Subsection
10420
10421 Z80 Interrupt Service Routines
10422 \layout Standard
10423
10424 The Z80 uses several different methods for determining the correct interrupt
10425  vector depending on the hardware implementation.
10426  Therefore, SDCC ignores the optional interrupt number and does not attempt
10427  to generate an interrupt vector table.
10428 \layout Standard
10429
10430 By default, SDCC generates code for a maskable interrupt, which uses an
10431  RETI instruction to return from the interrupt.
10432  To write an interrupt handler for the non-maskable interrupt, which needs
10433  an RETN instruction instead, add the
10434 \emph on
10435 critical
10436 \emph default
10437  keyword:
10438 \layout Verse
10439
10440
10441 \family typewriter
10442 void nmi_isr (void) critical interrupt
10443 \newline
10444 {
10445 \newline
10446 \SpecialChar ~
10447 \SpecialChar ~
10448 \SpecialChar ~
10449 \SpecialChar ~
10450 ...
10451
10452 \newline
10453 }
10454 \layout Section
10455
10456 Enabling and Disabling Interrupts
10457 \layout Subsection
10458
10459 Critical Functions and Critical Statements
10460 \layout Standard
10461
10462 A special keyword may be associated with a block or a function declaring
10463  it as
10464 \emph on
10465 critical
10466 \emph default
10467 .
10468  SDCC will generate code to disable all interrupts
10469 \begin_inset LatexCommand \index{interrupt}
10470
10471 \end_inset
10472
10473  upon entry to a critical function and restore the interrupt enable to the
10474  previous state before returning.
10475  Nesting critical functions will need one additional byte on the stack
10476 \begin_inset LatexCommand \index{stack}
10477
10478 \end_inset
10479
10480  for each call.
10481 \layout Verse
10482
10483
10484 \family typewriter
10485 int foo () critical
10486 \begin_inset LatexCommand \index{critical}
10487
10488 \end_inset
10489
10490
10491 \newline
10492 {
10493 \newline
10494 \SpecialChar ~
10495 \SpecialChar ~
10496 \SpecialChar ~
10497 \SpecialChar ~
10498 ...
10499
10500 \newline
10501 \SpecialChar ~
10502 \SpecialChar ~
10503 \SpecialChar ~
10504 \SpecialChar ~
10505 ...
10506
10507 \newline
10508 }
10509 \layout Standard
10510
10511 The critical attribute maybe used with other attributes like
10512 \emph on
10513 reentrant.
10514 \emph default
10515
10516 \newline
10517 The keyword
10518 \emph on
10519 critical
10520 \emph default
10521  may also be used to disable interrupts more locally:
10522 \layout Verse
10523
10524
10525 \family typewriter
10526 critical{ i++; }
10527 \layout Standard
10528
10529 More than one statement could have been included in the block.
10530 \layout Subsection
10531
10532 Enabling and Disabling Interrupts directly
10533 \layout Standard
10534
10535 Interrupts
10536 \begin_inset LatexCommand \index{interrupt}
10537
10538 \end_inset
10539
10540  can also be disabled and enabled directly (8051):
10541 \layout Verse
10542
10543
10544 \family typewriter
10545 EA = 0;\SpecialChar ~
10546 \SpecialChar ~
10547 \SpecialChar ~
10548 \SpecialChar ~
10549 \SpecialChar ~
10550 \SpecialChar ~
10551 \SpecialChar ~
10552 \SpecialChar ~
10553 \SpecialChar ~
10554 \SpecialChar ~
10555 \SpecialChar ~
10556 \SpecialChar ~
10557 or:\SpecialChar ~
10558 \SpecialChar ~
10559 \SpecialChar ~
10560 \SpecialChar ~
10561 \SpecialChar ~
10562 \SpecialChar ~
10563 \SpecialChar ~
10564 \SpecialChar ~
10565 \SpecialChar ~
10566 \SpecialChar ~
10567 \SpecialChar ~
10568 EA_SAVE = EA;
10569 \layout Verse
10570
10571
10572 \family typewriter
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 \SpecialChar ~
10587 \SpecialChar ~
10588 \SpecialChar ~
10589 \SpecialChar ~
10590 \SpecialChar ~
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 EA = 0;
10604 \layout Verse
10605
10606
10607 \family typewriter
10608 EA = 1;\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 \SpecialChar ~
10625 \SpecialChar ~
10626 \SpecialChar ~
10627 \SpecialChar ~
10628 \SpecialChar ~
10629 \SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632 \SpecialChar ~
10633 \SpecialChar ~
10634 ...
10635 \layout Verse
10636
10637
10638 \family typewriter
10639 \SpecialChar ~
10640 \SpecialChar ~
10641 \SpecialChar ~
10642 \SpecialChar ~
10643 \SpecialChar ~
10644 \SpecialChar ~
10645 \SpecialChar ~
10646 \SpecialChar ~
10647 \SpecialChar ~
10648 \SpecialChar ~
10649 \SpecialChar ~
10650 \SpecialChar ~
10651 \SpecialChar ~
10652 \SpecialChar ~
10653 \SpecialChar ~
10654 \SpecialChar ~
10655 \SpecialChar ~
10656 \SpecialChar ~
10657 \SpecialChar ~
10658 \SpecialChar ~
10659 \SpecialChar ~
10660 \SpecialChar ~
10661 \SpecialChar ~
10662 \SpecialChar ~
10663 \SpecialChar ~
10664 \SpecialChar ~
10665 \SpecialChar ~
10666 \SpecialChar ~
10667 \SpecialChar ~
10668 \SpecialChar ~
10669 \SpecialChar ~
10670 \SpecialChar ~
10671 \SpecialChar ~
10672 EA = EA_SAVE;
10673 \layout Standard
10674
10675 On other architectures which have seperate opcodes for enabling and disabling
10676  interrupts you might want to make use of defines with inline assembly
10677 \begin_inset LatexCommand \index{Assembler routines}
10678
10679 \end_inset
10680
10681  (HC08):
10682 \layout Verse
10683
10684
10685 \family typewriter
10686 #define CLI _asm
10687 \begin_inset LatexCommand \index{\_asm}
10688
10689 \end_inset
10690
10691 \SpecialChar ~
10692 \SpecialChar ~
10693 cli\SpecialChar ~
10694 \SpecialChar ~
10695 _endasm
10696 \begin_inset LatexCommand \index{\_endasm}
10697
10698 \end_inset
10699
10700 ;
10701 \layout Verse
10702
10703
10704 \family typewriter
10705 #define SEI _asm\SpecialChar ~
10706 \SpecialChar ~
10707 sei\SpecialChar ~
10708 \SpecialChar ~
10709 _endasm;
10710 \layout Verse
10711
10712
10713 \family typewriter
10714 ...
10715 \layout Standard
10716
10717 Note: it is sometimes sufficient to disable only a specific interrupt source
10718  like f.e.
10719  a timer or serial interrupt by manipulating an
10720 \emph on
10721 interrupt mask
10722 \begin_inset LatexCommand \index{interrupt mask}
10723
10724 \end_inset
10725
10726
10727 \emph default
10728  register.
10729
10730 \layout Standard
10731
10732 Usually the time during which interrupts are disabled should be kept as
10733  short as possible.
10734  This minimizes both
10735 \emph on
10736 interrupt latency
10737 \emph default
10738
10739 \begin_inset LatexCommand \index{interrupt latency}
10740
10741 \end_inset
10742
10743  (the time between the occurrence of the interrupt and the execution of
10744  the first code in the interrupt routine) and
10745 \emph on
10746 interrupt jitter
10747 \emph default
10748
10749 \begin_inset LatexCommand \index{interrupt jitter}
10750
10751 \end_inset
10752
10753  (the difference between the shortest and the longest interrupt latency).
10754  These really are something different, f.e.
10755  a serial interrupt has to be served before its buffer overruns so it cares
10756  for the maximum interrupt latency, whereas it does not care about jitter.
10757  On a loudspeaker driven via a digital to analog converter which is fed
10758  by an interrupt a latency of a few milliseconds might be tolerable, whereas
10759  a much smaller jitter will be very audible.
10760 \layout Standard
10761
10762 You can reenable interrupts within an interrupt routine and on some architecture
10763 s you can make use of two (or more) levels of
10764 \emph on
10765 interrupt priorities
10766 \emph default
10767
10768 \begin_inset LatexCommand \index{interrupt priority}
10769
10770 \end_inset
10771
10772 .
10773  On some architectures which don't support interrupt priorities these can
10774  be implemented by manipulating the interrupt mask and reenabling interrupts
10775  within the interrupt routine.
10776  Check there is sufficient space on the stack
10777 \begin_inset LatexCommand \index{stack}
10778
10779 \end_inset
10780
10781  and don't add complexity unless you have to.
10782
10783 \layout Subsection
10784
10785 Semaphore
10786 \begin_inset LatexCommand \index{semaphore}
10787
10788 \end_inset
10789
10790  locking (mcs51/ds390)
10791 \layout Standard
10792
10793 Some architectures (mcs51/ds390) have an atomic
10794 \begin_inset LatexCommand \index{atomic}
10795
10796 \end_inset
10797
10798  bit test and
10799 \emph on
10800
10801 \emph default
10802 clear
10803 \emph on
10804
10805 \emph default
10806 instruction.
10807  These type of instructions are typically used in preemptive multitasking
10808  systems, where a routine f.e.
10809  claims the use of a data structure ('acquires a lock
10810 \begin_inset LatexCommand \index{lock}
10811
10812 \end_inset
10813
10814  on it'), makes some modifications and then releases the lock when the data
10815  structure is consistent again.
10816  The instruction may also be used if interrupt and non-interrupt code have
10817  to compete for a resource.
10818  With the atomic bit test and clear instruction interrupts
10819 \begin_inset LatexCommand \index{interrupt}
10820
10821 \end_inset
10822
10823  don't have to be disabled for the locking operation.
10824
10825 \layout Standard
10826
10827 SDCC generates this instruction if the source follows this pattern:
10828 \layout Verse
10829
10830
10831 \family typewriter
10832 volatile bit resource_is_free;
10833 \newline
10834
10835 \newline
10836 if (resource_is_free)
10837 \newline
10838 \SpecialChar ~
10839 \SpecialChar ~
10840 {
10841 \newline
10842 \SpecialChar ~
10843 \SpecialChar ~
10844 \SpecialChar ~
10845 \SpecialChar ~
10846 resource_is_free=0;
10847 \newline
10848 \SpecialChar ~
10849 \SpecialChar ~
10850 \SpecialChar ~
10851 \SpecialChar ~
10852 ...
10853
10854 \newline
10855 \SpecialChar ~
10856 \SpecialChar ~
10857 \SpecialChar ~
10858 \SpecialChar ~
10859 resource_is_free=1;
10860 \newline
10861 \SpecialChar ~
10862 \SpecialChar ~
10863 }
10864 \layout Standard
10865
10866 Note, mcs51 and ds390 support only an atomic
10867 \begin_inset LatexCommand \index{atomic}
10868
10869 \end_inset
10870
10871  bit test and
10872 \emph on
10873 clear
10874 \emph default
10875  instruction (as opposed to atomic bit test and
10876 \emph on
10877 set).
10878 \layout Section
10879
10880 Functions using private register banks
10881 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
10882
10883 \end_inset
10884
10885  (mcs51/ds390)
10886 \layout Standard
10887
10888 Some architectures have support for quickly changing register sets.
10889  SDCC supports this feature with the
10890 \emph on
10891 using
10892 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10893
10894 \end_inset
10895
10896
10897 \emph default
10898  attribute (which tells the compiler to use a register bank
10899 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10900
10901 \end_inset
10902
10903  other than the default bank zero).
10904  It should only be applied to
10905 \emph on
10906 interrupt
10907 \begin_inset LatexCommand \index{interrupt}
10908
10909 \end_inset
10910
10911
10912 \emph default
10913  functions (see footnote below).
10914  This will in most circumstances make the generated ISR code more efficient
10915  since it will not have to save registers on the stack.
10916 \layout Standard
10917
10918 The
10919 \emph on
10920 using
10921 \emph default
10922  attribute will have no effect on the generated code for a
10923 \emph on
10924 non-interrupt
10925 \emph default
10926  function (but may occasionally be useful anyway
10927 \begin_inset Foot
10928 collapsed false
10929
10930 \layout Standard
10931
10932 possible exception: if a function is called ONLY from 'interrupt' functions
10933  using a particular bank, it can be declared with the same 'using' attribute
10934  as the calling 'interrupt' functions.
10935  For instance, if you have several ISRs using bank one, and all of them
10936  call memcpy(), it might make sense to create a specialized version of memcpy()
10937  'using 1', since this would prevent the ISR from having to save bank zero
10938  to the stack on entry and switch to bank zero before calling the function
10939 \end_inset
10940
10941 ).
10942 \newline
10943
10944 \emph on
10945 (pending: I don't think this has been done yet)
10946 \layout Standard
10947
10948 An
10949 \emph on
10950 interrupt
10951 \emph default
10952  function using a non-zero bank will assume that it can trash that register
10953  bank, and will not save it.
10954  Since high-priority interrupts
10955 \begin_inset LatexCommand \index{interrupt priority}
10956
10957 \end_inset
10958
10959  can interrupt low-priority ones on the 8051 and friends, this means that
10960  if a high-priority ISR
10961 \emph on
10962 using
10963 \emph default
10964  a particular bank occurs while processing a low-priority ISR
10965 \emph on
10966 using
10967 \emph default
10968  the same bank, terrible and bad things can happen.
10969  To prevent this, no single register bank should be
10970 \emph on
10971 used
10972 \emph default
10973  by both a high priority and a low priority ISR.
10974  This is probably most easily done by having all high priority ISRs use
10975  one bank and all low priority ISRs use another.
10976  If you have an ISR which can change priority at runtime, you're on your
10977  own: I suggest using the default bank zero and taking the small performance
10978  hit.
10979 \layout Standard
10980
10981 It is most efficient if your ISR calls no other functions.
10982  If your ISR must call other functions, it is most efficient if those functions
10983  use the same bank as the ISR (see note 1 below); the next best is if the
10984  called functions use bank zero.
10985  It is very inefficient to call a function using a different, non-zero bank
10986  from an ISR.
10987
10988 \layout Section
10989
10990 Startup Code
10991 \begin_inset LatexCommand \label{sub:Startup-Code}
10992
10993 \end_inset
10994
10995
10996 \begin_inset LatexCommand \index{Startup code}
10997
10998 \end_inset
10999
11000
11001 \layout Subsection
11002
11003 MCS51/DS390 Startup Code
11004 \layout Standard
11005
11006 The compiler inserts a call to the C routine
11007 \emph on
11008 _sdcc_external_startup()
11009 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11010
11011 \end_inset
11012
11013
11014 \series bold
11015 \emph default
11016
11017 \series default
11018 at the start of the CODE area.
11019  This routine is in the runtime library
11020 \begin_inset LatexCommand \index{Runtime library}
11021
11022 \end_inset
11023
11024 .
11025  By default this routine returns 0, if this routine returns a non-zero value,
11026  the static & global variable initialization will be skipped and the function
11027  main will be invoked.
11028  Otherwise static & global variables will be initialized before the function
11029  main is invoked.
11030  You could add a
11031 \emph on
11032 _sdcc_external_startup()
11033 \emph default
11034  routine to your program to override the default if you need to setup hardware
11035  or perform some other critical operation prior to static & global variable
11036  initialization.
11037  On some mcs51 variants xdata has to be explicitly enabled before it can
11038  be accessed, this is the place to do it.
11039  The startup code clears the complete 256 byte of idata memory, this might
11040  cause problems for 128 byte devices (endless loop reported for Chipcon
11041  CC1010).
11042 \layout Standard
11043
11044 See also the compiler option
11045 \emph on
11046 -
11047 \begin_inset ERT
11048 status Collapsed
11049
11050 \layout Standard
11051
11052 \backslash
11053 /
11054 \end_inset
11055
11056 -no-xinit
11057 \emph default
11058 -
11059 \emph on
11060 opt
11061 \emph default
11062
11063 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11064
11065 \end_inset
11066
11067  and section
11068 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11069
11070 \end_inset
11071
11072 \SpecialChar ~
11073 about MCS51-variants.
11074 \layout Subsection
11075
11076 HC08 Startup Code
11077 \layout Standard
11078
11079 The HC08 startup code follows the same scheme as the MCS51 startup code.
11080 \layout Subsection
11081
11082 Z80 Startup Code
11083 \layout Standard
11084
11085 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11086  from sdcc/device/lib/z80/crt0.s.
11087  If you need a different startup code you can use the compiler option
11088 \emph on
11089 -
11090 \series bold
11091 \emph default
11092
11093 \begin_inset ERT
11094 status Collapsed
11095
11096 \layout Standard
11097
11098 \backslash
11099 /
11100 \end_inset
11101
11102
11103 \series default
11104 \emph on
11105 -no-std-crt0
11106 \emph default
11107
11108 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11109
11110 \end_inset
11111
11112  and provide your own crt0.o.
11113
11114 \layout Section
11115
11116 Inline Assembler Code
11117 \begin_inset LatexCommand \index{Assembler routines}
11118
11119 \end_inset
11120
11121
11122 \layout Subsection
11123
11124 A Step by Step Introduction
11125 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11126
11127 \end_inset
11128
11129
11130 \layout Standard
11131
11132 Starting from a small snippet of c-code this example shows for the MCS51
11133  how to use inline assembly, access variables, a function parameter and
11134  an array in xdata memory.
11135  The example uses an MCS51 here but is easily adapted for other architectures.
11136  This is a buffer routine which should be optimized:
11137 \layout Verse
11138
11139
11140 \family typewriter
11141 \size footnotesize
11142 unsigned char far
11143 \begin_inset LatexCommand \index{far (storage class)}
11144
11145 \end_inset
11146
11147  at
11148 \begin_inset LatexCommand \index{at}
11149
11150 \end_inset
11151
11152  0x7f00 buf[0x100];
11153 \begin_inset LatexCommand \index{Aligned array}
11154
11155 \end_inset
11156
11157
11158 \newline
11159 unsigned char head,tail;
11160 \newline
11161
11162 \newline
11163 void to_buffer( unsigned char c )
11164 \newline
11165 {
11166 \newline
11167 \SpecialChar ~
11168 \SpecialChar ~
11169 \SpecialChar ~
11170 \SpecialChar ~
11171 if( head != tail-1 )
11172 \newline
11173 \SpecialChar ~
11174 \SpecialChar ~
11175 \SpecialChar ~
11176 \SpecialChar ~
11177 \SpecialChar ~
11178 \SpecialChar ~
11179 \SpecialChar ~
11180 \SpecialChar ~
11181 buf[ head++ ] = c;\SpecialChar ~
11182 \SpecialChar ~
11183 \SpecialChar ~
11184 \SpecialChar ~
11185 /* access to a 256 byte aligned array */
11186 \newline
11187 }
11188 \layout Standard
11189
11190 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
11191  then a corresponding buffer.asm file is generated.
11192  We define a new function
11193 \family typewriter
11194 to_buffer_asm()
11195 \family default
11196  in file buffer.c in which we cut and paste the generated code, removing
11197  unwanted comments and some ':'.
11198  Then add
11199 \begin_inset Quotes sld
11200 \end_inset
11201
11202 _asm
11203 \begin_inset Quotes srd
11204 \end_inset
11205
11206  and
11207 \begin_inset Quotes sld
11208 \end_inset
11209
11210 _endasm;
11211 \begin_inset Quotes srd
11212 \end_inset
11213
11214  to the beginning and the end of the function body:
11215 \layout Verse
11216
11217
11218 \family typewriter
11219 \size footnotesize
11220 /* With a cut and paste from the .asm file, we have something to start with.
11221 \newline
11222 \SpecialChar ~
11223 \SpecialChar ~
11224 \SpecialChar ~
11225 The function is not yet OK! (registers aren't saved) */
11226 \newline
11227 void to_buffer_asm( unsigned char c )
11228 \newline
11229 {
11230 \newline
11231 \SpecialChar ~
11232 \SpecialChar ~
11233 \SpecialChar ~
11234 \SpecialChar ~
11235 _asm
11236 \begin_inset LatexCommand \index{\_asm}
11237
11238 \end_inset
11239
11240
11241 \newline
11242 \SpecialChar ~
11243 \SpecialChar ~
11244 \SpecialChar ~
11245 \SpecialChar ~
11246 mov\SpecialChar ~
11247 \SpecialChar ~
11248 r2,dpl
11249 \newline
11250 ;buffer.c if( head != tail-1 )
11251 \newline
11252 \SpecialChar ~
11253 \SpecialChar ~
11254 \SpecialChar ~
11255 \SpecialChar ~
11256 mov\SpecialChar ~
11257 \SpecialChar ~
11258 a,_tail
11259 \newline
11260 \SpecialChar ~
11261 \SpecialChar ~
11262 \SpecialChar ~
11263 \SpecialChar ~
11264 dec\SpecialChar ~
11265 \SpecialChar ~
11266 a
11267 \newline
11268 \SpecialChar ~
11269 \SpecialChar ~
11270 \SpecialChar ~
11271 \SpecialChar ~
11272 mov\SpecialChar ~
11273 \SpecialChar ~
11274 r3,a
11275 \newline
11276 \SpecialChar ~
11277 \SpecialChar ~
11278 \SpecialChar ~
11279 \SpecialChar ~
11280 mov\SpecialChar ~
11281 \SpecialChar ~
11282 a,_head
11283 \newline
11284 \SpecialChar ~
11285 \SpecialChar ~
11286 \SpecialChar ~
11287 \SpecialChar ~
11288 cjne a,ar3,00106$
11289 \newline
11290 \SpecialChar ~
11291 \SpecialChar ~
11292 \SpecialChar ~
11293 \SpecialChar ~
11294 ret
11295 \newline
11296 00106$:
11297 \newline
11298 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
11299 \begin_inset LatexCommand \index{Aligned array}
11300
11301 \end_inset
11302
11303
11304 \newline
11305 \SpecialChar ~
11306 \SpecialChar ~
11307 \SpecialChar ~
11308 \SpecialChar ~
11309 mov\SpecialChar ~
11310 \SpecialChar ~
11311 r3,_head
11312 \newline
11313 \SpecialChar ~
11314 \SpecialChar ~
11315 \SpecialChar ~
11316 \SpecialChar ~
11317 inc\SpecialChar ~
11318 \SpecialChar ~
11319 _head
11320 \newline
11321 \SpecialChar ~
11322 \SpecialChar ~
11323 \SpecialChar ~
11324 \SpecialChar ~
11325 mov\SpecialChar ~
11326 \SpecialChar ~
11327 dpl,r3
11328 \newline
11329 \SpecialChar ~
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 mov\SpecialChar ~
11334 \SpecialChar ~
11335 dph,#(_buf >> 8)
11336 \newline
11337 \SpecialChar ~
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 \SpecialChar ~
11341 mov\SpecialChar ~
11342 \SpecialChar ~
11343 a,r2
11344 \newline
11345 \SpecialChar ~
11346 \SpecialChar ~
11347 \SpecialChar ~
11348 \SpecialChar ~
11349 movx @dptr,a
11350 \newline
11351 00103$:
11352 \newline
11353 \SpecialChar ~
11354 \SpecialChar ~
11355 \SpecialChar ~
11356 \SpecialChar ~
11357 ret
11358 \newline
11359 \SpecialChar ~
11360 \SpecialChar ~
11361 \SpecialChar ~
11362 \SpecialChar ~
11363 _endasm;
11364 \newline
11365 }
11366 \layout Standard
11367
11368 The new file buffer.c should compile with only one warning about the unreferenced
11369  function argument 'c'.
11370  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
11371  (1) and finally have:
11372 \layout Verse
11373
11374
11375 \family typewriter
11376 \size footnotesize
11377 unsigned char far at 0x7f00 buf[0x100];
11378 \newline
11379 unsigned char head,tail;
11380 \newline
11381 #define USE_ASSEMBLY (1)
11382 \newline
11383
11384 \newline
11385 #if !USE_ASSEMBLY
11386 \newline
11387
11388 \newline
11389 void to_buffer( unsigned char c )
11390 \newline
11391 {
11392 \newline
11393 \SpecialChar ~
11394 \SpecialChar ~
11395 \SpecialChar ~
11396 \SpecialChar ~
11397 if( head != tail-1 )
11398 \newline
11399 \SpecialChar ~
11400 \SpecialChar ~
11401 \SpecialChar ~
11402 \SpecialChar ~
11403 \SpecialChar ~
11404 \SpecialChar ~
11405 \SpecialChar ~
11406 \SpecialChar ~
11407 buf[ head++ ] = c;
11408 \newline
11409 }
11410 \newline
11411
11412 \newline
11413 #else
11414 \newline
11415
11416 \newline
11417 void to_buffer( unsigned char c )
11418 \newline
11419 {
11420 \newline
11421 \SpecialChar ~
11422 \SpecialChar ~
11423 \SpecialChar ~
11424 \SpecialChar ~
11425 c; // to avoid warning: unreferenced function argument
11426 \newline
11427 \SpecialChar ~
11428 \SpecialChar ~
11429 \SpecialChar ~
11430 \SpecialChar ~
11431 _asm
11432 \begin_inset LatexCommand \index{\_asm}
11433
11434 \end_inset
11435
11436
11437 \newline
11438 \SpecialChar ~
11439 \SpecialChar ~
11440 \SpecialChar ~
11441 \SpecialChar ~
11442 \SpecialChar ~
11443 \SpecialChar ~
11444 \SpecialChar ~
11445 \SpecialChar ~
11446 ; save used registers here.
11447
11448 \newline
11449 \SpecialChar ~
11450 \SpecialChar ~
11451 \SpecialChar ~
11452 \SpecialChar ~
11453 \SpecialChar ~
11454 \SpecialChar ~
11455 \SpecialChar ~
11456 \SpecialChar ~
11457 ; If we were still using r2,r3 we would have to push them here.
11458
11459 \newline
11460 ; if( head != tail-1 )
11461 \newline
11462 \SpecialChar ~
11463 \SpecialChar ~
11464 \SpecialChar ~
11465 \SpecialChar ~
11466 \SpecialChar ~
11467 \SpecialChar ~
11468 \SpecialChar ~
11469 \SpecialChar ~
11470 mov\SpecialChar ~
11471  a,_tail
11472 \newline
11473 \SpecialChar ~
11474 \SpecialChar ~
11475 \SpecialChar ~
11476 \SpecialChar ~
11477 \SpecialChar ~
11478 \SpecialChar ~
11479 \SpecialChar ~
11480 \SpecialChar ~
11481 dec\SpecialChar ~
11482  a
11483 \newline
11484 \SpecialChar ~
11485 \SpecialChar ~
11486 \SpecialChar ~
11487 \SpecialChar ~
11488 \SpecialChar ~
11489 \SpecialChar ~
11490 \SpecialChar ~
11491 \SpecialChar ~
11492 xrl\SpecialChar ~
11493  a,_head
11494 \newline
11495 \SpecialChar ~
11496 \SpecialChar ~
11497 \SpecialChar ~
11498 \SpecialChar ~
11499 \SpecialChar ~
11500 \SpecialChar ~
11501 \SpecialChar ~
11502 \SpecialChar ~
11503 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
11504 \newline
11505 \SpecialChar ~
11506 \SpecialChar ~
11507 \SpecialChar ~
11508 \SpecialChar ~
11509 \SpecialChar ~
11510 \SpecialChar ~
11511 \SpecialChar ~
11512 \SpecialChar ~
11513 jz\SpecialChar ~
11514 \SpecialChar ~
11515  t_b_end$
11516 \newline
11517 \SpecialChar ~
11518 \SpecialChar ~
11519 \SpecialChar ~
11520 \SpecialChar ~
11521 \SpecialChar ~
11522 \SpecialChar ~
11523 \SpecialChar ~
11524 \SpecialChar ~
11525 ;
11526 \newline
11527 ; buf[ head++ ] = c;
11528 \newline
11529 \SpecialChar ~
11530 \SpecialChar ~
11531 \SpecialChar ~
11532 \SpecialChar ~
11533 \SpecialChar ~
11534 \SpecialChar ~
11535 \SpecialChar ~
11536 \SpecialChar ~
11537 mov\SpecialChar ~
11538  a,dpl \SpecialChar ~
11539 \SpecialChar ~
11540 \SpecialChar ~
11541 \SpecialChar ~
11542 \SpecialChar ~
11543 \SpecialChar ~
11544 \SpecialChar ~
11545 ; dpl holds lower byte of function argument
11546 \newline
11547 \SpecialChar ~
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 \SpecialChar ~
11551 \SpecialChar ~
11552 \SpecialChar ~
11553 \SpecialChar ~
11554 \SpecialChar ~
11555 mov\SpecialChar ~
11556  dpl,_head \SpecialChar ~
11557 \SpecialChar ~
11558 \SpecialChar ~
11559 ; buf is 0x100 byte aligned so head can be used directly
11560 \newline
11561 \SpecialChar ~
11562 \SpecialChar ~
11563 \SpecialChar ~
11564 \SpecialChar ~
11565 \SpecialChar ~
11566 \SpecialChar ~
11567 \SpecialChar ~
11568 \SpecialChar ~
11569 mov\SpecialChar ~
11570  dph,#(_buf>>8)
11571 \newline
11572 \SpecialChar ~
11573 \SpecialChar ~
11574 \SpecialChar ~
11575 \SpecialChar ~
11576 \SpecialChar ~
11577 \SpecialChar ~
11578 \SpecialChar ~
11579 \SpecialChar ~
11580 movx @dptr,a
11581 \newline
11582 \SpecialChar ~
11583 \SpecialChar ~
11584 \SpecialChar ~
11585 \SpecialChar ~
11586 \SpecialChar ~
11587 \SpecialChar ~
11588 \SpecialChar ~
11589 \SpecialChar ~
11590 inc \SpecialChar ~
11591 _head
11592 \newline
11593 \SpecialChar ~
11594 \SpecialChar ~
11595 \SpecialChar ~
11596 \SpecialChar ~
11597 \SpecialChar ~
11598 \SpecialChar ~
11599 \SpecialChar ~
11600 \SpecialChar ~
11601 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
11602 \newline
11603 t_b_end$:
11604 \newline
11605 \SpecialChar ~
11606 \SpecialChar ~
11607 \SpecialChar ~
11608 \SpecialChar ~
11609 \SpecialChar ~
11610 \SpecialChar ~
11611 \SpecialChar ~
11612 \SpecialChar ~
11613 ; restore used registers here
11614 \newline
11615 \SpecialChar ~
11616 \SpecialChar ~
11617 \SpecialChar ~
11618 \SpecialChar ~
11619 _endasm;
11620 \newline
11621 }
11622 \newline
11623 #endif
11624 \layout Standard
11625
11626 The inline assembler code can contain any valid code understood by the assembler
11627 , this includes any assembler directives and comment lines
11628 \begin_inset Foot
11629 collapsed false
11630
11631 \layout Standard
11632
11633 The assembler does not like some characters like ':' or ''' in comments.
11634  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
11635 \end_inset
11636
11637 .
11638  The compiler does not do any validation of the code within the
11639 \family typewriter
11640 _asm
11641 \begin_inset LatexCommand \index{\_asm}
11642
11643 \end_inset
11644
11645  ...
11646  _endasm;
11647 \family default
11648  keyword pair.
11649  Specifically it will not know which registers are used and thus register
11650  pushing/popping
11651 \begin_inset LatexCommand \index{push/pop}
11652
11653 \end_inset
11654
11655  has to be done manually.
11656
11657 \layout Standard
11658
11659 It is recommended that each assembly instruction (including labels) be placed
11660  in a separate line (as the example shows).
11661  When the -
11662 \begin_inset ERT
11663 status Collapsed
11664
11665 \layout Standard
11666
11667 \backslash
11668 /
11669 \end_inset
11670
11671 -
11672 \emph on
11673 peep-asm
11674 \begin_inset LatexCommand \index{-\/-peep-asm}
11675
11676 \end_inset
11677
11678
11679 \emph default
11680  command line option is used, the inline assembler code will be passed through
11681  the peephole optimizer
11682 \begin_inset LatexCommand \index{Peephole optimizer}
11683
11684 \end_inset
11685
11686 .
11687  There are only a few (if any) cases where this option makes sense, it might
11688  cause some unexpected changes in the inline assembler code.
11689  Please go through the peephole optimizer rules defined in file
11690 \emph on
11691 SDCCpeeph.def
11692 \emph default
11693  before using this option.
11694 \layout Subsection
11695
11696 Naked Functions
11697 \begin_inset LatexCommand \label{sub:Naked-Functions}
11698
11699 \end_inset
11700
11701
11702 \begin_inset LatexCommand \index{Naked functions}
11703
11704 \end_inset
11705
11706
11707 \layout Standard
11708
11709 A special keyword may be associated with a function declaring it as
11710 \emph on
11711 _naked
11712 \begin_inset LatexCommand \index{\_naked}
11713
11714 \end_inset
11715
11716 .
11717
11718 \emph default
11719 The
11720 \emph on
11721 _naked
11722 \emph default
11723  function modifier attribute prevents the compiler from generating prologue
11724 \begin_inset LatexCommand \index{function prologue}
11725
11726 \end_inset
11727
11728  and epilogue
11729 \begin_inset LatexCommand \index{function epilogue}
11730
11731 \end_inset
11732
11733  code for that function.
11734  This means that the user is entirely responsible for such things as saving
11735  any registers that may need to be preserved, selecting the proper register
11736  bank, generating the
11737 \emph on
11738 return
11739 \emph default
11740  instruction at the end, etc.
11741  Practically, this means that the contents of the function must be written
11742  in inline assembler.
11743  This is particularly useful for interrupt functions, which can have a large
11744  (and often unnecessary) prologue/epilogue.
11745  For example, compare the code generated by these two functions:
11746 \layout Verse
11747
11748
11749 \family typewriter
11750 volatile
11751 \begin_inset LatexCommand \index{volatile}
11752
11753 \end_inset
11754
11755  data unsigned char counter;
11756 \newline
11757
11758 \newline
11759 void simpleInterrupt(void) interrupt
11760 \begin_inset LatexCommand \index{interrupt}
11761
11762 \end_inset
11763
11764  1
11765 \newline
11766 {
11767 \newline
11768 \SpecialChar ~
11769 \SpecialChar ~
11770 \SpecialChar ~
11771 \SpecialChar ~
11772 counter++;
11773 \newline
11774 }
11775 \newline
11776
11777 \newline
11778 void nakedInterrupt(void) interrupt 2 _naked
11779 \newline
11780 {
11781 \newline
11782 \SpecialChar ~
11783 \SpecialChar ~
11784 \SpecialChar ~
11785 \SpecialChar ~
11786 _asm
11787 \begin_inset LatexCommand \index{\_asm}
11788
11789 \end_inset
11790
11791
11792 \newline
11793 \SpecialChar ~
11794 \SpecialChar ~
11795 \SpecialChar ~
11796 \SpecialChar ~
11797 \SpecialChar ~
11798 \SpecialChar ~
11799 inc\SpecialChar ~
11800 \SpecialChar ~
11801 \SpecialChar ~
11802 \SpecialChar ~
11803 \SpecialChar ~
11804 _counter ; does not change flags, no need to save psw
11805 \newline
11806 \SpecialChar ~
11807 \SpecialChar ~
11808 \SpecialChar ~
11809 \SpecialChar ~
11810 \SpecialChar ~
11811 \SpecialChar ~
11812 reti\SpecialChar ~
11813 \SpecialChar ~
11814 \SpecialChar ~
11815 \SpecialChar ~
11816 ; MUST explicitly include ret or reti in _naked function.
11817 \newline
11818 \SpecialChar ~
11819 \SpecialChar ~
11820 \SpecialChar ~
11821 \SpecialChar ~
11822 _endasm
11823 \begin_inset LatexCommand \index{\_endasm}
11824
11825 \end_inset
11826
11827 ;
11828 \newline
11829 }
11830 \layout Standard
11831
11832 For an 8051 target, the generated simpleInterrupt looks like:
11833 \layout Verse
11834
11835
11836 \family typewriter
11837 _simpleInterrupt:
11838 \newline
11839 \SpecialChar ~
11840 \SpecialChar ~
11841 \SpecialChar ~
11842 \SpecialChar ~
11843 push\SpecialChar ~
11844 \SpecialChar ~
11845 \SpecialChar ~
11846 \SpecialChar ~
11847 acc
11848 \newline
11849 \SpecialChar ~
11850 \SpecialChar ~
11851 \SpecialChar ~
11852 \SpecialChar ~
11853 push\SpecialChar ~
11854 \SpecialChar ~
11855 \SpecialChar ~
11856 \SpecialChar ~
11857 b
11858 \newline
11859 \SpecialChar ~
11860 \SpecialChar ~
11861 \SpecialChar ~
11862 \SpecialChar ~
11863 push\SpecialChar ~
11864 \SpecialChar ~
11865 \SpecialChar ~
11866 \SpecialChar ~
11867 dpl
11868 \newline
11869 \SpecialChar ~
11870 \SpecialChar ~
11871 \SpecialChar ~
11872 \SpecialChar ~
11873 push\SpecialChar ~
11874 \SpecialChar ~
11875 \SpecialChar ~
11876 \SpecialChar ~
11877 dph
11878 \newline
11879 \SpecialChar ~
11880 \SpecialChar ~
11881 \SpecialChar ~
11882 \SpecialChar ~
11883 push\SpecialChar ~
11884 \SpecialChar ~
11885 \SpecialChar ~
11886 \SpecialChar ~
11887 psw
11888 \newline
11889 \SpecialChar ~
11890 \SpecialChar ~
11891 \SpecialChar ~
11892 \SpecialChar ~
11893 mov\SpecialChar ~
11894 \SpecialChar ~
11895 \SpecialChar ~
11896 \SpecialChar ~
11897 \SpecialChar ~
11898 psw,#0x00
11899 \newline
11900 \SpecialChar ~
11901 \SpecialChar ~
11902 \SpecialChar ~
11903 \SpecialChar ~
11904 inc\SpecialChar ~
11905 \SpecialChar ~
11906 \SpecialChar ~
11907 \SpecialChar ~
11908 \SpecialChar ~
11909 _counter
11910 \newline
11911 \SpecialChar ~
11912 \SpecialChar ~
11913 \SpecialChar ~
11914 \SpecialChar ~
11915 pop\SpecialChar ~
11916 \SpecialChar ~
11917 \SpecialChar ~
11918 \SpecialChar ~
11919 \SpecialChar ~
11920 psw
11921 \newline
11922 \SpecialChar ~
11923 \SpecialChar ~
11924 \SpecialChar ~
11925 \SpecialChar ~
11926 pop\SpecialChar ~
11927 \SpecialChar ~
11928 \SpecialChar ~
11929 \SpecialChar ~
11930 \SpecialChar ~
11931 dph
11932 \newline
11933 \SpecialChar ~
11934 \SpecialChar ~
11935 \SpecialChar ~
11936 \SpecialChar ~
11937 pop\SpecialChar ~
11938 \SpecialChar ~
11939 \SpecialChar ~
11940 \SpecialChar ~
11941 \SpecialChar ~
11942 dpl
11943 \newline
11944 \SpecialChar ~
11945 \SpecialChar ~
11946 \SpecialChar ~
11947 \SpecialChar ~
11948 pop\SpecialChar ~
11949 \SpecialChar ~
11950 \SpecialChar ~
11951 \SpecialChar ~
11952 \SpecialChar ~
11953 b
11954 \newline
11955 \SpecialChar ~
11956 \SpecialChar ~
11957 \SpecialChar ~
11958 \SpecialChar ~
11959 pop\SpecialChar ~
11960 \SpecialChar ~
11961 \SpecialChar ~
11962 \SpecialChar ~
11963 \SpecialChar ~
11964 acc
11965 \newline
11966 \SpecialChar ~
11967 \SpecialChar ~
11968 \SpecialChar ~
11969 \SpecialChar ~
11970 reti
11971 \layout Standard
11972
11973 whereas nakedInterrupt looks like:
11974 \layout Verse
11975
11976
11977 \family typewriter
11978 _nakedInterrupt:
11979 \newline
11980 \SpecialChar ~
11981 \SpecialChar ~
11982 \SpecialChar ~
11983 \SpecialChar ~
11984 inc\SpecialChar ~
11985 \SpecialChar ~
11986 \SpecialChar ~
11987 \SpecialChar ~
11988 _counter ; does not change flags, no need to save psw
11989 \newline
11990 \SpecialChar ~
11991 \SpecialChar ~
11992 \SpecialChar ~
11993 \SpecialChar ~
11994 reti\SpecialChar ~
11995 \SpecialChar ~
11996 \SpecialChar ~
11997 \SpecialChar ~
11998 \SpecialChar ~
11999 \SpecialChar ~
12000 \SpecialChar ~
12001 \SpecialChar ~
12002 \SpecialChar ~
12003 \SpecialChar ~
12004 \SpecialChar ~
12005 \SpecialChar ~
12006 ; MUST explicitly include ret or reti in _naked function
12007 \layout Standard
12008
12009 The related directive #pragma exclude
12010 \begin_inset LatexCommand \index{\#pragma exclude}
12011
12012 \end_inset
12013
12014  allows a more fine grained control over pushing & popping
12015 \begin_inset LatexCommand \index{push/pop}
12016
12017 \end_inset
12018
12019  the registers.
12020 \layout Standard
12021
12022 While there is nothing preventing you from writing C code inside a
12023 \family typewriter
12024 _naked
12025 \family default
12026  function, there are many ways to shoot yourself in the foot doing this,
12027  and it is recommended that you stick to inline assembler.
12028 \layout Subsection
12029
12030 Use of Labels within Inline Assembler
12031 \layout Standard
12032
12033 SDCC allows the use of in-line assembler with a few restrictions regarding
12034  labels.
12035  In older versions of the compiler all labels defined within inline assembler
12036  code
12037 \emph on
12038 had to be
12039 \emph default
12040  of the form
12041 \emph on
12042 nnnnn$
12043 \emph default
12044  where nnnn is a number less than 100 (which implies a limit of utmost 100
12045  inline assembler labels
12046 \emph on
12047 per function
12048 \emph default
12049 \noun on
12050 )
12051 \noun default
12052 .
12053
12054 \layout Verse
12055
12056
12057 \family typewriter
12058 _asm
12059 \begin_inset LatexCommand \index{\_asm}
12060
12061 \end_inset
12062
12063
12064 \newline
12065 \SpecialChar ~
12066 \SpecialChar ~
12067 \SpecialChar ~
12068 \SpecialChar ~
12069 mov\SpecialChar ~
12070 \SpecialChar ~
12071 \SpecialChar ~
12072 \SpecialChar ~
12073 \SpecialChar ~
12074 b,#10
12075 \newline
12076 00001$:
12077 \newline
12078 \SpecialChar ~
12079 \SpecialChar ~
12080 \SpecialChar ~
12081 \SpecialChar ~
12082 djnz\SpecialChar ~
12083 \SpecialChar ~
12084 \SpecialChar ~
12085 \SpecialChar ~
12086 b,00001$
12087 \newline
12088 _endasm
12089 \begin_inset LatexCommand \index{\_endasm}
12090
12091 \end_inset
12092
12093  ;
12094 \layout Standard
12095
12096 Inline assembler code cannot reference any C-Labels, however it can reference
12097  labels
12098 \begin_inset LatexCommand \index{Labels}
12099
12100 \end_inset
12101
12102  defined by the inline assembler, e.g.:
12103 \layout Verse
12104
12105
12106 \family typewriter
12107 foo() {
12108 \newline
12109 \SpecialChar ~
12110 \SpecialChar ~
12111 \SpecialChar ~
12112 \SpecialChar ~
12113 /* some c code */
12114 \newline
12115 \SpecialChar ~
12116 \SpecialChar ~
12117 \SpecialChar ~
12118 \SpecialChar ~
12119 _asm
12120 \newline
12121 \SpecialChar ~
12122 \SpecialChar ~
12123 \SpecialChar ~
12124 \SpecialChar ~
12125 \SpecialChar ~
12126 \SpecialChar ~
12127 ; some assembler code
12128 \newline
12129 \SpecialChar ~
12130 \SpecialChar ~
12131 \SpecialChar ~
12132 \SpecialChar ~
12133 \SpecialChar ~
12134 \SpecialChar ~
12135 ljmp $0003
12136 \newline
12137 \SpecialChar ~
12138 \SpecialChar ~
12139 \SpecialChar ~
12140 \SpecialChar ~
12141 _endasm;
12142 \newline
12143 \SpecialChar ~
12144 \SpecialChar ~
12145 \SpecialChar ~
12146 \SpecialChar ~
12147 /* some more c code */
12148 \newline
12149 clabel:\SpecialChar ~
12150 \SpecialChar ~
12151 /* inline assembler cannot reference this label */
12152 \newline
12153 \SpecialChar ~
12154 \SpecialChar ~
12155 \SpecialChar ~
12156 \SpecialChar ~
12157 _asm
12158 \newline
12159 \SpecialChar ~
12160 \SpecialChar ~
12161 \SpecialChar ~
12162 \SpecialChar ~
12163 $0003: ;label (can be referenced by inline assembler only)
12164 \newline
12165 \SpecialChar ~
12166 \SpecialChar ~
12167 \SpecialChar ~
12168 \SpecialChar ~
12169 _endasm ;
12170 \newline
12171 \SpecialChar ~
12172 \SpecialChar ~
12173 \SpecialChar ~
12174 \SpecialChar ~
12175 /* some more c code */
12176 \newline
12177 }
12178 \layout Standard
12179
12180 In other words inline assembly code can access labels defined in inline
12181  assembly within the scope of the function.
12182  The same goes the other way, i.e.
12183  labels defines in inline assembly can not be accessed by C statements.
12184 \layout Section
12185
12186 Interfacing with Assembler Code
12187 \begin_inset LatexCommand \index{Assembler routines}
12188
12189 \end_inset
12190
12191
12192 \layout Subsection
12193
12194 Global Registers used for Parameter Passing
12195 \begin_inset LatexCommand \index{Parameter passing}
12196
12197 \end_inset
12198
12199
12200 \layout Standard
12201
12202 The compiler always uses the global registers
12203 \emph on
12204 DPL, DPH
12205 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12206
12207 \end_inset
12208
12209
12210 \begin_inset LatexCommand \index{DPTR}
12211
12212 \end_inset
12213
12214 , B
12215 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
12216
12217 \end_inset
12218
12219
12220 \emph default
12221 and
12222 \emph on
12223  ACC
12224 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
12225
12226 \end_inset
12227
12228
12229 \emph default
12230  to pass the first parameter to a routine.
12231  The second parameter onwards is either allocated on the stack (for reentrant
12232  routines or if -
12233 \begin_inset ERT
12234 status Collapsed
12235
12236 \layout Standard
12237
12238 \backslash
12239 /
12240 \end_inset
12241
12242 -stack-auto is used) or in data / xdata memory (depending on the memory
12243  model).
12244
12245 \layout Subsection
12246
12247 Assembler Routine (non-reentrant)
12248 \layout Standard
12249
12250 In the following example
12251 \begin_inset LatexCommand \index{reentrant}
12252
12253 \end_inset
12254
12255
12256 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
12257
12258 \end_inset
12259
12260  the function c_func calls an assembler routine asm_func, which takes two
12261  parameters
12262 \begin_inset LatexCommand \index{function parameter}
12263
12264 \end_inset
12265
12266 .
12267 \layout Verse
12268
12269
12270 \family typewriter
12271 extern int asm_func(unsigned char, unsigned char);
12272 \newline
12273
12274 \newline
12275 int c_func (unsigned char i, unsigned char j)
12276 \newline
12277 {
12278 \newline
12279 \SpecialChar ~
12280 \SpecialChar ~
12281 \SpecialChar ~
12282 \SpecialChar ~
12283 return asm_func(i,j);
12284 \newline
12285 }
12286 \newline
12287
12288 \newline
12289 int main()
12290 \newline
12291 {
12292 \newline
12293 \SpecialChar ~
12294 \SpecialChar ~
12295 \SpecialChar ~
12296 \SpecialChar ~
12297 return c_func(10,9);
12298 \newline
12299 }
12300 \layout Standard
12301
12302 The corresponding assembler function is:
12303 \layout Verse
12304
12305
12306 \family typewriter
12307 .globl _asm_func_PARM_2
12308 \newline
12309 \SpecialChar ~
12310 \SpecialChar ~
12311 \SpecialChar ~
12312 \SpecialChar ~
12313 \SpecialChar ~
12314 \SpecialChar ~
12315 \SpecialChar ~
12316 \SpecialChar ~
12317 .globl _asm_func
12318 \newline
12319 \SpecialChar ~
12320 \SpecialChar ~
12321 \SpecialChar ~
12322 \SpecialChar ~
12323 \SpecialChar ~
12324 \SpecialChar ~
12325 \SpecialChar ~
12326 \SpecialChar ~
12327 .area OSEG
12328 \newline
12329 _asm_func_PARM_2:
12330 \newline
12331 \SpecialChar ~
12332 \SpecialChar ~
12333 \SpecialChar ~
12334 \SpecialChar ~
12335 \SpecialChar ~
12336 \SpecialChar ~
12337 \SpecialChar ~
12338 \SpecialChar ~
12339 .ds    1
12340 \newline
12341 \SpecialChar ~
12342 \SpecialChar ~
12343 \SpecialChar ~
12344 \SpecialChar ~
12345 \SpecialChar ~
12346 \SpecialChar ~
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 .area CSEG
12350 \newline
12351 _asm_func:
12352 \newline
12353 \SpecialChar ~
12354 \SpecialChar ~
12355 \SpecialChar ~
12356 \SpecialChar ~
12357 \SpecialChar ~
12358 \SpecialChar ~
12359 \SpecialChar ~
12360 \SpecialChar ~
12361 mov\SpecialChar ~
12362 \SpecialChar ~
12363 \SpecialChar ~
12364 \SpecialChar ~
12365 a,dpl
12366 \newline
12367 \SpecialChar ~
12368 \SpecialChar ~
12369 \SpecialChar ~
12370 \SpecialChar ~
12371 \SpecialChar ~
12372 \SpecialChar ~
12373 \SpecialChar ~
12374 \SpecialChar ~
12375 add\SpecialChar ~
12376 \SpecialChar ~
12377 \SpecialChar ~
12378 \SpecialChar ~
12379 a,_asm_func_PARM_2
12380 \newline
12381 \SpecialChar ~
12382 \SpecialChar ~
12383 \SpecialChar ~
12384 \SpecialChar ~
12385 \SpecialChar ~
12386 \SpecialChar ~
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 mov\SpecialChar ~
12390 \SpecialChar ~
12391 \SpecialChar ~
12392 \SpecialChar ~
12393 dpl,a
12394 \newline
12395 \SpecialChar ~
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 \SpecialChar ~
12399 \SpecialChar ~
12400 \SpecialChar ~
12401 \SpecialChar ~
12402 \SpecialChar ~
12403 mov\SpecialChar ~
12404 \SpecialChar ~
12405 \SpecialChar ~
12406 \SpecialChar ~
12407 dph
12408 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12409
12410 \end_inset
12411
12412 ,#0x00
12413 \newline
12414 \SpecialChar ~
12415 \SpecialChar ~
12416 \SpecialChar ~
12417 \SpecialChar ~
12418 \SpecialChar ~
12419 \SpecialChar ~
12420 \SpecialChar ~
12421 \SpecialChar ~
12422 ret
12423 \layout Standard
12424
12425 Note here that the return values
12426 \begin_inset LatexCommand \index{return value}
12427
12428 \end_inset
12429
12430  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
12431  two byte values.
12432  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
12433 b' & 'acc' for four byte values.
12434 \layout Standard
12435
12436 The parameter naming convention is _<function_name>_PARM_<n>, where n is
12437  the parameter number starting from 1, and counting from the left.
12438  The first parameter is passed in
12439 \begin_inset Quotes eld
12440 \end_inset
12441
12442 dpl
12443 \begin_inset Quotes erd
12444 \end_inset
12445
12446  for a one byte parameter,
12447 \begin_inset Quotes eld
12448 \end_inset
12449
12450 dptr
12451 \begin_inset Quotes erd
12452 \end_inset
12453
12454  for two bytes,
12455 \begin_inset Quotes eld
12456 \end_inset
12457
12458 b,dptr
12459 \begin_inset Quotes erd
12460 \end_inset
12461
12462  for three bytes and
12463 \begin_inset Quotes eld
12464 \end_inset
12465
12466 acc,b,dptr
12467 \begin_inset Quotes erd
12468 \end_inset
12469
12470  for a four bytes parameter.
12471  The variable name for the second parameter will be _<function_name>_PARM_2.
12472 \newline
12473
12474 \newline
12475 Assemble the assembler routine with the following command:
12476 \newline
12477
12478 \newline
12479
12480 \family sans
12481 \series bold
12482 asx8051 -losg asmfunc.asm
12483 \newline
12484
12485 \newline
12486
12487 \family default
12488 \series default
12489 Then compile and link the assembler routine to the C source file with the
12490  following command:
12491 \newline
12492
12493 \newline
12494
12495 \family sans
12496 \series bold
12497 sdcc cfunc.c asmfunc.rel
12498 \layout Subsection
12499
12500 Assembler Routine (reentrant)
12501 \layout Standard
12502
12503 In this case
12504 \begin_inset LatexCommand \index{reentrant}
12505
12506 \end_inset
12507
12508
12509 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
12510
12511 \end_inset
12512
12513  the second parameter
12514 \begin_inset LatexCommand \index{function parameter}
12515
12516 \end_inset
12517
12518  onwards will be passed on the stack, the parameters are pushed from right
12519  to left i.e.
12520  after the call the leftmost parameter will be on the top of the stack.
12521  Here is an example:
12522 \layout Verse
12523
12524
12525 \family typewriter
12526 extern int asm_func(unsigned char, unsigned char);
12527 \newline
12528
12529 \newline
12530 int c_func (unsigned char i, unsigned char j) reentrant
12531 \newline
12532 {
12533 \newline
12534 \SpecialChar ~
12535 \SpecialChar ~
12536 \SpecialChar ~
12537 \SpecialChar ~
12538 return asm_func(i,j);
12539 \newline
12540 }
12541 \newline
12542
12543 \newline
12544 int main()
12545 \newline
12546 {
12547 \newline
12548 \SpecialChar ~
12549 \SpecialChar ~
12550 \SpecialChar ~
12551 \SpecialChar ~
12552 return c_func(10,9);
12553 \newline
12554 }
12555 \layout Standard
12556
12557 The corresponding assembler routine is:
12558 \layout Verse
12559
12560
12561 \family typewriter
12562 .globl _asm_func
12563 \newline
12564 _asm_func:
12565 \newline
12566 \SpecialChar ~
12567 \SpecialChar ~
12568 \SpecialChar ~
12569 \SpecialChar ~
12570 push  _bp
12571 \newline
12572 \SpecialChar ~
12573 \SpecialChar ~
12574 \SpecialChar ~
12575 \SpecialChar ~
12576 mov _bp,sp
12577 \newline
12578 \SpecialChar ~
12579 \SpecialChar ~
12580 \SpecialChar ~
12581 \SpecialChar ~
12582 mov r2,dpl
12583 \newline
12584 \SpecialChar ~
12585 \SpecialChar ~
12586 \SpecialChar ~
12587 \SpecialChar ~
12588 mov a,_bp
12589 \newline
12590 \SpecialChar ~
12591 \SpecialChar ~
12592 \SpecialChar ~
12593 \SpecialChar ~
12594 add a,#0xfd
12595 \newline
12596 \SpecialChar ~
12597 \SpecialChar ~
12598 \SpecialChar ~
12599 \SpecialChar ~
12600 mov r0,a
12601 \newline
12602 \SpecialChar ~
12603 \SpecialChar ~
12604 \SpecialChar ~
12605 \SpecialChar ~
12606 add  a,#0xfc ;?
12607 \newline
12608 \SpecialChar ~
12609 \SpecialChar ~
12610 \SpecialChar ~
12611 \SpecialChar ~
12612 mov  r1,a
12613 \newline
12614 \SpecialChar ~
12615 \SpecialChar ~
12616 \SpecialChar ~
12617 \SpecialChar ~
12618 mov  a,@r0
12619 \newline
12620 \SpecialChar ~
12621 \SpecialChar ~
12622 \SpecialChar ~
12623 \SpecialChar ~
12624 add  a,r2 ;?
12625 \newline
12626 \SpecialChar ~
12627 \SpecialChar ~
12628 \SpecialChar ~
12629 \SpecialChar ~
12630 mov  dpl,a
12631 \newline
12632 \SpecialChar ~
12633 \SpecialChar ~
12634 \SpecialChar ~
12635 \SpecialChar ~
12636 mov  dph,#0x00
12637 \newline
12638 \SpecialChar ~
12639 \SpecialChar ~
12640 \SpecialChar ~
12641 \SpecialChar ~
12642 mov  sp,_bp
12643 \newline
12644 \SpecialChar ~
12645 \SpecialChar ~
12646 \SpecialChar ~
12647 \SpecialChar ~
12648 pop  _bp
12649 \newline
12650 \SpecialChar ~
12651 \SpecialChar ~
12652 \SpecialChar ~
12653 \SpecialChar ~
12654 ret
12655 \layout Standard
12656
12657 The compiling and linking procedure remains the same, however note the extra
12658  entry & exit linkage required for the assembler code, _bp is the stack
12659  frame pointer and is used to compute the offset into the stack for parameters
12660  and local variables.
12661 \layout Section
12662
12663 int (16 bit)
12664 \begin_inset LatexCommand \index{int (16 bit)}
12665
12666 \end_inset
12667
12668  and long (32 bit)
12669 \begin_inset LatexCommand \index{long (32 bit)}
12670
12671 \end_inset
12672
12673  Support
12674 \layout Standard
12675
12676 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
12677  multiplication and modulus operations are implemented by support routines.
12678  These support routines are all developed in ANSI-C to facilitate porting
12679  to other MCUs, although some model specific assembler optimizations are
12680  used.
12681  The following files contain the described routines, all of them can be
12682  found in <installdir>/share/sdcc/lib.
12683 \newline
12684
12685 \layout Standard
12686 \align center
12687
12688 \begin_inset  Tabular
12689 <lyxtabular version="3" rows="11" columns="2">
12690 <features>
12691 <column alignment="center" valignment="top" leftline="true" width="0">
12692 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12693 <row topline="true" bottomline="true">
12694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12695 \begin_inset Text
12696
12697 \layout Standard
12698
12699
12700 \series bold
12701 Function
12702 \end_inset
12703 </cell>
12704 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12705 \begin_inset Text
12706
12707 \layout Standard
12708
12709
12710 \series bold
12711 Description
12712 \end_inset
12713 </cell>
12714 </row>
12715 <row topline="true">
12716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12717 \begin_inset Text
12718
12719 \layout Standard
12720
12721 _mulint.c
12722 \end_inset
12723 </cell>
12724 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12725 \begin_inset Text
12726
12727 \layout Standard
12728
12729 16 bit multiplication
12730 \end_inset
12731 </cell>
12732 </row>
12733 <row topline="true">
12734 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12735 \begin_inset Text
12736
12737 \layout Standard
12738
12739 _divsint.c
12740 \end_inset
12741 </cell>
12742 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12743 \begin_inset Text
12744
12745 \layout Standard
12746
12747  signed 16 bit division (calls _divuint)
12748 \end_inset
12749 </cell>
12750 </row>
12751 <row topline="true">
12752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12753 \begin_inset Text
12754
12755 \layout Standard
12756
12757 _divuint.c
12758 \end_inset
12759 </cell>
12760 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12761 \begin_inset Text
12762
12763 \layout Standard
12764
12765  unsigned 16 bit division
12766 \end_inset
12767 </cell>
12768 </row>
12769 <row topline="true">
12770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12771 \begin_inset Text
12772
12773 \layout Standard
12774
12775 _modsint.c
12776 \end_inset
12777 </cell>
12778 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12779 \begin_inset Text
12780
12781 \layout Standard
12782
12783 signed 16 bit modulus (calls _moduint)
12784 \end_inset
12785 </cell>
12786 </row>
12787 <row topline="true">
12788 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12789 \begin_inset Text
12790
12791 \layout Standard
12792
12793 _moduint.c
12794 \end_inset
12795 </cell>
12796 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12797 \begin_inset Text
12798
12799 \layout Standard
12800
12801 unsigned 16 bit modulus
12802 \end_inset
12803 </cell>
12804 </row>
12805 <row topline="true">
12806 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12807 \begin_inset Text
12808
12809 \layout Standard
12810
12811 _mullong.c
12812 \end_inset
12813 </cell>
12814 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12815 \begin_inset Text
12816
12817 \layout Standard
12818
12819 32 bit multiplication
12820 \end_inset
12821 </cell>
12822 </row>
12823 <row topline="true">
12824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12825 \begin_inset Text
12826
12827 \layout Standard
12828
12829 _divslong.c
12830 \end_inset
12831 </cell>
12832 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12833 \begin_inset Text
12834
12835 \layout Standard
12836
12837  signed 32 division (calls _divulong)
12838 \end_inset
12839 </cell>
12840 </row>
12841 <row topline="true">
12842 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12843 \begin_inset Text
12844
12845 \layout Standard
12846
12847 _divulong.c
12848 \end_inset
12849 </cell>
12850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12851 \begin_inset Text
12852
12853 \layout Standard
12854
12855 unsigned 32 division
12856 \end_inset
12857 </cell>
12858 </row>
12859 <row topline="true">
12860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12861 \begin_inset Text
12862
12863 \layout Standard
12864
12865 _modslong.c
12866 \end_inset
12867 </cell>
12868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12869 \begin_inset Text
12870
12871 \layout Standard
12872
12873  signed 32 bit modulus (calls _modulong)
12874 \end_inset
12875 </cell>
12876 </row>
12877 <row topline="true" bottomline="true">
12878 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12879 \begin_inset Text
12880
12881 \layout Standard
12882
12883 _modulong.c
12884 \end_inset
12885 </cell>
12886 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12887 \begin_inset Text
12888
12889 \layout Standard
12890
12891 unsigned 32 bit modulus
12892 \end_inset
12893 </cell>
12894 </row>
12895 </lyxtabular>
12896
12897 \end_inset
12898
12899
12900 \newline
12901
12902 \layout Standard
12903
12904 Since they are compiled as
12905 \emph on
12906 non-reentrant
12907 \emph default
12908
12909 \begin_inset LatexCommand \index{reentrant}
12910
12911 \end_inset
12912
12913 , interrupt
12914 \begin_inset LatexCommand \index{interrupt}
12915
12916 \end_inset
12917
12918  service routines should not do any of the above operations.
12919  If this is unavoidable then the above routines will need to be compiled
12920  with the
12921 \emph on
12922 -
12923 \begin_inset ERT
12924 status Collapsed
12925
12926 \layout Standard
12927
12928 \backslash
12929 /
12930 \end_inset
12931
12932 -stack-auto
12933 \begin_inset LatexCommand \index{-\/-stack-auto}
12934
12935 \end_inset
12936
12937
12938 \emph default
12939  option, after which the source program will have to be compiled with
12940 \emph on
12941 -
12942 \begin_inset ERT
12943 status Collapsed
12944
12945 \layout Standard
12946
12947 \backslash
12948 /
12949 \end_inset
12950
12951 -int-long-reent
12952 \begin_inset LatexCommand \index{-\/-int-long-reent}
12953
12954 \end_inset
12955
12956
12957 \emph default
12958  option.
12959  Notice that you don't have to call these routines directly.
12960  The compiler will use them automatically every time an integer operation
12961  is required.
12962 \layout Section
12963
12964 Floating Point Support
12965 \begin_inset LatexCommand \index{Floating point support}
12966
12967 \end_inset
12968
12969
12970 \layout Standard
12971
12972 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
12973  floating point support routines are derived from gcc's floatlib.c and consist
12974  of the following routines:
12975 \newline
12976
12977 \layout Standard
12978 \align center
12979
12980 \size footnotesize
12981
12982 \begin_inset  Tabular
12983 <lyxtabular version="3" rows="17" columns="2">
12984 <features>
12985 <column alignment="center" valignment="top" leftline="true" width="0">
12986 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12987 <row topline="true" bottomline="true">
12988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12989 \begin_inset Text
12990
12991 \layout Standard
12992
12993
12994 \family roman
12995 \series medium
12996 \shape up
12997 \size normal
12998 \emph off
12999 \bar no
13000 \noun off
13001 \color none
13002 Function
13003 \end_inset
13004 </cell>
13005 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13006 \begin_inset Text
13007
13008 \layout Standard
13009
13010 Description
13011 \end_inset
13012 </cell>
13013 </row>
13014 <row topline="true">
13015 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13016 \begin_inset Text
13017
13018 \layout Standard
13019
13020
13021 \family roman
13022 \series medium
13023 \shape up
13024 \size normal
13025 \emph off
13026 \bar no
13027 \noun off
13028 \color none
13029 _fsadd.c
13030 \end_inset
13031 </cell>
13032 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13033 \begin_inset Text
13034
13035 \layout Standard
13036
13037
13038 \family roman
13039 \series medium
13040 \shape up
13041 \size normal
13042 \emph off
13043 \bar no
13044 \noun off
13045 \color none
13046 add floating point numbers
13047 \end_inset
13048 </cell>
13049 </row>
13050 <row topline="true">
13051 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13052 \begin_inset Text
13053
13054 \layout Standard
13055
13056
13057 \family roman
13058 \series medium
13059 \shape up
13060 \size normal
13061 \emph off
13062 \bar no
13063 \noun off
13064 \color none
13065 _fssub.c
13066 \end_inset
13067 </cell>
13068 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13069 \begin_inset Text
13070
13071 \layout Standard
13072
13073
13074 \family roman
13075 \series medium
13076 \shape up
13077 \size normal
13078 \emph off
13079 \bar no
13080 \noun off
13081 \color none
13082 subtract floating point numbers
13083 \end_inset
13084 </cell>
13085 </row>
13086 <row topline="true">
13087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13088 \begin_inset Text
13089
13090 \layout Standard
13091
13092
13093 \family roman
13094 \series medium
13095 \shape up
13096 \size normal
13097 \emph off
13098 \bar no
13099 \noun off
13100 \color none
13101 _fsdiv.c
13102 \end_inset
13103 </cell>
13104 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13105 \begin_inset Text
13106
13107 \layout Standard
13108
13109
13110 \family roman
13111 \series medium
13112 \shape up
13113 \size normal
13114 \emph off
13115 \bar no
13116 \noun off
13117 \color none
13118 divide floating point numbers
13119 \end_inset
13120 </cell>
13121 </row>
13122 <row topline="true">
13123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13124 \begin_inset Text
13125
13126 \layout Standard
13127
13128
13129 \family roman
13130 \series medium
13131 \shape up
13132 \size normal
13133 \emph off
13134 \bar no
13135 \noun off
13136 \color none
13137 _fsmul.c
13138 \end_inset
13139 </cell>
13140 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13141 \begin_inset Text
13142
13143 \layout Standard
13144
13145
13146 \family roman
13147 \series medium
13148 \shape up
13149 \size normal
13150 \emph off
13151 \bar no
13152 \noun off
13153 \color none
13154 multiply floating point numbers
13155 \end_inset
13156 </cell>
13157 </row>
13158 <row topline="true">
13159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13160 \begin_inset Text
13161
13162 \layout Standard
13163
13164
13165 \family roman
13166 \series medium
13167 \shape up
13168 \size normal
13169 \emph off
13170 \bar no
13171 \noun off
13172 \color none
13173 _fs2uchar.c
13174 \end_inset
13175 </cell>
13176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13177 \begin_inset Text
13178
13179 \layout Standard
13180
13181
13182 \family roman
13183 \series medium
13184 \shape up
13185 \size normal
13186 \emph off
13187 \bar no
13188 \noun off
13189 \color none
13190 convert floating point to unsigned char
13191 \end_inset
13192 </cell>
13193 </row>
13194 <row topline="true">
13195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13196 \begin_inset Text
13197
13198 \layout Standard
13199
13200
13201 \family roman
13202 \series medium
13203 \shape up
13204 \size normal
13205 \emph off
13206 \bar no
13207 \noun off
13208 \color none
13209 _fs2char.c
13210 \end_inset
13211 </cell>
13212 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13213 \begin_inset Text
13214
13215 \layout Standard
13216
13217
13218 \family roman
13219 \series medium
13220 \shape up
13221 \size normal
13222 \emph off
13223 \bar no
13224 \noun off
13225 \color none
13226 convert floating point to signed char
13227 \end_inset
13228 </cell>
13229 </row>
13230 <row topline="true">
13231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13232 \begin_inset Text
13233
13234 \layout Standard
13235
13236
13237 \family roman
13238 \series medium
13239 \shape up
13240 \size normal
13241 \emph off
13242 \bar no
13243 \noun off
13244 \color none
13245 _fs2uint.c
13246 \end_inset
13247 </cell>
13248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13249 \begin_inset Text
13250
13251 \layout Standard
13252
13253
13254 \family roman
13255 \series medium
13256 \shape up
13257 \size normal
13258 \emph off
13259 \bar no
13260 \noun off
13261 \color none
13262 convert floating point to unsigned int
13263 \end_inset
13264 </cell>
13265 </row>
13266 <row topline="true">
13267 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13268 \begin_inset Text
13269
13270 \layout Standard
13271
13272
13273 \family roman
13274 \series medium
13275 \shape up
13276 \size normal
13277 \emph off
13278 \bar no
13279 \noun off
13280 \color none
13281 _fs2int.c
13282 \end_inset
13283 </cell>
13284 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13285 \begin_inset Text
13286
13287 \layout Standard
13288
13289
13290 \family roman
13291 \series medium
13292 \shape up
13293 \size normal
13294 \emph off
13295 \bar no
13296 \noun off
13297 \color none
13298 convert floating point to signed int
13299 \end_inset
13300 </cell>
13301 </row>
13302 <row topline="true">
13303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13304 \begin_inset Text
13305
13306 \layout Standard
13307
13308
13309 \family roman
13310 \series medium
13311 \shape up
13312 \size normal
13313 \emph off
13314 \bar no
13315 \noun off
13316 \color none
13317 _fs2ulong.
13318 \family default
13319 \series default
13320 \shape default
13321 \size default
13322 \emph default
13323 \bar default
13324 \noun default
13325 \color default
13326 c
13327 \end_inset
13328 </cell>
13329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13330 \begin_inset Text
13331
13332 \layout Standard
13333
13334
13335 \family roman
13336 \series medium
13337 \shape up
13338 \size normal
13339 \emph off
13340 \bar no
13341 \noun off
13342 \color none
13343 convert floating point to unsigned long
13344 \end_inset
13345 </cell>
13346 </row>
13347 <row topline="true">
13348 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13349 \begin_inset Text
13350
13351 \layout Standard
13352
13353
13354 \family roman
13355 \series medium
13356 \shape up
13357 \size normal
13358 \emph off
13359 \bar no
13360 \noun off
13361 \color none
13362 _fs2long.c
13363 \end_inset
13364 </cell>
13365 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13366 \begin_inset Text
13367
13368 \layout Standard
13369
13370
13371 \family roman
13372 \series medium
13373 \shape up
13374 \size normal
13375 \emph off
13376 \bar no
13377 \noun off
13378 \color none
13379 convert floating point to signed long
13380 \end_inset
13381 </cell>
13382 </row>
13383 <row topline="true">
13384 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13385 \begin_inset Text
13386
13387 \layout Standard
13388
13389
13390 \family roman
13391 \series medium
13392 \shape up
13393 \size normal
13394 \emph off
13395 \bar no
13396 \noun off
13397 \color none
13398 _uchar2fs.c
13399 \end_inset
13400 </cell>
13401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13402 \begin_inset Text
13403
13404 \layout Standard
13405
13406
13407 \family roman
13408 \series medium
13409 \shape up
13410 \size normal
13411 \emph off
13412 \bar no
13413 \noun off
13414 \color none
13415 convert unsigned char to floating point
13416 \end_inset
13417 </cell>
13418 </row>
13419 <row topline="true">
13420 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13421 \begin_inset Text
13422
13423 \layout Standard
13424
13425
13426 \family roman
13427 \series medium
13428 \shape up
13429 \size normal
13430 \emph off
13431 \bar no
13432 \noun off
13433 \color none
13434 _char2fs.c
13435 \end_inset
13436 </cell>
13437 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13438 \begin_inset Text
13439
13440 \layout Standard
13441
13442
13443 \family roman
13444 \series medium
13445 \shape up
13446 \size normal
13447 \emph off
13448 \bar no
13449 \noun off
13450 \color none
13451 convert char to floating point number
13452 \end_inset
13453 </cell>
13454 </row>
13455 <row topline="true">
13456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13457 \begin_inset Text
13458
13459 \layout Standard
13460
13461
13462 \family roman
13463 \series medium
13464 \shape up
13465 \size normal
13466 \emph off
13467 \bar no
13468 \noun off
13469 \color none
13470 _uint2fs.c
13471 \end_inset
13472 </cell>
13473 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13474 \begin_inset Text
13475
13476 \layout Standard
13477
13478
13479 \family roman
13480 \series medium
13481 \shape up
13482 \size normal
13483 \emph off
13484 \bar no
13485 \noun off
13486 \color none
13487 convert unsigned int to floating point
13488 \end_inset
13489 </cell>
13490 </row>
13491 <row topline="true">
13492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13493 \begin_inset Text
13494
13495 \layout Standard
13496
13497
13498 \family roman
13499 \series medium
13500 \shape up
13501 \size normal
13502 \emph off
13503 \bar no
13504 \noun off
13505 \color none
13506 _int2fs.c
13507 \end_inset
13508 </cell>
13509 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13510 \begin_inset Text
13511
13512 \layout Standard
13513
13514
13515 \family roman
13516 \series medium
13517 \shape up
13518 \size normal
13519 \emph off
13520 \bar no
13521 \noun off
13522 \color none
13523 convert int to floating point numbers
13524 \end_inset
13525 </cell>
13526 </row>
13527 <row topline="true">
13528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13529 \begin_inset Text
13530
13531 \layout Standard
13532
13533
13534 \family roman
13535 \series medium
13536 \shape up
13537 \size normal
13538 \emph off
13539 \bar no
13540 \noun off
13541 \color none
13542 _ulong2fs.c
13543 \end_inset
13544 </cell>
13545 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13546 \begin_inset Text
13547
13548 \layout Standard
13549
13550
13551 \family roman
13552 \series medium
13553 \shape up
13554 \size normal
13555 \emph off
13556 \bar no
13557 \noun off
13558 \color none
13559 convert unsigned long to floating point number
13560 \end_inset
13561 </cell>
13562 </row>
13563 <row topline="true" bottomline="true">
13564 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13565 \begin_inset Text
13566
13567 \layout Standard
13568
13569
13570 \family roman
13571 \series medium
13572 \shape up
13573 \size normal
13574 \emph off
13575 \bar no
13576 \noun off
13577 \color none
13578 _long2fs.c
13579 \end_inset
13580 </cell>
13581 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13582 \begin_inset Text
13583
13584 \layout Standard
13585
13586
13587 \family roman
13588 \series medium
13589 \shape up
13590 \size normal
13591 \emph off
13592 \bar no
13593 \noun off
13594 \color none
13595 convert long to floating point number
13596 \end_inset
13597 </cell>
13598 </row>
13599 </lyxtabular>
13600
13601 \end_inset
13602
13603
13604 \newline
13605
13606 \layout Standard
13607
13608 These support routines are developed in ANSI-C so there is room for space
13609  and speed improvement.
13610  Note if all these routines are used simultaneously the data space might
13611  overflow.
13612  For serious floating point usage it is recommended that the large model
13613  be used.
13614  Also notice that you don't have to call this routines directly.
13615  The compiler will use them automatically every time a floating point operation
13616  is required.
13617 \layout Section
13618
13619 Library Routines
13620 \begin_inset LatexCommand \index{Libraries}
13621
13622 \end_inset
13623
13624
13625 \layout Standard
13626
13627
13628 \emph on
13629 <pending: this is messy and incomplete - a little more information is in
13630  sdcc/doc/libdoc.txt
13631 \emph default
13632  >
13633 \layout Subsection
13634
13635 Compiler support routines (_gptrget, _mulint etc.)
13636 \layout Subsection
13637
13638 Stdclib functions (puts, printf, strcat etc.)
13639 \layout Subsubsection
13640
13641 <stdio.h>
13642 \layout Standard
13643
13644
13645 \begin_inset LatexCommand \index{<stdio.h>}
13646
13647 \end_inset
13648
13649 As usual on embedded systems you have to provide your own
13650 \family typewriter
13651 getchar()
13652 \begin_inset LatexCommand \index{getchar()}
13653
13654 \end_inset
13655
13656
13657 \family default
13658 and
13659 \family typewriter
13660 putchar()
13661 \begin_inset LatexCommand \index{putchar()}
13662
13663 \end_inset
13664
13665
13666 \family default
13667  routines.
13668  SDCC does not know whether the system connects to a serial line with or
13669  without handshake, LCD, keyboard or other device.
13670  You'll find examples for serial routines f.e.
13671  in sdcc/device/lib.
13672 \layout Standard
13673
13674 If you're short on memory you might want to use
13675 \family typewriter
13676 printf_small()
13677 \family default
13678
13679 \emph on
13680 instead
13681 \emph default
13682  of
13683 \family typewriter
13684  printf()
13685 \begin_inset LatexCommand \index{printf()}
13686
13687 \end_inset
13688
13689 .
13690
13691 \family default
13692  For the mcs51 there is an assembly version
13693 \family typewriter
13694 printf_fast()
13695 \family default
13696  which should fit the requirements of many embedded systems (by unsetting
13697  #defines it can be customized to
13698 \emph on
13699 not
13700 \emph default
13701  support long variables and field widths).
13702 \layout Subsection
13703
13704 Math functions (sin, pow, sqrt etc.)
13705 \layout Subsection
13706
13707 Other libraries
13708 \layout Standard
13709
13710 Libraries
13711 \begin_inset LatexCommand \index{Libraries}
13712
13713 \end_inset
13714
13715  included in SDCC should have a license at least as liberal as the GNU Lesser
13716  General Public License
13717 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
13718
13719 \end_inset
13720
13721
13722 \emph on
13723 LGPL
13724 \emph default
13725 .
13726 \layout Comment
13727
13728 license statements for the libraries are missing.
13729  sdcc/device/lib/ser_ir.c
13730 \layout Comment
13731
13732 or _decdptr f.e.
13733  come with a GPL (as opposed to LGPL) License - this will not be liberal
13734  enough for many embedded programmers.
13735 \layout Standard
13736
13737 If you have ported some library or want to share experience about some code
13738  which f.e.
13739  falls into any of these categories Busses (I
13740 \begin_inset Formula $^{\textrm{2}}$
13741 \end_inset
13742
13743 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
13744  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
13745  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
13746 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
13747
13748 \end_inset
13749
13750 \SpecialChar ~
13751 would certainly like to hear about it.
13752  Programmers coding for embedded systems are not especially famous for being
13753  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
13754 e these references are very valuable.
13755  Let's help to create a climate where information is shared.
13756 \layout Section
13757
13758 Memory Models
13759 \layout Subsection
13760
13761 MCS51 Memory Models
13762 \begin_inset LatexCommand \index{Memory model}
13763
13764 \end_inset
13765
13766
13767 \begin_inset LatexCommand \index{MCS51 memory model}
13768
13769 \end_inset
13770
13771
13772 \layout Subsubsection
13773
13774 Small and Large
13775 \layout Standard
13776
13777 SDCC allows two memory models for MCS51 code,
13778 \shape slanted
13779 small
13780 \shape default
13781  and
13782 \shape slanted
13783 large
13784 \shape default
13785 .
13786  Modules compiled with different memory models should
13787 \emph on
13788 never
13789 \emph default
13790  be combined together or the results would be unpredictable.
13791  The library routines supplied with the compiler are compiled as both small
13792  and large.
13793  The compiled library modules are contained in separate directories as small
13794  and large so that you can link to either set.
13795
13796 \layout Standard
13797
13798 When the large model is used all variables declared without a storage class
13799  will be allocated into the external ram, this includes all parameters and
13800  local variables (for non-reentrant
13801 \begin_inset LatexCommand \index{reentrant}
13802
13803 \end_inset
13804
13805  functions).
13806  When the small model is used variables without storage class are allocated
13807  in the internal ram.
13808 \layout Standard
13809
13810 Judicious usage of the processor specific storage classes
13811 \begin_inset LatexCommand \index{Storage class}
13812
13813 \end_inset
13814
13815  and the 'reentrant' function type will yield much more efficient code,
13816  than using the large model.
13817  Several optimizations are disabled when the program is compiled using the
13818  large model, it is therefore recommended that the small model be used unless
13819  absolutely required.
13820 \layout Subsubsection
13821
13822 External Stack
13823 \begin_inset LatexCommand \label{sub:External-Stack}
13824
13825 \end_inset
13826
13827
13828 \begin_inset LatexCommand \index{stack}
13829
13830 \end_inset
13831
13832
13833 \begin_inset LatexCommand \index{External stack (mcs51)}
13834
13835 \end_inset
13836
13837
13838 \layout Standard
13839
13840
13841 \series bold
13842 Attention
13843 \series default
13844 : this option wasn't maintained for a long time and is quite buggy.
13845  Small programs might work.
13846  You've been warned!
13847 \layout Standard
13848
13849 The external stack (-
13850 \begin_inset ERT
13851 status Collapsed
13852
13853 \layout Standard
13854
13855 \backslash
13856 /
13857 \end_inset
13858
13859 -xstack option
13860 \begin_inset LatexCommand \index{-\/-xstack}
13861
13862 \end_inset
13863
13864 ) is located in pdata
13865 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
13866
13867 \end_inset
13868
13869  memory (usually at the start of the external ram segment) and is 256 bytes
13870  in size.
13871  When -
13872 \begin_inset ERT
13873 status Collapsed
13874
13875 \layout Standard
13876
13877 \backslash
13878 /
13879 \end_inset
13880
13881 -xstack option is used to compile the program, the parameters and local
13882  variables
13883 \begin_inset LatexCommand \index{local variables}
13884
13885 \end_inset
13886
13887  of all reentrant functions are allocated in this area.
13888  This option is provided for programs with large stack space requirements.
13889  When used with the -
13890 \begin_inset ERT
13891 status Collapsed
13892
13893 \layout Standard
13894
13895 \backslash
13896 /
13897 \end_inset
13898
13899 -stack-auto
13900 \begin_inset LatexCommand \index{-\/-stack-auto}
13901
13902 \end_inset
13903
13904  option, all parameters and local variables are allocated on the external
13905  stack (note: support libraries will need to be recompiled with the same
13906  options).
13907 \layout Standard
13908
13909 The compiler outputs the higher order address byte of the external ram segment
13910  into port P2
13911 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
13912
13913 \end_inset
13914
13915  (see also section
13916 \begin_inset LatexCommand \ref{sub:MCS51-variants}
13917
13918 \end_inset
13919
13920 ), therefore when using the External Stack option, this port
13921 \emph on
13922 may not
13923 \emph default
13924  be used by the application program.
13925 \layout Subsection
13926
13927 DS390 Memory Model
13928 \begin_inset LatexCommand \index{Memory model}
13929
13930 \end_inset
13931
13932
13933 \begin_inset LatexCommand \index{DS390 memory model}
13934
13935 \end_inset
13936
13937
13938 \layout Standard
13939
13940 The only model supported is Flat 24
13941 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
13942
13943 \end_inset
13944
13945 .
13946  This generates code for the 24 bit contiguous addressing mode of the Dallas
13947  DS80C390 part.
13948  In this mode, up to four meg of external RAM or code space can be directly
13949  addressed.
13950  See the data sheets at www.dalsemi.com for further information on this part.
13951 \newline
13952
13953 \newline
13954 Note that the compiler does not generate any code to place the processor
13955  into 24 bitmode (although
13956 \emph on
13957 tinibios
13958 \emph default
13959  in the ds390 libraries will do that for you).
13960  If you don't use
13961 \emph on
13962 tinibios
13963 \emph default
13964
13965 \begin_inset LatexCommand \index{Tinibios (DS390)}
13966
13967 \end_inset
13968
13969 , the boot loader or similar code must ensure that the processor is in 24
13970  bit contiguous addressing mode before calling the SDCC startup code.
13971 \newline
13972
13973 \newline
13974 Like the
13975 \emph on
13976 -
13977 \begin_inset ERT
13978 status Collapsed
13979
13980 \layout Standard
13981
13982 \backslash
13983 /
13984 \end_inset
13985
13986 -model-large
13987 \emph default
13988  option, variables will by default be placed into the XDATA segment.
13989
13990 \newline
13991
13992 \newline
13993 Segments may be placed anywhere in the 4 meg address space using the usual
13994  -
13995 \begin_inset ERT
13996 status Collapsed
13997
13998 \layout Standard
13999
14000 \backslash
14001 /
14002 \end_inset
14003
14004 -*-loc options.
14005  Note that if any segments are located above 64K, the -r flag must be passed
14006  to the linker to generate the proper segment relocations, and the Intel
14007  HEX output format must be used.
14008  The -r flag can be passed to the linker by using the option
14009 \emph on
14010 -Wl-r
14011 \emph default
14012  on the SDCC command line.
14013  However, currently the linker can not handle code segments > 64k.
14014 \layout Section
14015
14016 Pragmas
14017 \begin_inset LatexCommand \index{Pragmas}
14018
14019 \end_inset
14020
14021
14022 \layout Standard
14023
14024 SDCC supports the following #pragma directives:
14025 \layout Itemize
14026
14027 save
14028 \begin_inset LatexCommand \index{\#pragma save}
14029
14030 \end_inset
14031
14032  - this will save all current options to the save/restore stack.
14033  See #pragma\SpecialChar ~
14034 restore.
14035 \layout Itemize
14036
14037 restore
14038 \begin_inset LatexCommand \index{\#pragma restore}
14039
14040 \end_inset
14041
14042  - will restore saved options from the last save.
14043  saves & restores can be nested.
14044  SDCC uses a save/restore stack: save pushes current options to the stack,
14045  restore pulls current options from the stack.
14046  See #pragma\SpecialChar ~
14047 save.
14048 \newline
14049
14050 \layout Itemize
14051
14052 callee_saves
14053 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14054
14055 \end_inset
14056
14057
14058 \begin_inset LatexCommand \index{function prologue}
14059
14060 \end_inset
14061
14062  function1[,function2[,function3...]] - The compiler by default uses a caller
14063  saves convention for register saving across function calls, however this
14064  can cause unnecessary register pushing & popping
14065 \begin_inset LatexCommand \index{push/pop}
14066
14067 \end_inset
14068
14069  when calling small functions from larger functions.
14070  This option can be used to switch off the register saving convention for
14071  the function names specified.
14072  The compiler will not save registers when calling these functions, extra
14073  code need to be manually inserted at the entry & exit for these functions
14074  to save & restore the registers used by these functions, this can SUBSTANTIALLY
14075  reduce code & improve run time performance of the generated code.
14076  In the future the compiler (with inter procedural analysis) may be able
14077  to determine the appropriate scheme to use for each function call.
14078  If -
14079 \begin_inset ERT
14080 status Collapsed
14081
14082 \layout Standard
14083
14084 \backslash
14085 /
14086 \end_inset
14087
14088 -callee-saves command line option is used, the function names specified
14089  in #pragma\SpecialChar ~
14090 callee_saves
14091 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14092
14093 \end_inset
14094
14095  is appended to the list of functions specified in the command line.
14096 \layout Itemize
14097
14098 exclude
14099 \begin_inset LatexCommand \index{\#pragma exclude}
14100
14101 \end_inset
14102
14103  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
14104  of pairs of push/pop
14105 \begin_inset LatexCommand \index{push/pop}
14106
14107 \end_inset
14108
14109  instructions in
14110 \emph on
14111 I
14112 \emph default
14113 nterrupt
14114 \begin_inset LatexCommand \index{interrupt}
14115
14116 \end_inset
14117
14118
14119 \emph on
14120 S
14121 \emph default
14122 ervice
14123 \emph on
14124 R
14125 \emph default
14126 outines.
14127  The directive should be placed immediately before the ISR function definition
14128  and it affects ALL ISR functions following it.
14129  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
14130 exclude\SpecialChar ~
14131 none
14132 \begin_inset LatexCommand \index{\#pragma exclude}
14133
14134 \end_inset
14135
14136 .
14137  See also the related keyword _naked
14138 \begin_inset LatexCommand \index{\_naked}
14139
14140 \end_inset
14141
14142 .
14143 \layout Itemize
14144
14145 less_pedantic
14146 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
14147
14148 \end_inset
14149
14150  - the compiler will not warn you anymore for obvious mistakes, you'r on
14151  your own now ;-(
14152 \layout Itemize
14153
14154 nogcse
14155 \begin_inset LatexCommand \index{\#pragma nogcse}
14156
14157 \end_inset
14158
14159  - will stop global common subexpression elimination.
14160 \layout Itemize
14161
14162 noinduction
14163 \begin_inset LatexCommand \index{\#pragma noinduction}
14164
14165 \end_inset
14166
14167  - will stop loop induction optimizations.
14168 \layout Itemize
14169
14170 noinvariant
14171 \begin_inset LatexCommand \index{\#pragma noinvariant}
14172
14173 \end_inset
14174
14175  - will not do loop invariant optimizations.
14176  For more details see Loop Invariants in section
14177 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
14178
14179 \end_inset
14180
14181 .
14182 \layout Itemize
14183
14184 noiv
14185 \begin_inset LatexCommand \index{\#pragma noiv}
14186
14187 \end_inset
14188
14189  - Do not generate interrupt
14190 \begin_inset LatexCommand \index{interrupt}
14191
14192 \end_inset
14193
14194  vector table entries for all ISR functions defined after the pragma.
14195  This is useful in cases where the interrupt vector table must be defined
14196  manually, or when there is a secondary, manually defined interrupt vector
14197  table (e.g.
14198  for the autovector feature of the Cypress EZ-USB FX2).
14199  More elegantly this can be achieved by obmitting the optional interrupt
14200  number after the interrupt keyword, see section
14201 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
14202
14203 \end_inset
14204
14205 \SpecialChar ~
14206 about interrupts.
14207 \layout Itemize
14208
14209 nojtbound
14210 \begin_inset LatexCommand \index{\#pragma nojtbound}
14211
14212 \end_inset
14213
14214  - will not generate code for boundary value checking, when switch statements
14215  are turned into jump-tables (dangerous).
14216  For more details see section
14217 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
14218
14219 \end_inset
14220
14221 .
14222 \layout Itemize
14223
14224 noloopreverse
14225 \begin_inset LatexCommand \index{\#pragma noloopreverse}
14226
14227 \end_inset
14228
14229  - Will not do loop reversal optimization
14230 \layout Itemize
14231
14232 nooverlay
14233 \begin_inset LatexCommand \index{\#pragma nooverlay}
14234
14235 \end_inset
14236
14237  - the compiler will not overlay the parameters and local variables of a
14238  function.
14239 \layout Itemize
14240
14241 stackauto
14242 \begin_inset LatexCommand \index{\#pragma stackauto}
14243
14244 \end_inset
14245
14246 - See option -
14247 \begin_inset ERT
14248 status Collapsed
14249
14250 \layout Standard
14251
14252 \backslash
14253 /
14254 \end_inset
14255
14256 -stack-auto
14257 \begin_inset LatexCommand \index{-\/-stack-auto}
14258
14259 \end_inset
14260
14261  and section
14262 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
14263
14264 \end_inset
14265
14266  Parameters and Local Variables.
14267 \layout Itemize
14268
14269 opt_code_speed
14270 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
14271
14272 \end_inset
14273
14274 - The compiler will optimize code generation towards fast code, possibly
14275  at the expense of code size.
14276 \layout Itemize
14277
14278 opt_code_size
14279 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
14280
14281 \end_inset
14282
14283 - The compiler will optimize code generation towards compact code, possibly
14284  at the expense of code speed.
14285 \layout Itemize
14286
14287 opt_code_balanced
14288 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
14289
14290 \end_inset
14291
14292 - The compiler will attempt to generate code that is both compact and fast,
14293  as long as meeting one goal is not a detriment to the other (this is the
14294  default).
14295
14296 \layout Standard
14297
14298 SDCPP supports the following #pragma directives:
14299 \layout Itemize
14300
14301 preproc_asm
14302 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
14303
14304 \end_inset
14305
14306  (+ | -) - switch _asm _endasm block preprocessing on / off.
14307  Default is on.
14308 \layout Standard
14309
14310 The pragma's are intended to be used to turn-on or off certain optimizations
14311  which might cause the compiler to generate extra stack / data space to
14312  store compiler generated temporary variables.
14313  This usually happens in large functions.
14314  Pragma directives should be used as shown in the following example, they
14315  are used to control options & optimizations for a given function; pragmas
14316  should be placed before and/or after a function, placing pragma's inside
14317  a function body could have unpredictable results.
14318 \layout Verse
14319
14320
14321 \family typewriter
14322 #pragma save
14323 \begin_inset LatexCommand \index{\#pragma save}
14324
14325 \end_inset
14326
14327  \SpecialChar ~
14328 \SpecialChar ~
14329 \SpecialChar ~
14330 \SpecialChar ~
14331 \SpecialChar ~
14332 \SpecialChar ~
14333 \SpecialChar ~
14334 /* save the current settings */
14335 \newline
14336 #pragma nogcse
14337 \begin_inset LatexCommand \index{\#pragma nogcse}
14338
14339 \end_inset
14340
14341  \SpecialChar ~
14342 \SpecialChar ~
14343 \SpecialChar ~
14344 \SpecialChar ~
14345 \SpecialChar ~
14346 /* turnoff global subexpression elimination */
14347 \newline
14348 #pragma noinduction
14349 \begin_inset LatexCommand \index{\#pragma noinduction}
14350
14351 \end_inset
14352
14353  /* turn off induction optimizations */
14354 \newline
14355 int foo ()
14356 \newline
14357 {
14358 \newline
14359 \SpecialChar ~
14360  \SpecialChar ~
14361  ...
14362
14363 \newline
14364 \SpecialChar ~
14365  \SpecialChar ~
14366  /* large code */
14367 \newline
14368 \SpecialChar ~
14369  \SpecialChar ~
14370  ...
14371
14372 \newline
14373 }
14374 \newline
14375 #pragma restore
14376 \begin_inset LatexCommand \index{\#pragma restore}
14377
14378 \end_inset
14379
14380  /* turn the optimizations back on */
14381 \layout Standard
14382
14383 The compiler will generate a warning message when extra space is allocated.
14384  It is strongly recommended that the save and restore pragma's be used when
14385  changing options for a function.
14386 \layout Section
14387
14388 Defines Created by the Compiler
14389 \layout Standard
14390
14391 The compiler creates the following #defines
14392 \begin_inset LatexCommand \index{\#defines}
14393
14394 \end_inset
14395
14396
14397 \begin_inset LatexCommand \index{Defines created by the compiler}
14398
14399 \end_inset
14400
14401 :
14402 \newline
14403
14404 \layout Standard
14405
14406
14407 \begin_inset  Tabular
14408 <lyxtabular version="3" rows="10" columns="2">
14409 <features>
14410 <column alignment="center" valignment="top" leftline="true" width="0">
14411 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
14412 <row topline="true" bottomline="true">
14413 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14414 \begin_inset Text
14415
14416 \layout Standard
14417
14418
14419 \series bold
14420 #define
14421 \end_inset
14422 </cell>
14423 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14424 \begin_inset Text
14425
14426 \layout Standard
14427
14428
14429 \series bold
14430 Description
14431 \end_inset
14432 </cell>
14433 </row>
14434 <row topline="true">
14435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14436 \begin_inset Text
14437
14438 \layout Standard
14439
14440 SDCC
14441 \begin_inset LatexCommand \index{SDCC}
14442
14443 \end_inset
14444
14445
14446 \end_inset
14447 </cell>
14448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14449 \begin_inset Text
14450
14451 \layout Standard
14452
14453 this Symbol is always defined
14454 \end_inset
14455 </cell>
14456 </row>
14457 <row topline="true">
14458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14459 \begin_inset Text
14460
14461 \layout Standard
14462
14463 SDCC_mcs51
14464 \begin_inset LatexCommand \index{SDCC\_mcs51}
14465
14466 \end_inset
14467
14468  or SDCC_ds390
14469 \begin_inset LatexCommand \index{SDCC\_ds390}
14470
14471 \end_inset
14472
14473  or SDCC_z80
14474 \begin_inset LatexCommand \index{SDCC\_z80}
14475
14476 \end_inset
14477
14478 , etc
14479 \end_inset
14480 </cell>
14481 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14482 \begin_inset Text
14483
14484 \layout Standard
14485
14486 depending on the model used (e.g.: -mds390
14487 \end_inset
14488 </cell>
14489 </row>
14490 <row topline="true">
14491 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14492 \begin_inset Text
14493
14494 \layout Standard
14495
14496 __mcs51
14497 \begin_inset LatexCommand \index{\_\_mcs51}
14498
14499 \end_inset
14500
14501 , __ds390
14502 \begin_inset LatexCommand \index{\_\_ds390}
14503
14504 \end_inset
14505
14506 , __hc08
14507 \begin_inset LatexCommand \index{\_\_hc08}
14508
14509 \end_inset
14510
14511 , __z80
14512 \begin_inset LatexCommand \index{\_\_z80}
14513
14514 \end_inset
14515
14516 , etc
14517 \end_inset
14518 </cell>
14519 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14520 \begin_inset Text
14521
14522 \layout Standard
14523
14524 depending on the model used (e.g.
14525  -mz80)
14526 \end_inset
14527 </cell>
14528 </row>
14529 <row topline="true">
14530 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14531 \begin_inset Text
14532
14533 \layout Standard
14534
14535 SDCC_STACK_AUTO
14536 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
14537
14538 \end_inset
14539
14540
14541 \end_inset
14542 </cell>
14543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14544 \begin_inset Text
14545
14546 \layout Standard
14547
14548 when
14549 \emph on
14550 -
14551 \begin_inset ERT
14552 status Collapsed
14553
14554 \layout Standard
14555
14556 \backslash
14557 /
14558 \end_inset
14559
14560 -stack-auto
14561 \emph default
14562  option is used
14563 \end_inset
14564 </cell>
14565 </row>
14566 <row topline="true">
14567 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14568 \begin_inset Text
14569
14570 \layout Standard
14571
14572 SDCC_MODEL_SMALL
14573 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
14574
14575 \end_inset
14576
14577
14578 \end_inset
14579 </cell>
14580 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14581 \begin_inset Text
14582
14583 \layout Standard
14584
14585 when
14586 \emph on
14587 -
14588 \begin_inset ERT
14589 status Collapsed
14590
14591 \layout Standard
14592
14593 \backslash
14594 /
14595 \end_inset
14596
14597 -model-small
14598 \emph default
14599  is used
14600 \end_inset
14601 </cell>
14602 </row>
14603 <row topline="true">
14604 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14605 \begin_inset Text
14606
14607 \layout Standard
14608
14609 SDCC_MODEL_LARGE
14610 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
14611
14612 \end_inset
14613
14614
14615 \end_inset
14616 </cell>
14617 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14618 \begin_inset Text
14619
14620 \layout Standard
14621
14622 when
14623 \emph on
14624 -
14625 \begin_inset ERT
14626 status Collapsed
14627
14628 \layout Standard
14629
14630 \backslash
14631 /
14632 \end_inset
14633
14634 -model-large
14635 \emph default
14636  is used
14637 \end_inset
14638 </cell>
14639 </row>
14640 <row topline="true">
14641 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14642 \begin_inset Text
14643
14644 \layout Standard
14645
14646 SDCC_USE_XSTACK
14647 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
14648
14649 \end_inset
14650
14651
14652 \end_inset
14653 </cell>
14654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14655 \begin_inset Text
14656
14657 \layout Standard
14658
14659 when
14660 \emph on
14661 -
14662 \begin_inset ERT
14663 status Collapsed
14664
14665 \layout Standard
14666
14667 \backslash
14668 /
14669 \end_inset
14670
14671 -xstack
14672 \emph default
14673  option is used
14674 \end_inset
14675 </cell>
14676 </row>
14677 <row topline="true">
14678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14679 \begin_inset Text
14680
14681 \layout Standard
14682
14683 SDCC_STACK_TENBIT
14684 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
14685
14686 \end_inset
14687
14688
14689 \end_inset
14690 </cell>
14691 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14692 \begin_inset Text
14693
14694 \layout Standard
14695
14696 when
14697 \emph on
14698 -mds390
14699 \emph default
14700  is used
14701 \end_inset
14702 </cell>
14703 </row>
14704 <row topline="true" bottomline="true">
14705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14706 \begin_inset Text
14707
14708 \layout Standard
14709
14710 SDCC_MODEL_FLAT24
14711 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
14712
14713 \end_inset
14714
14715
14716 \end_inset
14717 </cell>
14718 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14719 \begin_inset Text
14720
14721 \layout Standard
14722
14723 when
14724 \emph on
14725 -mds390
14726 \emph default
14727  is used
14728 \end_inset
14729 </cell>
14730 </row>
14731 </lyxtabular>
14732
14733 \end_inset
14734
14735
14736 \layout Chapter
14737
14738 Notes on supported Processors
14739 \layout Section
14740
14741 MCS51 variants
14742 \begin_inset LatexCommand \label{sub:MCS51-variants}
14743
14744 \end_inset
14745
14746
14747 \begin_inset LatexCommand \index{MCS51 variants}
14748
14749 \end_inset
14750
14751
14752 \layout Standard
14753
14754 MCS51 processors are available from many vendors and come in many different
14755  flavours.
14756  While they might differ considerably in respect to Special Function Registers
14757  the core MCS51 is usually not modified or is kept compatible.
14758
14759 \layout Subsection
14760
14761 pdata access by SFR
14762 \layout Standard
14763
14764 With the upcome of devices with internal xdata and flash memory devices
14765  using port P2
14766 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14767
14768 \end_inset
14769
14770  as dedicated I/O port is becoming more popular.
14771  Switching the high byte for pdata
14772 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14773
14774 \end_inset
14775
14776  access which was formerly done by port P2 is then achieved by a Special
14777  Function Register
14778 \begin_inset LatexCommand \index{sfr}
14779
14780 \end_inset
14781
14782 .
14783  In well-established MCS51 tradition the address of this
14784 \emph on
14785 sfr
14786 \emph default
14787  is where the chip designers decided to put it.
14788  Needless to say that they didn't agree on a common name either.
14789  So that the startup code can correctly initialize xdata variables, you
14790  should define an sfr with the name _XPAGE
14791 \family typewriter
14792
14793 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
14794
14795 \end_inset
14796
14797
14798 \family default
14799  at the appropriate location if the default, port P2, is not used for this.
14800  Some examples are:
14801 \layout Verse
14802
14803
14804 \family typewriter
14805 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
14806 \layout Verse
14807
14808
14809 \family typewriter
14810 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
14811 \layout Verse
14812
14813
14814 \family typewriter
14815 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
14816 \layout Standard
14817
14818 For more exotic implementations further customizations may be needed.
14819  See section
14820 \begin_inset LatexCommand \ref{sub:Startup-Code}
14821
14822 \end_inset
14823
14824  for other possibilities.
14825 \layout Subsection
14826
14827 Other Features available by SFR
14828 \layout Standard
14829
14830 Some MCS51 variants offer features like Double DPTR
14831 \begin_inset LatexCommand \index{DPTR}
14832
14833 \end_inset
14834
14835 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
14836  These are currently not used for the MCS51 port.
14837  If you absolutely need them you can fall back to inline assembly or submit
14838  a patch to SDCC.
14839 \layout Section
14840
14841 DS400 port
14842 \layout Standard
14843
14844 The DS80C400 microcontroller has a rich set of peripherals.
14845  In its built-in ROM library it includes functions to access some of the
14846  features, among them is a TCP stack with IP4 and IP6 support.
14847  Library headers (currently in beta status) and other files are provided
14848  at
14849 \size footnotesize
14850
14851 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
14852
14853 \end_inset
14854
14855 .
14856
14857 \layout Section
14858
14859 The Z80 and gbz80 port
14860 \layout Standard
14861
14862 SDCC can target both the Zilog
14863 \begin_inset LatexCommand \index{Z80}
14864
14865 \end_inset
14866
14867  and the Nintendo Gameboy's Z80-like gbz80
14868 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
14869
14870 \end_inset
14871
14872 .
14873  The Z80 port is passed through the same
14874 \emph on
14875 regressions tests
14876 \begin_inset LatexCommand \index{Regression test}
14877
14878 \end_inset
14879
14880
14881 \emph default
14882  as the MCS51 and DS390 ports, so floating point support, support for long
14883  variables and bitfield support is fine.
14884  See mailing lists and forums about interrupt routines.
14885 \layout Standard
14886
14887 As always, the code is the authoritative reference - see z80/ralloc.c and
14888  z80/gen.c.
14889  The stack
14890 \begin_inset LatexCommand \index{stack}
14891
14892 \end_inset
14893
14894  frame is similar to that generated by the IAR Z80 compiler.
14895  IX is used as the base pointer, HL and IY are used as a temporary registers,
14896  and BC and DE are available for holding variables.
14897  Return values
14898 \begin_inset LatexCommand \index{return value}
14899
14900 \end_inset
14901
14902  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
14903  bytes).
14904  The gbz80 port use the same set of registers for the return values, but
14905  in a different order of significance: E (one byte), DE (two bytes), or
14906  HLDE (four bytes).
14907 \layout Section
14908
14909 The HC08 port
14910 \layout Standard
14911
14912 The port to the Motorola HC08
14913 \begin_inset LatexCommand \index{HC08}
14914
14915 \end_inset
14916
14917  family has been added in October 2003, and is still undergoing some basic
14918  development.
14919  The code generator is complete, but the register allocation is still quite
14920  unoptimized.
14921  Some of the SDCC's standard C library functions have embedded non-HC08
14922  inline assembly and so are not yet usable.
14923 \newline
14924
14925 \newline
14926
14927 \layout Section
14928
14929 The PIC14 port
14930 \layout Standard
14931
14932 The 14bit PIC
14933 \begin_inset LatexCommand \index{PIC14}
14934
14935 \end_inset
14936
14937  port still requires a major effort from the development community.
14938  However it can work for very simple code.
14939 \layout Subsection
14940
14941 C code and 14bit PIC code page
14942 \begin_inset LatexCommand \index{code page (pic14)}
14943
14944 \end_inset
14945
14946  and RAM banks
14947 \begin_inset LatexCommand \index{RAM bank (pic14)}
14948
14949 \end_inset
14950
14951
14952 \layout Standard
14953
14954 The linker organizes allocation for the code page and RAM banks.
14955  It does not have intimate knowledge of the code flow.
14956  It will put all the code section of a single asm file into a single code
14957  page.
14958  In order to make use of multiple code pages, separate asm files must be
14959  used.
14960  The compiler treats all functions of a single C file as being in the same
14961  code page unless it is non static.
14962  The compiler treats all local variables of a single C file as being in
14963  the same RAM bank unless it is an extern.
14964 \newline
14965
14966 \newline
14967 To get the best follow these guide lines:
14968 \layout Enumerate
14969
14970 make local functions static, as non static functions require code page selection
14971  overhead.
14972 \layout Enumerate
14973
14974 Make local variables static as extern variables require RAM bank selection
14975  overhead.
14976 \layout Enumerate
14977
14978 For devices that have multiple code pages it is more efficient to use the
14979  same number of files as pages, i.e.
14980  for the 16F877 use 4 separate files and i.e.
14981  for the 16F874 use 2 separate files.
14982  This way the linker can put the code for each file into different code
14983  pages and the compiler can allocate reusable variables more efficiently
14984  and there's less page selection overhead.
14985  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
14986  instruction set) use 'unsigned char' whereever possible instead of 'int'.
14987 \layout Subsection
14988
14989 Creating a device include file
14990 \layout Standard
14991
14992 For generating a device include file use the support perl script inc2h.pl
14993  kept in directory support/script.
14994 \layout Subsection
14995
14996 Interrupt code
14997 \layout Standard
14998
14999 For the interrupt function, use the keyword 'interrupt'
15000 \begin_inset LatexCommand \index{interrupt}
15001
15002 \end_inset
15003
15004  with level number of 0 (PIC14 only has 1 interrupt so this number is only
15005  there to avoid a syntax error - it ought to be fixed).
15006  E.g.:
15007 \layout Verse
15008
15009
15010 \family typewriter
15011 void Intr(void) interrupt 0
15012 \newline
15013 {
15014 \newline
15015 \SpecialChar ~
15016 \SpecialChar ~
15017 T0IF = 0; /* Clear timer interrupt */
15018 \newline
15019 }
15020 \layout Subsection
15021
15022 Linking and assembling
15023 \layout Standard
15024
15025 For assembling you can use either GPUTILS'
15026 \begin_inset LatexCommand \index{gputils (pic tools)}
15027
15028 \end_inset
15029
15030  gpasm.exe or MPLAB's mpasmwin.exe.
15031  GPUTILS is available from
15032 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
15033
15034 \end_inset
15035
15036 .
15037  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
15038  If you use MPLAB and an interrupt function then the linker script file
15039  vectors section will need to be enlarged to link with mplink.
15040 \newline
15041
15042 \newline
15043 Here is a
15044 \family typewriter
15045 Makefile
15046 \family default
15047  using GPUTILS:
15048 \layout Verse
15049
15050
15051 \family typewriter
15052 .c.o:
15053 \newline
15054 \SpecialChar ~
15055 \SpecialChar ~
15056 \SpecialChar ~
15057 \SpecialChar ~
15058 \SpecialChar ~
15059 \SpecialChar ~
15060 \SpecialChar ~
15061 \SpecialChar ~
15062 sdcc -S -V -mpic14 -p16F877 $<
15063 \newline
15064 \SpecialChar ~
15065 \SpecialChar ~
15066 \SpecialChar ~
15067 \SpecialChar ~
15068 \SpecialChar ~
15069 \SpecialChar ~
15070 \SpecialChar ~
15071 \SpecialChar ~
15072 gpasm -c $*.asm
15073 \newline
15074
15075 \newline
15076 $(PRJ).hex: $(OBJS)
15077 \newline
15078 \SpecialChar ~
15079 \SpecialChar ~
15080 \SpecialChar ~
15081 \SpecialChar ~
15082 \SpecialChar ~
15083 \SpecialChar ~
15084 \SpecialChar ~
15085 \SpecialChar ~
15086 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
15087 \layout Standard
15088
15089 Here is a
15090 \family typewriter
15091 Makefile
15092 \family default
15093  using MPLAB:
15094 \layout Verse
15095
15096
15097 \family typewriter
15098 .c.o:
15099 \newline
15100 \SpecialChar ~
15101 \SpecialChar ~
15102 \SpecialChar ~
15103 \SpecialChar ~
15104 \SpecialChar ~
15105 \SpecialChar ~
15106 \SpecialChar ~
15107 \SpecialChar ~
15108 sdcc -S -V -mpic14 -p16F877 $<
15109 \newline
15110 \SpecialChar ~
15111 \SpecialChar ~
15112 \SpecialChar ~
15113 \SpecialChar ~
15114 \SpecialChar ~
15115 \SpecialChar ~
15116 \SpecialChar ~
15117 \SpecialChar ~
15118 mpasmwin /q /o $*.asm
15119 \newline
15120
15121 \newline
15122 $(PRJ).hex: $(OBJS)
15123 \newline
15124 \SpecialChar ~
15125 \SpecialChar ~
15126 \SpecialChar ~
15127 \SpecialChar ~
15128 \SpecialChar ~
15129 \SpecialChar ~
15130 \SpecialChar ~
15131 \SpecialChar ~
15132 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
15133 \layout Standard
15134
15135 Please note that indentations within a
15136 \family typewriter
15137  Makefile
15138 \family default
15139  have to be done with a tabulator character.
15140 \layout Section
15141
15142 The PIC16
15143 \begin_inset LatexCommand \index{PIC16}
15144
15145 \end_inset
15146
15147  port
15148 \layout Standard
15149
15150 The PIC16
15151 \begin_inset LatexCommand \index{PIC16}
15152
15153 \end_inset
15154
15155  port is the portion of SDCC that is responsible to produce code for the
15156  Microchip
15157 \begin_inset LatexCommand \index{Microchip}
15158
15159 \end_inset
15160
15161 (TM) microcontrollers with 16 bit core.
15162  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
15163 \layout Subsection
15164
15165 Global Options
15166 \layout Standard
15167
15168 PIC16 port supports the standard command line arguments as supposed, with
15169  the exception of certain cases that will be mentioned in the following
15170  list:
15171 \layout List
15172 \labelwidthstring 00.00.0000
15173
15174 -
15175 \begin_inset ERT
15176 status Collapsed
15177
15178 \layout Standard
15179
15180 \backslash
15181 /
15182 \end_inset
15183
15184 -stack-auto Auto variables that are function parameters, will be saved on
15185  stack by default.
15186
15187 \emph on
15188 There is no need to specify this in the command line.
15189 \layout List
15190 \labelwidthstring 00.00.0000
15191
15192 -
15193 \begin_inset ERT
15194 status Collapsed
15195
15196 \layout Standard
15197
15198 \backslash
15199 /
15200 \end_inset
15201
15202 -float-reent All floating point functions are reentrant by default.
15203
15204 \emph on
15205 There is no need to specifiy this in the command line.
15206 \layout List
15207 \labelwidthstring 00.00.0000
15208
15209 -
15210 \begin_inset ERT
15211 status Collapsed
15212
15213 \layout Standard
15214
15215 \backslash
15216 /
15217 \end_inset
15218
15219 -callee-saves See -
15220 \begin_inset ERT
15221 status Collapsed
15222
15223 \layout Standard
15224
15225 \backslash
15226 /
15227 \end_inset
15228
15229 -all-callee-saves
15230 \layout List
15231 \labelwidthstring 00.00.0000
15232
15233 -
15234 \begin_inset ERT
15235 status Collapsed
15236
15237 \layout Standard
15238
15239 \backslash
15240 /
15241 \end_inset
15242
15243 -all-callee-saves All function arguments are passed on stack by default.
15244
15245 \emph on
15246 There is no need to specify this in the command line.
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 -fommit-frame-pointer Frame pointer will be omitted when the function uses
15261  no local variables.
15262 \layout Subsection
15263
15264 Port Specific Options
15265 \begin_inset LatexCommand \index{Options PIC16}
15266
15267 \end_inset
15268
15269
15270 \layout Standard
15271
15272 The port specific options appear after the global options in the sdcc --help
15273  output.
15274 \layout Subsubsection
15275
15276 General Options
15277 \layout Standard
15278
15279 General options enable certain port features and optimizations.
15280 \layout List
15281 \labelwidthstring 00.00.0000
15282
15283 -
15284 \begin_inset ERT
15285 status Collapsed
15286
15287 \layout Standard
15288
15289 \backslash
15290 /
15291 \end_inset
15292
15293 -pgen-bank Instructs the port to insert BANKSEL directives before instructions
15294  that use the Bank Select Register (BSR).
15295 \layout List
15296 \labelwidthstring 00.00.0000
15297
15298 -
15299 \begin_inset ERT
15300 status Collapsed
15301
15302 \layout Standard
15303
15304 \backslash
15305 /
15306 \end_inset
15307
15308 -pomit-config-words Instructs the port to omit the generation of the configurati
15309 on words.
15310 \layout List
15311 \labelwidthstring 00.00.0000
15312
15313 -
15314 \begin_inset ERT
15315 status Collapsed
15316
15317 \layout Standard
15318
15319 \backslash
15320 /
15321 \end_inset
15322
15323 -pomit-ivt Instructs the port to omit the generation of the interrupt vectors
15324 \layout List
15325 \labelwidthstring 00.00.0000
15326
15327 -
15328 \begin_inset ERT
15329 status Collapsed
15330
15331 \layout Standard
15332
15333 \backslash
15334 /
15335 \end_inset
15336
15337 -pleave-reset-vector Used in conjuction with the previous command, instructs
15338  the port NOT to omit the reset vector.
15339 \layout List
15340 \labelwidthstring 00.00.0000
15341
15342 -
15343 \begin_inset ERT
15344 status Collapsed
15345
15346 \layout Standard
15347
15348 \backslash
15349 /
15350 \end_inset
15351
15352 -stack-model=[model] Used in conjuction with the command above.
15353  Defines the stack model to be used, valid stack models are :
15354 \begin_deeper
15355 \layout List
15356 \labelwidthstring 00.00.0000
15357
15358
15359 \emph on
15360 small
15361 \emph default
15362  Selects small stack model.
15363  8 bit stack and frame pointers.
15364  Supports 256 bytes stack size.
15365 \layout List
15366 \labelwidthstring 00.00.0000
15367
15368
15369 \emph on
15370 large
15371 \emph default
15372  Selects large stack model.
15373  16 bit stack and frame pointers.
15374  Supports 65536 bytes stack size.
15375 \end_deeper
15376 \layout List
15377 \labelwidthstring 00.00.0000
15378
15379 -
15380 \begin_inset ERT
15381 status Collapsed
15382
15383 \layout Standard
15384
15385 \backslash
15386 /
15387 \end_inset
15388
15389 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
15390  unitialized data variables with [kword].
15391  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
15392 \layout List
15393 \labelwidthstring 00.00.0000
15394
15395 -
15396 \begin_inset ERT
15397 status Collapsed
15398
15399 \layout Standard
15400
15401 \backslash
15402 /
15403 \end_inset
15404
15405 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
15406  Useful for bootloaders.
15407 \layout List
15408 \labelwidthstring 00.00.0000
15409
15410 -
15411 \begin_inset ERT
15412 status Collapsed
15413
15414 \layout Standard
15415
15416 \backslash
15417 /
15418 \end_inset
15419
15420 -asm= sets the full path and name of an external assembler to call.
15421 \layout List
15422 \labelwidthstring 00.00.0000
15423
15424 -
15425 \begin_inset ERT
15426 status Collapsed
15427
15428 \layout Standard
15429
15430 \backslash
15431 /
15432 \end_inset
15433
15434 -link= sets the full path and name of an external linker to call.
15435 \layout Subsubsection
15436
15437 Debugging Options
15438 \layout Standard
15439
15440 Debugging options enable extra debugging information in the output files.
15441 \layout List
15442 \labelwidthstring 00.00.0000
15443
15444 -
15445 \begin_inset ERT
15446 status Collapsed
15447
15448 \layout Standard
15449
15450 \backslash
15451 /
15452 \end_inset
15453
15454 -debug-xtra Similar to -
15455 \begin_inset ERT
15456 status Collapsed
15457
15458 \layout Standard
15459
15460 \backslash
15461 /
15462 \end_inset
15463
15464 -debug
15465 \begin_inset LatexCommand \index{-\/-debug}
15466
15467 \end_inset
15468
15469 , but dumps more information.
15470 \layout List
15471 \labelwidthstring 00.00.0000
15472
15473 -
15474 \begin_inset ERT
15475 status Collapsed
15476
15477 \layout Standard
15478
15479 \backslash
15480 /
15481 \end_inset
15482
15483 -debug-ralloc Force register allocator to dump <source>.d file with debugging
15484  information.
15485  <source> is the name of the file compiled.
15486 \layout List
15487 \labelwidthstring 00.00.0000
15488
15489 -
15490 \begin_inset ERT
15491 status Collapsed
15492
15493 \layout Standard
15494
15495 \backslash
15496 /
15497 \end_inset
15498
15499 -pcode-verbose Enable pcode debugging information in translation.
15500 \layout Subsection
15501
15502 Preprocessor Macros
15503 \layout Standard
15504
15505 PIC16 port defines the following preprocessor macros while translating a
15506  source.
15507 \layout Standard
15508 \align center
15509
15510 \begin_inset  Tabular
15511 <lyxtabular version="3" rows="2" columns="2">
15512 <features>
15513 <column alignment="center" valignment="top" leftline="true" width="0">
15514 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15515 <row topline="true" bottomline="true">
15516 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15517 \begin_inset Text
15518
15519 \layout Standard
15520
15521 Macro
15522 \end_inset
15523 </cell>
15524 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15525 \begin_inset Text
15526
15527 \layout Standard
15528
15529 Description
15530 \end_inset
15531 </cell>
15532 </row>
15533 <row topline="true" bottomline="true">
15534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15535 \begin_inset Text
15536
15537 \layout Standard
15538
15539 pic18fxxxx
15540 \end_inset
15541 </cell>
15542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15543 \begin_inset Text
15544
15545 \layout Standard
15546
15547 MCU Identification.
15548
15549 \emph on
15550 xxxx
15551 \emph default
15552  is the microcontrol identification number, i.e.
15553  452, 6620, etc
15554 \end_inset
15555 </cell>
15556 </row>
15557 </lyxtabular>
15558
15559 \end_inset
15560
15561
15562 \layout Subsection
15563
15564 Directories
15565 \layout Standard
15566
15567 PIC16
15568 \begin_inset LatexCommand \index{PIC16}
15569
15570 \end_inset
15571
15572  port uses the following directories for searching header files and libraries.
15573 \layout Standard
15574 \align center
15575
15576 \begin_inset  Tabular
15577 <lyxtabular version="3" rows="3" columns="4">
15578 <features>
15579 <column alignment="center" valignment="top" leftline="true" width="0">
15580 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15581 <column alignment="center" valignment="top" width="0">
15582 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15583 <row topline="true" bottomline="true">
15584 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15585 \begin_inset Text
15586
15587 \layout Standard
15588
15589 Directory
15590 \end_inset
15591 </cell>
15592 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15593 \begin_inset Text
15594
15595 \layout Standard
15596
15597 Description
15598 \end_inset
15599 </cell>
15600 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15601 \begin_inset Text
15602
15603 \layout Standard
15604
15605 Target
15606 \end_inset
15607 </cell>
15608 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15609 \begin_inset Text
15610
15611 \layout Standard
15612
15613 Command prefix
15614 \end_inset
15615 </cell>
15616 </row>
15617 <row topline="true">
15618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15619 \begin_inset Text
15620
15621 \layout Standard
15622
15623 PREFIX/sdcc/include/pic16
15624 \end_inset
15625 </cell>
15626 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15627 \begin_inset Text
15628
15629 \layout Standard
15630
15631 PIC16 specific headers
15632 \end_inset
15633 </cell>
15634 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15635 \begin_inset Text
15636
15637 \layout Standard
15638
15639 Compiler
15640 \end_inset
15641 </cell>
15642 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15643 \begin_inset Text
15644
15645 \layout Standard
15646
15647 -I
15648 \end_inset
15649 </cell>
15650 </row>
15651 <row topline="true" bottomline="true">
15652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15653 \begin_inset Text
15654
15655 \layout Standard
15656
15657 PREFIX/sdcc/lib/pic16
15658 \end_inset
15659 </cell>
15660 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15661 \begin_inset Text
15662
15663 \layout Standard
15664
15665 PIC16 specific libraries
15666 \end_inset
15667 </cell>
15668 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15669 \begin_inset Text
15670
15671 \layout Standard
15672
15673 Linker
15674 \end_inset
15675 </cell>
15676 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15677 \begin_inset Text
15678
15679 \layout Standard
15680
15681 -L
15682 \end_inset
15683 </cell>
15684 </row>
15685 </lyxtabular>
15686
15687 \end_inset
15688
15689
15690 \layout Subsection
15691
15692 Pragmas
15693 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
15694
15695 \end_inset
15696
15697
15698 \layout Standard
15699
15700 PIC16 port currently supports the following pragmas:
15701 \layout List
15702 \labelwidthstring 00.00.0000
15703
15704 stack pragma stack forces the code generator to initialize the stack & frame
15705  pointers at a specific address.
15706  This is an adhoc solution since gplink does not support yet stack.
15707  When the gplink issue is resolved the pragma will be deprecated
15708 \begin_inset Foot
15709 collapsed true
15710
15711 \layout Standard
15712
15713
15714 \emph on
15715 It is important to initialize the stack, otherwise strange things can happen.
15716  Stack is not initialized by default because there are some sources that
15717  do not require it.
15718  (like library sources)
15719 \end_inset
15720
15721 .
15722 \newline
15723 The stack pragma should be used only once in a project.
15724  Multiple pragmas may result in indeterminate behaviour of the program.
15725 \layout LyX-Code
15726
15727 Example:
15728 \layout LyX-Code
15729
15730 \layout LyX-Code
15731
15732 /* initializes stack at RAM address 0x5ff */
15733 \layout LyX-Code
15734
15735 #pragma stack 0x5ff
15736 \layout List
15737 \labelwidthstring 00.00.0000
15738
15739 udata pragma udata instructs the compiler to emit code so that linker will
15740  place a variable at a specific memory bank
15741 \layout LyX-Code
15742
15743 Example:
15744 \layout LyX-Code
15745
15746 \layout LyX-Code
15747
15748 /* places variable foo at bank2 */
15749 \layout LyX-Code
15750
15751 #pragma udata bank2 foo
15752 \layout LyX-Code
15753
15754 char foo;
15755 \layout Standard
15756
15757 In order for this pragma to work there are some changes that must be made
15758  in the .lkr script used in link stage.
15759  In the following example a sample .lkr file is shown:
15760 \layout LyX-Code
15761
15762 \layout LyX-Code
15763
15764 // Sample linker script for the PIC18F452 processor
15765 \layout LyX-Code
15766
15767 LIBPATH .
15768 \layout LyX-Code
15769
15770 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
15771 \layout LyX-Code
15772
15773 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
15774 \layout LyX-Code
15775
15776 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
15777 \layout LyX-Code
15778
15779 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
15780 \layout LyX-Code
15781
15782 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
15783 \layout LyX-Code
15784
15785 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
15786 \layout LyX-Code
15787
15788 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
15789 \layout LyX-Code
15790
15791 \layout LyX-Code
15792
15793 DATABANK   NAME=gpr0       START=0x80           END=0xFF
15794 \layout LyX-Code
15795
15796 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
15797 \layout LyX-Code
15798
15799 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
15800 \layout LyX-Code
15801
15802 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
15803 \layout LyX-Code
15804
15805 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
15806 \layout LyX-Code
15807
15808 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
15809 \layout LyX-Code
15810
15811 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
15812 \layout LyX-Code
15813
15814 \layout LyX-Code
15815
15816 SECTION    NAME=CONFIG     ROM=config
15817 \layout LyX-Code
15818
15819 \layout LyX-Code
15820
15821 SECTION    NAME=bank0      RAM=gpr0
15822 \layout LyX-Code
15823
15824 SECTION    NAME=bank1      RAM=gpr1
15825 \layout LyX-Code
15826
15827 SECTION    NAME=bank2      RAM=gpr2
15828 \layout LyX-Code
15829
15830 SECTION    NAME=bank3      RAM=gpr3
15831 \layout LyX-Code
15832
15833 SECTION    NAME=bank4      RAM=gpr4
15834 \layout LyX-Code
15835
15836 SECTION    NAME=bank5      RAM=gpr5
15837 \layout Standard
15838
15839 The linker will recognise the section name set in the pragma statement and
15840  will position the variable at the memory bank set with the RAM field at
15841  the SECTION line in the linker script file.
15842 \layout Subsection
15843
15844 Header Files
15845 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
15846
15847 \end_inset
15848
15849
15850 \layout Standard
15851
15852 There is one main header file that can be included to the source files using
15853  the pic16 port.
15854  That file is the
15855 \series bold
15856 pic18fregs.h
15857 \series default
15858 .
15859  This header file contains the definitions for the processor special registers,
15860  so it is necessary if the source accesses them.
15861  It can be included by adding the following line in the beginning of the
15862  file:
15863 \layout LyX-Code
15864
15865 #include <pic18fregs.h>
15866 \layout Standard
15867
15868 The specific microcontroller is selected within the pic18fregs.h automatically,
15869  so the same source can be used with a variety of devices.
15870 \layout Subsection
15871
15872 Libraries
15873 \layout Standard
15874
15875 The libraries that PIC16
15876 \begin_inset LatexCommand \index{PIC16}
15877
15878 \end_inset
15879
15880  port depends on are the microcontroller device libraries which contain
15881  the symbol definitions for the microcontroller special function registers.
15882  These libraries have the format pic18fxxxx.lib, where
15883 \emph on
15884 xxxx
15885 \emph default
15886  is the microcontroller identification number.
15887  The specific library is selected automatically by the compiler at link
15888  stage according to the selected device.
15889 \layout Standard
15890
15891 Libraries are created with gplib which is part of the gputils package
15892 \begin_inset LatexCommand \url{http://gputils.sourceforge.net}
15893
15894 \end_inset
15895
15896 .
15897 \layout Subsection
15898
15899 Memory Models
15900 \layout Standard
15901
15902 The following memory models are supported by the PIC16 port:
15903 \layout Itemize
15904
15905 small model
15906 \layout Itemize
15907
15908 large model
15909 \layout Standard
15910
15911 Memory model affects the default size of pointers within the source.
15912  The sizes are shown in the next table:
15913 \layout Standard
15914 \align center
15915
15916 \begin_inset  Tabular
15917 <lyxtabular version="3" rows="3" columns="3">
15918 <features>
15919 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15920 <column alignment="center" valignment="top" leftline="true" width="0">
15921 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15922 <row topline="true" bottomline="true">
15923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15924 \begin_inset Text
15925
15926 \layout Standard
15927
15928 Pointer sizes according to memory model
15929 \end_inset
15930 </cell>
15931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15932 \begin_inset Text
15933
15934 \layout Standard
15935
15936 small model
15937 \end_inset
15938 </cell>
15939 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15940 \begin_inset Text
15941
15942 \layout Standard
15943
15944 large model
15945 \end_inset
15946 </cell>
15947 </row>
15948 <row topline="true" bottomline="true">
15949 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15950 \begin_inset Text
15951
15952 \layout Standard
15953
15954 code pointers
15955 \end_inset
15956 </cell>
15957 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15958 \begin_inset Text
15959
15960 \layout Standard
15961
15962 16-bits
15963 \end_inset
15964 </cell>
15965 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15966 \begin_inset Text
15967
15968 \layout Standard
15969
15970 24-bits
15971 \end_inset
15972 </cell>
15973 </row>
15974 <row topline="true" bottomline="true">
15975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15976 \begin_inset Text
15977
15978 \layout Standard
15979
15980 data pointers
15981 \end_inset
15982 </cell>
15983 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
15984 \begin_inset Text
15985
15986 \layout Standard
15987
15988 16-bits
15989 \end_inset
15990 </cell>
15991 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15992 \begin_inset Text
15993
15994 \layout Standard
15995
15996 16-bits
15997 \end_inset
15998 </cell>
15999 </row>
16000 </lyxtabular>
16001
16002 \end_inset
16003
16004
16005 \layout Standard
16006
16007 It is advisable that all sources within a project are compiled with the
16008  same memory model.
16009  If one wants to override the default memory model, this can be done by
16010  declaring a pointer as
16011 \series bold
16012 far
16013 \series default
16014  or
16015 \series bold
16016 near
16017 \series default
16018 .
16019  Far selects large memory model's pointers, while near selects small memory
16020  model's pointers.
16021 \layout Standard
16022
16023 The standard device libraries (see
16024 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
16025
16026 \end_inset
16027
16028 ) contain no reference to pointers, so they can be used with both memory
16029  models.
16030 \layout Subsection
16031
16032 Stack
16033 \layout Standard
16034
16035 The stack implementation for the PIC16 port uses two indirect registers,
16036  FSR1 and FSR2.
16037 \layout List
16038 \labelwidthstring 00.00.0000
16039
16040 FSR1 is assigned as stack pointer
16041 \layout List
16042 \labelwidthstring 00.00.0000
16043
16044 FSR2 is assigned as frame pointer
16045 \layout Standard
16046
16047 The following stack models are supported by the PIC16 port
16048 \layout Itemize
16049
16050 small model
16051 \layout Itemize
16052
16053 large model
16054 \layout Standard
16055
16056
16057 \noun on
16058 Small
16059 \noun default
16060  model means that only the FSRxL byte is used to access stack and frame,
16061  while
16062 \emph on
16063 \noun on
16064 large
16065 \emph default
16066 \noun default
16067  uses both FSRxL and FSRxH registers.
16068  The following table shows the stack/frame pointers sizes according to stack
16069  model and the maximum space they can address:
16070 \layout Standard
16071 \align center
16072
16073 \begin_inset  Tabular
16074 <lyxtabular version="3" rows="3" columns="3">
16075 <features>
16076 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16077 <column alignment="center" valignment="top" leftline="true" width="0">
16078 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16079 <row topline="true" bottomline="true">
16080 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16081 \begin_inset Text
16082
16083 \layout Standard
16084
16085 Stack & Frame pointer sizes according to stack model
16086 \end_inset
16087 </cell>
16088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16089 \begin_inset Text
16090
16091 \layout Standard
16092
16093 small
16094 \end_inset
16095 </cell>
16096 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16097 \begin_inset Text
16098
16099 \layout Standard
16100
16101 large
16102 \end_inset
16103 </cell>
16104 </row>
16105 <row topline="true">
16106 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16107 \begin_inset Text
16108
16109 \layout Standard
16110
16111 Stack pointer FSR1
16112 \end_inset
16113 </cell>
16114 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16115 \begin_inset Text
16116
16117 \layout Standard
16118
16119 8-bits
16120 \end_inset
16121 </cell>
16122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16123 \begin_inset Text
16124
16125 \layout Standard
16126
16127 16-bits
16128 \end_inset
16129 </cell>
16130 </row>
16131 <row topline="true" bottomline="true">
16132 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16133 \begin_inset Text
16134
16135 \layout Standard
16136
16137 Frame pointer FSR2
16138 \end_inset
16139 </cell>
16140 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16141 \begin_inset Text
16142
16143 \layout Standard
16144
16145 8-bits
16146 \end_inset
16147 </cell>
16148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16149 \begin_inset Text
16150
16151 \layout Standard
16152
16153 16-bits
16154 \end_inset
16155 </cell>
16156 </row>
16157 </lyxtabular>
16158
16159 \end_inset
16160
16161
16162 \layout Standard
16163
16164
16165 \series bold
16166 Currently stack and frame pointers should be initialized explicit by the
16167  user at the desired Data RAM position (see
16168 \begin_inset LatexCommand \ref{sub:PIC16_Pragmas}
16169
16170 \end_inset
16171
16172  Pragma stack).
16173  Uninitialized stack and frame pointers can result in unexpected behavior
16174  of the resulting binary.
16175 \layout Subsection
16176
16177 Function return values
16178 \layout Standard
16179
16180 Return values from functions are placed to the appropriate registers following
16181  a modified Microchip policy optimized for SDCC.
16182  The following table shows these registers:
16183 \layout Standard
16184 \align center
16185
16186 \begin_inset  Tabular
16187 <lyxtabular version="3" rows="6" columns="2">
16188 <features>
16189 <column alignment="center" valignment="top" leftline="true" width="0">
16190 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16191 <row topline="true" bottomline="true">
16192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16193 \begin_inset Text
16194
16195 \layout Standard
16196
16197 size
16198 \end_inset
16199 </cell>
16200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16201 \begin_inset Text
16202
16203 \layout Standard
16204
16205 destination register
16206 \end_inset
16207 </cell>
16208 </row>
16209 <row topline="true">
16210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16211 \begin_inset Text
16212
16213 \layout Standard
16214
16215 8 bits
16216 \end_inset
16217 </cell>
16218 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16219 \begin_inset Text
16220
16221 \layout Standard
16222
16223 WREG
16224 \end_inset
16225 </cell>
16226 </row>
16227 <row topline="true">
16228 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16229 \begin_inset Text
16230
16231 \layout Standard
16232
16233 16 bits
16234 \end_inset
16235 </cell>
16236 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16237 \begin_inset Text
16238
16239 \layout Standard
16240
16241 PRODL:WREG
16242 \end_inset
16243 </cell>
16244 </row>
16245 <row topline="true">
16246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16247 \begin_inset Text
16248
16249 \layout Standard
16250
16251 24 bits
16252 \end_inset
16253 </cell>
16254 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16255 \begin_inset Text
16256
16257 \layout Standard
16258
16259 PRODH:PRODL:WREG
16260 \end_inset
16261 </cell>
16262 </row>
16263 <row topline="true">
16264 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16265 \begin_inset Text
16266
16267 \layout Standard
16268
16269 32 bits
16270 \end_inset
16271 </cell>
16272 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16273 \begin_inset Text
16274
16275 \layout Standard
16276
16277 FSR0L:PRODH:PRODL:WREG
16278 \end_inset
16279 </cell>
16280 </row>
16281 <row topline="true" bottomline="true">
16282 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16283 \begin_inset Text
16284
16285 \layout Standard
16286
16287 >32 bits
16288 \end_inset
16289 </cell>
16290 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16291 \begin_inset Text
16292
16293 \layout Standard
16294
16295 on stack, FSR0 points to the beginning
16296 \end_inset
16297 </cell>
16298 </row>
16299 </lyxtabular>
16300
16301 \end_inset
16302
16303
16304 \layout Subsection
16305
16306 Interrupts
16307 \layout Standard
16308
16309 When entering an interrupt, currently the PIC16
16310 \begin_inset LatexCommand \index{PIC16}
16311
16312 \end_inset
16313
16314  port automatically saves the following registers:
16315 \layout Itemize
16316
16317 WREG
16318 \layout Itemize
16319
16320 STATUS
16321 \layout Itemize
16322
16323 BSR
16324 \layout Itemize
16325
16326 PROD (PRODL and PRODH)
16327 \layout Itemize
16328
16329 FSR0 (FSR0L and FSR0H)
16330 \layout Standard
16331
16332 These registers are restored upon return from the interrupt routine.
16333
16334 \layout Standard
16335
16336 When entering a high priority interrupt WREG, STATUS and BSR are not explicit
16337  saved by software.
16338  The hardware shadow registers for WREG, STATUS and BSR are used in these
16339  cases.
16340 \layout Standard
16341
16342
16343 \begin_inset Foot
16344 collapsed false
16345
16346 \layout Standard
16347
16348 NOTE that when the _naked attribute is specified for an interrupt routine,
16349  then NO registers are stored or restored.
16350 \end_inset
16351
16352 .
16353 \layout Chapter
16354
16355 Debugging with SDCDB
16356 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
16357
16358 \end_inset
16359
16360
16361 \begin_inset LatexCommand \index{sdcdb (debugger)}
16362
16363 \end_inset
16364
16365
16366 \layout Standard
16367
16368 SDCC is distributed with a source level debugger
16369 \begin_inset LatexCommand \index{Debugger}
16370
16371 \end_inset
16372
16373 .
16374  The debugger uses a command line interface, the command repertoire of the
16375  debugger has been kept as close to gdb
16376 \begin_inset LatexCommand \index{gdb}
16377
16378 \end_inset
16379
16380  (the GNU debugger) as possible.
16381  The configuration and build process is part of the standard compiler installati
16382 on, which also builds and installs the debugger in the target directory
16383  specified during configuration.
16384  The debugger allows you debug BOTH at the C source and at the ASM source
16385  level.
16386  Sdcdb is available on Unix platforms only.
16387 \layout Section
16388
16389 Compiling for Debugging
16390 \layout Standard
16391
16392 The -
16393 \begin_inset ERT
16394 status Collapsed
16395
16396 \layout Standard
16397
16398 \backslash
16399 /
16400 \end_inset
16401
16402 -debug
16403 \begin_inset LatexCommand \index{-\/-debug}
16404
16405 \end_inset
16406
16407  option must be specified for all files for which debug information is to
16408  be generated.
16409  The complier generates a .adb file for each of these files.
16410  The linker creates the .cdb
16411 \begin_inset LatexCommand \index{<file>.cdb}
16412
16413 \end_inset
16414
16415  file from the .adb
16416 \begin_inset LatexCommand \index{<file>.adb}
16417
16418 \end_inset
16419
16420  files and the address information.
16421  This .cdb is used by the debugger.
16422 \layout Section
16423
16424 How the Debugger Works
16425 \layout Standard
16426
16427 When the -
16428 \begin_inset ERT
16429 status Collapsed
16430
16431 \layout Standard
16432
16433 \backslash
16434 /
16435 \end_inset
16436
16437 -debug option is specified the compiler generates extra symbol information
16438  some of which are put into the assembler source and some are put into the
16439  .adb file.
16440   Then the linker creates the .cdb file from the individual .adb files with
16441  the address information for the symbols.
16442  The debugger reads the symbolic information generated by the compiler &
16443  the address information generated by the linker.
16444  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
16445  execution is controlled by the debugger.
16446  When a command is issued for the debugger, it translates it into appropriate
16447  commands for the simulator.
16448 \layout Section
16449
16450 Starting the Debugger
16451 \layout Standard
16452
16453 The debugger can be started using the following command line.
16454  (Assume the file you are debugging has the file name foo).
16455 \newline
16456
16457 \newline
16458
16459 \family sans
16460 \series bold
16461 sdcdb foo
16462 \newline
16463
16464 \family default
16465 \series default
16466
16467 \newline
16468 The debugger will look for the following files.
16469 \layout Itemize
16470
16471 foo.c - the source file.
16472 \layout Itemize
16473
16474 foo.cdb - the debugger symbol information file.
16475 \layout Itemize
16476
16477 foo.ihx - the Intel hex format
16478 \begin_inset LatexCommand \index{Intel hex format}
16479
16480 \end_inset
16481
16482  object file.
16483 \layout Section
16484
16485 Command Line Options.
16486 \layout Itemize
16487
16488 -
16489 \begin_inset ERT
16490 status Collapsed
16491
16492 \layout Standard
16493
16494 \backslash
16495 /
16496 \end_inset
16497
16498 -directory=<source file directory> this option can used to specify the directory
16499  search list.
16500  The debugger will look into the directory list specified for source, cdb
16501  & ihx files.
16502  The items in the directory list must be separated by ':', e.g.
16503  if the source files can be in the directories /home/src1 and /home/src2,
16504  the -
16505 \begin_inset ERT
16506 status Collapsed
16507
16508 \layout Standard
16509
16510 \backslash
16511 /
16512 \end_inset
16513
16514 -directory option should be -
16515 \begin_inset ERT
16516 status Collapsed
16517
16518 \layout Standard
16519
16520 \backslash
16521 /
16522 \end_inset
16523
16524 -directory=/home/src1:/home/src2.
16525  Note there can be no spaces in the option.
16526
16527 \layout Itemize
16528
16529 -cd <directory> - change to the <directory>.
16530 \layout Itemize
16531
16532 -fullname - used by GUI front ends.
16533 \layout Itemize
16534
16535 -cpu <cpu-type> - this argument is passed to the simulator please see the
16536  simulator docs for details.
16537 \layout Itemize
16538
16539 -X <Clock frequency > this options is passed to the simulator please see
16540  the simulator docs for details.
16541 \layout Itemize
16542
16543 -s <serial port file> passed to simulator see the simulator docs for details.
16544 \layout Itemize
16545
16546 -S <serial in,out> passed to simulator see the simulator docs for details.
16547 \layout Itemize
16548
16549 -k <port number> passed to simulator see the simulator docs for details.
16550 \layout Section
16551
16552 Debugger Commands.
16553 \layout Standard
16554
16555 As mentioned earlier the command interface for the debugger has been deliberatel
16556 y kept as close the GNU debugger gdb, as possible.
16557  This will help the integration with existing graphical user interfaces
16558  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
16559  If you use a graphical user interface for the debugger you can skip the
16560  next sections.
16561 \layout Subsubsection*
16562
16563 break [line | file:line | function | file:function]
16564 \layout Standard
16565
16566 Set breakpoint at specified line or function:
16567 \newline
16568
16569 \newline
16570
16571 \family sans
16572 \series bold
16573 sdcdb>break 100
16574 \newline
16575 sdcdb>break foo.c:100
16576 \newline
16577 sdcdb>break funcfoo
16578 \newline
16579 sdcdb>break foo.c:funcfoo
16580 \layout Subsubsection*
16581
16582 clear [line | file:line | function | file:function ]
16583 \layout Standard
16584
16585 Clear breakpoint at specified line or function:
16586 \newline
16587
16588 \newline
16589
16590 \family sans
16591 \series bold
16592 sdcdb>clear 100
16593 \newline
16594 sdcdb>clear foo.c:100
16595 \newline
16596 sdcdb>clear funcfoo
16597 \newline
16598 sdcdb>clear foo.c:funcfoo
16599 \layout Subsubsection*
16600
16601 continue
16602 \layout Standard
16603
16604 Continue program being debugged, after breakpoint.
16605 \layout Subsubsection*
16606
16607 finish
16608 \layout Standard
16609
16610 Execute till the end of the current function.
16611 \layout Subsubsection*
16612
16613 delete [n]
16614 \layout Standard
16615
16616 Delete breakpoint number 'n'.
16617  If used without any option clear ALL user defined break points.
16618 \layout Subsubsection*
16619
16620 info [break | stack | frame | registers ]
16621 \layout Itemize
16622
16623 info break - list all breakpoints
16624 \layout Itemize
16625
16626 info stack - show the function call stack.
16627 \layout Itemize
16628
16629 info frame - show information about the current execution frame.
16630 \layout Itemize
16631
16632 info registers - show content of all registers.
16633 \layout Subsubsection*
16634
16635 step
16636 \layout Standard
16637
16638 Step program until it reaches a different source line.
16639  Note: pressing <return> repeats the last command.
16640 \layout Subsubsection*
16641
16642 next
16643 \layout Standard
16644
16645 Step program, proceeding through subroutine calls.
16646 \layout Subsubsection*
16647
16648 run
16649 \layout Standard
16650
16651 Start debugged program.
16652 \layout Subsubsection*
16653
16654 ptype variable
16655 \layout Standard
16656
16657 Print type information of the variable.
16658 \layout Subsubsection*
16659
16660 print variable
16661 \layout Standard
16662
16663 print value of variable.
16664 \layout Subsubsection*
16665
16666 file filename
16667 \layout Standard
16668
16669 load the given file name.
16670  Note this is an alternate method of loading file for debugging.
16671 \layout Subsubsection*
16672
16673 frame
16674 \layout Standard
16675
16676 print information about current frame.
16677 \layout Subsubsection*
16678
16679 set srcmode
16680 \layout Standard
16681
16682 Toggle between C source & assembly source.
16683 \layout Subsubsection*
16684
16685 ! simulator command
16686 \layout Standard
16687
16688 Send the string following '!' to the simulator, the simulator response is
16689  displayed.
16690  Note the debugger does not interpret the command being sent to the simulator,
16691  so if a command like 'go' is sent the debugger can loose its execution
16692  context and may display incorrect values.
16693 \layout Subsubsection*
16694
16695 quit
16696 \layout Standard
16697
16698 "Watch me now.
16699  Iam going Down.
16700  My name is Bobby Brown"
16701 \layout Section
16702
16703 Interfacing with XEmacs
16704 \begin_inset LatexCommand \index{XEmacs}
16705
16706 \end_inset
16707
16708
16709 \begin_inset LatexCommand \index{Emacs}
16710
16711 \end_inset
16712
16713 .
16714 \layout Standard
16715
16716 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
16717  sdcdb.el and sdcdbsrc.el.
16718  These two files can be found in the $(prefix)/bin directory after the installat
16719 ion is complete.
16720  These files need to be loaded into XEmacs for the interface to work.
16721  This can be done at XEmacs startup time by inserting the following into
16722  your '.xemacs' file (which can be found in your HOME directory):
16723 \newline
16724
16725 \newline
16726
16727 \family typewriter
16728 (load-file sdcdbsrc.el)
16729 \family default
16730
16731 \newline
16732
16733 \newline
16734 .xemacs is a lisp file so the () around the command is REQUIRED.
16735  The files can also be loaded dynamically while XEmacs is running, set the
16736  environment variable 'EMACSLOADPATH' to the installation bin directory
16737  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
16738  To start the interface enter the following command:
16739 \newline
16740
16741 \newline
16742
16743 \family sans
16744 \series bold
16745 ESC-x sdcdbsrc
16746 \family default
16747 \series default
16748
16749 \newline
16750
16751 \newline
16752 You will prompted to enter the file name to be debugged.
16753
16754 \newline
16755
16756 \newline
16757 The command line options that are passed to the simulator directly are bound
16758  to default values in the file sdcdbsrc.el.
16759  The variables are listed below, these values maybe changed as required.
16760 \layout Itemize
16761
16762 sdcdbsrc-cpu-type '51
16763 \layout Itemize
16764
16765 sdcdbsrc-frequency '11059200
16766 \layout Itemize
16767
16768 sdcdbsrc-serial nil
16769 \layout Standard
16770
16771 The following is a list of key mapping for the debugger interface.
16772 \layout Standard
16773
16774 \SpecialChar ~
16775
16776 \family typewriter
16777
16778 \newline
16779 ;;\SpecialChar ~
16780 Current Listing ::
16781 \newline
16782 ;;key\SpecialChar ~
16783 \SpecialChar ~
16784 \SpecialChar ~
16785 \SpecialChar ~
16786 \SpecialChar ~
16787 \SpecialChar ~
16788 \SpecialChar ~
16789 \SpecialChar ~
16790 \SpecialChar ~
16791 \SpecialChar ~
16792 \SpecialChar ~
16793 \SpecialChar ~
16794 \SpecialChar ~
16795 \SpecialChar ~
16796 binding\SpecialChar ~
16797 \SpecialChar ~
16798 \SpecialChar ~
16799 \SpecialChar ~
16800 \SpecialChar ~
16801 \SpecialChar ~
16802 \SpecialChar ~
16803 \SpecialChar ~
16804 \SpecialChar ~
16805 \SpecialChar ~
16806 \SpecialChar ~
16807 \SpecialChar ~
16808 \SpecialChar ~
16809 \SpecialChar ~
16810 \SpecialChar ~
16811 \SpecialChar ~
16812 \SpecialChar ~
16813 \SpecialChar ~
16814 \SpecialChar ~
16815 \SpecialChar ~
16816 \SpecialChar ~
16817 \SpecialChar ~
16818 Comment
16819 \newline
16820 ;;---\SpecialChar ~
16821 \SpecialChar ~
16822 \SpecialChar ~
16823 \SpecialChar ~
16824 \SpecialChar ~
16825 \SpecialChar ~
16826 \SpecialChar ~
16827 \SpecialChar ~
16828 \SpecialChar ~
16829 \SpecialChar ~
16830 \SpecialChar ~
16831 \SpecialChar ~
16832 \SpecialChar ~
16833 \SpecialChar ~
16834 -------\SpecialChar ~
16835 \SpecialChar ~
16836 \SpecialChar ~
16837 \SpecialChar ~
16838 \SpecialChar ~
16839 \SpecialChar ~
16840 \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 \SpecialChar ~
16856 -------
16857 \newline
16858 ;;
16859 \newline
16860 ;;\SpecialChar ~
16861 n\SpecialChar ~
16862 \SpecialChar ~
16863 \SpecialChar ~
16864 \SpecialChar ~
16865 \SpecialChar ~
16866 \SpecialChar ~
16867 \SpecialChar ~
16868 \SpecialChar ~
16869 \SpecialChar ~
16870 \SpecialChar ~
16871 \SpecialChar ~
16872 \SpecialChar ~
16873 \SpecialChar ~
16874 \SpecialChar ~
16875 \SpecialChar ~
16876 sdcdb-next-from-src\SpecialChar ~
16877 \SpecialChar ~
16878 \SpecialChar ~
16879 \SpecialChar ~
16880 \SpecialChar ~
16881 \SpecialChar ~
16882 \SpecialChar ~
16883 \SpecialChar ~
16884 \SpecialChar ~
16885 \SpecialChar ~
16886 SDCDB next command
16887 \newline
16888 ;;\SpecialChar ~
16889 b\SpecialChar ~
16890 \SpecialChar ~
16891 \SpecialChar ~
16892 \SpecialChar ~
16893 \SpecialChar ~
16894 \SpecialChar ~
16895 \SpecialChar ~
16896 \SpecialChar ~
16897 \SpecialChar ~
16898 \SpecialChar ~
16899 \SpecialChar ~
16900 \SpecialChar ~
16901 \SpecialChar ~
16902 \SpecialChar ~
16903 \SpecialChar ~
16904 sdcdb-back-from-src\SpecialChar ~
16905 \SpecialChar ~
16906 \SpecialChar ~
16907 \SpecialChar ~
16908 \SpecialChar ~
16909 \SpecialChar ~
16910 \SpecialChar ~
16911 \SpecialChar ~
16912 \SpecialChar ~
16913 \SpecialChar ~
16914 SDCDB back command
16915 \newline
16916 ;;\SpecialChar ~
16917 c\SpecialChar ~
16918 \SpecialChar ~
16919 \SpecialChar ~
16920 \SpecialChar ~
16921 \SpecialChar ~
16922 \SpecialChar ~
16923 \SpecialChar ~
16924 \SpecialChar ~
16925 \SpecialChar ~
16926 \SpecialChar ~
16927 \SpecialChar ~
16928 \SpecialChar ~
16929 \SpecialChar ~
16930 \SpecialChar ~
16931 \SpecialChar ~
16932 sdcdb-cont-from-src\SpecialChar ~
16933 \SpecialChar ~
16934 \SpecialChar ~
16935 \SpecialChar ~
16936 \SpecialChar ~
16937 \SpecialChar ~
16938 \SpecialChar ~
16939 \SpecialChar ~
16940 \SpecialChar ~
16941 \SpecialChar ~
16942 SDCDB continue command
16943 \newline
16944 ;;\SpecialChar ~
16945 s\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 sdcdb-step-from-src\SpecialChar ~
16961 \SpecialChar ~
16962 \SpecialChar ~
16963 \SpecialChar ~
16964 \SpecialChar ~
16965 \SpecialChar ~
16966 \SpecialChar ~
16967 \SpecialChar ~
16968 \SpecialChar ~
16969 \SpecialChar ~
16970 SDCDB step command
16971 \newline
16972 ;;\SpecialChar ~
16973 ?\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 sdcdb-whatis-c-sexp\SpecialChar ~
16989 \SpecialChar ~
16990 \SpecialChar ~
16991 \SpecialChar ~
16992 \SpecialChar ~
16993 \SpecialChar ~
16994 \SpecialChar ~
16995 \SpecialChar ~
16996 \SpecialChar ~
16997 \SpecialChar ~
16998 SDCDB ptypecommand for data at
16999 \newline
17000 ;;\SpecialChar ~
17001 \SpecialChar ~
17002 \SpecialChar ~
17003 \SpecialChar ~
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 buffer point
17048 \newline
17049 ;;\SpecialChar ~
17050 x\SpecialChar ~
17051 \SpecialChar ~
17052 \SpecialChar ~
17053 \SpecialChar ~
17054 \SpecialChar ~
17055 \SpecialChar ~
17056 \SpecialChar ~
17057 \SpecialChar ~
17058 \SpecialChar ~
17059 \SpecialChar ~
17060 \SpecialChar ~
17061 \SpecialChar ~
17062 \SpecialChar ~
17063 \SpecialChar ~
17064 \SpecialChar ~
17065 sdcdbsrc-delete\SpecialChar ~
17066 \SpecialChar ~
17067 \SpecialChar ~
17068 \SpecialChar ~
17069 \SpecialChar ~
17070 \SpecialChar ~
17071 \SpecialChar ~
17072 \SpecialChar ~
17073 \SpecialChar ~
17074 \SpecialChar ~
17075 \SpecialChar ~
17076 \SpecialChar ~
17077 \SpecialChar ~
17078 \SpecialChar ~
17079 SDCDB Delete all breakpoints if no arg
17080 \newline
17081 ;;\SpecialChar ~
17082 \SpecialChar ~
17083 \SpecialChar ~
17084 \SpecialChar ~
17085 \SpecialChar ~
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 given or delete arg (C-u arg x)
17129 \newline
17130 ;;\SpecialChar ~
17131 m\SpecialChar ~
17132 \SpecialChar ~
17133 \SpecialChar ~
17134 \SpecialChar ~
17135 \SpecialChar ~
17136 \SpecialChar ~
17137 \SpecialChar ~
17138 \SpecialChar ~
17139 \SpecialChar ~
17140 \SpecialChar ~
17141 \SpecialChar ~
17142 \SpecialChar ~
17143 \SpecialChar ~
17144 \SpecialChar ~
17145 \SpecialChar ~
17146 sdcdbsrc-frame\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 SDCDB Display current frame if no arg,
17162 \newline
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 \SpecialChar ~
17183 \SpecialChar ~
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 \SpecialChar ~
17201 \SpecialChar ~
17202 \SpecialChar ~
17203 \SpecialChar ~
17204 \SpecialChar ~
17205 \SpecialChar ~
17206 \SpecialChar ~
17207 \SpecialChar ~
17208 \SpecialChar ~
17209 \SpecialChar ~
17210 given or display frame arg
17211 \newline
17212 ;;\SpecialChar ~
17213 \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 \SpecialChar ~
17229 \SpecialChar ~
17230 \SpecialChar ~
17231 \SpecialChar ~
17232 \SpecialChar ~
17233 \SpecialChar ~
17234 \SpecialChar ~
17235 \SpecialChar ~
17236 \SpecialChar ~
17237 \SpecialChar ~
17238 \SpecialChar ~
17239 \SpecialChar ~
17240 \SpecialChar ~
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 buffer point
17260 \newline
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 sdcdbsrc-goto-sdcdb\SpecialChar ~
17278 \SpecialChar ~
17279 \SpecialChar ~
17280 \SpecialChar ~
17281 \SpecialChar ~
17282 \SpecialChar ~
17283 \SpecialChar ~
17284 \SpecialChar ~
17285 \SpecialChar ~
17286 \SpecialChar ~
17287 Goto the SDCDB output buffer
17288 \newline
17289 ;;\SpecialChar ~
17290 p\SpecialChar ~
17291 \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 sdcdb-print-c-sexp\SpecialChar ~
17306 \SpecialChar ~
17307 \SpecialChar ~
17308 \SpecialChar ~
17309 \SpecialChar ~
17310 \SpecialChar ~
17311 \SpecialChar ~
17312 \SpecialChar ~
17313 \SpecialChar ~
17314 \SpecialChar ~
17315 \SpecialChar ~
17316 SDCDB print command for data at
17317 \newline
17318 ;;\SpecialChar ~
17319 \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 \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 \SpecialChar ~
17351 \SpecialChar ~
17352 \SpecialChar ~
17353 \SpecialChar ~
17354 \SpecialChar ~
17355 \SpecialChar ~
17356 \SpecialChar ~
17357 \SpecialChar ~
17358 \SpecialChar ~
17359 \SpecialChar ~
17360 \SpecialChar ~
17361 \SpecialChar ~
17362 \SpecialChar ~
17363 \SpecialChar ~
17364 \SpecialChar ~
17365 buffer point
17366 \newline
17367 ;;\SpecialChar ~
17368 g\SpecialChar ~
17369 \SpecialChar ~
17370 \SpecialChar ~
17371 \SpecialChar ~
17372 \SpecialChar ~
17373 \SpecialChar ~
17374 \SpecialChar ~
17375 \SpecialChar ~
17376 \SpecialChar ~
17377 \SpecialChar ~
17378 \SpecialChar ~
17379 \SpecialChar ~
17380 \SpecialChar ~
17381 \SpecialChar ~
17382 \SpecialChar ~
17383 sdcdbsrc-goto-sdcdb\SpecialChar ~
17384 \SpecialChar ~
17385 \SpecialChar ~
17386 \SpecialChar ~
17387 \SpecialChar ~
17388 \SpecialChar ~
17389 \SpecialChar ~
17390 \SpecialChar ~
17391 \SpecialChar ~
17392 \SpecialChar ~
17393 Goto the SDCDB output buffer
17394 \newline
17395 ;;\SpecialChar ~
17396 t\SpecialChar ~
17397 \SpecialChar ~
17398 \SpecialChar ~
17399 \SpecialChar ~
17400 \SpecialChar ~
17401 \SpecialChar ~
17402 \SpecialChar ~
17403 \SpecialChar ~
17404 \SpecialChar ~
17405 \SpecialChar ~
17406 \SpecialChar ~
17407 \SpecialChar ~
17408 \SpecialChar ~
17409 \SpecialChar ~
17410 \SpecialChar ~
17411 sdcdbsrc-mode\SpecialChar ~
17412 \SpecialChar ~
17413 \SpecialChar ~
17414 \SpecialChar ~
17415 \SpecialChar ~
17416 \SpecialChar ~
17417 \SpecialChar ~
17418 \SpecialChar ~
17419 \SpecialChar ~
17420 \SpecialChar ~
17421 \SpecialChar ~
17422 \SpecialChar ~
17423 \SpecialChar ~
17424 \SpecialChar ~
17425 \SpecialChar ~
17426 \SpecialChar ~
17427 Toggles Sdcdbsrc mode (turns it off)
17428 \newline
17429 ;;
17430 \newline
17431 ;;\SpecialChar ~
17432 C-c\SpecialChar ~
17433 C-f\SpecialChar ~
17434 \SpecialChar ~
17435 \SpecialChar ~
17436 \SpecialChar ~
17437 \SpecialChar ~
17438 \SpecialChar ~
17439 \SpecialChar ~
17440 \SpecialChar ~
17441 \SpecialChar ~
17442 sdcdb-finish-from-src\SpecialChar ~
17443 \SpecialChar ~
17444 \SpecialChar ~
17445 \SpecialChar ~
17446 \SpecialChar ~
17447 \SpecialChar ~
17448 \SpecialChar ~
17449 \SpecialChar ~
17450 SDCDB finish command
17451 \newline
17452 ;;
17453 \newline
17454 ;;\SpecialChar ~
17455 C-x\SpecialChar ~
17456 SPC\SpecialChar ~
17457 \SpecialChar ~
17458 \SpecialChar ~
17459 \SpecialChar ~
17460 \SpecialChar ~
17461 \SpecialChar ~
17462 \SpecialChar ~
17463 \SpecialChar ~
17464 \SpecialChar ~
17465 sdcdb-break\SpecialChar ~
17466 \SpecialChar ~
17467 \SpecialChar ~
17468 \SpecialChar ~
17469 \SpecialChar ~
17470 \SpecialChar ~
17471 \SpecialChar ~
17472 \SpecialChar ~
17473 \SpecialChar ~
17474 \SpecialChar ~
17475 \SpecialChar ~
17476 \SpecialChar ~
17477 \SpecialChar ~
17478 \SpecialChar ~
17479 \SpecialChar ~
17480 \SpecialChar ~
17481 \SpecialChar ~
17482 \SpecialChar ~
17483 Set break for line with point
17484 \newline
17485 ;;\SpecialChar ~
17486 ESC\SpecialChar ~
17487 t\SpecialChar ~
17488 \SpecialChar ~
17489 \SpecialChar ~
17490 \SpecialChar ~
17491 \SpecialChar ~
17492 \SpecialChar ~
17493 \SpecialChar ~
17494 \SpecialChar ~
17495 \SpecialChar ~
17496 \SpecialChar ~
17497 \SpecialChar ~
17498 sdcdbsrc-mode\SpecialChar ~
17499 \SpecialChar ~
17500 \SpecialChar ~
17501 \SpecialChar ~
17502 \SpecialChar ~
17503 \SpecialChar ~
17504 \SpecialChar ~
17505 \SpecialChar ~
17506 \SpecialChar ~
17507 \SpecialChar ~
17508 \SpecialChar ~
17509 \SpecialChar ~
17510 \SpecialChar ~
17511 \SpecialChar ~
17512 \SpecialChar ~
17513 \SpecialChar ~
17514 Toggle Sdcdbsrc mode
17515 \newline
17516 ;;\SpecialChar ~
17517 ESC\SpecialChar ~
17518 m\SpecialChar ~
17519 \SpecialChar ~
17520 \SpecialChar ~
17521 \SpecialChar ~
17522 \SpecialChar ~
17523 \SpecialChar ~
17524 \SpecialChar ~
17525 \SpecialChar ~
17526 \SpecialChar ~
17527 \SpecialChar ~
17528 \SpecialChar ~
17529 sdcdbsrc-srcmode\SpecialChar ~
17530 \SpecialChar ~
17531 \SpecialChar ~
17532 \SpecialChar ~
17533 \SpecialChar ~
17534 \SpecialChar ~
17535 \SpecialChar ~
17536 \SpecialChar ~
17537 \SpecialChar ~
17538 \SpecialChar ~
17539 \SpecialChar ~
17540 \SpecialChar ~
17541 \SpecialChar ~
17542 Toggle list mode
17543 \newline
17544 ;;
17545 \newline
17546
17547 \layout Chapter
17548 \pagebreak_top
17549 TIPS
17550 \layout Standard
17551
17552 Here are a few guidelines that will help the compiler generate more efficient
17553  code, some of the tips are specific to this compiler others are generally
17554  good programming practice.
17555 \layout Itemize
17556
17557 Use the smallest data type to represent your data-value.
17558  If it is known in advance that the value is going to be less than 256 then
17559  use an 'unsigned char' instead of a 'short' or 'int'.
17560  Please note, that ANSI C requires both signed and unsigned chars to be
17561  promoted to 'signed int' before doing any operation.
17562  This promotion can be omitted, if the result is the same.
17563  The effect of the promotion rules together with the sign-extension is often
17564  surprising:
17565 \begin_deeper
17566 \layout Verse
17567
17568
17569 \family typewriter
17570 unsigned char uc = 0xfe;
17571 \newline
17572 if (uc * uc < 0) /* this is true! */
17573 \newline
17574 {
17575 \newline
17576 \SpecialChar ~
17577 \SpecialChar ~
17578 \SpecialChar ~
17579 \SpecialChar ~
17580 ....
17581 \newline
17582 }
17583 \layout Standard
17584
17585
17586 \family typewriter
17587 uc * uc
17588 \family default
17589  is evaluated as
17590 \family typewriter
17591 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
17592 \family default
17593 .
17594
17595 \newline
17596 Another one:
17597 \layout Verse
17598
17599
17600 \family typewriter
17601 (unsigned char) -12 / (signed char) -3 = ...
17602 \layout Standard
17603
17604 No, the result is not 4:
17605 \layout Verse
17606
17607
17608 \family typewriter
17609 (int) (unsigned char) -12 / (int) (signed char) -3 =
17610 \newline
17611 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
17612 \newline
17613 (int) 0x00f4 / (int) 0xfffd =
17614 \newline
17615 (int) 0x00f4 / (int) 0xfffd =
17616 \newline
17617 (int) 244 / (int) -3 =
17618 \newline
17619 (int) -81 = (int) 0xffaf;
17620 \layout Standard
17621
17622 Don't complain, that gcc gives you a different result.
17623  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
17624  Therefore the results are different.
17625 \newline
17626 From
17627 \begin_inset Quotes sld
17628 \end_inset
17629
17630 comp.lang.c FAQ
17631 \begin_inset Quotes srd
17632 \end_inset
17633
17634 :
17635 \layout Quote
17636
17637 If well-defined overflow characteristics are important and negative values
17638  are not, or if you want to steer clear of sign-extension problems when
17639  manipulating bits or bytes, use one of the corresponding unsigned types.
17640  (Beware when mixing signed and unsigned values in expressions, though.)
17641 \newline
17642 Although character types (especially unsigned char) can be used as "tiny"
17643  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
17644 ble sign extension and increased code size.
17645 \end_deeper
17646 \layout Itemize
17647
17648 Use unsigned when it is known in advance that the value is not going to
17649  be negative.
17650  This helps especially if you are doing division or multiplication, bit-shifting
17651  or are using an array index.
17652 \layout Itemize
17653
17654 NEVER jump into a LOOP.
17655 \layout Itemize
17656
17657 Declare the variables to be local
17658 \begin_inset LatexCommand \index{local variables}
17659
17660 \end_inset
17661
17662  whenever possible, especially loop control variables (induction).
17663 \layout Itemize
17664
17665 Since the compiler does not always do implicit integral promotion, the programme
17666 r should do an explicit cast when integral promotion is required.
17667 \layout Itemize
17668
17669 Reducing the size of division, multiplication & modulus operations can reduce
17670  code size substantially.
17671  Take the following code for example.
17672 \begin_deeper
17673 \layout Verse
17674
17675
17676 \family typewriter
17677 foobar(unsigned int p1, unsigned char ch)
17678 \newline
17679 {
17680 \newline
17681 \SpecialChar ~
17682 \SpecialChar ~
17683 \SpecialChar ~
17684 \SpecialChar ~
17685 unsigned char ch1 = p1 % ch ;
17686 \newline
17687 \SpecialChar ~
17688 \SpecialChar ~
17689 \SpecialChar ~
17690 \SpecialChar ~
17691 ....
17692 \newline
17693 }
17694 \layout Standard
17695
17696 For the modulus operation the variable ch will be promoted to unsigned int
17697  first then the modulus operation will be performed (this will lead to a
17698  call to support routine _moduint()), and the result will be casted to a
17699  char.
17700  If the code is changed to
17701 \layout Verse
17702
17703
17704 \family typewriter
17705 foobar(unsigned int p1, unsigned char ch)
17706 \newline
17707 {
17708 \newline
17709 \SpecialChar ~
17710 \SpecialChar ~
17711 \SpecialChar ~
17712 \SpecialChar ~
17713 unsigned char ch1 = (unsigned char)p1 % ch ;
17714 \newline
17715 \SpecialChar ~
17716 \SpecialChar ~
17717 \SpecialChar ~
17718 \SpecialChar ~
17719 ....
17720 \newline
17721 }
17722 \layout Standard
17723
17724 It would substantially reduce the code generated (future versions of the
17725  compiler will be smart enough to detect such optimization opportunities).
17726 \end_deeper
17727 \layout Itemize
17728
17729 Have a look at the assembly listing to get a
17730 \begin_inset Quotes sld
17731 \end_inset
17732
17733 feeling
17734 \begin_inset Quotes srd
17735 \end_inset
17736
17737  for the code generation.
17738 \layout Section
17739
17740 Tools
17741 \begin_inset LatexCommand \index{Tools}
17742
17743 \end_inset
17744
17745  included in the distribution
17746 \layout Standard
17747 \align center
17748
17749 \begin_inset  Tabular
17750 <lyxtabular version="3" rows="12" columns="3">
17751 <features>
17752 <column alignment="center" valignment="top" leftline="true" width="0pt">
17753 <column alignment="center" valignment="top" leftline="true" width="0pt">
17754 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
17755 <row topline="true" bottomline="true">
17756 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17757 \begin_inset Text
17758
17759 \layout Standard
17760
17761 Name
17762 \end_inset
17763 </cell>
17764 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17765 \begin_inset Text
17766
17767 \layout Standard
17768
17769 Purpose
17770 \end_inset
17771 </cell>
17772 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17773 \begin_inset Text
17774
17775 \layout Standard
17776
17777 Directory
17778 \end_inset
17779 </cell>
17780 </row>
17781 <row topline="true">
17782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17783 \begin_inset Text
17784
17785 \layout Standard
17786
17787 uCsim
17788 \end_inset
17789 </cell>
17790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17791 \begin_inset Text
17792
17793 \layout Standard
17794
17795 Simulator for various architectures
17796 \end_inset
17797 </cell>
17798 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17799 \begin_inset Text
17800
17801 \layout Standard
17802
17803 sdcc/sim/ucsim
17804 \end_inset
17805 </cell>
17806 </row>
17807 <row topline="true">
17808 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17809 \begin_inset Text
17810
17811 \layout Standard
17812
17813 keil2sdcc.pl
17814 \end_inset
17815 </cell>
17816 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17817 \begin_inset Text
17818
17819 \layout Standard
17820
17821 header file conversion
17822 \end_inset
17823 </cell>
17824 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17825 \begin_inset Text
17826
17827 \layout Standard
17828
17829 sdcc/support/scripts
17830 \end_inset
17831 </cell>
17832 </row>
17833 <row topline="true">
17834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17835 \begin_inset Text
17836
17837 \layout Standard
17838
17839 mh2h.c
17840 \end_inset
17841 </cell>
17842 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17843 \begin_inset Text
17844
17845 \layout Standard
17846
17847 header file conversion
17848 \end_inset
17849 </cell>
17850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17851 \begin_inset Text
17852
17853 \layout Standard
17854
17855 sdcc/support/scripts
17856 \end_inset
17857 </cell>
17858 </row>
17859 <row topline="true">
17860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17861 \begin_inset Text
17862
17863 \layout Standard
17864
17865 as-gbz80
17866 \end_inset
17867 </cell>
17868 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17869 \begin_inset Text
17870
17871 \layout Standard
17872
17873 Assembler
17874 \end_inset
17875 </cell>
17876 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17877 \begin_inset Text
17878
17879 \layout Standard
17880
17881
17882 \family roman
17883 \series medium
17884 \shape up
17885 \size normal
17886 \emph off
17887 \bar no
17888 \noun off
17889 \color none
17890 sdcc/bin
17891 \end_inset
17892 </cell>
17893 </row>
17894 <row topline="true">
17895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17896 \begin_inset Text
17897
17898 \layout Standard
17899
17900 as-z80
17901 \end_inset
17902 </cell>
17903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17904 \begin_inset Text
17905
17906 \layout Standard
17907
17908 Assembler
17909 \end_inset
17910 </cell>
17911 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17912 \begin_inset Text
17913
17914 \layout Standard
17915
17916
17917 \family roman
17918 \series medium
17919 \shape up
17920 \size normal
17921 \emph off
17922 \bar no
17923 \noun off
17924 \color none
17925 sdcc/bin
17926 \end_inset
17927 </cell>
17928 </row>
17929 <row topline="true">
17930 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17931 \begin_inset Text
17932
17933 \layout Standard
17934
17935 asx8051
17936 \end_inset
17937 </cell>
17938 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17939 \begin_inset Text
17940
17941 \layout Standard
17942
17943 Assembler
17944 \end_inset
17945 </cell>
17946 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17947 \begin_inset Text
17948
17949 \layout Standard
17950
17951
17952 \family roman
17953 \series medium
17954 \shape up
17955 \size normal
17956 \emph off
17957 \bar no
17958 \noun off
17959 \color none
17960 sdcc/bin
17961 \end_inset
17962 </cell>
17963 </row>
17964 <row topline="true">
17965 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17966 \begin_inset Text
17967
17968 \layout Standard
17969
17970 sdcdb
17971 \end_inset
17972 </cell>
17973 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17974 \begin_inset Text
17975
17976 \layout Standard
17977
17978 Simulator
17979 \end_inset
17980 </cell>
17981 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17982 \begin_inset Text
17983
17984 \layout Standard
17985
17986
17987 \family roman
17988 \series medium
17989 \shape up
17990 \size normal
17991 \emph off
17992 \bar no
17993 \noun off
17994 \color none
17995 sdcc/bin
17996 \end_inset
17997 </cell>
17998 </row>
17999 <row topline="true">
18000 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18001 \begin_inset Text
18002
18003 \layout Standard
18004
18005 aslink
18006 \end_inset
18007 </cell>
18008 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18009 \begin_inset Text
18010
18011 \layout Standard
18012
18013 Linker
18014 \end_inset
18015 </cell>
18016 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18017 \begin_inset Text
18018
18019 \layout Standard
18020
18021
18022 \family roman
18023 \series medium
18024 \shape up
18025 \size normal
18026 \emph off
18027 \bar no
18028 \noun off
18029 \color none
18030 sdcc/bin
18031 \end_inset
18032 </cell>
18033 </row>
18034 <row topline="true">
18035 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18036 \begin_inset Text
18037
18038 \layout Standard
18039
18040 link-z80
18041 \end_inset
18042 </cell>
18043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18044 \begin_inset Text
18045
18046 \layout Standard
18047
18048 Linker
18049 \end_inset
18050 </cell>
18051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18052 \begin_inset Text
18053
18054 \layout Standard
18055
18056
18057 \family roman
18058 \series medium
18059 \shape up
18060 \size normal
18061 \emph off
18062 \bar no
18063 \noun off
18064 \color none
18065 sdcc/bin
18066 \end_inset
18067 </cell>
18068 </row>
18069 <row topline="true">
18070 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18071 \begin_inset Text
18072
18073 \layout Standard
18074
18075 link-gbz80
18076 \end_inset
18077 </cell>
18078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18079 \begin_inset Text
18080
18081 \layout Standard
18082
18083 Linker
18084 \end_inset
18085 </cell>
18086 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18087 \begin_inset Text
18088
18089 \layout Standard
18090
18091
18092 \family roman
18093 \series medium
18094 \shape up
18095 \size normal
18096 \emph off
18097 \bar no
18098 \noun off
18099 \color none
18100 sdcc/bin
18101 \end_inset
18102 </cell>
18103 </row>
18104 <row topline="true" bottomline="true">
18105 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18106 \begin_inset Text
18107
18108 \layout Standard
18109
18110 packihx
18111 \end_inset
18112 </cell>
18113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18114 \begin_inset Text
18115
18116 \layout Standard
18117
18118 ihx packer
18119 \end_inset
18120 </cell>
18121 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18122 \begin_inset Text
18123
18124 \layout Standard
18125
18126
18127 \family roman
18128 \series medium
18129 \shape up
18130 \size normal
18131 \emph off
18132 \bar no
18133 \noun off
18134 \color none
18135 sdcc/bin
18136 \end_inset
18137 </cell>
18138 </row>
18139 </lyxtabular>
18140
18141 \end_inset
18142
18143
18144 \newline
18145
18146 \layout Section
18147
18148 Documentation
18149 \begin_inset LatexCommand \index{Documentation}
18150
18151 \end_inset
18152
18153  included in the distribution
18154 \layout Standard
18155 \align center
18156
18157 \begin_inset  Tabular
18158 <lyxtabular version="3" rows="10" columns="2">
18159 <features>
18160 <column alignment="left" valignment="top" leftline="true" width="0">
18161 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
18162 <row topline="true" bottomline="true">
18163 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18164 \begin_inset Text
18165
18166 \layout Standard
18167
18168 Subject / Title
18169 \end_inset
18170 </cell>
18171 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18172 \begin_inset Text
18173
18174 \layout Standard
18175
18176 Where to get / filename
18177 \end_inset
18178 </cell>
18179 </row>
18180 <row topline="true">
18181 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18182 \begin_inset Text
18183
18184 \layout Standard
18185
18186 SDCC Compiler User Guide
18187 \end_inset
18188 </cell>
18189 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18190 \begin_inset Text
18191
18192 \layout Standard
18193
18194 You're reading it right now
18195 \end_inset
18196 </cell>
18197 </row>
18198 <row topline="true">
18199 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18200 \begin_inset Text
18201
18202 \layout Standard
18203
18204 Changelog of SDCC
18205 \end_inset
18206 </cell>
18207 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18208 \begin_inset Text
18209
18210 \layout Standard
18211
18212 sdcc/Changelog
18213 \end_inset
18214 </cell>
18215 </row>
18216 <row topline="true">
18217 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18218 \begin_inset Text
18219
18220 \layout Standard
18221
18222 ASXXXX
18223 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
18224
18225 \end_inset
18226
18227
18228 \begin_inset LatexCommand \index{Assembler documentation}
18229
18230 \end_inset
18231
18232  Assemblers and ASLINK
18233 \begin_inset LatexCommand \index{aslink}
18234
18235 \end_inset
18236
18237
18238 \begin_inset LatexCommand \index{Linker documentation}
18239
18240 \end_inset
18241
18242  Relocating Linker
18243 \end_inset
18244 </cell>
18245 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18246 \begin_inset Text
18247
18248 \layout Standard
18249
18250 sdcc/as/doc/asxhtm.html
18251 \end_inset
18252 </cell>
18253 </row>
18254 <row topline="true">
18255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18256 \begin_inset Text
18257
18258 \layout Standard
18259
18260 SDCC regression test
18261 \begin_inset LatexCommand \index{Regression test}
18262
18263 \end_inset
18264
18265
18266 \end_inset
18267 </cell>
18268 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18269 \begin_inset Text
18270
18271 \layout Standard
18272
18273 sdcc/doc/test_suite_spec.pdf
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 Various notes
18284 \end_inset
18285 </cell>
18286 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18287 \begin_inset Text
18288
18289 \layout Standard
18290
18291 sdcc/doc/*
18292 \end_inset
18293 </cell>
18294 </row>
18295 <row topline="true">
18296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18297 \begin_inset Text
18298
18299 \layout Standard
18300
18301 Notes on debugging with sdcdb
18302 \begin_inset LatexCommand \index{sdcdb (debugger)}
18303
18304 \end_inset
18305
18306
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/debugger/README
18315 \end_inset
18316 </cell>
18317 </row>
18318 <row topline="true">
18319 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18320 \begin_inset Text
18321
18322 \layout Standard
18323
18324 Software simulator for microcontrollers
18325 \end_inset
18326 </cell>
18327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18328 \begin_inset Text
18329
18330 \layout Standard
18331
18332
18333 \family roman
18334 \series medium
18335 \shape up
18336 \size normal
18337 \emph off
18338 \bar no
18339 \noun off
18340 \color none
18341 sdcc/sim/ucsim/doc
18342 \family default
18343 \series default
18344 \shape default
18345 \size default
18346 \emph default
18347 \bar default
18348 \noun default
18349 \color default
18350 /index.html
18351 \end_inset
18352 </cell>
18353 </row>
18354 <row topline="true">
18355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18356 \begin_inset Text
18357
18358 \layout Standard
18359
18360 Temporary notes on the pic16
18361 \begin_inset LatexCommand \index{PIC16}
18362
18363 \end_inset
18364
18365  port
18366 \end_inset
18367 </cell>
18368 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18369 \begin_inset Text
18370
18371 \layout Standard
18372
18373 sdcc/src/pic16/NOTES
18374 \end_inset
18375 </cell>
18376 </row>
18377 <row topline="true" bottomline="true">
18378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18379 \begin_inset Text
18380
18381 \layout Standard
18382
18383 SDCC internal documentation (debugging file format)
18384 \end_inset
18385 </cell>
18386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18387 \begin_inset Text
18388
18389 \layout Standard
18390
18391 sdcc/doc/
18392 \family roman
18393 \series medium
18394 \shape up
18395 \size normal
18396 \emph off
18397 \bar no
18398 \noun off
18399 \color none
18400 cdbfileformat.pd
18401 \family default
18402 \series default
18403 \shape default
18404 \size default
18405 \emph default
18406 \bar default
18407 \noun default
18408 \color default
18409 f
18410 \end_inset
18411 </cell>
18412 </row>
18413 </lyxtabular>
18414
18415 \end_inset
18416
18417
18418 \newline
18419
18420 \layout Section
18421
18422 Related open source tools
18423 \begin_inset LatexCommand \index{Related tools}
18424
18425 \end_inset
18426
18427
18428 \layout Standard
18429 \align center
18430
18431 \begin_inset  Tabular
18432 <lyxtabular version="3" rows="11" columns="3">
18433 <features>
18434 <column alignment="center" valignment="top" leftline="true" width="0pt">
18435 <column alignment="block" valignment="top" leftline="true" width="30line%">
18436 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18437 <row topline="true" bottomline="true">
18438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18439 \begin_inset Text
18440
18441 \layout Standard
18442
18443 Name
18444 \end_inset
18445 </cell>
18446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18447 \begin_inset Text
18448
18449 \layout Standard
18450
18451 Purpose
18452 \end_inset
18453 </cell>
18454 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18455 \begin_inset Text
18456
18457 \layout Standard
18458
18459 Where to get
18460 \end_inset
18461 </cell>
18462 </row>
18463 <row topline="true">
18464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18465 \begin_inset Text
18466
18467 \layout Standard
18468
18469 gpsim
18470 \begin_inset LatexCommand \index{gpsim (pic simulator)}
18471
18472 \end_inset
18473
18474
18475 \end_inset
18476 </cell>
18477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18478 \begin_inset Text
18479
18480 \layout Standard
18481
18482 PIC simulator
18483 \end_inset
18484 </cell>
18485 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18486 \begin_inset Text
18487
18488 \layout Standard
18489
18490
18491 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
18492
18493 \end_inset
18494
18495
18496 \end_inset
18497 </cell>
18498 </row>
18499 <row topline="true">
18500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18501 \begin_inset Text
18502
18503 \layout Standard
18504
18505 gputils
18506 \begin_inset LatexCommand \index{gputils (pic tools)}
18507
18508 \end_inset
18509
18510
18511 \end_inset
18512 </cell>
18513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18514 \begin_inset Text
18515
18516 \layout Standard
18517
18518 GNU PIC utilities
18519 \end_inset
18520 </cell>
18521 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18522 \begin_inset Text
18523
18524 \layout Standard
18525
18526
18527 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
18528
18529 \end_inset
18530
18531
18532 \end_inset
18533 </cell>
18534 </row>
18535 <row topline="true">
18536 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18537 \begin_inset Text
18538
18539 \layout Standard
18540
18541 flP5
18542 \end_inset
18543 </cell>
18544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18545 \begin_inset Text
18546
18547 \layout Standard
18548
18549 PIC programmer
18550 \end_inset
18551 </cell>
18552 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18553 \begin_inset Text
18554
18555 \layout Standard
18556
18557
18558 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
18559
18560 \end_inset
18561
18562
18563 \end_inset
18564 </cell>
18565 </row>
18566 <row topline="true">
18567 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18568 \begin_inset Text
18569
18570 \layout Standard
18571
18572 indent
18573 \begin_inset LatexCommand \index{indent (source formatting tool)}
18574
18575 \end_inset
18576
18577
18578 \end_inset
18579 </cell>
18580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18581 \begin_inset Text
18582
18583 \layout Standard
18584
18585 Formats C source - Master of the white spaces
18586 \end_inset
18587 </cell>
18588 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18589 \begin_inset Text
18590
18591 \layout Standard
18592
18593
18594 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
18595
18596 \end_inset
18597
18598
18599 \end_inset
18600 </cell>
18601 </row>
18602 <row topline="true">
18603 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18604 \begin_inset Text
18605
18606 \layout Standard
18607
18608 srecord
18609 \begin_inset LatexCommand \index{srecord (tool)}
18610
18611 \end_inset
18612
18613
18614 \end_inset
18615 </cell>
18616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18617 \begin_inset Text
18618
18619 \layout Standard
18620
18621 Object file conversion, checksumming, ...
18622 \end_inset
18623 </cell>
18624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18625 \begin_inset Text
18626
18627 \layout Standard
18628
18629
18630 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
18631
18632 \end_inset
18633
18634
18635 \end_inset
18636 </cell>
18637 </row>
18638 <row topline="true">
18639 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18640 \begin_inset Text
18641
18642 \layout Standard
18643
18644 objdump
18645 \begin_inset LatexCommand \index{objdump (tool)}
18646
18647 \end_inset
18648
18649
18650 \end_inset
18651 </cell>
18652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18653 \begin_inset Text
18654
18655 \layout Standard
18656
18657 Object file conversion, ...
18658 \end_inset
18659 </cell>
18660 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18661 \begin_inset Text
18662
18663 \layout Standard
18664
18665 Part of binutils (should be there anyway)
18666 \end_inset
18667 </cell>
18668 </row>
18669 <row topline="true">
18670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18671 \begin_inset Text
18672
18673 \layout Standard
18674
18675 doxygen
18676 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
18677
18678 \end_inset
18679
18680
18681 \end_inset
18682 </cell>
18683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18684 \begin_inset Text
18685
18686 \layout Standard
18687
18688 Source code documentation system
18689 \end_inset
18690 </cell>
18691 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18692 \begin_inset Text
18693
18694 \layout Standard
18695
18696
18697 \begin_inset LatexCommand \url{http://www.doxygen.org}
18698
18699 \end_inset
18700
18701
18702 \end_inset
18703 </cell>
18704 </row>
18705 <row topline="true">
18706 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18707 \begin_inset Text
18708
18709 \layout Standard
18710
18711 kdevelop
18712 \end_inset
18713 </cell>
18714 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18715 \begin_inset Text
18716
18717 \layout Standard
18718
18719 IDE (has anyone tried integrating SDCC & sdcdb? 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.kdevelop.org}
18729
18730 \end_inset
18731
18732
18733 \end_inset
18734 </cell>
18735 </row>
18736 <row topline="true">
18737 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18738 \begin_inset Text
18739
18740 \layout Standard
18741
18742 splint
18743 \begin_inset LatexCommand \index{splint (syntax checking tool)}
18744
18745 \end_inset
18746
18747
18748 \end_inset
18749 </cell>
18750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18751 \begin_inset Text
18752
18753 \layout Standard
18754
18755 Statically checks c sources (has anyone adapted splint for SDCC?)
18756 \end_inset
18757 </cell>
18758 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18759 \begin_inset Text
18760
18761 \layout Standard
18762
18763
18764 \begin_inset LatexCommand \url{http://www.splint.org}
18765
18766 \end_inset
18767
18768
18769 \end_inset
18770 </cell>
18771 </row>
18772 <row topline="true" bottomline="true">
18773 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18774 \begin_inset Text
18775
18776 \layout Standard
18777
18778 ddd
18779 \begin_inset LatexCommand \index{ddd (debugger)}
18780
18781 \end_inset
18782
18783
18784 \end_inset
18785 </cell>
18786 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18787 \begin_inset Text
18788
18789 \layout Standard
18790
18791 Debugger, serves nicely as GUI to sdcdb
18792 \begin_inset LatexCommand \index{sdcdb (debugger)}
18793
18794 \end_inset
18795
18796  (Unix only)
18797 \end_inset
18798 </cell>
18799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18800 \begin_inset Text
18801
18802 \layout Standard
18803
18804
18805 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
18806
18807 \end_inset
18808
18809
18810 \end_inset
18811 </cell>
18812 </row>
18813 </lyxtabular>
18814
18815 \end_inset
18816
18817
18818 \newline
18819
18820 \layout Section
18821
18822 Related documentation / recommended reading
18823 \layout Standard
18824 \align center
18825
18826 \begin_inset  Tabular
18827 <lyxtabular version="3" rows="6" columns="3">
18828 <features>
18829 <column alignment="center" valignment="top" leftline="true" width="0pt">
18830 <column alignment="block" valignment="top" leftline="true" width="30line%">
18831 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18832 <row topline="true" bottomline="true">
18833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18834 \begin_inset Text
18835
18836 \layout Standard
18837
18838 Name
18839 \end_inset
18840 </cell>
18841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18842 \begin_inset Text
18843
18844 \layout Standard
18845
18846 Subject / Title
18847 \end_inset
18848 </cell>
18849 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18850 \begin_inset Text
18851
18852 \layout Standard
18853
18854 Where to get
18855 \end_inset
18856 </cell>
18857 </row>
18858 <row topline="true">
18859 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18860 \begin_inset Text
18861
18862 \layout Standard
18863
18864
18865 \family roman
18866 \series medium
18867 \shape up
18868 \size normal
18869 \emph off
18870 \bar no
18871 \noun off
18872 \color none
18873 c-refcard.pdf
18874 \end_inset
18875 </cell>
18876 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18877 \begin_inset Text
18878
18879 \layout Standard
18880
18881 C Reference Card
18882 \begin_inset LatexCommand \index{C Reference card}
18883
18884 \end_inset
18885
18886 , 2 pages
18887 \end_inset
18888 </cell>
18889 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18890 \begin_inset Text
18891
18892 \layout Standard
18893
18894
18895 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
18896
18897 \end_inset
18898
18899
18900 \end_inset
18901 </cell>
18902 </row>
18903 <row topline="true">
18904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18905 \begin_inset Text
18906
18907 \layout Standard
18908
18909 c-faq
18910 \end_inset
18911 </cell>
18912 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18913 \begin_inset Text
18914
18915 \layout Standard
18916
18917 C-FAQ-list
18918 \end_inset
18919 </cell>
18920 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18921 \begin_inset Text
18922
18923 \layout Standard
18924
18925
18926 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
18927
18928 \end_inset
18929
18930
18931 \end_inset
18932 </cell>
18933 </row>
18934 <row topline="true">
18935 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18936 \begin_inset Text
18937
18938 \layout Standard
18939
18940 \end_inset
18941 </cell>
18942 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18943 \begin_inset Text
18944
18945 \layout Standard
18946
18947 Latest datasheet of the target CPU
18948 \end_inset
18949 </cell>
18950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18951 \begin_inset Text
18952
18953 \layout Standard
18954
18955 vendor
18956 \end_inset
18957 </cell>
18958 </row>
18959 <row topline="true">
18960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18961 \begin_inset Text
18962
18963 \layout Standard
18964
18965 \end_inset
18966 </cell>
18967 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18968 \begin_inset Text
18969
18970 \layout Standard
18971
18972 Revision history of datasheet
18973 \end_inset
18974 </cell>
18975 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18976 \begin_inset Text
18977
18978 \layout Standard
18979
18980 vendor
18981 \end_inset
18982 </cell>
18983 </row>
18984 <row topline="true" bottomline="true">
18985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18986 \begin_inset Text
18987
18988 \layout Standard
18989
18990 S.
18991  S.
18992  Muchnick
18993 \end_inset
18994 </cell>
18995 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18996 \begin_inset Text
18997
18998 \layout Standard
18999
19000 Advanced Compiler Design and Implementation
19001 \end_inset
19002 </cell>
19003 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19004 \begin_inset Text
19005
19006 \layout Standard
19007
19008 bookstore (very dedicated, probably read other books first)
19009 \end_inset
19010 </cell>
19011 </row>
19012 </lyxtabular>
19013
19014 \end_inset
19015
19016
19017 \newline
19018
19019 \layout Section
19020
19021 Some Questions
19022 \layout Standard
19023
19024 Some questions answered, some pointers given - it might be time to in turn
19025  ask
19026 \emph on
19027 you
19028 \emph default
19029  some questions:
19030 \layout Itemize
19031
19032 can you solve your project with the selected microcontroller? Would you
19033  find out early or rather late that your target is too small/slow/whatever?
19034  Can you switch to a slightly better device if it doesn't fit?
19035 \layout Itemize
19036
19037 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
19038  and/or another programming language be more adequate? Would an operating
19039  system on the target device help?
19040 \layout Itemize
19041
19042 if you solved the problem, will the marketing department be happy?
19043 \layout Itemize
19044
19045 if the marketing department is happy, will customers be happy?
19046 \layout Itemize
19047
19048 if you're the project manager, marketing department and maybe even the customer
19049  in one person, have you tried to see the project from the outside?
19050 \layout Itemize
19051
19052 is the project done if you think it is done? Or is just that other interface/pro
19053 tocol/feature/configuration/option missing? How about website, manual(s),
19054  internationali(z|s)ation, packaging, labels, 2nd source for components,
19055  electromagnetic compatability/interference, documentation for production,
19056  production test software, update mechanism, patent issues?
19057 \layout Itemize
19058
19059 is your project adequately positioned in that magic triangle: fame, fortune,
19060  fun?
19061 \layout Standard
19062
19063 Maybe not all answers to these questions are known and some answers may
19064  even be
19065 \emph on
19066 no
19067 \emph default
19068 , nevertheless knowing these questions may help you to avoid burnout
19069 \begin_inset Foot
19070 collapsed false
19071
19072 \layout Standard
19073
19074 burnout is bad for electronic devices, programmers and motorcycle tyres
19075 \end_inset
19076
19077 .
19078  Chances are you didn't want to hear some of them...
19079 \layout Chapter
19080
19081 Support
19082 \begin_inset LatexCommand \index{Support}
19083
19084 \end_inset
19085
19086
19087 \layout Standard
19088
19089 SDCC has grown to be a large project.
19090  The compiler alone (without the preprocessor, assembler and linker) is
19091  well over 100,000 lines of code (blank stripped).
19092  The open source nature of this project is a key to its continued growth
19093  and support.
19094  You gain the benefit and support of many active software developers and
19095  end users.
19096  Is SDCC perfect? No, that's why we need your help.
19097  The developers take pride in fixing reported bugs.
19098  You can help by reporting the bugs and helping other SDCC users.
19099  There are lots of ways to contribute, and we encourage you to take part
19100  in making SDCC a great software package.
19101
19102 \layout Standard
19103
19104 The SDCC project is hosted on the SDCC sourceforge site at
19105 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
19106
19107 \end_inset
19108
19109 .
19110  You'll find the complete set of mailing lists
19111 \begin_inset LatexCommand \index{Mailing list(s)}
19112
19113 \end_inset
19114
19115 , forums, bug reporting system, patch submission
19116 \begin_inset LatexCommand \index{Patch submission}
19117
19118 \end_inset
19119
19120  system, download
19121 \begin_inset LatexCommand \index{download}
19122
19123 \end_inset
19124
19125  area and cvs code repository
19126 \begin_inset LatexCommand \index{cvs code repository}
19127
19128 \end_inset
19129
19130  there.
19131 \layout Section
19132
19133 Reporting Bugs
19134 \begin_inset LatexCommand \index{Bug reporting}
19135
19136 \end_inset
19137
19138
19139 \begin_inset LatexCommand \index{Reporting bugs}
19140
19141 \end_inset
19142
19143
19144 \layout Standard
19145
19146 The recommended way of reporting bugs is using the infrastructure of the
19147  sourceforge site.
19148  You can follow the status of bug reports there and have an overview about
19149  the known bugs.
19150 \layout Standard
19151
19152 Bug reports are automatically forwarded to the developer mailing list and
19153  will be fixed ASAP.
19154  When reporting a bug, it is very useful to include a small test program
19155  (the smaller the better) which reproduces the problem.
19156  If you can isolate the problem by looking at the generated assembly code,
19157  this can be very helpful.
19158  Compiling your program with the -
19159 \begin_inset ERT
19160 status Collapsed
19161
19162 \layout Standard
19163
19164 \backslash
19165 /
19166 \end_inset
19167
19168 -dumpall
19169 \begin_inset LatexCommand \index{-\/-dumpall}
19170
19171 \end_inset
19172
19173  option can sometimes be useful in locating optimization problems.
19174  When reporting a bug please maker sure you:
19175 \layout Enumerate
19176
19177 Attach the code you are compiling with SDCC.
19178
19179 \layout Enumerate
19180
19181 Specify the exact command you use to run SDCC, or attach your Makefile.
19182
19183 \layout Enumerate
19184
19185 Specify the SDCC version (type "
19186 \family sans
19187 \series bold
19188 sdcc -v
19189 \family default
19190 \series default
19191 "), your platform, and operating system.
19192
19193 \layout Enumerate
19194
19195 Provide an exact copy of any error message or incorrect output.
19196
19197 \layout Enumerate
19198
19199 Put something meaningful in the subject of your message.
19200 \layout Standard
19201
19202 Please attempt to include these 5 important parts, as applicable, in all
19203  requests for support or when reporting any problems or bugs with SDCC.
19204  Though this will make your message lengthy, it will greatly improve your
19205  chance that SDCC users and developers will be able to help you.
19206  Some SDCC developers are frustrated by bug reports without code provided
19207  that they can use to reproduce and ultimately fix the problem, so please
19208  be sure to provide sample code if you are reporting a bug!
19209 \layout Standard
19210
19211 Please have a short check that you are using a recent version of SDCC and
19212  the bug is not yet known.
19213  This is the link for reporting bugs:
19214 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
19215
19216 \end_inset
19217
19218 .
19219 \layout Section
19220
19221 Requesting Features
19222 \begin_inset LatexCommand \label{sub:Requesting-Features}
19223
19224 \end_inset
19225
19226
19227 \begin_inset LatexCommand \index{Feature request}
19228
19229 \end_inset
19230
19231
19232 \begin_inset LatexCommand \index{Requesting features}
19233
19234 \end_inset
19235
19236
19237 \layout Standard
19238
19239 Like bug reports feature requests are forwarded to the developer mailing
19240  list.
19241  This is the link for requesting features:
19242 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
19243
19244 \end_inset
19245
19246 .
19247 \layout Section
19248
19249 Submitting patches
19250 \layout Standard
19251
19252 Like bug reports contributed patches are forwarded to the developer mailing
19253  list.
19254  This is the link for submitting patches
19255 \begin_inset LatexCommand \index{Patch submission}
19256
19257 \end_inset
19258
19259 :
19260 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
19261
19262 \end_inset
19263
19264 .
19265 \layout Standard
19266
19267 You need to specify some parameters to the
19268 \family typewriter
19269 diff
19270 \family default
19271  command for the patches to be useful.
19272  If you modified more than one file a patch created f.e.
19273  with
19274 \family sans
19275 \series bold
19276
19277 \begin_inset Quotes sld
19278 \end_inset
19279
19280 diff -Naur unmodified_directory modified_directory >my_changes.patch
19281 \begin_inset Quotes srd
19282 \end_inset
19283
19284
19285 \family default
19286 \series default
19287  will be fine, otherwise
19288 \family sans
19289 \series bold
19290
19291 \begin_inset Quotes sld
19292 \end_inset
19293
19294 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
19295 \begin_inset Quotes srd
19296 \end_inset
19297
19298
19299 \series default
19300
19301 \family default
19302 will do.
19303 \layout Section
19304
19305 Getting Help
19306 \layout Standard
19307
19308 These links should take you directly to the
19309 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
19310
19311 \end_inset
19312
19313
19314 \begin_inset Foot
19315 collapsed false
19316
19317 \layout Standard
19318
19319 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
19320  automated messages (mid 2003)
19321 \end_inset
19322
19323  and the
19324 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
19325
19326 \end_inset
19327
19328 , lists
19329 \begin_inset LatexCommand \index{Mailing list(s)}
19330
19331 \end_inset
19332
19333  and forums are archived and searchable so if you are lucky someone already
19334  had a similar problem.
19335  While mails to the lists themselves are delivered promptly their web front
19336  end on sourceforge sometimes shows a severe time lag (up to several weeks),
19337  if you're seriously using SDCC please consider subscribing to the lists.
19338 \layout Section
19339
19340 ChangeLog
19341 \layout Standard
19342
19343 You can follow the status of the cvs version
19344 \begin_inset LatexCommand \index{version}
19345
19346 \end_inset
19347
19348  of SDCC by watching the Changelog
19349 \begin_inset LatexCommand \index{Changelog}
19350
19351 \end_inset
19352
19353  in the cvs-repository
19354 \newline
19355
19356 \size footnotesize
19357
19358 \begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
19359
19360 \end_inset
19361
19362 .
19363 \layout Section
19364
19365 Release policy
19366 \begin_inset LatexCommand \index{Release policy}
19367
19368 \end_inset
19369
19370
19371 \layout Standard
19372
19373 Historically there often were long delays between official releases and
19374  the sourceforge download area tends to get not updated at all.
19375  Excuses in the past might have referred to problems with live range analysis,
19376  but as this was fixed a while ago, the current problem is that another
19377  excuse has to be found.
19378  Kidding aside, we have to get better there! On the other hand there are
19379  daily snapshots available at
19380 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
19381
19382 \end_inset
19383
19384 , and you can always build the very last version (hopefully with many bugs
19385  fixed, and features added) from the source code available at
19386 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
19387
19388 \end_inset
19389
19390 .
19391 \layout Section
19392
19393 Examples
19394 \begin_inset LatexCommand \index{Examples}
19395
19396 \end_inset
19397
19398
19399 \layout Standard
19400
19401 You'll find some small examples in the directory
19402 \emph on
19403 sdcc/device/examples/.
19404
19405 \emph default
19406 More examples and libraries are available at
19407 \emph on
19408  The SDCC Open Knowledge Resource
19409 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
19410
19411 \end_inset
19412
19413
19414 \emph default
19415 web site or at
19416 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
19417
19418 \end_inset
19419
19420 .
19421 \layout Comment
19422
19423 I did insert a reference to Paul's web site here although it seems rather
19424  dedicated to a specific 8032 board (I think it's okay because it f.e.
19425  shows LCD/Harddisc interface and has a free 8051 monitor.
19426  Independent 8032 board vendors face hard competition of heavily subsidized
19427  development boards anyway).
19428 \layout Comment
19429
19430 Maybe we should include some links to real world applications.
19431  Preferably pointer to pointers (one for each architecture) so this stays
19432  manageable here?
19433 \layout Section
19434
19435 Quality control
19436 \begin_inset LatexCommand \index{Quality control}
19437
19438 \end_inset
19439
19440
19441 \layout Standard
19442
19443 The compiler is passed through nightly compile and build checks.
19444  The so called
19445 \shape italic
19446 regression tests
19447 \shape default
19448
19449 \begin_inset LatexCommand \index{Regression test}
19450
19451 \end_inset
19452
19453  check that SDCC itself compiles flawlessly on several platforms and checks
19454  the quality of the code generated by SDCC by running the code through simulator
19455 s.
19456  There is a separate document
19457 \shape italic
19458 test_suite.pdf
19459 \begin_inset LatexCommand \index{Test suite}
19460
19461 \end_inset
19462
19463
19464 \shape default
19465  about this.
19466 \layout Standard
19467
19468 You'll find the test code in the directory
19469 \shape italic
19470 sdcc/support/regression
19471 \shape default
19472 .
19473  You can run these tests manually by running
19474 \family sans
19475 make
19476 \family default
19477  in this directory (or f.e.
19478
19479 \family sans
19480 \series bold
19481
19482 \begin_inset Quotes sld
19483 \end_inset
19484
19485 make test-mcs51
19486 \begin_inset Quotes srd
19487 \end_inset
19488
19489
19490 \family default
19491 \series default
19492  if you don't want to run the complete tests).
19493  The test code might also be interesting if you want to look for examples
19494 \begin_inset LatexCommand \index{Examples}
19495
19496 \end_inset
19497
19498  checking corner cases of SDCC or if you plan to submit patches
19499 \begin_inset LatexCommand \index{Patch submission}
19500
19501 \end_inset
19502
19503 .
19504 \layout Standard
19505
19506 The pic port uses a different set of regression tests, you'll find them
19507  in the directory
19508 \shape italic
19509 sdcc/src/regression
19510 \shape default
19511 .
19512 \layout Chapter
19513 \pagebreak_top
19514 SDCC Technical Data
19515 \layout Section
19516
19517 Optimizations
19518 \begin_inset LatexCommand \index{Optimizations}
19519
19520 \end_inset
19521
19522
19523 \layout Standard
19524
19525 SDCC performs a host of standard optimizations in addition to some MCU specific
19526  optimizations.
19527
19528 \layout Subsection
19529
19530 Sub-expression Elimination
19531 \begin_inset LatexCommand \index{Subexpression elimination}
19532
19533 \end_inset
19534
19535
19536 \layout Standard
19537
19538 The compiler does local and
19539 \emph on
19540 g
19541 \emph default
19542 lobal
19543 \emph on
19544 c
19545 \emph default
19546 ommon
19547 \emph on
19548 s
19549 \emph default
19550 ubexpression
19551 \emph on
19552 e
19553 \emph default
19554 limination, e.g.:
19555 \layout Verse
19556
19557
19558 \family typewriter
19559 i = x + y + 1;
19560 \newline
19561 j = x + y;
19562 \layout Standard
19563
19564 will be translated to
19565 \layout Verse
19566
19567
19568 \family typewriter
19569 iTemp = x + y;
19570 \newline
19571 i = iTemp + 1;
19572 \newline
19573 j = iTemp;
19574 \layout Standard
19575
19576 Some subexpressions are not as obvious as the above example, e.g.:
19577 \layout Verse
19578
19579
19580 \family typewriter
19581 a->b[i].c = 10;
19582 \newline
19583 a->b[i].d = 11;
19584 \layout Standard
19585
19586 In this case the address arithmetic a->b[i] will be computed only once;
19587  the equivalent code in C would be.
19588 \layout Verse
19589
19590
19591 \family typewriter
19592 iTemp = a->b[i];
19593 \newline
19594 iTemp.c = 10;
19595 \newline
19596 iTemp.d = 11;
19597 \layout Standard
19598
19599 The compiler will try to keep these temporary variables in registers.
19600 \layout Subsection
19601
19602 Dead-Code Elimination
19603 \begin_inset LatexCommand \index{Dead-code elimination}
19604
19605 \end_inset
19606
19607
19608 \layout Verse
19609
19610
19611 \family typewriter
19612 int global;
19613 \newline
19614
19615 \newline
19616 void f () {
19617 \newline
19618 \SpecialChar ~
19619 \SpecialChar ~
19620 int i;
19621 \newline
19622 \SpecialChar ~
19623 \SpecialChar ~
19624 i = 1; \SpecialChar ~
19625 \SpecialChar ~
19626 \SpecialChar ~
19627 \SpecialChar ~
19628 \SpecialChar ~
19629 /* dead store */
19630 \newline
19631 \SpecialChar ~
19632 \SpecialChar ~
19633 global = 1;\SpecialChar ~
19634 /* dead store */
19635 \newline
19636 \SpecialChar ~
19637 \SpecialChar ~
19638 global = 2;
19639 \newline
19640 \SpecialChar ~
19641 \SpecialChar ~
19642 return;
19643 \newline
19644 \SpecialChar ~
19645 \SpecialChar ~
19646 global = 3;\SpecialChar ~
19647 /* unreachable */
19648 \newline
19649 }
19650 \layout Standard
19651
19652 will be changed to
19653 \layout Verse
19654
19655
19656 \family typewriter
19657 int global;
19658 \newline
19659
19660 \newline
19661 void f () {
19662 \newline
19663 \SpecialChar ~
19664 \SpecialChar ~
19665 global = 2;
19666 \newline
19667 }
19668 \layout Subsection
19669
19670 Copy-Propagation
19671 \begin_inset LatexCommand \index{Copy propagation}
19672
19673 \end_inset
19674
19675
19676 \layout Verse
19677
19678
19679 \family typewriter
19680 int f() {
19681 \newline
19682 \SpecialChar ~
19683 \SpecialChar ~
19684 int i, j;
19685 \newline
19686 \SpecialChar ~
19687 \SpecialChar ~
19688 i = 10;
19689 \newline
19690 \SpecialChar ~
19691 \SpecialChar ~
19692 j = i;
19693 \newline
19694 \SpecialChar ~
19695 \SpecialChar ~
19696 return j;
19697 \newline
19698 }
19699 \layout Standard
19700
19701 will be changed to
19702 \layout Verse
19703
19704
19705 \family typewriter
19706 int f() {
19707 \newline
19708 \SpecialChar ~
19709 \SpecialChar ~
19710 int i, j;
19711 \newline
19712 \SpecialChar ~
19713 \SpecialChar ~
19714 i = 10;
19715 \newline
19716 \SpecialChar ~
19717 \SpecialChar ~
19718 j = 10;
19719 \newline
19720 \SpecialChar ~
19721 \SpecialChar ~
19722 return 10;
19723 \newline
19724 }
19725 \layout Standard
19726
19727 Note: the dead stores created by this copy propagation will be eliminated
19728  by dead-code elimination.
19729 \layout Subsection
19730
19731 Loop Optimizations
19732 \begin_inset LatexCommand \index{Loop optimization}
19733
19734 \end_inset
19735
19736
19737 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
19738
19739 \end_inset
19740
19741
19742 \layout Standard
19743
19744 Two types of loop optimizations are done by SDCC
19745 \emph on
19746 loop invariant
19747 \emph default
19748  lifting and
19749 \emph on
19750  strength reduction
19751 \emph default
19752  of loop induction variables.
19753  In addition to the strength reduction the optimizer marks the induction
19754  variables and the register allocator tries to keep the induction variables
19755  in registers for the duration of the loop.
19756  Because of this preference of the register allocator
19757 \begin_inset LatexCommand \index{Register allocation}
19758
19759 \end_inset
19760
19761 , loop induction optimization causes an increase in register pressure, which
19762  may cause unwanted spilling of other temporary variables into the stack
19763 \begin_inset LatexCommand \index{stack}
19764
19765 \end_inset
19766
19767  / data space.
19768  The compiler will generate a warning message when it is forced to allocate
19769  extra space either on the stack or data space.
19770  If this extra space allocation is undesirable then induction optimization
19771  can be eliminated either for the entire source file (with -
19772 \begin_inset ERT
19773 status Collapsed
19774
19775 \layout Standard
19776
19777 \backslash
19778 /
19779 \end_inset
19780
19781 -noinduction option) or for a given function only using #pragma\SpecialChar ~
19782 noinduction
19783 \begin_inset LatexCommand \index{\#pragma noinduction}
19784
19785 \end_inset
19786
19787 .
19788 \newline
19789
19790 \newline
19791 Loop Invariant:
19792 \layout Verse
19793
19794
19795 \family typewriter
19796 for (i = 0 ; i < 100 ; i ++)
19797 \newline
19798 \SpecialChar ~
19799 \SpecialChar ~
19800 \SpecialChar ~
19801 \SpecialChar ~
19802 f += k + l;
19803 \layout Standard
19804
19805 changed to
19806 \layout Verse
19807
19808
19809 \family typewriter
19810 itemp = k + l;
19811 \newline
19812 for (i = 0; i < 100; i++)
19813 \newline
19814 \SpecialChar ~
19815 \SpecialChar ~
19816 \SpecialChar ~
19817 \SpecialChar ~
19818 f += itemp;
19819 \layout Standard
19820
19821 As mentioned previously some loop invariants are not as apparent, all static
19822  address computations are also moved out of the loop.
19823 \newline
19824
19825 \newline
19826 Strength Reduction
19827 \begin_inset LatexCommand \index{Strength reduction}
19828
19829 \end_inset
19830
19831 , this optimization substitutes an expression by a cheaper expression:
19832 \layout Verse
19833
19834
19835 \family typewriter
19836 for (i=0;i < 100; i++)
19837 \newline
19838 \SpecialChar ~
19839 \SpecialChar ~
19840 \SpecialChar ~
19841 \SpecialChar ~
19842 ar[i*5] = i*3;
19843 \layout Standard
19844
19845 changed to
19846 \layout Verse
19847
19848
19849 \family typewriter
19850 itemp1 = 0;
19851 \newline
19852 itemp2 = 0;
19853 \newline
19854 for (i=0;i< 100;i++) {
19855 \newline
19856 \SpecialChar ~
19857 \SpecialChar ~
19858 \SpecialChar ~
19859 \SpecialChar ~
19860 ar[itemp1] = itemp2;
19861 \newline
19862 \SpecialChar ~
19863 \SpecialChar ~
19864 \SpecialChar ~
19865 \SpecialChar ~
19866 itemp1 += 5;
19867 \newline
19868 \SpecialChar ~
19869 \SpecialChar ~
19870 \SpecialChar ~
19871 \SpecialChar ~
19872 itemp2 += 3;
19873 \newline
19874 }
19875 \layout Standard
19876
19877 The more expensive multiplication
19878 \begin_inset LatexCommand \index{Multiplication}
19879
19880 \end_inset
19881
19882  is changed to a less expensive addition.
19883 \layout Subsection
19884
19885 Loop Reversing
19886 \begin_inset LatexCommand \index{Loop reversing}
19887
19888 \end_inset
19889
19890
19891 \layout Standard
19892
19893 This optimization is done to reduce the overhead of checking loop boundaries
19894  for every iteration.
19895  Some simple loops can be reversed and implemented using a
19896 \begin_inset Quotes eld
19897 \end_inset
19898
19899 decrement and jump if not zero
19900 \begin_inset Quotes erd
19901 \end_inset
19902
19903  instruction.
19904  SDCC checks for the following criterion to determine if a loop is reversible
19905  (note: more sophisticated compilers use data-dependency analysis to make
19906  this determination, SDCC uses a more simple minded analysis).
19907 \layout Itemize
19908
19909 The 'for' loop is of the form
19910 \newline
19911
19912 \newline
19913
19914 \family typewriter
19915 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
19916  += 1])
19917 \newline
19918 \SpecialChar ~
19919 \SpecialChar ~
19920 \SpecialChar ~
19921 \SpecialChar ~
19922 <for body>
19923 \layout Itemize
19924
19925 The <for body> does not contain
19926 \begin_inset Quotes eld
19927 \end_inset
19928
19929 continue
19930 \begin_inset Quotes erd
19931 \end_inset
19932
19933  or 'break
19934 \begin_inset Quotes erd
19935 \end_inset
19936
19937 .
19938 \layout Itemize
19939
19940 All goto's are contained within the loop.
19941 \layout Itemize
19942
19943 No function calls within the loop.
19944 \layout Itemize
19945
19946 The loop control variable <sym> is not assigned any value within the loop
19947 \layout Itemize
19948
19949 The loop control variable does NOT participate in any arithmetic operation
19950  within the loop.
19951 \layout Itemize
19952
19953 There are NO switch statements in the loop.
19954 \layout Subsection
19955
19956 Algebraic Simplifications
19957 \layout Standard
19958
19959 SDCC does numerous algebraic simplifications, the following is a small sub-set
19960  of these optimizations.
19961 \layout Verse
19962
19963
19964 \family typewriter
19965 i = j + 0;\SpecialChar ~
19966 \SpecialChar ~
19967 \SpecialChar ~
19968 \SpecialChar ~
19969  /* changed to: */\SpecialChar ~
19970 \SpecialChar ~
19971 \SpecialChar ~
19972 \SpecialChar ~
19973  i = j;
19974 \newline
19975 i /= 2;\SpecialChar ~
19976 \SpecialChar ~
19977 \SpecialChar ~
19978 \SpecialChar ~
19979 \SpecialChar ~
19980 \SpecialChar ~
19981 \SpecialChar ~
19982  /* changed to: */\SpecialChar ~
19983 \SpecialChar ~
19984 \SpecialChar ~
19985 \SpecialChar ~
19986  i >>= 1;
19987 \newline
19988 i = j - j;\SpecialChar ~
19989 \SpecialChar ~
19990 \SpecialChar ~
19991 \SpecialChar ~
19992  /* changed to: */\SpecialChar ~
19993 \SpecialChar ~
19994 \SpecialChar ~
19995 \SpecialChar ~
19996  i = 0;
19997 \newline
19998 i = j / 1;\SpecialChar ~
19999 \SpecialChar ~
20000 \SpecialChar ~
20001 \SpecialChar ~
20002  /* changed to: */\SpecialChar ~
20003 \SpecialChar ~
20004 \SpecialChar ~
20005 \SpecialChar ~
20006  i = j;
20007 \layout Standard
20008
20009 Note the subexpressions
20010 \begin_inset LatexCommand \index{Subexpression}
20011
20012 \end_inset
20013
20014  given above are generally introduced by macro expansions or as a result
20015  of copy/constant propagation.
20016 \layout Subsection
20017
20018 'switch' Statements
20019 \begin_inset LatexCommand \label{sub:'switch'-Statements}
20020
20021 \end_inset
20022
20023
20024 \begin_inset LatexCommand \index{switch statement}
20025
20026 \end_inset
20027
20028
20029 \layout Standard
20030
20031 SDCC can optimize switch statements to jump tables
20032 \begin_inset LatexCommand \index{jump tables}
20033
20034 \end_inset
20035
20036 .
20037  It makes the decision based on an estimate of the generated code size.
20038  SDCC is quite liberal in the requirements for jump table generation:
20039 \layout Itemize
20040
20041 The labels need not be in order, and the starting number need not be one
20042  or zero, the case labels are in numerical sequence or not too many case
20043  labels are missing.
20044 \begin_deeper
20045 \layout Verse
20046
20047
20048 \family typewriter
20049 switch(i) {\SpecialChar ~
20050 \SpecialChar ~
20051 \SpecialChar ~
20052 \SpecialChar ~
20053 \SpecialChar ~
20054 \SpecialChar ~
20055 \SpecialChar ~
20056 \SpecialChar ~
20057 \SpecialChar ~
20058 \SpecialChar ~
20059 \SpecialChar ~
20060 \SpecialChar ~
20061 \SpecialChar ~
20062 \SpecialChar ~
20063 \SpecialChar ~
20064 \SpecialChar ~
20065 \SpecialChar ~
20066 \SpecialChar ~
20067 \SpecialChar ~
20068 \SpecialChar ~
20069 \SpecialChar ~
20070 \SpecialChar ~
20071 \SpecialChar ~
20072 \SpecialChar ~
20073 \SpecialChar ~
20074 \SpecialChar ~
20075 switch (i) {
20076 \newline
20077 \SpecialChar ~
20078 \SpecialChar ~
20079 \SpecialChar ~
20080 case 4: ...\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 \SpecialChar ~
20094 \SpecialChar ~
20095 \SpecialChar ~
20096 \SpecialChar ~
20097 \SpecialChar ~
20098 \SpecialChar ~
20099 \SpecialChar ~
20100 \SpecialChar ~
20101 \SpecialChar ~
20102 \SpecialChar ~
20103 \SpecialChar ~
20104 \SpecialChar ~
20105 \SpecialChar ~
20106 case 0: ...
20107
20108 \newline
20109 \SpecialChar ~
20110 \SpecialChar ~
20111 \SpecialChar ~
20112 case 5: ...\SpecialChar ~
20113 \SpecialChar ~
20114 \SpecialChar ~
20115 \SpecialChar ~
20116 \SpecialChar ~
20117 \SpecialChar ~
20118 \SpecialChar ~
20119 \SpecialChar ~
20120 \SpecialChar ~
20121 \SpecialChar ~
20122 \SpecialChar ~
20123 \SpecialChar ~
20124 \SpecialChar ~
20125 \SpecialChar ~
20126 \SpecialChar ~
20127 \SpecialChar ~
20128 \SpecialChar ~
20129 \SpecialChar ~
20130 \SpecialChar ~
20131 \SpecialChar ~
20132 \SpecialChar ~
20133 \SpecialChar ~
20134 \SpecialChar ~
20135 \SpecialChar ~
20136 \SpecialChar ~
20137 \SpecialChar ~
20138 case 1: ...
20139
20140 \newline
20141 \SpecialChar ~
20142 \SpecialChar ~
20143 \SpecialChar ~
20144 case 3: ...\SpecialChar ~
20145 \SpecialChar ~
20146 \SpecialChar ~
20147 \SpecialChar ~
20148 \SpecialChar ~
20149 \SpecialChar ~
20150 \SpecialChar ~
20151 \SpecialChar ~
20152 \SpecialChar ~
20153 \SpecialChar ~
20154 \SpecialChar ~
20155 \SpecialChar ~
20156 \SpecialChar ~
20157 \SpecialChar ~
20158 \SpecialChar ~
20159 \SpecialChar ~
20160 \SpecialChar ~
20161 \SpecialChar ~
20162 \SpecialChar ~
20163 \SpecialChar ~
20164 \SpecialChar ~
20165 \SpecialChar ~
20166 \SpecialChar ~
20167 \SpecialChar ~
20168 \SpecialChar ~
20169 \SpecialChar ~
20170
20171 \newline
20172 \SpecialChar ~
20173 \SpecialChar ~
20174 \SpecialChar ~
20175 case 6: ...\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 \SpecialChar ~
20189 \SpecialChar ~
20190 \SpecialChar ~
20191 \SpecialChar ~
20192 \SpecialChar ~
20193 \SpecialChar ~
20194 \SpecialChar ~
20195 \SpecialChar ~
20196 \SpecialChar ~
20197 \SpecialChar ~
20198 \SpecialChar ~
20199 \SpecialChar ~
20200 \SpecialChar ~
20201 case 3: ...
20202
20203 \newline
20204 \SpecialChar ~
20205 \SpecialChar ~
20206 \SpecialChar ~
20207 case 7: ...\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 \SpecialChar ~
20221 \SpecialChar ~
20222 \SpecialChar ~
20223 \SpecialChar ~
20224 \SpecialChar ~
20225 \SpecialChar ~
20226 \SpecialChar ~
20227 \SpecialChar ~
20228 \SpecialChar ~
20229 \SpecialChar ~
20230 \SpecialChar ~
20231 \SpecialChar ~
20232 \SpecialChar ~
20233 case 4: ...
20234
20235 \newline
20236 \SpecialChar ~
20237 \SpecialChar ~
20238 \SpecialChar ~
20239 case 8: ...\SpecialChar ~
20240 \SpecialChar ~
20241 \SpecialChar ~
20242 \SpecialChar ~
20243 \SpecialChar ~
20244 \SpecialChar ~
20245 \SpecialChar ~
20246 \SpecialChar ~
20247 \SpecialChar ~
20248 \SpecialChar ~
20249 \SpecialChar ~
20250 \SpecialChar ~
20251 \SpecialChar ~
20252 \SpecialChar ~
20253 \SpecialChar ~
20254 \SpecialChar ~
20255 \SpecialChar ~
20256 \SpecialChar ~
20257 \SpecialChar ~
20258 \SpecialChar ~
20259 \SpecialChar ~
20260 \SpecialChar ~
20261 \SpecialChar ~
20262 \SpecialChar ~
20263 \SpecialChar ~
20264 \SpecialChar ~
20265 case 5: ...
20266
20267 \newline
20268 \SpecialChar ~
20269 \SpecialChar ~
20270 \SpecialChar ~
20271 case 9: ...\SpecialChar ~
20272 \SpecialChar ~
20273 \SpecialChar ~
20274 \SpecialChar ~
20275 \SpecialChar ~
20276 \SpecialChar ~
20277 \SpecialChar ~
20278 \SpecialChar ~
20279 \SpecialChar ~
20280 \SpecialChar ~
20281 \SpecialChar ~
20282 \SpecialChar ~
20283 \SpecialChar ~
20284 \SpecialChar ~
20285 \SpecialChar ~
20286 \SpecialChar ~
20287 \SpecialChar ~
20288 \SpecialChar ~
20289 \SpecialChar ~
20290 \SpecialChar ~
20291 \SpecialChar ~
20292 \SpecialChar ~
20293 \SpecialChar ~
20294 \SpecialChar ~
20295 \SpecialChar ~
20296 \SpecialChar ~
20297 case 6: ...
20298
20299 \newline
20300 \SpecialChar ~
20301 \SpecialChar ~
20302 \SpecialChar ~
20303 case 10: ...\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 \SpecialChar ~
20322 \SpecialChar ~
20323 \SpecialChar ~
20324 \SpecialChar ~
20325 \SpecialChar ~
20326 \SpecialChar ~
20327 \SpecialChar ~
20328 case 7: ...
20329
20330 \newline
20331 \SpecialChar ~
20332 \SpecialChar ~
20333 \SpecialChar ~
20334 case 11: ...\SpecialChar ~
20335 \SpecialChar ~
20336 \SpecialChar ~
20337 \SpecialChar ~
20338 \SpecialChar ~
20339 \SpecialChar ~
20340 \SpecialChar ~
20341 \SpecialChar ~
20342 \SpecialChar ~
20343 \SpecialChar ~
20344 \SpecialChar ~
20345 \SpecialChar ~
20346 \SpecialChar ~
20347 \SpecialChar ~
20348 \SpecialChar ~
20349 \SpecialChar ~
20350 \SpecialChar ~
20351 \SpecialChar ~
20352 \SpecialChar ~
20353 \SpecialChar ~
20354 \SpecialChar ~
20355 \SpecialChar ~
20356 \SpecialChar ~
20357 \SpecialChar ~
20358 \SpecialChar ~
20359 case 8: ...
20360
20361 \newline
20362 }\SpecialChar ~
20363 \SpecialChar ~
20364 \SpecialChar ~
20365 \SpecialChar ~
20366 \SpecialChar ~
20367 \SpecialChar ~
20368 \SpecialChar ~
20369 \SpecialChar ~
20370 \SpecialChar ~
20371 \SpecialChar ~
20372 \SpecialChar ~
20373 \SpecialChar ~
20374 \SpecialChar ~
20375 \SpecialChar ~
20376 \SpecialChar ~
20377 \SpecialChar ~
20378 \SpecialChar ~
20379 \SpecialChar ~
20380 \SpecialChar ~
20381 \SpecialChar ~
20382 \SpecialChar ~
20383 \SpecialChar ~
20384 \SpecialChar ~
20385 \SpecialChar ~
20386 \SpecialChar ~
20387 \SpecialChar ~
20388 \SpecialChar ~
20389 \SpecialChar ~
20390 \SpecialChar ~
20391 \SpecialChar ~
20392 \SpecialChar ~
20393 \SpecialChar ~
20394 \SpecialChar ~
20395 \SpecialChar ~
20396 \SpecialChar ~
20397 \SpecialChar ~
20398 }
20399 \layout Standard
20400
20401 Both the above switch statements will be implemented using a jump-table.
20402  The example to the right side is slightly more efficient as the check for
20403  the lower boundary of the jump-table is not needed.
20404 \end_deeper
20405 \layout Itemize
20406
20407 The number of case labels is not larger than supported by the target architectur
20408 e.
20409 \layout Itemize
20410
20411 If the case labels are not in numerical sequence ('gaps' between cases)
20412  SDCC checks whether a jump table with additionally inserted dummy cases
20413  is still attractive.
20414
20415 \layout Itemize
20416
20417 If the starting number is not zero and a check for the lower boundary of
20418  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
20419  ...
20420  .
20421 \layout Standard
20422
20423 Switch statements which have large gaps in the numeric sequence or those
20424  that have too many case labels can be split into more than one switch statement
20425  for efficient code generation, e.g.:
20426 \layout Verse
20427
20428
20429 \family typewriter
20430 switch (i) {
20431 \newline
20432 \SpecialChar ~
20433 \SpecialChar ~
20434 case 1: ...
20435
20436 \newline
20437 \SpecialChar ~
20438 \SpecialChar ~
20439 case 2: ...
20440
20441 \newline
20442 \SpecialChar ~
20443 \SpecialChar ~
20444 case 3: ...
20445
20446 \newline
20447 \SpecialChar ~
20448 \SpecialChar ~
20449 case 4: ...
20450
20451 \newline
20452 \SpecialChar ~
20453 \SpecialChar ~
20454 case 5: ...
20455
20456 \newline
20457 \SpecialChar ~
20458 \SpecialChar ~
20459 case 6: ...
20460
20461 \newline
20462 \SpecialChar ~
20463 \SpecialChar ~
20464 case 7: ...
20465
20466 \newline
20467 \SpecialChar ~
20468 \SpecialChar ~
20469 case 101: ...
20470
20471 \newline
20472 \SpecialChar ~
20473 \SpecialChar ~
20474 case 102: ...
20475
20476 \newline
20477 \SpecialChar ~
20478 \SpecialChar ~
20479 case 103: ...
20480
20481 \newline
20482 \SpecialChar ~
20483 \SpecialChar ~
20484 case 104: ...
20485
20486 \newline
20487 \SpecialChar ~
20488 \SpecialChar ~
20489 case 105: ...
20490
20491 \newline
20492 \SpecialChar ~
20493 \SpecialChar ~
20494 case 106: ...
20495
20496 \newline
20497 \SpecialChar ~
20498 \SpecialChar ~
20499 case 107: ...
20500
20501 \newline
20502 }
20503 \layout Standard
20504
20505 If the above switch statement is broken down into two switch statements
20506 \layout Verse
20507
20508
20509 \family typewriter
20510 switch (i) {
20511 \newline
20512 \SpecialChar ~
20513 \SpecialChar ~
20514 case 1: ...
20515
20516 \newline
20517 \SpecialChar ~
20518 \SpecialChar ~
20519 case 2: ...
20520
20521 \newline
20522 \SpecialChar ~
20523 \SpecialChar ~
20524 case 3: ...
20525
20526 \newline
20527 \SpecialChar ~
20528 \SpecialChar ~
20529 case 4: ...
20530
20531 \newline
20532 \SpecialChar ~
20533 \SpecialChar ~
20534 case 5: ...
20535
20536 \newline
20537 \SpecialChar ~
20538 \SpecialChar ~
20539 case 6: ...
20540
20541 \newline
20542 \SpecialChar ~
20543 \SpecialChar ~
20544 case 7: ...
20545
20546 \newline
20547 }
20548 \layout Standard
20549
20550 and
20551 \layout Verse
20552
20553
20554 \family typewriter
20555 switch (i) {
20556 \newline
20557 \SpecialChar ~
20558 \SpecialChar ~
20559 case 101: ...
20560
20561 \newline
20562 \SpecialChar ~
20563 \SpecialChar ~
20564 case 102: ...
20565
20566 \newline
20567 \SpecialChar ~
20568 \SpecialChar ~
20569 case 103: ...
20570
20571 \newline
20572 \SpecialChar ~
20573 \SpecialChar ~
20574 case 104: ...
20575
20576 \newline
20577 \SpecialChar ~
20578 \SpecialChar ~
20579 case 105: ...
20580
20581 \newline
20582 \SpecialChar ~
20583 \SpecialChar ~
20584 case 106: ...
20585
20586 \newline
20587 \SpecialChar ~
20588 \SpecialChar ~
20589 case 107: ...
20590
20591 \newline
20592 }
20593 \layout Standard
20594
20595 then both the switch statements will be implemented using jump-tables whereas
20596  the unmodified switch statement will not be.
20597 \layout Comment
20598
20599 There might be reasons which SDCC cannot know about to either favour or
20600  not favour jump tables.
20601  If the target system has to be as quick for the last switch case as for
20602  the first (pro jump table), or if the switch argument is known to be zero
20603  in the majority of the cases (contra jump table).
20604 \layout Standard
20605
20606 The pragma nojtbound
20607 \begin_inset LatexCommand \index{\#pragma nojtbound}
20608
20609 \end_inset
20610
20611  can be used to turn off checking the
20612 \emph on
20613 j
20614 \emph default
20615 ump
20616 \emph on
20617 t
20618 \emph default
20619 able
20620 \emph on
20621 bound
20622 \emph default
20623 aries.
20624  It has no effect if a default label is supplied.
20625  Use of this pragma is dangerous: if the switch argument is not matched
20626  by a case statement the processor will happily jump into Nirvana.
20627 \layout Subsection
20628
20629 Bit-shifting Operations
20630 \begin_inset LatexCommand \index{Bit shifting}
20631
20632 \end_inset
20633
20634 .
20635 \layout Standard
20636
20637 Bit shifting is one of the most frequently used operation in embedded programmin
20638 g.
20639  SDCC tries to implement bit-shift operations in the most efficient way
20640  possible, e.g.:
20641 \layout Verse
20642
20643
20644 \family typewriter
20645 unsigned char i;
20646 \newline
20647 ...
20648
20649 \newline
20650 i >>= 4;
20651 \newline
20652 ...
20653 \layout Standard
20654
20655 generates the following code:
20656 \layout Verse
20657
20658
20659 \family typewriter
20660 mov\SpecialChar ~
20661  a,_i
20662 \newline
20663 swap a
20664 \newline
20665 anl\SpecialChar ~
20666  a,#0x0f
20667 \newline
20668 mov\SpecialChar ~
20669  _i,a
20670 \layout Standard
20671
20672 In general SDCC will never setup a loop if the shift count is known.
20673  Another example:
20674 \layout Verse
20675
20676
20677 \family typewriter
20678 unsigned int i;
20679 \newline
20680 ...
20681
20682 \newline
20683 i >>= 9;
20684 \newline
20685 ...
20686 \layout Standard
20687
20688 will generate:
20689 \layout Verse
20690
20691
20692 \family typewriter
20693 mov\SpecialChar ~
20694 \SpecialChar ~
20695 a,(_i + 1)
20696 \newline
20697 mov\SpecialChar ~
20698 \SpecialChar ~
20699 (_i + 1),#0x00
20700 \newline
20701 clr\SpecialChar ~
20702 \SpecialChar ~
20703 c
20704 \newline
20705 rrc\SpecialChar ~
20706 \SpecialChar ~
20707 a
20708 \newline
20709 mov\SpecialChar ~
20710 \SpecialChar ~
20711 _i,a
20712 \layout Subsection
20713
20714 Bit-rotation
20715 \begin_inset LatexCommand \index{Bit rotation}
20716
20717 \end_inset
20718
20719
20720 \layout Standard
20721
20722 A special case of the bit-shift operation is bit rotation
20723 \begin_inset LatexCommand \index{rotating bits}
20724
20725 \end_inset
20726
20727 , SDCC recognizes the following expression to be a left bit-rotation:
20728 \layout Verse
20729
20730
20731 \family typewriter
20732 \series bold
20733 unsigned
20734 \series default
20735 \SpecialChar ~
20736 \SpecialChar ~
20737 char i;\SpecialChar ~
20738 \SpecialChar ~
20739 \SpecialChar ~
20740 \SpecialChar ~
20741 \SpecialChar ~
20742 \SpecialChar ~
20743 \SpecialChar ~
20744 \SpecialChar ~
20745 \SpecialChar ~
20746 \SpecialChar ~
20747 \SpecialChar ~
20748 /* unsigned is needed for rotation */
20749 \newline
20750 ...
20751
20752 \newline
20753 i = ((i << 1) | (i >> 7));
20754 \family default
20755
20756 \newline
20757
20758 \family typewriter
20759 ...
20760 \layout Standard
20761
20762 will generate the following code:
20763 \layout Verse
20764
20765
20766 \family typewriter
20767 mov\SpecialChar ~
20768 \SpecialChar ~
20769 a,_i
20770 \newline
20771 rl\SpecialChar ~
20772 \SpecialChar ~
20773 \SpecialChar ~
20774 a
20775 \newline
20776 mov\SpecialChar ~
20777 \SpecialChar ~
20778 _i,a
20779 \layout Standard
20780
20781 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
20782 ns of this case will also be recognized as bit-rotation, i.e.:
20783 \layout Verse
20784
20785
20786 \family typewriter
20787 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
20788 \layout Subsection
20789
20790 Nibble and Byte Swapping
20791 \layout Standard
20792
20793 Other special cases of the bit-shift operations are nibble or byte swapping
20794 \begin_inset LatexCommand \index{swapping nibbles/bytes}
20795
20796 \end_inset
20797
20798 , SDCC recognizes the following expressions:
20799 \layout Verse
20800
20801
20802 \family typewriter
20803 \series bold
20804 unsigned
20805 \series default
20806 \SpecialChar ~
20807 \SpecialChar ~
20808 char i;
20809 \newline
20810
20811 \series bold
20812 unsigned
20813 \series default
20814 \SpecialChar ~
20815 \SpecialChar ~
20816 int j;
20817 \newline
20818 ...
20819
20820 \newline
20821 i = ((i << 4) | (i >> 4));
20822 \family default
20823
20824 \newline
20825
20826 \family typewriter
20827 j = ((j << 8) | (j >> 8));
20828 \layout Standard
20829
20830 and generates a swap instruction for the nibble swapping
20831 \begin_inset LatexCommand \index{Nibble swapping}
20832
20833 \end_inset
20834
20835  or move instructions for the byte swapping
20836 \begin_inset LatexCommand \index{Byte swapping}
20837
20838 \end_inset
20839
20840 .
20841  The
20842 \begin_inset Quotes sld
20843 \end_inset
20844
20845 j
20846 \begin_inset Quotes srd
20847 \end_inset
20848
20849  example can be used to convert from little to big-endian or vice versa.
20850  If you want to change the endianness of a
20851 \emph on
20852 signed
20853 \emph default
20854  integer you have to cast to
20855 \family typewriter
20856 (unsigned int)
20857 \family default
20858  first.
20859 \layout Standard
20860
20861 Note that SDCC stores numbers in little-endian
20862 \begin_inset Foot
20863 collapsed false
20864
20865 \layout Standard
20866
20867 Usually 8-bit processors don't care much about endianness.
20868  This is not the case for the standard 8051 which only has an instruction
20869  to increment its
20870 \emph on
20871 dptr
20872 \emph default
20873
20874 \begin_inset LatexCommand \index{DPTR}
20875
20876 \end_inset
20877
20878 -datapointer
20879 \emph on
20880
20881 \emph default
20882 so little-endian is the more efficient byte order.
20883 \end_inset
20884
20885
20886 \begin_inset LatexCommand \index{little-endian}
20887
20888 \end_inset
20889
20890
20891 \begin_inset LatexCommand \index{Endianness}
20892
20893 \end_inset
20894
20895  format (i.e.
20896  lowest order first).
20897 \layout Subsection
20898
20899 Highest Order Bit
20900 \begin_inset LatexCommand \index{Highest Order Bit}
20901
20902 \end_inset
20903
20904
20905 \layout Standard
20906
20907 It is frequently required to obtain the highest order bit of an integral
20908  type (long, int, short or char types).
20909  SDCC recognizes the following expression to yield the highest order bit
20910  and generates optimized code for it, e.g.:
20911 \layout Verse
20912
20913
20914 \family typewriter
20915 unsigned int gint;
20916 \newline
20917
20918 \newline
20919 foo () {
20920 \newline
20921 \SpecialChar ~
20922 \SpecialChar ~
20923 unsigned char hob;
20924 \newline
20925 \SpecialChar ~
20926 \SpecialChar ~
20927 ...
20928
20929 \newline
20930 \SpecialChar ~
20931 \SpecialChar ~
20932 hob = (gint >> 15) & 1;
20933 \newline
20934 \SpecialChar ~
20935 \SpecialChar ~
20936 ..
20937
20938 \newline
20939 }
20940 \layout Standard
20941
20942 will generate the following code:
20943 \layout Verse
20944
20945
20946 \family typewriter
20947 \SpecialChar ~
20948 \SpecialChar ~
20949 \SpecialChar ~
20950 \SpecialChar ~
20951 \SpecialChar ~
20952 \SpecialChar ~
20953 \SpecialChar ~
20954 \SpecialChar ~
20955 \SpecialChar ~
20956 \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 \SpecialChar ~
20972  61 ;\SpecialChar ~
20973  hob.c 7
20974 \newline
20975 000A E5*01\SpecialChar ~
20976 \SpecialChar ~
20977 \SpecialChar ~
20978 \SpecialChar ~
20979 \SpecialChar ~
20980 \SpecialChar ~
20981 \SpecialChar ~
20982 \SpecialChar ~
20983 \SpecialChar ~
20984 \SpecialChar ~
20985 \SpecialChar ~
20986 \SpecialChar ~
20987 \SpecialChar ~
20988 \SpecialChar ~
20989 \SpecialChar ~
20990  62\SpecialChar ~
20991 \SpecialChar ~
20992 \SpecialChar ~
20993 \SpecialChar ~
20994 \SpecialChar ~
20995 \SpecialChar ~
20996 \SpecialChar ~
20997 \SpecialChar ~
20998  mov\SpecialChar ~
20999 \SpecialChar ~
21000  a,(_gint + 1)
21001 \newline
21002 000C 23\SpecialChar ~
21003 \SpecialChar ~
21004 \SpecialChar ~
21005 \SpecialChar ~
21006 \SpecialChar ~
21007 \SpecialChar ~
21008 \SpecialChar ~
21009 \SpecialChar ~
21010 \SpecialChar ~
21011 \SpecialChar ~
21012 \SpecialChar ~
21013 \SpecialChar ~
21014 \SpecialChar ~
21015 \SpecialChar ~
21016 \SpecialChar ~
21017 \SpecialChar ~
21018 \SpecialChar ~
21019 \SpecialChar ~
21020  63\SpecialChar ~
21021 \SpecialChar ~
21022 \SpecialChar ~
21023 \SpecialChar ~
21024 \SpecialChar ~
21025 \SpecialChar ~
21026 \SpecialChar ~
21027 \SpecialChar ~
21028  rl\SpecialChar ~
21029 \SpecialChar ~
21030 \SpecialChar ~
21031  a
21032 \newline
21033 000D 54 01\SpecialChar ~
21034 \SpecialChar ~
21035 \SpecialChar ~
21036 \SpecialChar ~
21037 \SpecialChar ~
21038 \SpecialChar ~
21039 \SpecialChar ~
21040 \SpecialChar ~
21041 \SpecialChar ~
21042 \SpecialChar ~
21043 \SpecialChar ~
21044 \SpecialChar ~
21045 \SpecialChar ~
21046 \SpecialChar ~
21047 \SpecialChar ~
21048  64\SpecialChar ~
21049 \SpecialChar ~
21050 \SpecialChar ~
21051 \SpecialChar ~
21052 \SpecialChar ~
21053 \SpecialChar ~
21054 \SpecialChar ~
21055 \SpecialChar ~
21056  anl\SpecialChar ~
21057 \SpecialChar ~
21058  a,#0x01
21059 \newline
21060 000F F5*02\SpecialChar ~
21061 \SpecialChar ~
21062 \SpecialChar ~
21063 \SpecialChar ~
21064 \SpecialChar ~
21065 \SpecialChar ~
21066 \SpecialChar ~
21067 \SpecialChar ~
21068 \SpecialChar ~
21069 \SpecialChar ~
21070 \SpecialChar ~
21071 \SpecialChar ~
21072 \SpecialChar ~
21073 \SpecialChar ~
21074 \SpecialChar ~
21075  65\SpecialChar ~
21076 \SpecialChar ~
21077 \SpecialChar ~
21078 \SpecialChar ~
21079 \SpecialChar ~
21080 \SpecialChar ~
21081 \SpecialChar ~
21082 \SpecialChar ~
21083  mov\SpecialChar ~
21084 \SpecialChar ~
21085  _foo_hob_1_1,a
21086 \layout Standard
21087
21088 Variations of this case however will
21089 \emph on
21090 not
21091 \emph default
21092  be recognized.
21093  It is a standard C expression, so I heartily recommend this be the only
21094  way to get the highest order bit, (it is portable).
21095  Of course it will be recognized even if it is embedded in other expressions,
21096  e.g.:
21097 \layout Verse
21098
21099
21100 \family typewriter
21101 xyz = gint + ((gint >> 15) & 1);
21102 \layout Standard
21103
21104 will still be recognized.
21105 \layout Subsection
21106
21107 Peephole Optimizer
21108 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
21109
21110 \end_inset
21111
21112
21113 \begin_inset LatexCommand \index{Peephole optimizer}
21114
21115 \end_inset
21116
21117
21118 \layout Standard
21119
21120 The compiler uses a rule based, pattern matching and re-writing mechanism
21121  for peep-hole optimization.
21122  It is inspired by
21123 \emph on
21124 copt
21125 \emph default
21126  a peep-hole optimizer by Christopher W.
21127  Fraser (cwfraser@microsoft.com).
21128  A default set of rules are compiled into the compiler, additional rules
21129  may be added with the
21130 \emph on
21131 -
21132 \begin_inset ERT
21133 status Collapsed
21134
21135 \layout Standard
21136
21137 \backslash
21138 /
21139 \end_inset
21140
21141 -peep-file
21142 \begin_inset LatexCommand \index{-\/-peep-file}
21143
21144 \end_inset
21145
21146  <filename>
21147 \emph default
21148  option.
21149  The rule language is best illustrated with examples.
21150 \layout Verse
21151
21152
21153 \family typewriter
21154 replace {
21155 \newline
21156 \SpecialChar ~
21157 \SpecialChar ~
21158 mov %1,a
21159 \newline
21160 \SpecialChar ~
21161 \SpecialChar ~
21162 mov a,%1
21163 \newline
21164 } by {
21165 \newline
21166 \SpecialChar ~
21167 \SpecialChar ~
21168 mov %1,a
21169 \newline
21170 }
21171 \layout Standard
21172
21173 The above rule will change the following assembly
21174 \begin_inset LatexCommand \index{Assembler routines}
21175
21176 \end_inset
21177
21178  sequence:
21179 \layout Verse
21180
21181
21182 \family typewriter
21183 mov r1,a
21184 \newline
21185 mov a,r1
21186 \layout Standard
21187
21188 to
21189 \layout Verse
21190
21191
21192 \family typewriter
21193 mov r1,a
21194 \layout Standard
21195
21196 Note: All occurrences of a
21197 \emph on
21198 %n
21199 \emph default
21200  (pattern variable) must denote the same string.
21201  With the above rule, the assembly sequence:
21202 \layout Verse
21203
21204
21205 \family typewriter
21206 mov r1,a
21207 \newline
21208 mov a,r2
21209 \layout Standard
21210
21211 will remain unmodified.
21212 \newline
21213
21214 \newline
21215 Other special case optimizations may be added by the user (via
21216 \emph on
21217 -
21218 \begin_inset ERT
21219 status Collapsed
21220
21221 \layout Standard
21222
21223 \backslash
21224 /
21225 \end_inset
21226
21227 -peep-file option
21228 \emph default
21229 ).
21230  E.g.
21231  some variants of the 8051 MCU
21232 \begin_inset LatexCommand \index{MCS51 variants}
21233
21234 \end_inset
21235
21236  allow only
21237 \family typewriter
21238 ajmp
21239 \family default
21240  and
21241 \family typewriter
21242 acall
21243 \family default
21244 .
21245  The following two rules will change all
21246 \family typewriter
21247 ljmp
21248 \family default
21249  and
21250 \family typewriter
21251 lcall
21252 \family default
21253  to
21254 \family typewriter
21255 ajmp
21256 \family default
21257  and
21258 \family typewriter
21259 acall
21260 \layout Verse
21261
21262
21263 \family typewriter
21264 replace { lcall %1 } by { acall %1 }
21265 \newline
21266 replace { ljmp %1 } by { ajmp %1 }
21267 \layout Standard
21268
21269 The
21270 \emph on
21271 inline-assembler code
21272 \emph default
21273  is also passed through the peep hole optimizer, thus the peephole optimizer
21274  can also be used as an assembly level macro expander.
21275  The rules themselves are MCU dependent whereas the rule language infra-structur
21276 e is MCU independent.
21277  Peephole optimization rules for other MCU can be easily programmed using
21278  the rule language.
21279 \newline
21280
21281 \newline
21282 The syntax for a rule is as follows:
21283 \layout Verse
21284
21285
21286 \family typewriter
21287 rule := replace [ restart ] '{' <assembly sequence> '
21288 \backslash
21289 n'
21290 \newline
21291 \SpecialChar ~
21292  \SpecialChar ~
21293  \SpecialChar ~
21294  \SpecialChar ~
21295  \SpecialChar ~
21296  \SpecialChar ~
21297  \SpecialChar ~
21298  \SpecialChar ~
21299  \SpecialChar ~
21300  \SpecialChar ~
21301  \SpecialChar ~
21302  \SpecialChar ~
21303  \SpecialChar ~
21304  \SpecialChar ~
21305  '}' by '{' '
21306 \backslash
21307 n'
21308 \newline
21309 \SpecialChar ~
21310  \SpecialChar ~
21311  \SpecialChar ~
21312  \SpecialChar ~
21313  \SpecialChar ~
21314  \SpecialChar ~
21315  \SpecialChar ~
21316  \SpecialChar ~
21317  \SpecialChar ~
21318  \SpecialChar ~
21319  \SpecialChar ~
21320  \SpecialChar ~
21321  \SpecialChar ~
21322  \SpecialChar ~
21323  \SpecialChar ~
21324  \SpecialChar ~
21325  <assembly sequence> '
21326 \backslash
21327 n'
21328 \newline
21329 \SpecialChar ~
21330  \SpecialChar ~
21331  \SpecialChar ~
21332  \SpecialChar ~
21333  \SpecialChar ~
21334  \SpecialChar ~
21335  \SpecialChar ~
21336  \SpecialChar ~
21337  \SpecialChar ~
21338  \SpecialChar ~
21339  \SpecialChar ~
21340  \SpecialChar ~
21341  \SpecialChar ~
21342  \SpecialChar ~
21343  '}' [if <functionName> ] '
21344 \backslash
21345 n'
21346 \layout Standard
21347
21348 <assembly sequence> := assembly instruction (each instruction including
21349  labels must be on a separate line).
21350 \newline
21351
21352 \newline
21353 The optimizer will apply to the rules one by one from the top in the sequence
21354  of their appearance, it will terminate when all rules are exhausted.
21355  If the 'restart' option is specified, then the optimizer will start matching
21356  the rules again from the top, this option for a rule is expensive (performance)
21357 , it is intended to be used in situations where a transformation will trigger
21358  the same rule again.
21359  An example of this (not a good one, it has side effects) is the following
21360  rule:
21361 \layout Verse
21362
21363
21364 \family typewriter
21365 replace restart {
21366 \newline
21367 \SpecialChar ~
21368 \SpecialChar ~
21369 pop %1
21370 \newline
21371 \SpecialChar ~
21372 \SpecialChar ~
21373 push %1 } by {
21374 \newline
21375 \SpecialChar ~
21376 \SpecialChar ~
21377 ; nop
21378 \newline
21379 }
21380 \layout Standard
21381
21382 Note that the replace pattern cannot be a blank, but can be a comment line.
21383  Without the 'restart' option only the innermost 'pop' 'push' pair would
21384  be eliminated, i.e.:
21385 \layout Verse
21386
21387
21388 \family typewriter
21389 pop ar1
21390 \newline
21391 pop ar2
21392 \newline
21393 push ar2
21394 \newline
21395 push ar1
21396 \layout Standard
21397
21398 would result in:
21399 \layout Verse
21400
21401
21402 \family typewriter
21403 pop ar1
21404 \newline
21405 ; nop
21406 \newline
21407 push ar1
21408 \layout Standard
21409
21410
21411 \emph on
21412 with
21413 \emph default
21414  the restart option the rule will be applied again to the resulting code
21415  and then all the pop-push pairs will be eliminated to yield:
21416 \layout Verse
21417
21418
21419 \family typewriter
21420 ; nop
21421 \newline
21422 ; nop
21423 \layout Standard
21424
21425 A conditional function can be attached to a rule.
21426  Attaching rules are somewhat more involved, let me illustrate this with
21427  an example.
21428 \layout Verse
21429
21430
21431 \family typewriter
21432 replace {
21433 \newline
21434 \SpecialChar ~
21435  \SpecialChar ~
21436  \SpecialChar ~
21437 ljmp %5
21438 \newline
21439 %2:
21440 \newline
21441 } by {
21442 \newline
21443 \SpecialChar ~
21444  \SpecialChar ~
21445  \SpecialChar ~
21446 sjmp %5
21447 \newline
21448 %2:
21449 \newline
21450 } if labelInRange
21451 \layout Standard
21452
21453 The optimizer does a look-up of a function name table defined in function
21454
21455 \emph on
21456 callFuncByName
21457 \emph default
21458  in the source file SDCCpeeph.c, with the name
21459 \emph on
21460 labelInRange
21461 \emph default
21462 .
21463  If it finds a corresponding entry the function is called.
21464  Note there can be no parameters specified for these functions, in this
21465  case the use of
21466 \emph on
21467 %5
21468 \emph default
21469  is crucial, since the function
21470 \emph on
21471 labelInRange
21472 \emph default
21473  expects to find the label in that particular variable (the hash table containin
21474 g the variable bindings is passed as a parameter).
21475  If you want to code more such functions, take a close look at the function
21476  labelInRange and the calling mechanism in source file SDCCpeeph.c.
21477  Currently implemented are
21478 \emph on
21479 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
21480  24bitMode, portIsDS390, 24bitModeAndPortDS390
21481 \emph default
21482 and
21483 \emph on
21484  notVolatile
21485 \emph default
21486 .
21487 \layout Standard
21488
21489 I know this whole thing is a little kludgey, but maybe some day we will
21490  have some better means.
21491  If you are looking at this file, you will see the default rules that are
21492  compiled into the compiler, you can add your own rules in the default set
21493  there if you get tired of specifying the -
21494 \begin_inset ERT
21495 status Collapsed
21496
21497 \layout Standard
21498
21499 \backslash
21500 /
21501 \end_inset
21502
21503 -peep-file option.
21504 \layout Section
21505
21506 ANSI-Compliance
21507 \begin_inset LatexCommand \index{ANSI-compliance}
21508
21509 \end_inset
21510
21511
21512 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
21513
21514 \end_inset
21515
21516
21517 \layout Standard
21518
21519 Deviations from the compliance:
21520 \layout Itemize
21521
21522 functions are not always reentrant
21523 \begin_inset LatexCommand \index{reentrant}
21524
21525 \end_inset
21526
21527 .
21528 \layout Itemize
21529
21530 structures cannot be assigned values directly, cannot be passed as function
21531  parameters or assigned to each other and cannot be a return value from
21532  a function, e.g.:
21533 \begin_deeper
21534 \layout Verse
21535
21536
21537 \family typewriter
21538 struct s { ...
21539  };
21540 \newline
21541 struct s s1, s2;
21542 \newline
21543 foo()
21544 \newline
21545 {
21546 \newline
21547 \SpecialChar ~
21548 \SpecialChar ~
21549 \SpecialChar ~
21550 \SpecialChar ~
21551 ...
21552
21553 \newline
21554 \SpecialChar ~
21555 \SpecialChar ~
21556 \SpecialChar ~
21557 \SpecialChar ~
21558 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
21559 \newline
21560 \SpecialChar ~
21561 \SpecialChar ~
21562 \SpecialChar ~
21563 \SpecialChar ~
21564 ...
21565
21566 \newline
21567 }
21568 \newline
21569 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
21570  */
21571 \newline
21572 {
21573 \newline
21574 \SpecialChar ~
21575 \SpecialChar ~
21576 \SpecialChar ~
21577 \SpecialChar ~
21578 struct s rets;
21579 \newline
21580 \SpecialChar ~
21581 \SpecialChar ~
21582 \SpecialChar ~
21583 \SpecialChar ~
21584 ...
21585
21586 \newline
21587 \SpecialChar ~
21588 \SpecialChar ~
21589 \SpecialChar ~
21590 \SpecialChar ~
21591 return rets;/* is invalid in SDCC although allowed in ANSI */
21592 \newline
21593 }
21594 \end_deeper
21595 \layout Itemize
21596
21597 'long long
21598 \begin_inset LatexCommand \index{long long (not supported)}
21599
21600 \end_inset
21601
21602 ' (64 bit integers
21603 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
21604
21605 \end_inset
21606
21607 ) not supported.
21608 \layout Itemize
21609
21610 'double
21611 \begin_inset LatexCommand \index{double (not supported)}
21612
21613 \end_inset
21614
21615 ' precision floating point
21616 \begin_inset LatexCommand \index{Floating point support}
21617
21618 \end_inset
21619
21620 not supported.
21621 \layout Itemize
21622
21623 No support for setjmp
21624 \begin_inset LatexCommand \index{setjmp (not supported)}
21625
21626 \end_inset
21627
21628  and longjmp
21629 \begin_inset LatexCommand \index{longjmp (not supported)}
21630
21631 \end_inset
21632
21633  (for now).
21634 \layout Itemize
21635
21636 Old K&R style
21637 \begin_inset LatexCommand \index{K\&R style}
21638
21639 \end_inset
21640
21641  function declarations are NOT allowed.
21642 \begin_deeper
21643 \layout Verse
21644
21645
21646 \family typewriter
21647 foo(i,j) /* this old style of function declarations */
21648 \newline
21649 int i,j; /* are valid in ANSI but not valid in SDCC */
21650 \newline
21651 {
21652 \newline
21653 \SpecialChar ~
21654 \SpecialChar ~
21655 \SpecialChar ~
21656 \SpecialChar ~
21657 ...
21658
21659 \newline
21660 }
21661 \end_deeper
21662 \layout Section
21663
21664 Cyclomatic Complexity
21665 \begin_inset LatexCommand \index{Cyclomatic complexity}
21666
21667 \end_inset
21668
21669
21670 \layout Standard
21671
21672 Cyclomatic complexity of a function is defined as the number of independent
21673  paths the program can take during execution of the function.
21674  This is an important number since it defines the number test cases you
21675  have to generate to validate the function.
21676  The accepted industry standard for complexity number is 10, if the cyclomatic
21677  complexity reported by SDCC exceeds 10 you should think about simplification
21678  of the function logic.
21679  Note that the complexity level is not related to the number of lines of
21680  code in a function.
21681  Large functions can have low complexity, and small functions can have large
21682  complexity levels.
21683
21684 \newline
21685
21686 \newline
21687 SDCC uses the following formula to compute the complexity:
21688 \newline
21689
21690 \layout Standard
21691
21692 complexity = (number of edges in control flow graph) - (number of nodes
21693  in control flow graph) + 2;
21694 \newline
21695
21696 \newline
21697 Having said that the industry standard is 10, you should be aware that in
21698  some cases it be may unavoidable to have a complexity level of less than
21699  10.
21700  For example if you have switch statement with more than 10 case labels,
21701  each case label adds one to the complexity level.
21702  The complexity level is by no means an absolute measure of the algorithmic
21703  complexity of the function, it does however provide a good starting point
21704  for which functions you might look at for further optimization.
21705 \layout Section
21706
21707 Retargetting for other Processors
21708 \layout Standard
21709
21710 The issues for retargetting the compiler are far too numerous to be covered
21711  by this document.
21712  What follows is a brief description of each of the seven phases of the
21713  compiler and its MCU dependency.
21714 \layout Itemize
21715
21716 Parsing the source and building the annotated parse tree.
21717  This phase is largely MCU independent (except for the language extensions).
21718  Syntax & semantic checks are also done in this phase, along with some initial
21719  optimizations like back patching labels and the pattern matching optimizations
21720  like bit-rotation etc.
21721 \layout Itemize
21722
21723 The second phase involves generating an intermediate code which can be easy
21724  manipulated during the later phases.
21725  This phase is entirely MCU independent.
21726  The intermediate code generation assumes the target machine has unlimited
21727  number of registers, and designates them with the name iTemp.
21728  The compiler can be made to dump a human readable form of the code generated
21729  by using the -
21730 \begin_inset ERT
21731 status Collapsed
21732
21733 \layout Standard
21734
21735 \backslash
21736 /
21737 \end_inset
21738
21739 -dumpraw option.
21740 \layout Itemize
21741
21742 This phase does the bulk of the standard optimizations and is also MCU independe
21743 nt.
21744  This phase can be broken down into several sub-phases:
21745 \newline
21746
21747 \newline
21748 Break down intermediate code (iCode) into basic blocks.
21749 \newline
21750 Do control flow & data flow analysis on the basic blocks.
21751 \newline
21752 Do local common subexpression elimination, then global subexpression elimination
21753 \newline
21754 Dead code elimination
21755 \newline
21756 Loop optimizations
21757 \newline
21758 If loop optimizations caused any changes then do 'global subexpression eliminati
21759 on' and 'dead code elimination' again.
21760 \layout Itemize
21761
21762 This phase determines the live-ranges; by live range I mean those iTemp
21763  variables defined by the compiler that still survive after all the optimization
21764 s.
21765  Live range analysis
21766 \begin_inset LatexCommand \index{Live range analysis}
21767
21768 \end_inset
21769
21770  is essential for register allocation, since these computation determines
21771  which of these iTemps will be assigned to registers, and for how long.
21772 \layout Itemize
21773
21774 Phase five is register allocation.
21775  There are two parts to this process.
21776 \newline
21777
21778 \newline
21779 The first part I call 'register packing' (for lack of a better term).
21780  In this case several MCU specific expression folding is done to reduce
21781  register pressure.
21782 \newline
21783
21784 \newline
21785 The second part is more MCU independent and deals with allocating registers
21786  to the remaining live ranges.
21787  A lot of MCU specific code does creep into this phase because of the limited
21788  number of index registers available in the 8051.
21789 \layout Itemize
21790
21791 The Code generation phase is (unhappily), entirely MCU dependent and very
21792  little (if any at all) of this code can be reused for other MCU.
21793  However the scheme for allocating a homogenized assembler operand for each
21794  iCode operand may be reused.
21795 \layout Itemize
21796
21797 As mentioned in the optimization section the peep-hole optimizer is rule
21798  based system, which can reprogrammed for other MCUs.
21799 \layout Chapter
21800
21801 Compiler internals
21802 \begin_inset LatexCommand \index{Compiler internals}
21803
21804 \end_inset
21805
21806
21807 \layout Section
21808
21809 The anatomy of the compiler
21810 \begin_inset LatexCommand \label{sub:The-anatomy-of}
21811
21812 \end_inset
21813
21814
21815 \layout Standard
21816
21817
21818 \shape italic
21819 This is an excerpt from an article published in Circuit Cellar Magazine
21820  in august 2000.
21821  It's a little outdated (the compiler is much more efficient now and user/develo
21822 per friendly), but pretty well exposes the guts of it all.
21823 \shape default
21824
21825 \newline
21826
21827 \newline
21828 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
21829  It is fairly easy to retarget for other 8-bit MCU.
21830  Here we take a look at some of the internals of the compiler.
21831
21832 \layout Paragraph*
21833
21834 Parsing
21835 \begin_inset LatexCommand \index{Parsing}
21836
21837 \end_inset
21838
21839
21840 \layout Standard
21841
21842 Parsing the input source file and creating an AST (Annotated Syntax Tree
21843 \begin_inset LatexCommand \index{Annotated syntax tree}
21844
21845 \end_inset
21846
21847 ).
21848  This phase also involves propagating types (annotating each node of the
21849  parse tree with type information) and semantic analysis.
21850  There are some MCU specific parsing rules.
21851  For example the storage classes, the extended storage classes are MCU specific
21852  while there may be a xdata storage class for 8051 there is no such storage
21853  class for z80 or Atmel AVR.
21854  SDCC allows MCU specific storage class extensions, i.e.
21855  xdata will be treated as a storage class specifier when parsing 8051 C
21856  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
21857  C code.
21858 \layout Paragraph*
21859
21860 Generating iCode
21861 \begin_inset LatexCommand \index{iCode}
21862
21863 \end_inset
21864
21865
21866 \layout Standard
21867
21868 Intermediate code generation.
21869  In this phase the AST is broken down into three-operand form (iCode).
21870  These three operand forms are represented as doubly linked lists.
21871  ICode is the term given to the intermediate form generated by the compiler.
21872  ICode example section shows some examples of iCode generated for some simple
21873  C source functions.
21874 \layout Paragraph*
21875
21876 Optimizations
21877 \begin_inset LatexCommand \index{Optimizations}
21878
21879 \end_inset
21880
21881 .
21882 \layout Standard
21883
21884 Bulk of the target independent optimizations is performed in this phase.
21885  The optimizations include constant propagation, common sub-expression eliminati
21886 on, loop invariant code movement, strength reduction of loop induction variables
21887  and dead-code elimination.
21888 \layout Paragraph*
21889
21890 Live range analysis
21891 \begin_inset LatexCommand \index{Live range analysis}
21892
21893 \end_inset
21894
21895
21896 \layout Standard
21897
21898 During intermediate code generation phase, the compiler assumes the target
21899  machine has infinite number of registers and generates a lot of temporary
21900  variables.
21901  The live range computation determines the lifetime of each of these compiler-ge
21902 nerated temporaries.
21903  A picture speaks a thousand words.
21904  ICode example sections show the live range annotations for each of the
21905  operand.
21906  It is important to note here, each iCode is assigned a number in the order
21907  of its execution in the function.
21908  The live ranges are computed in terms of these numbers.
21909  The from number is the number of the iCode which first defines the operand
21910  and the to number signifies the iCode which uses this operand last.
21911 \layout Paragraph*
21912
21913 Register Allocation
21914 \begin_inset LatexCommand \index{Register allocation}
21915
21916 \end_inset
21917
21918
21919 \layout Standard
21920
21921 The register allocation determines the type and number of registers needed
21922  by each operand.
21923  In most MCUs only a few registers can be used for indirect addressing.
21924  In case of 8051 for example the registers R0 & R1 can be used to indirectly
21925  address the internal ram and DPTR to indirectly address the external ram.
21926  The compiler will try to allocate the appropriate register to pointer variables
21927  if it can.
21928  ICode example section shows the operands annotated with the registers assigned
21929  to them.
21930  The compiler will try to keep operands in registers as much as possible;
21931  there are several schemes the compiler uses to do achieve this.
21932  When the compiler runs out of registers the compiler will check to see
21933  if there are any live operands which is not used or defined in the current
21934  basic block being processed, if there are any found then it will push that
21935  operand and use the registers in this block, the operand will then be popped
21936  at the end of the basic block.
21937
21938 \layout Standard
21939
21940 There are other MCU specific considerations in this phase.
21941  Some MCUs have an accumulator; very short-lived operands could be assigned
21942  to the accumulator instead of a general-purpose register.
21943 \layout Paragraph*
21944
21945 Code generation
21946 \layout Standard
21947
21948 Figure II gives a table of iCode operations supported by the compiler.
21949  The code generation involves translating these operations into corresponding
21950  assembly code for the processor.
21951  This sounds overly simple but that is the essence of code generation.
21952  Some of the iCode operations are generated on a MCU specific manner for
21953  example, the z80 port does not use registers to pass parameters so the
21954  SEND and RECV iCode operations will not be generated, and it also does
21955  not support JUMPTABLES.
21956
21957 \newline
21958
21959 \series bold
21960 \shape italic
21961 \color red
21962 <Where is Figure II?>
21963 \layout Comment
21964
21965 In the original article Figure II was announced to be downloadable on
21966 \shape italic
21967 Circuit Cellar
21968 \shape default
21969 's web site.
21970  Unfortunately it never seemed to have shown up there, so: where is Figure
21971  II?
21972 \layout Paragraph*
21973
21974 ICode Example
21975 \begin_inset LatexCommand \index{iCode}
21976
21977 \end_inset
21978
21979
21980 \layout Standard
21981
21982 This section shows some details of iCode.
21983  The example C code does not do anything useful; it is used as an example
21984  to illustrate the intermediate code generated by the compiler.
21985 \layout Verse
21986
21987
21988 \family typewriter
21989 1.\SpecialChar ~
21990 xdata int * p;
21991 \newline
21992 2.\SpecialChar ~
21993 int gint;
21994 \newline
21995 3.\SpecialChar ~
21996 /* This function does nothing useful.
21997  It is used
21998 \newline
21999 4.\SpecialChar ~
22000 \SpecialChar ~
22001 \SpecialChar ~
22002 \SpecialChar ~
22003 for the purpose of explaining iCode */
22004 \newline
22005 5.\SpecialChar ~
22006 short function (data int *x)
22007 \newline
22008 6.\SpecialChar ~
22009 {
22010 \newline
22011 7.\SpecialChar ~
22012 \SpecialChar ~
22013 \SpecialChar ~
22014 short i=10; \SpecialChar ~
22015 \SpecialChar ~
22016 /* dead initialization eliminated */
22017 \newline
22018 8.\SpecialChar ~
22019 \SpecialChar ~
22020 \SpecialChar ~
22021 short sum=10; /* dead initialization eliminated */
22022 \newline
22023 9.\SpecialChar ~
22024 \SpecialChar ~
22025 \SpecialChar ~
22026 short mul;
22027 \newline
22028 10.\SpecialChar ~
22029 \SpecialChar ~
22030 int j ;
22031 \newline
22032 11.\SpecialChar ~
22033 \SpecialChar ~
22034 while (*x) *x++ = *p++;
22035 \newline
22036 12.\SpecialChar ~
22037 \SpecialChar ~
22038 \SpecialChar ~
22039 \SpecialChar ~
22040 sum = 0 ;
22041 \newline
22042 13.\SpecialChar ~
22043 \SpecialChar ~
22044 mul = 0;
22045 \newline
22046 14.\SpecialChar ~
22047 \SpecialChar ~
22048 /* compiler detects i,j to be induction variables */
22049 \newline
22050 15.\SpecialChar ~
22051 \SpecialChar ~
22052 for (i = 0, j = 10 ; i < 10 ; i++, j
22053 \family default
22054 -
22055 \begin_inset ERT
22056 status Collapsed
22057
22058 \layout Standard
22059
22060 \backslash
22061 /
22062 \end_inset
22063
22064 -
22065 \family typewriter
22066 ) {
22067 \newline
22068 16.\SpecialChar ~
22069 \SpecialChar ~
22070 \SpecialChar ~
22071 \SpecialChar ~
22072 sum += i;
22073 \newline
22074 17.\SpecialChar ~
22075 \SpecialChar ~
22076 \SpecialChar ~
22077 \SpecialChar ~
22078 mul += i * 3; \SpecialChar ~
22079 \SpecialChar ~
22080 /* this multiplication remains */
22081 \newline
22082 18.\SpecialChar ~
22083 \SpecialChar ~
22084 \SpecialChar ~
22085 \SpecialChar ~
22086 gint += j * 3;\SpecialChar ~
22087 \SpecialChar ~
22088 /* this multiplication changed to addition */
22089 \newline
22090 19.\SpecialChar ~
22091 \SpecialChar ~
22092 }
22093 \newline
22094 20.\SpecialChar ~
22095 \SpecialChar ~
22096 return sum+mul;
22097 \newline
22098 21.\SpecialChar ~
22099 }
22100 \layout Standard
22101
22102 In addition to the operands each iCode contains information about the filename
22103  and line it corresponds to in the source file.
22104  The first field in the listing should be interpreted as follows:
22105 \newline
22106
22107 \shape italic
22108 \size footnotesize
22109 Filename(linenumber: iCode Execution sequence number : ICode hash table
22110  key : loop depth of the iCode).
22111 \shape default
22112 \size default
22113
22114 \newline
22115 Then follows the human readable form of the ICode operation.
22116  Each operand of this triplet form can be of three basic types a) compiler
22117  generated temporary b) user defined variable c) a constant value.
22118  Note that local variables and parameters are replaced by compiler generated
22119  temporaries.
22120  Live ranges
22121 \begin_inset LatexCommand \index{Live range analysis}
22122
22123 \end_inset
22124
22125  are computed only for temporaries (i.e.
22126  live ranges are not computed for global variables).
22127  Registers
22128 \begin_inset LatexCommand \index{Register allocation}
22129
22130 \end_inset
22131
22132  are allocated for temporaries only.
22133  Operands are formatted in the following manner:
22134 \newline
22135
22136 \shape italic
22137 \size footnotesize
22138 Operand Name [lr live-from : live-to ] { type information } [ registers
22139  allocated ].
22140 \shape default
22141 \size default
22142
22143 \newline
22144 As mentioned earlier the live ranges are computed in terms of the execution
22145  sequence number of the iCodes, for example
22146 \newline
22147 the iTemp0 is live from (i.e.
22148  first defined in iCode with execution sequence number 3, and is last used
22149  in the iCode with sequence number 5).
22150  For induction variables such as iTemp21 the live range computation extends
22151  the lifetime from the start to the end of the loop.
22152 \newline
22153 The register allocator used the live range information to allocate registers,
22154  the same registers may be used for different temporaries if their live
22155  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
22156  iTemp17 since their live ranges do not overlap.
22157  In addition the allocator also takes into consideration the type and usage
22158  of a temporary, for example itemp6 is a pointer to near space and is used
22159  as to fetch data from (i.e.
22160  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
22161  Some short lived temporaries are allocated to special registers which have
22162  meaning to the code generator e.g.
22163  iTemp13 is allocated to a pseudo register CC which tells the back end that
22164  the temporary is used only for a conditional jump the code generation makes
22165  use of this information to optimize a compare and jump ICode.
22166 \newline
22167 There are several loop optimizations
22168 \begin_inset LatexCommand \index{Loop optimization}
22169
22170 \end_inset
22171
22172  performed by the compiler.
22173  It can detect induction variables iTemp21(i) and iTemp23(j).
22174  Also note the compiler does selective strength reduction
22175 \begin_inset LatexCommand \index{Strength reduction}
22176
22177 \end_inset
22178
22179 , i.e.
22180  the multiplication of an induction variable in line 18 (gint = j * 3) is
22181  changed to addition, a new temporary iTemp17 is allocated and assigned
22182  a initial value, a constant 3 is then added for each iteration of the loop.
22183  The compiler does not change the multiplication
22184 \begin_inset LatexCommand \index{Multiplication}
22185
22186 \end_inset
22187
22188  in line 17 however since the processor does support an 8 * 8 bit multiplication.
22189 \newline
22190 Note the dead code elimination
22191 \begin_inset LatexCommand \index{Dead-code elimination}
22192
22193 \end_inset
22194
22195  optimization eliminated the dead assignments in line 7 & 8 to I and sum
22196  respectively.
22197 \newline
22198
22199 \layout Standard
22200
22201
22202 \size footnotesize
22203 Sample.c (5:1:0:0) _entry($9) :
22204 \layout Standard
22205
22206
22207 \size footnotesize
22208 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
22209 \layout Standard
22210
22211
22212 \size footnotesize
22213 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
22214 \layout Standard
22215
22216
22217 \size footnotesize
22218 Sample.c(11:4:53:0) preHeaderLbl0($11) :
22219 \layout Standard
22220
22221
22222 \size footnotesize
22223 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
22224  * int}[r2]
22225 \layout Standard
22226
22227
22228 \size footnotesize
22229 Sample.c(11:6:5:1) _whilecontinue_0($1) :
22230 \layout Standard
22231
22232
22233 \size footnotesize
22234 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
22235  int}[r0]]
22236 \layout Standard
22237
22238
22239 \size footnotesize
22240 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
22241 \layout Standard
22242
22243
22244 \size footnotesize
22245 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
22246  * int}
22247 \layout Standard
22248
22249
22250 \size footnotesize
22251 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
22252  {short}
22253 \layout Standard
22254
22255
22256 \size footnotesize
22257 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
22258  * int}[DPTR]]
22259 \layout Standard
22260
22261
22262 \size footnotesize
22263 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
22264 }[r2 r3]
22265 \layout Standard
22266
22267
22268 \size footnotesize
22269 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
22270  * int}[r0] + 0x2 {short}
22271 \layout Standard
22272
22273
22274 \size footnotesize
22275 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
22276 \layout Standard
22277
22278
22279 \size footnotesize
22280 Sample.c(11:17:21:0)_whilebreak_0($3) :
22281 \layout Standard
22282
22283
22284 \size footnotesize
22285 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
22286 \layout Standard
22287
22288
22289 \size footnotesize
22290 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
22291 \layout Standard
22292
22293
22294 \size footnotesize
22295 Sample.c(15:20:54:0)preHeaderLbl1($13) :
22296 \layout Standard
22297
22298
22299 \size footnotesize
22300 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
22301 \layout Standard
22302
22303
22304 \size footnotesize
22305 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
22306 \layout Standard
22307
22308
22309 \size footnotesize
22310 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
22311 \layout Standard
22312
22313
22314 \size footnotesize
22315 Sample.c(15:24:26:1)_forcond_0($4) :
22316 \layout Standard
22317
22318
22319 \size footnotesize
22320 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
22321  < 0xa {short}
22322 \layout Standard
22323
22324
22325 \size footnotesize
22326 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
22327 \layout Standard
22328
22329
22330 \size footnotesize
22331 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
22332  + ITemp21 [lr21:38]{short}[r4]
22333 \layout Standard
22334
22335
22336 \size footnotesize
22337 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
22338  * 0x3 {short}
22339 \layout Standard
22340
22341
22342 \size footnotesize
22343 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
22344  + iTemp15 [lr29:30]{short}[r1]
22345 \layout Standard
22346
22347
22348 \size footnotesize
22349 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
22350  r0]- 0x3 {short}
22351 \layout Standard
22352
22353
22354 \size footnotesize
22355 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
22356 int}[r7 r0]
22357 \layout Standard
22358
22359
22360 \size footnotesize
22361 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
22362  + 0x1 {short}
22363 \layout Standard
22364
22365
22366 \size footnotesize
22367 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
22368  r6]- 0x1 {short}
22369 \layout Standard
22370
22371
22372 \size footnotesize
22373 Sample.c(19:38:47:1) goto _forcond_0($4)
22374 \layout Standard
22375
22376
22377 \size footnotesize
22378 Sample.c(19:39:48:0)_forbreak_0($7) :
22379 \layout Standard
22380
22381
22382 \size footnotesize
22383 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
22384  + ITemp11 [lr19:40]{short}[r3]
22385 \layout Standard
22386
22387
22388 \size footnotesize
22389 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
22390 \layout Standard
22391
22392
22393 \size footnotesize
22394 Sample.c(20:42:51:0)_return($8) :
22395 \layout Standard
22396
22397
22398 \size footnotesize
22399 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
22400 \size default
22401
22402 \newline
22403
22404 \newline
22405 Finally the code generated for this function:
22406 \newline
22407
22408 \layout Standard
22409
22410
22411 \size footnotesize
22412 .area DSEG (DATA)
22413 \layout Standard
22414
22415
22416 \size footnotesize
22417 _p::
22418 \layout Standard
22419
22420
22421 \size footnotesize
22422 \SpecialChar ~
22423 \SpecialChar ~
22424 .ds 2
22425 \layout Standard
22426
22427
22428 \size footnotesize
22429 _gint::
22430 \layout Standard
22431
22432
22433 \size footnotesize
22434 \SpecialChar ~
22435 \SpecialChar ~
22436 .ds 2
22437 \layout Standard
22438
22439
22440 \size footnotesize
22441 ; sample.c 5
22442 \layout Standard
22443
22444
22445 \size footnotesize
22446 ; ----------------------------------------------
22447 \layout Standard
22448
22449
22450 \size footnotesize
22451 ; function function
22452 \layout Standard
22453
22454
22455 \size footnotesize
22456 ; ----------------------------------------------
22457 \layout Standard
22458
22459
22460 \size footnotesize
22461 _function:
22462 \layout Standard
22463
22464
22465 \size footnotesize
22466 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
22467 \layout Standard
22468
22469
22470 \size footnotesize
22471 \SpecialChar ~
22472 \SpecialChar ~
22473 mov r2,dpl
22474 \layout Standard
22475
22476
22477 \size footnotesize
22478 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
22479 \layout Standard
22480
22481
22482 \size footnotesize
22483 \SpecialChar ~
22484 \SpecialChar ~
22485 mov ar0,r2
22486 \layout Standard
22487
22488
22489 \size footnotesize
22490 ;_whilecontinue_0($1) :
22491 \layout Standard
22492
22493
22494 \size footnotesize
22495 00101$:
22496 \layout Standard
22497
22498
22499 \size footnotesize
22500 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
22501 \layout Standard
22502
22503
22504 \size footnotesize
22505 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
22506 \layout Standard
22507
22508
22509 \size footnotesize
22510 \SpecialChar ~
22511 \SpecialChar ~
22512 mov ar2,@r0
22513 \layout Standard
22514
22515
22516 \size footnotesize
22517 \SpecialChar ~
22518 \SpecialChar ~
22519 inc r0
22520 \layout Standard
22521
22522
22523 \size footnotesize
22524 \SpecialChar ~
22525 \SpecialChar ~
22526 mov ar3,@r0
22527 \layout Standard
22528
22529
22530 \size footnotesize
22531 \SpecialChar ~
22532 \SpecialChar ~
22533 dec r0
22534 \layout Standard
22535
22536
22537 \size footnotesize
22538 \SpecialChar ~
22539 \SpecialChar ~
22540 mov a,r2
22541 \layout Standard
22542
22543
22544 \size footnotesize
22545 \SpecialChar ~
22546 \SpecialChar ~
22547 orl a,r3
22548 \layout Standard
22549
22550
22551 \size footnotesize
22552 \SpecialChar ~
22553 \SpecialChar ~
22554 jz 00103$
22555 \layout Standard
22556
22557
22558 \size footnotesize
22559 00114$:
22560 \layout Standard
22561
22562
22563 \size footnotesize
22564 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
22565 \layout Standard
22566
22567
22568 \size footnotesize
22569 \SpecialChar ~
22570 \SpecialChar ~
22571 mov dpl,_p
22572 \layout Standard
22573
22574
22575 \size footnotesize
22576 \SpecialChar ~
22577 \SpecialChar ~
22578 mov dph,(_p + 1)
22579 \layout Standard
22580
22581
22582 \size footnotesize
22583 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
22584 \layout Standard
22585
22586
22587 \size footnotesize
22588 \SpecialChar ~
22589 \SpecialChar ~
22590 mov a,#0x02
22591 \layout Standard
22592
22593
22594 \size footnotesize
22595 \SpecialChar ~
22596 \SpecialChar ~
22597 add a,_p
22598 \layout Standard
22599
22600
22601 \size footnotesize
22602 \SpecialChar ~
22603 \SpecialChar ~
22604 mov _p,a
22605 \layout Standard
22606
22607
22608 \size footnotesize
22609 \SpecialChar ~
22610 \SpecialChar ~
22611 clr a
22612 \layout Standard
22613
22614
22615 \size footnotesize
22616 \SpecialChar ~
22617 \SpecialChar ~
22618 addc a,(_p + 1)
22619 \layout Standard
22620
22621
22622 \size footnotesize
22623 \SpecialChar ~
22624 \SpecialChar ~
22625 mov (_p + 1),a
22626 \layout Standard
22627
22628
22629 \size footnotesize
22630 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
22631 \layout Standard
22632
22633
22634 \size footnotesize
22635 \SpecialChar ~
22636 \SpecialChar ~
22637 movx a,@dptr
22638 \layout Standard
22639
22640
22641 \size footnotesize
22642 \SpecialChar ~
22643 \SpecialChar ~
22644 mov r2,a
22645 \layout Standard
22646
22647
22648 \size footnotesize
22649 \SpecialChar ~
22650 \SpecialChar ~
22651 inc dptr
22652 \layout Standard
22653
22654
22655 \size footnotesize
22656 \SpecialChar ~
22657 \SpecialChar ~
22658 movx a,@dptr
22659 \layout Standard
22660
22661
22662 \size footnotesize
22663 \SpecialChar ~
22664 \SpecialChar ~
22665 mov r3,a
22666 \layout Standard
22667
22668
22669 \size footnotesize
22670 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
22671 \layout Standard
22672
22673
22674 \size footnotesize
22675 \SpecialChar ~
22676 \SpecialChar ~
22677 mov @r0,ar2
22678 \layout Standard
22679
22680
22681 \size footnotesize
22682 \SpecialChar ~
22683 \SpecialChar ~
22684 inc r0
22685 \layout Standard
22686
22687
22688 \size footnotesize
22689 \SpecialChar ~
22690 \SpecialChar ~
22691 mov @r0,ar3
22692 \layout Standard
22693
22694
22695 \size footnotesize
22696 ; iTemp6 [lr5:16]{_near * int}[r0] =
22697 \layout Standard
22698
22699
22700 \size footnotesize
22701 ; iTemp6 [lr5:16]{_near * int}[r0] +
22702 \layout Standard
22703
22704
22705 \size footnotesize
22706 ; 0x2 {short}
22707 \layout Standard
22708
22709
22710 \size footnotesize
22711 \SpecialChar ~
22712 \SpecialChar ~
22713 inc r0
22714 \layout Standard
22715
22716
22717 \size footnotesize
22718 ; goto _whilecontinue_0($1)
22719 \layout Standard
22720
22721
22722 \size footnotesize
22723 \SpecialChar ~
22724 \SpecialChar ~
22725 sjmp 00101$
22726 \layout Standard
22727
22728
22729 \size footnotesize
22730 ; _whilebreak_0($3) :
22731 \layout Standard
22732
22733
22734 \size footnotesize
22735 00103$:
22736 \layout Standard
22737
22738
22739 \size footnotesize
22740 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
22741 \layout Standard
22742
22743
22744 \size footnotesize
22745 \SpecialChar ~
22746 \SpecialChar ~
22747 mov r2,#0x00
22748 \layout Standard
22749
22750
22751 \size footnotesize
22752 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
22753 \layout Standard
22754
22755
22756 \size footnotesize
22757 \SpecialChar ~
22758 \SpecialChar ~
22759 mov r3,#0x00
22760 \layout Standard
22761
22762
22763 \size footnotesize
22764 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
22765 \layout Standard
22766
22767
22768 \size footnotesize
22769 \SpecialChar ~
22770 \SpecialChar ~
22771 mov r4,#0x00
22772 \layout Standard
22773
22774
22775 \size footnotesize
22776 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
22777 \layout Standard
22778
22779
22780 \size footnotesize
22781 \SpecialChar ~
22782 \SpecialChar ~
22783 mov r5,#0x0A
22784 \layout Standard
22785
22786
22787 \size footnotesize
22788 \SpecialChar ~
22789 \SpecialChar ~
22790 mov r6,#0x00
22791 \layout Standard
22792
22793
22794 \size footnotesize
22795 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
22796 \layout Standard
22797
22798
22799 \size footnotesize
22800 \SpecialChar ~
22801 \SpecialChar ~
22802 mov r7,#0x1E
22803 \layout Standard
22804
22805
22806 \size footnotesize
22807 \SpecialChar ~
22808 \SpecialChar ~
22809 mov r0,#0x00
22810 \layout Standard
22811
22812
22813 \size footnotesize
22814 ; _forcond_0($4) :
22815 \layout Standard
22816
22817
22818 \size footnotesize
22819 00104$:
22820 \layout Standard
22821
22822
22823 \size footnotesize
22824 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
22825 \layout Standard
22826
22827
22828 \size footnotesize
22829 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
22830 \layout Standard
22831
22832
22833 \size footnotesize
22834 \SpecialChar ~
22835 \SpecialChar ~
22836 clr c
22837 \layout Standard
22838
22839
22840 \size footnotesize
22841 \SpecialChar ~
22842 \SpecialChar ~
22843 mov a,r4
22844 \layout Standard
22845
22846
22847 \size footnotesize
22848 \SpecialChar ~
22849 \SpecialChar ~
22850 xrl a,#0x80
22851 \layout Standard
22852
22853
22854 \size footnotesize
22855 \SpecialChar ~
22856 \SpecialChar ~
22857 subb a,#0x8a
22858 \layout Standard
22859
22860
22861 \size footnotesize
22862 \SpecialChar ~
22863 \SpecialChar ~
22864 jnc 00107$
22865 \layout Standard
22866
22867
22868 \size footnotesize
22869 00115$:
22870 \layout Standard
22871
22872
22873 \size footnotesize
22874 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
22875 \layout Standard
22876
22877
22878 \size footnotesize
22879 ; iTemp21 [lr21:38]{short}[r4]
22880 \layout Standard
22881
22882
22883 \size footnotesize
22884 \SpecialChar ~
22885 \SpecialChar ~
22886 mov a,r4
22887 \layout Standard
22888
22889
22890 \size footnotesize
22891 \SpecialChar ~
22892 \SpecialChar ~
22893 add a,r2
22894 \layout Standard
22895
22896
22897 \size footnotesize
22898 \SpecialChar ~
22899 \SpecialChar ~
22900 mov r2,a
22901 \layout Standard
22902
22903
22904 \size footnotesize
22905 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
22906 \layout Standard
22907
22908
22909 \size footnotesize
22910 \SpecialChar ~
22911 \SpecialChar ~
22912 mov b,#0x03
22913 \layout Standard
22914
22915
22916 \size footnotesize
22917 \SpecialChar ~
22918 \SpecialChar ~
22919 mov a,r4
22920 \layout Standard
22921
22922
22923 \size footnotesize
22924 \SpecialChar ~
22925 \SpecialChar ~
22926 mul ab
22927 \layout Standard
22928
22929
22930 \size footnotesize
22931 \SpecialChar ~
22932 \SpecialChar ~
22933 mov r1,a
22934 \layout Standard
22935
22936
22937 \size footnotesize
22938 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
22939 \layout Standard
22940
22941
22942 \size footnotesize
22943 ; iTemp15 [lr29:30]{short}[r1]
22944 \layout Standard
22945
22946
22947 \size footnotesize
22948 \SpecialChar ~
22949 \SpecialChar ~
22950 add a,r3
22951 \layout Standard
22952
22953
22954 \size footnotesize
22955 \SpecialChar ~
22956 \SpecialChar ~
22957 mov r3,a
22958 \layout Standard
22959
22960
22961 \size footnotesize
22962 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
22963 \layout Standard
22964
22965
22966 \size footnotesize
22967 \SpecialChar ~
22968 \SpecialChar ~
22969 mov a,r7
22970 \layout Standard
22971
22972
22973 \size footnotesize
22974 \SpecialChar ~
22975 \SpecialChar ~
22976 add a,#0xfd
22977 \layout Standard
22978
22979
22980 \size footnotesize
22981 \SpecialChar ~
22982 \SpecialChar ~
22983 mov r7,a
22984 \layout Standard
22985
22986
22987 \size footnotesize
22988 \SpecialChar ~
22989 \SpecialChar ~
22990 mov a,r0
22991 \layout Standard
22992
22993
22994 \size footnotesize
22995 \SpecialChar ~
22996 \SpecialChar ~
22997 addc a,#0xff
22998 \layout Standard
22999
23000
23001 \size footnotesize
23002 \SpecialChar ~
23003 \SpecialChar ~
23004 mov r0,a
23005 \layout Standard
23006
23007
23008 \size footnotesize
23009 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
23010 \layout Standard
23011
23012
23013 \size footnotesize
23014 \SpecialChar ~
23015 \SpecialChar ~
23016 mov a,r7
23017 \layout Standard
23018
23019
23020 \size footnotesize
23021 \SpecialChar ~
23022 \SpecialChar ~
23023 add a,_gint
23024 \layout Standard
23025
23026
23027 \size footnotesize
23028 \SpecialChar ~
23029 \SpecialChar ~
23030 mov _gint,a
23031 \layout Standard
23032
23033
23034 \size footnotesize
23035 \SpecialChar ~
23036 \SpecialChar ~
23037 mov a,r0
23038 \layout Standard
23039
23040
23041 \size footnotesize
23042 \SpecialChar ~
23043 \SpecialChar ~
23044 addc a,(_gint + 1)
23045 \layout Standard
23046
23047
23048 \size footnotesize
23049 \SpecialChar ~
23050 \SpecialChar ~
23051 mov (_gint + 1),a
23052 \layout Standard
23053
23054
23055 \size footnotesize
23056 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
23057 \layout Standard
23058
23059
23060 \size footnotesize
23061 \SpecialChar ~
23062 \SpecialChar ~
23063 inc r4
23064 \layout Standard
23065
23066
23067 \size footnotesize
23068 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
23069 \layout Standard
23070
23071
23072 \size footnotesize
23073 \SpecialChar ~
23074 \SpecialChar ~
23075 dec r5
23076 \layout Standard
23077
23078
23079 \size footnotesize
23080 \SpecialChar ~
23081 \SpecialChar ~
23082 cjne r5,#0xff,00104$
23083 \layout Standard
23084
23085
23086 \size footnotesize
23087 \SpecialChar ~
23088 \SpecialChar ~
23089 dec r6
23090 \layout Standard
23091
23092
23093 \size footnotesize
23094 ; goto _forcond_0($4)
23095 \layout Standard
23096
23097
23098 \size footnotesize
23099 \SpecialChar ~
23100 \SpecialChar ~
23101 sjmp 00104$
23102 \layout Standard
23103
23104
23105 \size footnotesize
23106 ; _forbreak_0($7) :
23107 \layout Standard
23108
23109
23110 \size footnotesize
23111 00107$:
23112 \layout Standard
23113
23114
23115 \size footnotesize
23116 ; ret iTemp24 [lr40:41]{short}
23117 \layout Standard
23118
23119
23120 \size footnotesize
23121 \SpecialChar ~
23122 \SpecialChar ~
23123 mov a,r3
23124 \layout Standard
23125
23126
23127 \size footnotesize
23128 \SpecialChar ~
23129 \SpecialChar ~
23130 add a,r2
23131 \layout Standard
23132
23133
23134 \size footnotesize
23135 \SpecialChar ~
23136 \SpecialChar ~
23137 mov dpl,a
23138 \layout Standard
23139
23140
23141 \size footnotesize
23142 ; _return($8) :
23143 \layout Standard
23144
23145
23146 \size footnotesize
23147 00108$:
23148 \layout Standard
23149
23150
23151 \size footnotesize
23152 \SpecialChar ~
23153 \SpecialChar ~
23154 ret
23155 \newline
23156
23157 \layout Section
23158
23159 A few words about basic block successors, predecessors and dominators
23160 \layout Standard
23161
23162 Successors are basic blocks
23163 \begin_inset LatexCommand \index{Basic blocks}
23164
23165 \end_inset
23166
23167  that might execute after this basic block.
23168 \newline
23169 Predecessors are basic blocks that might execute before reaching this basic
23170  block.
23171 \newline
23172 Dominators are basic blocks that WILL execute before reaching this basic
23173  block.
23174 \newline
23175
23176 \layout Standard
23177
23178 [basic block 1]
23179 \layout Standard
23180
23181 if (something)
23182 \layout Standard
23183
23184 \SpecialChar ~
23185 \SpecialChar ~
23186 \SpecialChar ~
23187 \SpecialChar ~
23188 [basic block 2]
23189 \layout Standard
23190
23191 else
23192 \layout Standard
23193
23194 \SpecialChar ~
23195 \SpecialChar ~
23196 \SpecialChar ~
23197 \SpecialChar ~
23198 [basic block 3]
23199 \layout Standard
23200
23201 [basic block 4]
23202 \newline
23203
23204 \layout Standard
23205
23206 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
23207 \layout Standard
23208
23209 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
23210 \layout Standard
23211
23212 c) domVect of [BB4] = BB1 ...
23213  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
23214  was executed.
23215 \layout Chapter
23216
23217 Acknowledgments
23218 \layout Standard
23219
23220
23221 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
23222
23223 \end_inset
23224
23225
23226 \newline
23227
23228 \newline
23229
23230 \emph on
23231 Thanks to all the other volunteer developers who have helped with coding,
23232  testing, web-page creation, distribution sets, etc.
23233  You know who you are :-)
23234 \emph default
23235
23236 \newline
23237
23238 \layout Standard
23239
23240 This document was initially written by Sandeep Dutta
23241 \layout Standard
23242
23243 All product names mentioned herein may be trademarks
23244 \begin_inset LatexCommand \index{Trademarks}
23245
23246 \end_inset
23247
23248  of their respective companies.
23249
23250 \layout Section*
23251
23252 Alphabetical index
23253 \layout Standard
23254
23255 To avoid confusion, the installation and building options for SDCC itself
23256  (chapter 2) are not part of the index.
23257 \layout Standard
23258
23259
23260 \begin_inset LatexCommand \printindex{}
23261
23262 \end_inset
23263
23264
23265 \the_end