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.
14294
14295 \layout Standard
14296
14297 SDCPP supports the following #pragma directives:
14298 \layout Itemize
14299
14300 preproc_asm
14301 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
14302
14303 \end_inset
14304
14305  (+ | -) - switch _asm _endasm block preprocessing on / off.
14306  Default is on.
14307 \layout Standard
14308
14309 The pragma's are intended to be used to turn-on or off certain optimizations
14310  which might cause the compiler to generate extra stack / data space to
14311  store compiler generated temporary variables.
14312  This usually happens in large functions.
14313  Pragma directives should be used as shown in the following example, they
14314  are used to control options & optimizations for a given function; pragmas
14315  should be placed before and/or after a function, placing pragma's inside
14316  a function body could have unpredictable results.
14317 \layout Verse
14318
14319
14320 \family typewriter
14321 #pragma save
14322 \begin_inset LatexCommand \index{\#pragma save}
14323
14324 \end_inset
14325
14326  \SpecialChar ~
14327 \SpecialChar ~
14328 \SpecialChar ~
14329 \SpecialChar ~
14330 \SpecialChar ~
14331 \SpecialChar ~
14332 \SpecialChar ~
14333 /* save the current settings */
14334 \newline
14335 #pragma nogcse
14336 \begin_inset LatexCommand \index{\#pragma nogcse}
14337
14338 \end_inset
14339
14340  \SpecialChar ~
14341 \SpecialChar ~
14342 \SpecialChar ~
14343 \SpecialChar ~
14344 \SpecialChar ~
14345 /* turnoff global subexpression elimination */
14346 \newline
14347 #pragma noinduction
14348 \begin_inset LatexCommand \index{\#pragma noinduction}
14349
14350 \end_inset
14351
14352  /* turn off induction optimizations */
14353 \newline
14354 int foo ()
14355 \newline
14356 {
14357 \newline
14358 \SpecialChar ~
14359  \SpecialChar ~
14360  ...
14361
14362 \newline
14363 \SpecialChar ~
14364  \SpecialChar ~
14365  /* large code */
14366 \newline
14367 \SpecialChar ~
14368  \SpecialChar ~
14369  ...
14370
14371 \newline
14372 }
14373 \newline
14374 #pragma restore
14375 \begin_inset LatexCommand \index{\#pragma restore}
14376
14377 \end_inset
14378
14379  /* turn the optimizations back on */
14380 \layout Standard
14381
14382 The compiler will generate a warning message when extra space is allocated.
14383  It is strongly recommended that the save and restore pragma's be used when
14384  changing options for a function.
14385 \layout Section
14386
14387 Defines Created by the Compiler
14388 \layout Standard
14389
14390 The compiler creates the following #defines
14391 \begin_inset LatexCommand \index{\#defines}
14392
14393 \end_inset
14394
14395
14396 \begin_inset LatexCommand \index{Defines created by the compiler}
14397
14398 \end_inset
14399
14400 :
14401 \newline
14402
14403 \layout Standard
14404
14405
14406 \begin_inset  Tabular
14407 <lyxtabular version="3" rows="10" columns="2">
14408 <features>
14409 <column alignment="center" valignment="top" leftline="true" width="0">
14410 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
14411 <row topline="true" bottomline="true">
14412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14413 \begin_inset Text
14414
14415 \layout Standard
14416
14417
14418 \series bold
14419 #define
14420 \end_inset
14421 </cell>
14422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14423 \begin_inset Text
14424
14425 \layout Standard
14426
14427
14428 \series bold
14429 Description
14430 \end_inset
14431 </cell>
14432 </row>
14433 <row topline="true">
14434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14435 \begin_inset Text
14436
14437 \layout Standard
14438
14439 SDCC
14440 \begin_inset LatexCommand \index{SDCC}
14441
14442 \end_inset
14443
14444
14445 \end_inset
14446 </cell>
14447 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14448 \begin_inset Text
14449
14450 \layout Standard
14451
14452 this Symbol is always defined
14453 \end_inset
14454 </cell>
14455 </row>
14456 <row topline="true">
14457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14458 \begin_inset Text
14459
14460 \layout Standard
14461
14462 SDCC_mcs51
14463 \begin_inset LatexCommand \index{SDCC\_mcs51}
14464
14465 \end_inset
14466
14467  or SDCC_ds390
14468 \begin_inset LatexCommand \index{SDCC\_ds390}
14469
14470 \end_inset
14471
14472  or SDCC_z80
14473 \begin_inset LatexCommand \index{SDCC\_z80}
14474
14475 \end_inset
14476
14477 , etc
14478 \end_inset
14479 </cell>
14480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14481 \begin_inset Text
14482
14483 \layout Standard
14484
14485 depending on the model used (e.g.: -mds390
14486 \end_inset
14487 </cell>
14488 </row>
14489 <row topline="true">
14490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14491 \begin_inset Text
14492
14493 \layout Standard
14494
14495 __mcs51
14496 \begin_inset LatexCommand \index{\_\_mcs51}
14497
14498 \end_inset
14499
14500 , __ds390
14501 \begin_inset LatexCommand \index{\_\_ds390}
14502
14503 \end_inset
14504
14505 , __hc08
14506 \begin_inset LatexCommand \index{\_\_hc08}
14507
14508 \end_inset
14509
14510 , __z80
14511 \begin_inset LatexCommand \index{\_\_z80}
14512
14513 \end_inset
14514
14515 , etc
14516 \end_inset
14517 </cell>
14518 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14519 \begin_inset Text
14520
14521 \layout Standard
14522
14523 depending on the model used (e.g.
14524  -mz80)
14525 \end_inset
14526 </cell>
14527 </row>
14528 <row topline="true">
14529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14530 \begin_inset Text
14531
14532 \layout Standard
14533
14534 SDCC_STACK_AUTO
14535 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
14536
14537 \end_inset
14538
14539
14540 \end_inset
14541 </cell>
14542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14543 \begin_inset Text
14544
14545 \layout Standard
14546
14547 when
14548 \emph on
14549 -
14550 \begin_inset ERT
14551 status Collapsed
14552
14553 \layout Standard
14554
14555 \backslash
14556 /
14557 \end_inset
14558
14559 -stack-auto
14560 \emph default
14561  option is used
14562 \end_inset
14563 </cell>
14564 </row>
14565 <row topline="true">
14566 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14567 \begin_inset Text
14568
14569 \layout Standard
14570
14571 SDCC_MODEL_SMALL
14572 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
14573
14574 \end_inset
14575
14576
14577 \end_inset
14578 </cell>
14579 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14580 \begin_inset Text
14581
14582 \layout Standard
14583
14584 when
14585 \emph on
14586 -
14587 \begin_inset ERT
14588 status Collapsed
14589
14590 \layout Standard
14591
14592 \backslash
14593 /
14594 \end_inset
14595
14596 -model-small
14597 \emph default
14598  is used
14599 \end_inset
14600 </cell>
14601 </row>
14602 <row topline="true">
14603 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14604 \begin_inset Text
14605
14606 \layout Standard
14607
14608 SDCC_MODEL_LARGE
14609 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
14610
14611 \end_inset
14612
14613
14614 \end_inset
14615 </cell>
14616 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14617 \begin_inset Text
14618
14619 \layout Standard
14620
14621 when
14622 \emph on
14623 -
14624 \begin_inset ERT
14625 status Collapsed
14626
14627 \layout Standard
14628
14629 \backslash
14630 /
14631 \end_inset
14632
14633 -model-large
14634 \emph default
14635  is used
14636 \end_inset
14637 </cell>
14638 </row>
14639 <row topline="true">
14640 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14641 \begin_inset Text
14642
14643 \layout Standard
14644
14645 SDCC_USE_XSTACK
14646 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
14647
14648 \end_inset
14649
14650
14651 \end_inset
14652 </cell>
14653 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14654 \begin_inset Text
14655
14656 \layout Standard
14657
14658 when
14659 \emph on
14660 -
14661 \begin_inset ERT
14662 status Collapsed
14663
14664 \layout Standard
14665
14666 \backslash
14667 /
14668 \end_inset
14669
14670 -xstack
14671 \emph default
14672  option is used
14673 \end_inset
14674 </cell>
14675 </row>
14676 <row topline="true">
14677 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14678 \begin_inset Text
14679
14680 \layout Standard
14681
14682 SDCC_STACK_TENBIT
14683 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
14684
14685 \end_inset
14686
14687
14688 \end_inset
14689 </cell>
14690 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14691 \begin_inset Text
14692
14693 \layout Standard
14694
14695 when
14696 \emph on
14697 -mds390
14698 \emph default
14699  is used
14700 \end_inset
14701 </cell>
14702 </row>
14703 <row topline="true" bottomline="true">
14704 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14705 \begin_inset Text
14706
14707 \layout Standard
14708
14709 SDCC_MODEL_FLAT24
14710 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
14711
14712 \end_inset
14713
14714
14715 \end_inset
14716 </cell>
14717 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14718 \begin_inset Text
14719
14720 \layout Standard
14721
14722 when
14723 \emph on
14724 -mds390
14725 \emph default
14726  is used
14727 \end_inset
14728 </cell>
14729 </row>
14730 </lyxtabular>
14731
14732 \end_inset
14733
14734
14735 \layout Chapter
14736
14737 Notes on supported Processors
14738 \layout Section
14739
14740 MCS51 variants
14741 \begin_inset LatexCommand \label{sub:MCS51-variants}
14742
14743 \end_inset
14744
14745
14746 \begin_inset LatexCommand \index{MCS51 variants}
14747
14748 \end_inset
14749
14750
14751 \layout Standard
14752
14753 MCS51 processors are available from many vendors and come in many different
14754  flavours.
14755  While they might differ considerably in respect to Special Function Registers
14756  the core MCS51 is usually not modified or is kept compatible.
14757
14758 \layout Subsection
14759
14760 pdata access by SFR
14761 \layout Standard
14762
14763 With the upcome of devices with internal xdata and flash memory devices
14764  using port P2
14765 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14766
14767 \end_inset
14768
14769  as dedicated I/O port is becoming more popular.
14770  Switching the high byte for pdata
14771 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14772
14773 \end_inset
14774
14775  access which was formerly done by port P2 is then achieved by a Special
14776  Function Register
14777 \begin_inset LatexCommand \index{sfr}
14778
14779 \end_inset
14780
14781 .
14782  In well-established MCS51 tradition the address of this
14783 \emph on
14784 sfr
14785 \emph default
14786  is where the chip designers decided to put it.
14787  Needless to say that they didn't agree on a common name either.
14788  So that the startup code can correctly initialize xdata variables, you
14789  should define an sfr with the name _XPAGE
14790 \family typewriter
14791
14792 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
14793
14794 \end_inset
14795
14796
14797 \family default
14798  at the appropriate location if the default, port P2, is not used for this.
14799  Some examples are:
14800 \layout Verse
14801
14802
14803 \family typewriter
14804 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
14805 \layout Verse
14806
14807
14808 \family typewriter
14809 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
14810 \layout Verse
14811
14812
14813 \family typewriter
14814 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
14815 \layout Standard
14816
14817 For more exotic implementations further customizations may be needed.
14818  See section
14819 \begin_inset LatexCommand \ref{sub:Startup-Code}
14820
14821 \end_inset
14822
14823  for other possibilities.
14824 \layout Subsection
14825
14826 Other Features available by SFR
14827 \layout Standard
14828
14829 Some MCS51 variants offer features like Double DPTR
14830 \begin_inset LatexCommand \index{DPTR}
14831
14832 \end_inset
14833
14834 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
14835  These are currently not used for the MCS51 port.
14836  If you absolutely need them you can fall back to inline assembly or submit
14837  a patch to SDCC.
14838 \layout Section
14839
14840 DS400 port
14841 \layout Standard
14842
14843 The DS80C400 microcontroller has a rich set of peripherals.
14844  In its built-in ROM library it includes functions to access some of the
14845  features, among them is a TCP stack with IP4 and IP6 support.
14846  Library headers (currently in beta status) and other files are provided
14847  at
14848 \size footnotesize
14849
14850 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
14851
14852 \end_inset
14853
14854 .
14855
14856 \layout Section
14857
14858 The Z80 and gbz80 port
14859 \layout Standard
14860
14861 SDCC can target both the Zilog
14862 \begin_inset LatexCommand \index{Z80}
14863
14864 \end_inset
14865
14866  and the Nintendo Gameboy's Z80-like gbz80
14867 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
14868
14869 \end_inset
14870
14871 .
14872  The Z80 port is passed through the same
14873 \emph on
14874 regressions tests
14875 \begin_inset LatexCommand \index{Regression test}
14876
14877 \end_inset
14878
14879
14880 \emph default
14881  as the MCS51 and DS390 ports, so floating point support, support for long
14882  variables and bitfield support is fine.
14883  See mailing lists and forums about interrupt routines.
14884 \layout Standard
14885
14886 As always, the code is the authoritative reference - see z80/ralloc.c and
14887  z80/gen.c.
14888  The stack
14889 \begin_inset LatexCommand \index{stack}
14890
14891 \end_inset
14892
14893  frame is similar to that generated by the IAR Z80 compiler.
14894  IX is used as the base pointer, HL and IY are used as a temporary registers,
14895  and BC and DE are available for holding variables.
14896  Return values
14897 \begin_inset LatexCommand \index{return value}
14898
14899 \end_inset
14900
14901  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
14902  bytes).
14903  The gbz80 port use the same set of registers for the return values, but
14904  in a different order of significance: E (one byte), DE (two bytes), or
14905  HLDE (four bytes).
14906 \layout Section
14907
14908 The HC08 port
14909 \layout Standard
14910
14911 The port to the Motorola HC08
14912 \begin_inset LatexCommand \index{HC08}
14913
14914 \end_inset
14915
14916  family has been added in October 2003, and is still undergoing some basic
14917  development.
14918  The code generator is complete, but the register allocation is still quite
14919  unoptimized.
14920  Some of the SDCC's standard C library functions have embedded non-HC08
14921  inline assembly and so are not yet usable.
14922 \newline
14923
14924 \newline
14925
14926 \layout Section
14927
14928 The PIC14 port
14929 \layout Standard
14930
14931 The 14bit PIC
14932 \begin_inset LatexCommand \index{PIC14}
14933
14934 \end_inset
14935
14936  port still requires a major effort from the development community.
14937  However it can work for very simple code.
14938 \layout Subsection
14939
14940 C code and 14bit PIC code page
14941 \begin_inset LatexCommand \index{code page (pic14)}
14942
14943 \end_inset
14944
14945  and RAM banks
14946 \begin_inset LatexCommand \index{RAM bank (pic14)}
14947
14948 \end_inset
14949
14950
14951 \layout Standard
14952
14953 The linker organizes allocation for the code page and RAM banks.
14954  It does not have intimate knowledge of the code flow.
14955  It will put all the code section of a single asm file into a single code
14956  page.
14957  In order to make use of multiple code pages, separate asm files must be
14958  used.
14959  The compiler treats all functions of a single C file as being in the same
14960  code page unless it is non static.
14961  The compiler treats all local variables of a single C file as being in
14962  the same RAM bank unless it is an extern.
14963 \newline
14964
14965 \newline
14966 To get the best follow these guide lines:
14967 \layout Enumerate
14968
14969 make local functions static, as non static functions require code page selection
14970  overhead.
14971 \layout Enumerate
14972
14973 Make local variables static as extern variables require RAM bank selection
14974  overhead.
14975 \layout Enumerate
14976
14977 For devices that have multiple code pages it is more efficient to use the
14978  same number of files as pages, i.e.
14979  for the 16F877 use 4 separate files and i.e.
14980  for the 16F874 use 2 separate files.
14981  This way the linker can put the code for each file into different code
14982  pages and the compiler can allocate reusable variables more efficiently
14983  and there's less page selection overhead.
14984  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
14985  instruction set) use 'unsigned char' whereever possible instead of 'int'.
14986 \layout Subsection
14987
14988 Creating a device include file
14989 \layout Standard
14990
14991 For generating a device include file use the support perl script inc2h.pl
14992  kept in directory support/script.
14993 \layout Subsection
14994
14995 Interrupt code
14996 \layout Standard
14997
14998 For the interrupt function, use the keyword 'interrupt'
14999 \begin_inset LatexCommand \index{interrupt}
15000
15001 \end_inset
15002
15003  with level number of 0 (PIC14 only has 1 interrupt so this number is only
15004  there to avoid a syntax error - it ought to be fixed).
15005  E.g.:
15006 \layout Verse
15007
15008
15009 \family typewriter
15010 void Intr(void) interrupt 0
15011 \newline
15012 {
15013 \newline
15014 \SpecialChar ~
15015 \SpecialChar ~
15016 T0IF = 0; /* Clear timer interrupt */
15017 \newline
15018 }
15019 \layout Subsection
15020
15021 Linking and assembling
15022 \layout Standard
15023
15024 For assembling you can use either GPUTILS'
15025 \begin_inset LatexCommand \index{gputils (pic tools)}
15026
15027 \end_inset
15028
15029  gpasm.exe or MPLAB's mpasmwin.exe.
15030  GPUTILS is available from
15031 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
15032
15033 \end_inset
15034
15035 .
15036  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
15037  If you use MPLAB and an interrupt function then the linker script file
15038  vectors section will need to be enlarged to link with mplink.
15039 \newline
15040
15041 \newline
15042 Here is a
15043 \family typewriter
15044 Makefile
15045 \family default
15046  using GPUTILS:
15047 \layout Verse
15048
15049
15050 \family typewriter
15051 .c.o:
15052 \newline
15053 \SpecialChar ~
15054 \SpecialChar ~
15055 \SpecialChar ~
15056 \SpecialChar ~
15057 \SpecialChar ~
15058 \SpecialChar ~
15059 \SpecialChar ~
15060 \SpecialChar ~
15061 sdcc -S -V -mpic14 -p16F877 $<
15062 \newline
15063 \SpecialChar ~
15064 \SpecialChar ~
15065 \SpecialChar ~
15066 \SpecialChar ~
15067 \SpecialChar ~
15068 \SpecialChar ~
15069 \SpecialChar ~
15070 \SpecialChar ~
15071 gpasm -c $*.asm
15072 \newline
15073
15074 \newline
15075 $(PRJ).hex: $(OBJS)
15076 \newline
15077 \SpecialChar ~
15078 \SpecialChar ~
15079 \SpecialChar ~
15080 \SpecialChar ~
15081 \SpecialChar ~
15082 \SpecialChar ~
15083 \SpecialChar ~
15084 \SpecialChar ~
15085 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
15086 \layout Standard
15087
15088 Here is a
15089 \family typewriter
15090 Makefile
15091 \family default
15092  using MPLAB:
15093 \layout Verse
15094
15095
15096 \family typewriter
15097 .c.o:
15098 \newline
15099 \SpecialChar ~
15100 \SpecialChar ~
15101 \SpecialChar ~
15102 \SpecialChar ~
15103 \SpecialChar ~
15104 \SpecialChar ~
15105 \SpecialChar ~
15106 \SpecialChar ~
15107 sdcc -S -V -mpic14 -p16F877 $<
15108 \newline
15109 \SpecialChar ~
15110 \SpecialChar ~
15111 \SpecialChar ~
15112 \SpecialChar ~
15113 \SpecialChar ~
15114 \SpecialChar ~
15115 \SpecialChar ~
15116 \SpecialChar ~
15117 mpasmwin /q /o $*.asm
15118 \newline
15119
15120 \newline
15121 $(PRJ).hex: $(OBJS)
15122 \newline
15123 \SpecialChar ~
15124 \SpecialChar ~
15125 \SpecialChar ~
15126 \SpecialChar ~
15127 \SpecialChar ~
15128 \SpecialChar ~
15129 \SpecialChar ~
15130 \SpecialChar ~
15131 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
15132 \layout Standard
15133
15134 Please note that indentations within a
15135 \family typewriter
15136  Makefile
15137 \family default
15138  have to be done with a tabulator character.
15139 \layout Section
15140
15141 The PIC16
15142 \begin_inset LatexCommand \index{PIC16}
15143
15144 \end_inset
15145
15146  port
15147 \layout Standard
15148
15149 The PIC16
15150 \begin_inset LatexCommand \index{PIC16}
15151
15152 \end_inset
15153
15154  port is the portion of SDCC that is responsible to produce code for the
15155  Microchip
15156 \begin_inset LatexCommand \index{Microchip}
15157
15158 \end_inset
15159
15160 (TM) microcontrollers with 16 bit core.
15161  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
15162 \layout Subsection
15163
15164 Global Options
15165 \layout Standard
15166
15167 PIC16 port supports the standard command line arguments as supposed, with
15168  the exception of certain cases that will be mentioned in the following
15169  list:
15170 \layout List
15171 \labelwidthstring 00.00.0000
15172
15173 -
15174 \begin_inset ERT
15175 status Collapsed
15176
15177 \layout Standard
15178
15179 \backslash
15180 /
15181 \end_inset
15182
15183 -stack-auto Auto variables that are function parameters, will be saved on
15184  stack by default.
15185
15186 \emph on
15187 There is no need to specify this in the command line.
15188 \layout List
15189 \labelwidthstring 00.00.0000
15190
15191 -
15192 \begin_inset ERT
15193 status Collapsed
15194
15195 \layout Standard
15196
15197 \backslash
15198 /
15199 \end_inset
15200
15201 -float-reent All floating point functions are reentrant by default.
15202
15203 \emph on
15204 There is no need to specifiy this in the command line.
15205 \layout List
15206 \labelwidthstring 00.00.0000
15207
15208 -
15209 \begin_inset ERT
15210 status Collapsed
15211
15212 \layout Standard
15213
15214 \backslash
15215 /
15216 \end_inset
15217
15218 -callee-saves See -
15219 \begin_inset ERT
15220 status Collapsed
15221
15222 \layout Standard
15223
15224 \backslash
15225 /
15226 \end_inset
15227
15228 -all-callee-saves
15229 \layout List
15230 \labelwidthstring 00.00.0000
15231
15232 -
15233 \begin_inset ERT
15234 status Collapsed
15235
15236 \layout Standard
15237
15238 \backslash
15239 /
15240 \end_inset
15241
15242 -all-callee-saves All function arguments are passed on stack by default.
15243
15244 \emph on
15245 There is no need to specify this in the command line.
15246 \layout List
15247 \labelwidthstring 00.00.0000
15248
15249 -
15250 \begin_inset ERT
15251 status Collapsed
15252
15253 \layout Standard
15254
15255 \backslash
15256 /
15257 \end_inset
15258
15259 -fommit-frame-pointer Frame pointer will be omitted when the function uses
15260  no local variables.
15261 \layout Subsection
15262
15263 Port Specific Options
15264 \begin_inset LatexCommand \index{Options PIC16}
15265
15266 \end_inset
15267
15268
15269 \layout Standard
15270
15271 The port specific options appear after the global options in the sdcc --help
15272  output.
15273 \layout Subsubsection
15274
15275 General Options
15276 \layout Standard
15277
15278 General options enable certain port features and optimizations.
15279 \layout List
15280 \labelwidthstring 00.00.0000
15281
15282 -
15283 \begin_inset ERT
15284 status Collapsed
15285
15286 \layout Standard
15287
15288 \backslash
15289 /
15290 \end_inset
15291
15292 -pgen-bank Instructs the port to insert BANKSEL directives before instructions
15293  that use the Bank Select Register (BSR).
15294 \layout List
15295 \labelwidthstring 00.00.0000
15296
15297 -
15298 \begin_inset ERT
15299 status Collapsed
15300
15301 \layout Standard
15302
15303 \backslash
15304 /
15305 \end_inset
15306
15307 -pomit-config-words Instructs the port to omit the generation of the configurati
15308 on words.
15309 \layout List
15310 \labelwidthstring 00.00.0000
15311
15312 -
15313 \begin_inset ERT
15314 status Collapsed
15315
15316 \layout Standard
15317
15318 \backslash
15319 /
15320 \end_inset
15321
15322 -pomit-ivt Instructs the port to omit the generation of the interrupt vectors
15323 \layout List
15324 \labelwidthstring 00.00.0000
15325
15326 -
15327 \begin_inset ERT
15328 status Collapsed
15329
15330 \layout Standard
15331
15332 \backslash
15333 /
15334 \end_inset
15335
15336 -pleave-reset-vector Used in conjuction with the previous command, instructs
15337  the port NOT to omit the reset vector.
15338 \layout List
15339 \labelwidthstring 00.00.0000
15340
15341 -
15342 \begin_inset ERT
15343 status Collapsed
15344
15345 \layout Standard
15346
15347 \backslash
15348 /
15349 \end_inset
15350
15351 -stack-model=[model] Used in conjuction with the command above.
15352  Defines the stack model to be used, valid stack models are :
15353 \begin_deeper
15354 \layout List
15355 \labelwidthstring 00.00.0000
15356
15357
15358 \emph on
15359 small
15360 \emph default
15361  Selects small stack model.
15362  8 bit stack and frame pointers.
15363  Supports 256 bytes stack size.
15364 \layout List
15365 \labelwidthstring 00.00.0000
15366
15367
15368 \emph on
15369 large
15370 \emph default
15371  Selects large stack model.
15372  16 bit stack and frame pointers.
15373  Supports 65536 bytes stack size.
15374 \end_deeper
15375 \layout List
15376 \labelwidthstring 00.00.0000
15377
15378 -
15379 \begin_inset ERT
15380 status Collapsed
15381
15382 \layout Standard
15383
15384 \backslash
15385 /
15386 \end_inset
15387
15388 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
15389  unitialized data variables with [kword].
15390  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
15391 \layout List
15392 \labelwidthstring 00.00.0000
15393
15394 -
15395 \begin_inset ERT
15396 status Collapsed
15397
15398 \layout Standard
15399
15400 \backslash
15401 /
15402 \end_inset
15403
15404 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
15405  Useful for bootloaders.
15406 \layout List
15407 \labelwidthstring 00.00.0000
15408
15409 -
15410 \begin_inset ERT
15411 status Collapsed
15412
15413 \layout Standard
15414
15415 \backslash
15416 /
15417 \end_inset
15418
15419 -asm= sets the full path and name of an external assembler to call.
15420 \layout List
15421 \labelwidthstring 00.00.0000
15422
15423 -
15424 \begin_inset ERT
15425 status Collapsed
15426
15427 \layout Standard
15428
15429 \backslash
15430 /
15431 \end_inset
15432
15433 -link= sets the full path and name of an external linker to call.
15434 \layout Subsubsection
15435
15436 Debugging Options
15437 \layout Standard
15438
15439 Debugging options enable extra debugging information in the output files.
15440 \layout List
15441 \labelwidthstring 00.00.0000
15442
15443 -
15444 \begin_inset ERT
15445 status Collapsed
15446
15447 \layout Standard
15448
15449 \backslash
15450 /
15451 \end_inset
15452
15453 -debug-xtra Similar to -
15454 \begin_inset ERT
15455 status Collapsed
15456
15457 \layout Standard
15458
15459 \backslash
15460 /
15461 \end_inset
15462
15463 -debug
15464 \begin_inset LatexCommand \index{-\/-debug}
15465
15466 \end_inset
15467
15468 , but dumps more information.
15469 \layout List
15470 \labelwidthstring 00.00.0000
15471
15472 -
15473 \begin_inset ERT
15474 status Collapsed
15475
15476 \layout Standard
15477
15478 \backslash
15479 /
15480 \end_inset
15481
15482 -debug-ralloc Force register allocator to dump <source>.d file with debugging
15483  information.
15484  <source> is the name of the file compiled.
15485 \layout List
15486 \labelwidthstring 00.00.0000
15487
15488 -
15489 \begin_inset ERT
15490 status Collapsed
15491
15492 \layout Standard
15493
15494 \backslash
15495 /
15496 \end_inset
15497
15498 -pcode-verbose Enable pcode debugging information in translation.
15499 \layout Subsection
15500
15501 Preprocessor Macros
15502 \layout Standard
15503
15504 PIC16 port defines the following preprocessor macros while translating a
15505  source.
15506 \layout Standard
15507 \align center
15508
15509 \begin_inset  Tabular
15510 <lyxtabular version="3" rows="2" columns="2">
15511 <features>
15512 <column alignment="center" valignment="top" leftline="true" width="0">
15513 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15514 <row topline="true" bottomline="true">
15515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15516 \begin_inset Text
15517
15518 \layout Standard
15519
15520 Macro
15521 \end_inset
15522 </cell>
15523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15524 \begin_inset Text
15525
15526 \layout Standard
15527
15528 Description
15529 \end_inset
15530 </cell>
15531 </row>
15532 <row topline="true" bottomline="true">
15533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15534 \begin_inset Text
15535
15536 \layout Standard
15537
15538 pic18fxxxx
15539 \end_inset
15540 </cell>
15541 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15542 \begin_inset Text
15543
15544 \layout Standard
15545
15546 MCU Identification.
15547
15548 \emph on
15549 xxxx
15550 \emph default
15551  is the microcontrol identification number, i.e.
15552  452, 6620, etc
15553 \end_inset
15554 </cell>
15555 </row>
15556 </lyxtabular>
15557
15558 \end_inset
15559
15560
15561 \layout Subsection
15562
15563 Directories
15564 \layout Standard
15565
15566 PIC16
15567 \begin_inset LatexCommand \index{PIC16}
15568
15569 \end_inset
15570
15571  port uses the following directories for searching header files and libraries.
15572 \layout Standard
15573 \align center
15574
15575 \begin_inset  Tabular
15576 <lyxtabular version="3" rows="3" columns="4">
15577 <features>
15578 <column alignment="center" valignment="top" leftline="true" width="0">
15579 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15580 <column alignment="center" valignment="top" width="0">
15581 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15582 <row topline="true" bottomline="true">
15583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15584 \begin_inset Text
15585
15586 \layout Standard
15587
15588 Directory
15589 \end_inset
15590 </cell>
15591 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15592 \begin_inset Text
15593
15594 \layout Standard
15595
15596 Description
15597 \end_inset
15598 </cell>
15599 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15600 \begin_inset Text
15601
15602 \layout Standard
15603
15604 Target
15605 \end_inset
15606 </cell>
15607 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15608 \begin_inset Text
15609
15610 \layout Standard
15611
15612 Command prefix
15613 \end_inset
15614 </cell>
15615 </row>
15616 <row topline="true">
15617 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15618 \begin_inset Text
15619
15620 \layout Standard
15621
15622 PREFIX/sdcc/include/pic16
15623 \end_inset
15624 </cell>
15625 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15626 \begin_inset Text
15627
15628 \layout Standard
15629
15630 PIC16 specific headers
15631 \end_inset
15632 </cell>
15633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15634 \begin_inset Text
15635
15636 \layout Standard
15637
15638 Compiler
15639 \end_inset
15640 </cell>
15641 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15642 \begin_inset Text
15643
15644 \layout Standard
15645
15646 -I
15647 \end_inset
15648 </cell>
15649 </row>
15650 <row topline="true" bottomline="true">
15651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15652 \begin_inset Text
15653
15654 \layout Standard
15655
15656 PREFIX/sdcc/lib/pic16
15657 \end_inset
15658 </cell>
15659 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15660 \begin_inset Text
15661
15662 \layout Standard
15663
15664 PIC16 specific libraries
15665 \end_inset
15666 </cell>
15667 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15668 \begin_inset Text
15669
15670 \layout Standard
15671
15672 Linker
15673 \end_inset
15674 </cell>
15675 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15676 \begin_inset Text
15677
15678 \layout Standard
15679
15680 -L
15681 \end_inset
15682 </cell>
15683 </row>
15684 </lyxtabular>
15685
15686 \end_inset
15687
15688
15689 \layout Subsection
15690
15691 Pragmas
15692 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
15693
15694 \end_inset
15695
15696
15697 \layout Standard
15698
15699 PIC16 port currently supports the following pragmas:
15700 \layout List
15701 \labelwidthstring 00.00.0000
15702
15703 stack pragma stack forces the code generator to initialize the stack & frame
15704  pointers at a specific address.
15705  This is an adhoc solution since gplink does not support yet stack.
15706  When the gplink issue is resolved the pragma will be deprecated
15707 \begin_inset Foot
15708 collapsed true
15709
15710 \layout Standard
15711
15712
15713 \emph on
15714 It is important to initialize the stack, otherwise strange things can happen.
15715  Stack is not initialized by default because there are some sources that
15716  do not require it.
15717  (like library sources)
15718 \end_inset
15719
15720 .
15721 \newline
15722 The stack pragma should be used only once in a project.
15723  Multiple pragmas may result in indeterminate behaviour of the program.
15724 \layout LyX-Code
15725
15726 Example:
15727 \layout LyX-Code
15728
15729 \layout LyX-Code
15730
15731 /* initializes stack at RAM address 0x5ff */
15732 \layout LyX-Code
15733
15734 #pragma stack 0x5ff
15735 \layout List
15736 \labelwidthstring 00.00.0000
15737
15738 udata pragma udata instructs the compiler to emit code so that linker will
15739  place a variable at a specific memory bank
15740 \layout LyX-Code
15741
15742 Example:
15743 \layout LyX-Code
15744
15745 \layout LyX-Code
15746
15747 /* places variable foo at bank2 */
15748 \layout LyX-Code
15749
15750 #pragma udata bank2 foo
15751 \layout LyX-Code
15752
15753 char foo;
15754 \layout Standard
15755
15756 In order for this pragma to work there are some changes that must be made
15757  in the .lkr script used in link stage.
15758  In the following example a sample .lkr file is shown:
15759 \layout LyX-Code
15760
15761 \layout LyX-Code
15762
15763 // Sample linker script for the PIC18F452 processor
15764 \layout LyX-Code
15765
15766 LIBPATH .
15767 \layout LyX-Code
15768
15769 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
15770 \layout LyX-Code
15771
15772 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
15773 \layout LyX-Code
15774
15775 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
15776 \layout LyX-Code
15777
15778 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
15779 \layout LyX-Code
15780
15781 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
15782 \layout LyX-Code
15783
15784 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
15785 \layout LyX-Code
15786
15787 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
15788 \layout LyX-Code
15789
15790 \layout LyX-Code
15791
15792 DATABANK   NAME=gpr0       START=0x80           END=0xFF
15793 \layout LyX-Code
15794
15795 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
15796 \layout LyX-Code
15797
15798 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
15799 \layout LyX-Code
15800
15801 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
15802 \layout LyX-Code
15803
15804 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
15805 \layout LyX-Code
15806
15807 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
15808 \layout LyX-Code
15809
15810 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
15811 \layout LyX-Code
15812
15813 \layout LyX-Code
15814
15815 SECTION    NAME=CONFIG     ROM=config
15816 \layout LyX-Code
15817
15818 \layout LyX-Code
15819
15820 SECTION    NAME=bank0      RAM=gpr0
15821 \layout LyX-Code
15822
15823 SECTION    NAME=bank1      RAM=gpr1
15824 \layout LyX-Code
15825
15826 SECTION    NAME=bank2      RAM=gpr2
15827 \layout LyX-Code
15828
15829 SECTION    NAME=bank3      RAM=gpr3
15830 \layout LyX-Code
15831
15832 SECTION    NAME=bank4      RAM=gpr4
15833 \layout LyX-Code
15834
15835 SECTION    NAME=bank5      RAM=gpr5
15836 \layout Standard
15837
15838 The linker will recognise the section name set in the pragma statement and
15839  will position the variable at the memory bank set with the RAM field at
15840  the SECTION line in the linker script file.
15841 \layout Subsection
15842
15843 Header Files
15844 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
15845
15846 \end_inset
15847
15848
15849 \layout Standard
15850
15851 There is one main header file that can be included to the source files using
15852  the pic16 port.
15853  That file is the
15854 \series bold
15855 pic18fregs.h
15856 \series default
15857 .
15858  This header file contains the definitions for the processor special registers,
15859  so it is necessary if the source accesses them.
15860  It can be included by adding the following line in the beginning of the
15861  file:
15862 \layout LyX-Code
15863
15864 #include <pic18fregs.h>
15865 \layout Standard
15866
15867 The specific microcontroller is selected within the pic18fregs.h automatically,
15868  so the same source can be used with a variety of devices.
15869 \layout Subsection
15870
15871 Libraries
15872 \layout Standard
15873
15874 The libraries that PIC16
15875 \begin_inset LatexCommand \index{PIC16}
15876
15877 \end_inset
15878
15879  port depends on are the microcontroller device libraries which contain
15880  the symbol definitions for the microcontroller special function registers.
15881  These libraries have the format pic18fxxxx.lib, where
15882 \emph on
15883 xxxx
15884 \emph default
15885  is the microcontroller identification number.
15886  The specific library is selected automatically by the compiler at link
15887  stage according to the selected device.
15888 \layout Standard
15889
15890 Libraries are created with gplib which is part of the gputils package
15891 \begin_inset LatexCommand \url{http://gputils.sourceforge.net}
15892
15893 \end_inset
15894
15895 .
15896 \layout Subsection
15897
15898 Memory Models
15899 \layout Standard
15900
15901 The following memory models are supported by the PIC16 port:
15902 \layout Itemize
15903
15904 small model
15905 \layout Itemize
15906
15907 large model
15908 \layout Standard
15909
15910 Memory model affects the default size of pointers within the source.
15911  The sizes are shown in the next table:
15912 \layout Standard
15913 \align center
15914
15915 \begin_inset  Tabular
15916 <lyxtabular version="3" rows="3" columns="3">
15917 <features>
15918 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15919 <column alignment="center" valignment="top" leftline="true" width="0">
15920 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15921 <row topline="true" bottomline="true">
15922 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15923 \begin_inset Text
15924
15925 \layout Standard
15926
15927 Pointer sizes according to memory model
15928 \end_inset
15929 </cell>
15930 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15931 \begin_inset Text
15932
15933 \layout Standard
15934
15935 small model
15936 \end_inset
15937 </cell>
15938 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15939 \begin_inset Text
15940
15941 \layout Standard
15942
15943 large model
15944 \end_inset
15945 </cell>
15946 </row>
15947 <row topline="true" bottomline="true">
15948 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15949 \begin_inset Text
15950
15951 \layout Standard
15952
15953 code pointers
15954 \end_inset
15955 </cell>
15956 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15957 \begin_inset Text
15958
15959 \layout Standard
15960
15961 16-bits
15962 \end_inset
15963 </cell>
15964 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15965 \begin_inset Text
15966
15967 \layout Standard
15968
15969 24-bits
15970 \end_inset
15971 </cell>
15972 </row>
15973 <row topline="true" bottomline="true">
15974 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15975 \begin_inset Text
15976
15977 \layout Standard
15978
15979 data pointers
15980 \end_inset
15981 </cell>
15982 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
15983 \begin_inset Text
15984
15985 \layout Standard
15986
15987 16-bits
15988 \end_inset
15989 </cell>
15990 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15991 \begin_inset Text
15992
15993 \layout Standard
15994
15995 16-bits
15996 \end_inset
15997 </cell>
15998 </row>
15999 </lyxtabular>
16000
16001 \end_inset
16002
16003
16004 \layout Standard
16005
16006 It is advisable that all sources within a project are compiled with the
16007  same memory model.
16008  If one wants to override the default memory model, this can be done by
16009  declaring a pointer as
16010 \series bold
16011 far
16012 \series default
16013  or
16014 \series bold
16015 near
16016 \series default
16017 .
16018  Far selects large memory model's pointers, while near selects small memory
16019  model's pointers.
16020 \layout Standard
16021
16022 The standard device libraries (see
16023 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
16024
16025 \end_inset
16026
16027 ) contain no reference to pointers, so they can be used with both memory
16028  models.
16029 \layout Subsection
16030
16031 Stack
16032 \layout Standard
16033
16034 The stack implementation for the PIC16 port uses two indirect registers,
16035  FSR1 and FSR2.
16036 \layout List
16037 \labelwidthstring 00.00.0000
16038
16039 FSR1 is assigned as stack pointer
16040 \layout List
16041 \labelwidthstring 00.00.0000
16042
16043 FSR2 is assigned as frame pointer
16044 \layout Standard
16045
16046 The following stack models are supported by the PIC16 port
16047 \layout Itemize
16048
16049 small model
16050 \layout Itemize
16051
16052 large model
16053 \layout Standard
16054
16055
16056 \noun on
16057 Small
16058 \noun default
16059  model means that only the FSRxL byte is used to access stack and frame,
16060  while
16061 \emph on
16062 \noun on
16063 large
16064 \emph default
16065 \noun default
16066  uses both FSRxL and FSRxH registers.
16067  The following table shows the stack/frame pointers sizes according to stack
16068  model and the maximum space they can address:
16069 \layout Standard
16070 \align center
16071
16072 \begin_inset  Tabular
16073 <lyxtabular version="3" rows="3" columns="3">
16074 <features>
16075 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16076 <column alignment="center" valignment="top" leftline="true" width="0">
16077 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16078 <row topline="true" bottomline="true">
16079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16080 \begin_inset Text
16081
16082 \layout Standard
16083
16084 Stack & Frame pointer sizes according to stack model
16085 \end_inset
16086 </cell>
16087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16088 \begin_inset Text
16089
16090 \layout Standard
16091
16092 small
16093 \end_inset
16094 </cell>
16095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16096 \begin_inset Text
16097
16098 \layout Standard
16099
16100 large
16101 \end_inset
16102 </cell>
16103 </row>
16104 <row topline="true">
16105 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16106 \begin_inset Text
16107
16108 \layout Standard
16109
16110 Stack pointer FSR1
16111 \end_inset
16112 </cell>
16113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16114 \begin_inset Text
16115
16116 \layout Standard
16117
16118 8-bits
16119 \end_inset
16120 </cell>
16121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16122 \begin_inset Text
16123
16124 \layout Standard
16125
16126 16-bits
16127 \end_inset
16128 </cell>
16129 </row>
16130 <row topline="true" bottomline="true">
16131 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16132 \begin_inset Text
16133
16134 \layout Standard
16135
16136 Frame pointer FSR2
16137 \end_inset
16138 </cell>
16139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16140 \begin_inset Text
16141
16142 \layout Standard
16143
16144 8-bits
16145 \end_inset
16146 </cell>
16147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16148 \begin_inset Text
16149
16150 \layout Standard
16151
16152 16-bits
16153 \end_inset
16154 </cell>
16155 </row>
16156 </lyxtabular>
16157
16158 \end_inset
16159
16160
16161 \layout Standard
16162
16163
16164 \series bold
16165 Currently stack and frame pointers should be initialized explicit by the
16166  user at the desired Data RAM position (see
16167 \begin_inset LatexCommand \ref{sub:PIC16_Pragmas}
16168
16169 \end_inset
16170
16171  Pragma stack).
16172  Uninitialized stack and frame pointers can result in unexpected behavior
16173  of the resulting binary.
16174 \layout Subsection
16175
16176 Function return values
16177 \layout Standard
16178
16179 Return values from functions are placed to the appropriate registers following
16180  a modified Microchip policy optimized for SDCC.
16181  The following table shows these registers:
16182 \layout Standard
16183 \align center
16184
16185 \begin_inset  Tabular
16186 <lyxtabular version="3" rows="6" columns="2">
16187 <features>
16188 <column alignment="center" valignment="top" leftline="true" width="0">
16189 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16190 <row topline="true" bottomline="true">
16191 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16192 \begin_inset Text
16193
16194 \layout Standard
16195
16196 size
16197 \end_inset
16198 </cell>
16199 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16200 \begin_inset Text
16201
16202 \layout Standard
16203
16204 destination register
16205 \end_inset
16206 </cell>
16207 </row>
16208 <row topline="true">
16209 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16210 \begin_inset Text
16211
16212 \layout Standard
16213
16214 8 bits
16215 \end_inset
16216 </cell>
16217 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16218 \begin_inset Text
16219
16220 \layout Standard
16221
16222 WREG
16223 \end_inset
16224 </cell>
16225 </row>
16226 <row topline="true">
16227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16228 \begin_inset Text
16229
16230 \layout Standard
16231
16232 16 bits
16233 \end_inset
16234 </cell>
16235 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16236 \begin_inset Text
16237
16238 \layout Standard
16239
16240 PRODL:WREG
16241 \end_inset
16242 </cell>
16243 </row>
16244 <row topline="true">
16245 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16246 \begin_inset Text
16247
16248 \layout Standard
16249
16250 24 bits
16251 \end_inset
16252 </cell>
16253 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16254 \begin_inset Text
16255
16256 \layout Standard
16257
16258 PRODH:PRODL:WREG
16259 \end_inset
16260 </cell>
16261 </row>
16262 <row topline="true">
16263 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16264 \begin_inset Text
16265
16266 \layout Standard
16267
16268 32 bits
16269 \end_inset
16270 </cell>
16271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16272 \begin_inset Text
16273
16274 \layout Standard
16275
16276 FSR0L:PRODH:PRODL:WREG
16277 \end_inset
16278 </cell>
16279 </row>
16280 <row topline="true" bottomline="true">
16281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16282 \begin_inset Text
16283
16284 \layout Standard
16285
16286 >32 bits
16287 \end_inset
16288 </cell>
16289 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16290 \begin_inset Text
16291
16292 \layout Standard
16293
16294 on stack, FSR0 points to the beginning
16295 \end_inset
16296 </cell>
16297 </row>
16298 </lyxtabular>
16299
16300 \end_inset
16301
16302
16303 \layout Subsection
16304
16305 Interrupts
16306 \layout Standard
16307
16308 When entering an interrupt, currently the PIC16
16309 \begin_inset LatexCommand \index{PIC16}
16310
16311 \end_inset
16312
16313  port automatically saves the following registers:
16314 \layout Itemize
16315
16316 WREG
16317 \layout Itemize
16318
16319 STATUS
16320 \layout Itemize
16321
16322 BSR
16323 \layout Itemize
16324
16325 PROD (PRODL and PRODH)
16326 \layout Itemize
16327
16328 FSR0 (FSR0L and FSR0H)
16329 \layout Standard
16330
16331 These registers are restored upon return from the interrupt routine.
16332
16333 \layout Standard
16334
16335 When entering a high priority interrupt WREG, STATUS and BSR are not explicit
16336  saved by software.
16337  The hardware shadow registers for WREG, STATUS and BSR are used in these
16338  cases.
16339 \layout Standard
16340
16341
16342 \begin_inset Foot
16343 collapsed false
16344
16345 \layout Standard
16346
16347 NOTE that when the _naked attribute is specified for an interrupt routine,
16348  then NO registers are stored or restored.
16349 \end_inset
16350
16351 .
16352 \layout Chapter
16353
16354 Debugging with SDCDB
16355 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
16356
16357 \end_inset
16358
16359
16360 \begin_inset LatexCommand \index{sdcdb (debugger)}
16361
16362 \end_inset
16363
16364
16365 \layout Standard
16366
16367 SDCC is distributed with a source level debugger
16368 \begin_inset LatexCommand \index{Debugger}
16369
16370 \end_inset
16371
16372 .
16373  The debugger uses a command line interface, the command repertoire of the
16374  debugger has been kept as close to gdb
16375 \begin_inset LatexCommand \index{gdb}
16376
16377 \end_inset
16378
16379  (the GNU debugger) as possible.
16380  The configuration and build process is part of the standard compiler installati
16381 on, which also builds and installs the debugger in the target directory
16382  specified during configuration.
16383  The debugger allows you debug BOTH at the C source and at the ASM source
16384  level.
16385  Sdcdb is available on Unix platforms only.
16386 \layout Section
16387
16388 Compiling for Debugging
16389 \layout Standard
16390
16391 The -
16392 \begin_inset ERT
16393 status Collapsed
16394
16395 \layout Standard
16396
16397 \backslash
16398 /
16399 \end_inset
16400
16401 -debug
16402 \begin_inset LatexCommand \index{-\/-debug}
16403
16404 \end_inset
16405
16406  option must be specified for all files for which debug information is to
16407  be generated.
16408  The complier generates a .adb file for each of these files.
16409  The linker creates the .cdb
16410 \begin_inset LatexCommand \index{<file>.cdb}
16411
16412 \end_inset
16413
16414  file from the .adb
16415 \begin_inset LatexCommand \index{<file>.adb}
16416
16417 \end_inset
16418
16419  files and the address information.
16420  This .cdb is used by the debugger.
16421 \layout Section
16422
16423 How the Debugger Works
16424 \layout Standard
16425
16426 When the -
16427 \begin_inset ERT
16428 status Collapsed
16429
16430 \layout Standard
16431
16432 \backslash
16433 /
16434 \end_inset
16435
16436 -debug option is specified the compiler generates extra symbol information
16437  some of which are put into the assembler source and some are put into the
16438  .adb file.
16439   Then the linker creates the .cdb file from the individual .adb files with
16440  the address information for the symbols.
16441  The debugger reads the symbolic information generated by the compiler &
16442  the address information generated by the linker.
16443  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
16444  execution is controlled by the debugger.
16445  When a command is issued for the debugger, it translates it into appropriate
16446  commands for the simulator.
16447 \layout Section
16448
16449 Starting the Debugger
16450 \layout Standard
16451
16452 The debugger can be started using the following command line.
16453  (Assume the file you are debugging has the file name foo).
16454 \newline
16455
16456 \newline
16457
16458 \family sans
16459 \series bold
16460 sdcdb foo
16461 \newline
16462
16463 \family default
16464 \series default
16465
16466 \newline
16467 The debugger will look for the following files.
16468 \layout Itemize
16469
16470 foo.c - the source file.
16471 \layout Itemize
16472
16473 foo.cdb - the debugger symbol information file.
16474 \layout Itemize
16475
16476 foo.ihx - the Intel hex format
16477 \begin_inset LatexCommand \index{Intel hex format}
16478
16479 \end_inset
16480
16481  object file.
16482 \layout Section
16483
16484 Command Line Options.
16485 \layout Itemize
16486
16487 -
16488 \begin_inset ERT
16489 status Collapsed
16490
16491 \layout Standard
16492
16493 \backslash
16494 /
16495 \end_inset
16496
16497 -directory=<source file directory> this option can used to specify the directory
16498  search list.
16499  The debugger will look into the directory list specified for source, cdb
16500  & ihx files.
16501  The items in the directory list must be separated by ':', e.g.
16502  if the source files can be in the directories /home/src1 and /home/src2,
16503  the -
16504 \begin_inset ERT
16505 status Collapsed
16506
16507 \layout Standard
16508
16509 \backslash
16510 /
16511 \end_inset
16512
16513 -directory option should be -
16514 \begin_inset ERT
16515 status Collapsed
16516
16517 \layout Standard
16518
16519 \backslash
16520 /
16521 \end_inset
16522
16523 -directory=/home/src1:/home/src2.
16524  Note there can be no spaces in the option.
16525
16526 \layout Itemize
16527
16528 -cd <directory> - change to the <directory>.
16529 \layout Itemize
16530
16531 -fullname - used by GUI front ends.
16532 \layout Itemize
16533
16534 -cpu <cpu-type> - this argument is passed to the simulator please see the
16535  simulator docs for details.
16536 \layout Itemize
16537
16538 -X <Clock frequency > this options is passed to the simulator please see
16539  the simulator docs for details.
16540 \layout Itemize
16541
16542 -s <serial port file> passed to simulator see the simulator docs for details.
16543 \layout Itemize
16544
16545 -S <serial in,out> passed to simulator see the simulator docs for details.
16546 \layout Itemize
16547
16548 -k <port number> passed to simulator see the simulator docs for details.
16549 \layout Section
16550
16551 Debugger Commands.
16552 \layout Standard
16553
16554 As mentioned earlier the command interface for the debugger has been deliberatel
16555 y kept as close the GNU debugger gdb, as possible.
16556  This will help the integration with existing graphical user interfaces
16557  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
16558  If you use a graphical user interface for the debugger you can skip the
16559  next sections.
16560 \layout Subsubsection*
16561
16562 break [line | file:line | function | file:function]
16563 \layout Standard
16564
16565 Set breakpoint at specified line or function:
16566 \newline
16567
16568 \newline
16569
16570 \family sans
16571 \series bold
16572 sdcdb>break 100
16573 \newline
16574 sdcdb>break foo.c:100
16575 \newline
16576 sdcdb>break funcfoo
16577 \newline
16578 sdcdb>break foo.c:funcfoo
16579 \layout Subsubsection*
16580
16581 clear [line | file:line | function | file:function ]
16582 \layout Standard
16583
16584 Clear breakpoint at specified line or function:
16585 \newline
16586
16587 \newline
16588
16589 \family sans
16590 \series bold
16591 sdcdb>clear 100
16592 \newline
16593 sdcdb>clear foo.c:100
16594 \newline
16595 sdcdb>clear funcfoo
16596 \newline
16597 sdcdb>clear foo.c:funcfoo
16598 \layout Subsubsection*
16599
16600 continue
16601 \layout Standard
16602
16603 Continue program being debugged, after breakpoint.
16604 \layout Subsubsection*
16605
16606 finish
16607 \layout Standard
16608
16609 Execute till the end of the current function.
16610 \layout Subsubsection*
16611
16612 delete [n]
16613 \layout Standard
16614
16615 Delete breakpoint number 'n'.
16616  If used without any option clear ALL user defined break points.
16617 \layout Subsubsection*
16618
16619 info [break | stack | frame | registers ]
16620 \layout Itemize
16621
16622 info break - list all breakpoints
16623 \layout Itemize
16624
16625 info stack - show the function call stack.
16626 \layout Itemize
16627
16628 info frame - show information about the current execution frame.
16629 \layout Itemize
16630
16631 info registers - show content of all registers.
16632 \layout Subsubsection*
16633
16634 step
16635 \layout Standard
16636
16637 Step program until it reaches a different source line.
16638  Note: pressing <return> repeats the last command.
16639 \layout Subsubsection*
16640
16641 next
16642 \layout Standard
16643
16644 Step program, proceeding through subroutine calls.
16645 \layout Subsubsection*
16646
16647 run
16648 \layout Standard
16649
16650 Start debugged program.
16651 \layout Subsubsection*
16652
16653 ptype variable
16654 \layout Standard
16655
16656 Print type information of the variable.
16657 \layout Subsubsection*
16658
16659 print variable
16660 \layout Standard
16661
16662 print value of variable.
16663 \layout Subsubsection*
16664
16665 file filename
16666 \layout Standard
16667
16668 load the given file name.
16669  Note this is an alternate method of loading file for debugging.
16670 \layout Subsubsection*
16671
16672 frame
16673 \layout Standard
16674
16675 print information about current frame.
16676 \layout Subsubsection*
16677
16678 set srcmode
16679 \layout Standard
16680
16681 Toggle between C source & assembly source.
16682 \layout Subsubsection*
16683
16684 ! simulator command
16685 \layout Standard
16686
16687 Send the string following '!' to the simulator, the simulator response is
16688  displayed.
16689  Note the debugger does not interpret the command being sent to the simulator,
16690  so if a command like 'go' is sent the debugger can loose its execution
16691  context and may display incorrect values.
16692 \layout Subsubsection*
16693
16694 quit
16695 \layout Standard
16696
16697 "Watch me now.
16698  Iam going Down.
16699  My name is Bobby Brown"
16700 \layout Section
16701
16702 Interfacing with XEmacs
16703 \begin_inset LatexCommand \index{XEmacs}
16704
16705 \end_inset
16706
16707
16708 \begin_inset LatexCommand \index{Emacs}
16709
16710 \end_inset
16711
16712 .
16713 \layout Standard
16714
16715 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
16716  sdcdb.el and sdcdbsrc.el.
16717  These two files can be found in the $(prefix)/bin directory after the installat
16718 ion is complete.
16719  These files need to be loaded into XEmacs for the interface to work.
16720  This can be done at XEmacs startup time by inserting the following into
16721  your '.xemacs' file (which can be found in your HOME directory):
16722 \newline
16723
16724 \newline
16725
16726 \family typewriter
16727 (load-file sdcdbsrc.el)
16728 \family default
16729
16730 \newline
16731
16732 \newline
16733 .xemacs is a lisp file so the () around the command is REQUIRED.
16734  The files can also be loaded dynamically while XEmacs is running, set the
16735  environment variable 'EMACSLOADPATH' to the installation bin directory
16736  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
16737  To start the interface enter the following command:
16738 \newline
16739
16740 \newline
16741
16742 \family sans
16743 \series bold
16744 ESC-x sdcdbsrc
16745 \family default
16746 \series default
16747
16748 \newline
16749
16750 \newline
16751 You will prompted to enter the file name to be debugged.
16752
16753 \newline
16754
16755 \newline
16756 The command line options that are passed to the simulator directly are bound
16757  to default values in the file sdcdbsrc.el.
16758  The variables are listed below, these values maybe changed as required.
16759 \layout Itemize
16760
16761 sdcdbsrc-cpu-type '51
16762 \layout Itemize
16763
16764 sdcdbsrc-frequency '11059200
16765 \layout Itemize
16766
16767 sdcdbsrc-serial nil
16768 \layout Standard
16769
16770 The following is a list of key mapping for the debugger interface.
16771 \layout Standard
16772
16773 \SpecialChar ~
16774
16775 \family typewriter
16776
16777 \newline
16778 ;;\SpecialChar ~
16779 Current Listing ::
16780 \newline
16781 ;;key\SpecialChar ~
16782 \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 binding\SpecialChar ~
16796 \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 Comment
16818 \newline
16819 ;;---\SpecialChar ~
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 -------
16856 \newline
16857 ;;
16858 \newline
16859 ;;\SpecialChar ~
16860 n\SpecialChar ~
16861 \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 sdcdb-next-from-src\SpecialChar ~
16876 \SpecialChar ~
16877 \SpecialChar ~
16878 \SpecialChar ~
16879 \SpecialChar ~
16880 \SpecialChar ~
16881 \SpecialChar ~
16882 \SpecialChar ~
16883 \SpecialChar ~
16884 \SpecialChar ~
16885 SDCDB next command
16886 \newline
16887 ;;\SpecialChar ~
16888 b\SpecialChar ~
16889 \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 sdcdb-back-from-src\SpecialChar ~
16904 \SpecialChar ~
16905 \SpecialChar ~
16906 \SpecialChar ~
16907 \SpecialChar ~
16908 \SpecialChar ~
16909 \SpecialChar ~
16910 \SpecialChar ~
16911 \SpecialChar ~
16912 \SpecialChar ~
16913 SDCDB back command
16914 \newline
16915 ;;\SpecialChar ~
16916 c\SpecialChar ~
16917 \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 sdcdb-cont-from-src\SpecialChar ~
16932 \SpecialChar ~
16933 \SpecialChar ~
16934 \SpecialChar ~
16935 \SpecialChar ~
16936 \SpecialChar ~
16937 \SpecialChar ~
16938 \SpecialChar ~
16939 \SpecialChar ~
16940 \SpecialChar ~
16941 SDCDB continue command
16942 \newline
16943 ;;\SpecialChar ~
16944 s\SpecialChar ~
16945 \SpecialChar ~
16946 \SpecialChar ~
16947 \SpecialChar ~
16948 \SpecialChar ~
16949 \SpecialChar ~
16950 \SpecialChar ~
16951 \SpecialChar ~
16952 \SpecialChar ~
16953 \SpecialChar ~
16954 \SpecialChar ~
16955 \SpecialChar ~
16956 \SpecialChar ~
16957 \SpecialChar ~
16958 \SpecialChar ~
16959 sdcdb-step-from-src\SpecialChar ~
16960 \SpecialChar ~
16961 \SpecialChar ~
16962 \SpecialChar ~
16963 \SpecialChar ~
16964 \SpecialChar ~
16965 \SpecialChar ~
16966 \SpecialChar ~
16967 \SpecialChar ~
16968 \SpecialChar ~
16969 SDCDB step command
16970 \newline
16971 ;;\SpecialChar ~
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 sdcdb-whatis-c-sexp\SpecialChar ~
16988 \SpecialChar ~
16989 \SpecialChar ~
16990 \SpecialChar ~
16991 \SpecialChar ~
16992 \SpecialChar ~
16993 \SpecialChar ~
16994 \SpecialChar ~
16995 \SpecialChar ~
16996 \SpecialChar ~
16997 SDCDB ptypecommand for data at
16998 \newline
16999 ;;\SpecialChar ~
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 buffer point
17047 \newline
17048 ;;\SpecialChar ~
17049 x\SpecialChar ~
17050 \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 sdcdbsrc-delete\SpecialChar ~
17065 \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 SDCDB Delete all breakpoints if no arg
17079 \newline
17080 ;;\SpecialChar ~
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 given or delete arg (C-u arg x)
17128 \newline
17129 ;;\SpecialChar ~
17130 m\SpecialChar ~
17131 \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 sdcdbsrc-frame\SpecialChar ~
17146 \SpecialChar ~
17147 \SpecialChar ~
17148 \SpecialChar ~
17149 \SpecialChar ~
17150 \SpecialChar ~
17151 \SpecialChar ~
17152 \SpecialChar ~
17153 \SpecialChar ~
17154 \SpecialChar ~
17155 \SpecialChar ~
17156 \SpecialChar ~
17157 \SpecialChar ~
17158 \SpecialChar ~
17159 \SpecialChar ~
17160 SDCDB Display current frame if no arg,
17161 \newline
17162 ;;\SpecialChar ~
17163 \SpecialChar ~
17164 \SpecialChar ~
17165 \SpecialChar ~
17166 \SpecialChar ~
17167 \SpecialChar ~
17168 \SpecialChar ~
17169 \SpecialChar ~
17170 \SpecialChar ~
17171 \SpecialChar ~
17172 \SpecialChar ~
17173 \SpecialChar ~
17174 \SpecialChar ~
17175 \SpecialChar ~
17176 \SpecialChar ~
17177 \SpecialChar ~
17178 \SpecialChar ~
17179 \SpecialChar ~
17180 \SpecialChar ~
17181 \SpecialChar ~
17182 \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 given or display frame arg
17210 \newline
17211 ;;\SpecialChar ~
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 buffer point
17259 \newline
17260 ;;\SpecialChar ~
17261 !\SpecialChar ~
17262 \SpecialChar ~
17263 \SpecialChar ~
17264 \SpecialChar ~
17265 \SpecialChar ~
17266 \SpecialChar ~
17267 \SpecialChar ~
17268 \SpecialChar ~
17269 \SpecialChar ~
17270 \SpecialChar ~
17271 \SpecialChar ~
17272 \SpecialChar ~
17273 \SpecialChar ~
17274 \SpecialChar ~
17275 \SpecialChar ~
17276 sdcdbsrc-goto-sdcdb\SpecialChar ~
17277 \SpecialChar ~
17278 \SpecialChar ~
17279 \SpecialChar ~
17280 \SpecialChar ~
17281 \SpecialChar ~
17282 \SpecialChar ~
17283 \SpecialChar ~
17284 \SpecialChar ~
17285 \SpecialChar ~
17286 Goto the SDCDB output buffer
17287 \newline
17288 ;;\SpecialChar ~
17289 p\SpecialChar ~
17290 \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 sdcdb-print-c-sexp\SpecialChar ~
17305 \SpecialChar ~
17306 \SpecialChar ~
17307 \SpecialChar ~
17308 \SpecialChar ~
17309 \SpecialChar ~
17310 \SpecialChar ~
17311 \SpecialChar ~
17312 \SpecialChar ~
17313 \SpecialChar ~
17314 \SpecialChar ~
17315 SDCDB print command for data at
17316 \newline
17317 ;;\SpecialChar ~
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 buffer point
17365 \newline
17366 ;;\SpecialChar ~
17367 g\SpecialChar ~
17368 \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 sdcdbsrc-goto-sdcdb\SpecialChar ~
17383 \SpecialChar ~
17384 \SpecialChar ~
17385 \SpecialChar ~
17386 \SpecialChar ~
17387 \SpecialChar ~
17388 \SpecialChar ~
17389 \SpecialChar ~
17390 \SpecialChar ~
17391 \SpecialChar ~
17392 Goto the SDCDB output buffer
17393 \newline
17394 ;;\SpecialChar ~
17395 t\SpecialChar ~
17396 \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 sdcdbsrc-mode\SpecialChar ~
17411 \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 Toggles Sdcdbsrc mode (turns it off)
17427 \newline
17428 ;;
17429 \newline
17430 ;;\SpecialChar ~
17431 C-c\SpecialChar ~
17432 C-f\SpecialChar ~
17433 \SpecialChar ~
17434 \SpecialChar ~
17435 \SpecialChar ~
17436 \SpecialChar ~
17437 \SpecialChar ~
17438 \SpecialChar ~
17439 \SpecialChar ~
17440 \SpecialChar ~
17441 sdcdb-finish-from-src\SpecialChar ~
17442 \SpecialChar ~
17443 \SpecialChar ~
17444 \SpecialChar ~
17445 \SpecialChar ~
17446 \SpecialChar ~
17447 \SpecialChar ~
17448 \SpecialChar ~
17449 SDCDB finish command
17450 \newline
17451 ;;
17452 \newline
17453 ;;\SpecialChar ~
17454 C-x\SpecialChar ~
17455 SPC\SpecialChar ~
17456 \SpecialChar ~
17457 \SpecialChar ~
17458 \SpecialChar ~
17459 \SpecialChar ~
17460 \SpecialChar ~
17461 \SpecialChar ~
17462 \SpecialChar ~
17463 \SpecialChar ~
17464 sdcdb-break\SpecialChar ~
17465 \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 Set break for line with point
17483 \newline
17484 ;;\SpecialChar ~
17485 ESC\SpecialChar ~
17486 t\SpecialChar ~
17487 \SpecialChar ~
17488 \SpecialChar ~
17489 \SpecialChar ~
17490 \SpecialChar ~
17491 \SpecialChar ~
17492 \SpecialChar ~
17493 \SpecialChar ~
17494 \SpecialChar ~
17495 \SpecialChar ~
17496 \SpecialChar ~
17497 sdcdbsrc-mode\SpecialChar ~
17498 \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 Toggle Sdcdbsrc mode
17514 \newline
17515 ;;\SpecialChar ~
17516 ESC\SpecialChar ~
17517 m\SpecialChar ~
17518 \SpecialChar ~
17519 \SpecialChar ~
17520 \SpecialChar ~
17521 \SpecialChar ~
17522 \SpecialChar ~
17523 \SpecialChar ~
17524 \SpecialChar ~
17525 \SpecialChar ~
17526 \SpecialChar ~
17527 \SpecialChar ~
17528 sdcdbsrc-srcmode\SpecialChar ~
17529 \SpecialChar ~
17530 \SpecialChar ~
17531 \SpecialChar ~
17532 \SpecialChar ~
17533 \SpecialChar ~
17534 \SpecialChar ~
17535 \SpecialChar ~
17536 \SpecialChar ~
17537 \SpecialChar ~
17538 \SpecialChar ~
17539 \SpecialChar ~
17540 \SpecialChar ~
17541 Toggle list mode
17542 \newline
17543 ;;
17544 \newline
17545
17546 \layout Chapter
17547 \pagebreak_top
17548 TIPS
17549 \layout Standard
17550
17551 Here are a few guidelines that will help the compiler generate more efficient
17552  code, some of the tips are specific to this compiler others are generally
17553  good programming practice.
17554 \layout Itemize
17555
17556 Use the smallest data type to represent your data-value.
17557  If it is known in advance that the value is going to be less than 256 then
17558  use an 'unsigned char' instead of a 'short' or 'int'.
17559  Please note, that ANSI C requires both signed and unsigned chars to be
17560  promoted to 'signed int' before doing any operation.
17561  This promotion can be omitted, if the result is the same.
17562  The effect of the promotion rules together with the sign-extension is often
17563  surprising:
17564 \begin_deeper
17565 \layout Verse
17566
17567
17568 \family typewriter
17569 unsigned char uc = 0xfe;
17570 \newline
17571 if (uc * uc < 0) /* this is true! */
17572 \newline
17573 {
17574 \newline
17575 \SpecialChar ~
17576 \SpecialChar ~
17577 \SpecialChar ~
17578 \SpecialChar ~
17579 ....
17580 \newline
17581 }
17582 \layout Standard
17583
17584
17585 \family typewriter
17586 uc * uc
17587 \family default
17588  is evaluated as
17589 \family typewriter
17590 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
17591 \family default
17592 .
17593
17594 \newline
17595 Another one:
17596 \layout Verse
17597
17598
17599 \family typewriter
17600 (unsigned char) -12 / (signed char) -3 = ...
17601 \layout Standard
17602
17603 No, the result is not 4:
17604 \layout Verse
17605
17606
17607 \family typewriter
17608 (int) (unsigned char) -12 / (int) (signed char) -3 =
17609 \newline
17610 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
17611 \newline
17612 (int) 0x00f4 / (int) 0xfffd =
17613 \newline
17614 (int) 0x00f4 / (int) 0xfffd =
17615 \newline
17616 (int) 244 / (int) -3 =
17617 \newline
17618 (int) -81 = (int) 0xffaf;
17619 \layout Standard
17620
17621 Don't complain, that gcc gives you a different result.
17622  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
17623  Therefore the results are different.
17624 \newline
17625 From
17626 \begin_inset Quotes sld
17627 \end_inset
17628
17629 comp.lang.c FAQ
17630 \begin_inset Quotes srd
17631 \end_inset
17632
17633 :
17634 \layout Quote
17635
17636 If well-defined overflow characteristics are important and negative values
17637  are not, or if you want to steer clear of sign-extension problems when
17638  manipulating bits or bytes, use one of the corresponding unsigned types.
17639  (Beware when mixing signed and unsigned values in expressions, though.)
17640 \newline
17641 Although character types (especially unsigned char) can be used as "tiny"
17642  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
17643 ble sign extension and increased code size.
17644 \end_deeper
17645 \layout Itemize
17646
17647 Use unsigned when it is known in advance that the value is not going to
17648  be negative.
17649  This helps especially if you are doing division or multiplication, bit-shifting
17650  or are using an array index.
17651 \layout Itemize
17652
17653 NEVER jump into a LOOP.
17654 \layout Itemize
17655
17656 Declare the variables to be local
17657 \begin_inset LatexCommand \index{local variables}
17658
17659 \end_inset
17660
17661  whenever possible, especially loop control variables (induction).
17662 \layout Itemize
17663
17664 Since the compiler does not always do implicit integral promotion, the programme
17665 r should do an explicit cast when integral promotion is required.
17666 \layout Itemize
17667
17668 Reducing the size of division, multiplication & modulus operations can reduce
17669  code size substantially.
17670  Take the following code for example.
17671 \begin_deeper
17672 \layout Verse
17673
17674
17675 \family typewriter
17676 foobar(unsigned int p1, unsigned char ch)
17677 \newline
17678 {
17679 \newline
17680 \SpecialChar ~
17681 \SpecialChar ~
17682 \SpecialChar ~
17683 \SpecialChar ~
17684 unsigned char ch1 = p1 % ch ;
17685 \newline
17686 \SpecialChar ~
17687 \SpecialChar ~
17688 \SpecialChar ~
17689 \SpecialChar ~
17690 ....
17691 \newline
17692 }
17693 \layout Standard
17694
17695 For the modulus operation the variable ch will be promoted to unsigned int
17696  first then the modulus operation will be performed (this will lead to a
17697  call to support routine _moduint()), and the result will be casted to a
17698  char.
17699  If the code is changed to
17700 \layout Verse
17701
17702
17703 \family typewriter
17704 foobar(unsigned int p1, unsigned char ch)
17705 \newline
17706 {
17707 \newline
17708 \SpecialChar ~
17709 \SpecialChar ~
17710 \SpecialChar ~
17711 \SpecialChar ~
17712 unsigned char ch1 = (unsigned char)p1 % ch ;
17713 \newline
17714 \SpecialChar ~
17715 \SpecialChar ~
17716 \SpecialChar ~
17717 \SpecialChar ~
17718 ....
17719 \newline
17720 }
17721 \layout Standard
17722
17723 It would substantially reduce the code generated (future versions of the
17724  compiler will be smart enough to detect such optimization opportunities).
17725 \end_deeper
17726 \layout Itemize
17727
17728 Have a look at the assembly listing to get a
17729 \begin_inset Quotes sld
17730 \end_inset
17731
17732 feeling
17733 \begin_inset Quotes srd
17734 \end_inset
17735
17736  for the code generation.
17737 \layout Section
17738
17739 Tools
17740 \begin_inset LatexCommand \index{Tools}
17741
17742 \end_inset
17743
17744  included in the distribution
17745 \layout Standard
17746 \align center
17747
17748 \begin_inset  Tabular
17749 <lyxtabular version="3" rows="12" columns="3">
17750 <features>
17751 <column alignment="center" valignment="top" leftline="true" width="0pt">
17752 <column alignment="center" valignment="top" leftline="true" width="0pt">
17753 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
17754 <row topline="true" bottomline="true">
17755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17756 \begin_inset Text
17757
17758 \layout Standard
17759
17760 Name
17761 \end_inset
17762 </cell>
17763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17764 \begin_inset Text
17765
17766 \layout Standard
17767
17768 Purpose
17769 \end_inset
17770 </cell>
17771 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17772 \begin_inset Text
17773
17774 \layout Standard
17775
17776 Directory
17777 \end_inset
17778 </cell>
17779 </row>
17780 <row topline="true">
17781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17782 \begin_inset Text
17783
17784 \layout Standard
17785
17786 uCsim
17787 \end_inset
17788 </cell>
17789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17790 \begin_inset Text
17791
17792 \layout Standard
17793
17794 Simulator for various architectures
17795 \end_inset
17796 </cell>
17797 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17798 \begin_inset Text
17799
17800 \layout Standard
17801
17802 sdcc/sim/ucsim
17803 \end_inset
17804 </cell>
17805 </row>
17806 <row topline="true">
17807 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17808 \begin_inset Text
17809
17810 \layout Standard
17811
17812 keil2sdcc.pl
17813 \end_inset
17814 </cell>
17815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17816 \begin_inset Text
17817
17818 \layout Standard
17819
17820 header file conversion
17821 \end_inset
17822 </cell>
17823 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17824 \begin_inset Text
17825
17826 \layout Standard
17827
17828 sdcc/support/scripts
17829 \end_inset
17830 </cell>
17831 </row>
17832 <row topline="true">
17833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17834 \begin_inset Text
17835
17836 \layout Standard
17837
17838 mh2h.c
17839 \end_inset
17840 </cell>
17841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17842 \begin_inset Text
17843
17844 \layout Standard
17845
17846 header file conversion
17847 \end_inset
17848 </cell>
17849 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17850 \begin_inset Text
17851
17852 \layout Standard
17853
17854 sdcc/support/scripts
17855 \end_inset
17856 </cell>
17857 </row>
17858 <row topline="true">
17859 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17860 \begin_inset Text
17861
17862 \layout Standard
17863
17864 as-gbz80
17865 \end_inset
17866 </cell>
17867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17868 \begin_inset Text
17869
17870 \layout Standard
17871
17872 Assembler
17873 \end_inset
17874 </cell>
17875 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17876 \begin_inset Text
17877
17878 \layout Standard
17879
17880
17881 \family roman
17882 \series medium
17883 \shape up
17884 \size normal
17885 \emph off
17886 \bar no
17887 \noun off
17888 \color none
17889 sdcc/bin
17890 \end_inset
17891 </cell>
17892 </row>
17893 <row topline="true">
17894 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17895 \begin_inset Text
17896
17897 \layout Standard
17898
17899 as-z80
17900 \end_inset
17901 </cell>
17902 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17903 \begin_inset Text
17904
17905 \layout Standard
17906
17907 Assembler
17908 \end_inset
17909 </cell>
17910 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17911 \begin_inset Text
17912
17913 \layout Standard
17914
17915
17916 \family roman
17917 \series medium
17918 \shape up
17919 \size normal
17920 \emph off
17921 \bar no
17922 \noun off
17923 \color none
17924 sdcc/bin
17925 \end_inset
17926 </cell>
17927 </row>
17928 <row topline="true">
17929 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17930 \begin_inset Text
17931
17932 \layout Standard
17933
17934 asx8051
17935 \end_inset
17936 </cell>
17937 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17938 \begin_inset Text
17939
17940 \layout Standard
17941
17942 Assembler
17943 \end_inset
17944 </cell>
17945 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17946 \begin_inset Text
17947
17948 \layout Standard
17949
17950
17951 \family roman
17952 \series medium
17953 \shape up
17954 \size normal
17955 \emph off
17956 \bar no
17957 \noun off
17958 \color none
17959 sdcc/bin
17960 \end_inset
17961 </cell>
17962 </row>
17963 <row topline="true">
17964 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17965 \begin_inset Text
17966
17967 \layout Standard
17968
17969 sdcdb
17970 \end_inset
17971 </cell>
17972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17973 \begin_inset Text
17974
17975 \layout Standard
17976
17977 Simulator
17978 \end_inset
17979 </cell>
17980 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17981 \begin_inset Text
17982
17983 \layout Standard
17984
17985
17986 \family roman
17987 \series medium
17988 \shape up
17989 \size normal
17990 \emph off
17991 \bar no
17992 \noun off
17993 \color none
17994 sdcc/bin
17995 \end_inset
17996 </cell>
17997 </row>
17998 <row topline="true">
17999 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18000 \begin_inset Text
18001
18002 \layout Standard
18003
18004 aslink
18005 \end_inset
18006 </cell>
18007 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18008 \begin_inset Text
18009
18010 \layout Standard
18011
18012 Linker
18013 \end_inset
18014 </cell>
18015 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18016 \begin_inset Text
18017
18018 \layout Standard
18019
18020
18021 \family roman
18022 \series medium
18023 \shape up
18024 \size normal
18025 \emph off
18026 \bar no
18027 \noun off
18028 \color none
18029 sdcc/bin
18030 \end_inset
18031 </cell>
18032 </row>
18033 <row topline="true">
18034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18035 \begin_inset Text
18036
18037 \layout Standard
18038
18039 link-z80
18040 \end_inset
18041 </cell>
18042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18043 \begin_inset Text
18044
18045 \layout Standard
18046
18047 Linker
18048 \end_inset
18049 </cell>
18050 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18051 \begin_inset Text
18052
18053 \layout Standard
18054
18055
18056 \family roman
18057 \series medium
18058 \shape up
18059 \size normal
18060 \emph off
18061 \bar no
18062 \noun off
18063 \color none
18064 sdcc/bin
18065 \end_inset
18066 </cell>
18067 </row>
18068 <row topline="true">
18069 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18070 \begin_inset Text
18071
18072 \layout Standard
18073
18074 link-gbz80
18075 \end_inset
18076 </cell>
18077 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18078 \begin_inset Text
18079
18080 \layout Standard
18081
18082 Linker
18083 \end_inset
18084 </cell>
18085 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18086 \begin_inset Text
18087
18088 \layout Standard
18089
18090
18091 \family roman
18092 \series medium
18093 \shape up
18094 \size normal
18095 \emph off
18096 \bar no
18097 \noun off
18098 \color none
18099 sdcc/bin
18100 \end_inset
18101 </cell>
18102 </row>
18103 <row topline="true" bottomline="true">
18104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18105 \begin_inset Text
18106
18107 \layout Standard
18108
18109 packihx
18110 \end_inset
18111 </cell>
18112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18113 \begin_inset Text
18114
18115 \layout Standard
18116
18117 ihx packer
18118 \end_inset
18119 </cell>
18120 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18121 \begin_inset Text
18122
18123 \layout Standard
18124
18125
18126 \family roman
18127 \series medium
18128 \shape up
18129 \size normal
18130 \emph off
18131 \bar no
18132 \noun off
18133 \color none
18134 sdcc/bin
18135 \end_inset
18136 </cell>
18137 </row>
18138 </lyxtabular>
18139
18140 \end_inset
18141
18142
18143 \newline
18144
18145 \layout Section
18146
18147 Documentation
18148 \begin_inset LatexCommand \index{Documentation}
18149
18150 \end_inset
18151
18152  included in the distribution
18153 \layout Standard
18154 \align center
18155
18156 \begin_inset  Tabular
18157 <lyxtabular version="3" rows="10" columns="2">
18158 <features>
18159 <column alignment="left" valignment="top" leftline="true" width="0">
18160 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
18161 <row topline="true" bottomline="true">
18162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18163 \begin_inset Text
18164
18165 \layout Standard
18166
18167 Subject / Title
18168 \end_inset
18169 </cell>
18170 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18171 \begin_inset Text
18172
18173 \layout Standard
18174
18175 Where to get / filename
18176 \end_inset
18177 </cell>
18178 </row>
18179 <row topline="true">
18180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18181 \begin_inset Text
18182
18183 \layout Standard
18184
18185 SDCC Compiler User Guide
18186 \end_inset
18187 </cell>
18188 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18189 \begin_inset Text
18190
18191 \layout Standard
18192
18193 You're reading it right now
18194 \end_inset
18195 </cell>
18196 </row>
18197 <row topline="true">
18198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18199 \begin_inset Text
18200
18201 \layout Standard
18202
18203 Changelog of SDCC
18204 \end_inset
18205 </cell>
18206 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18207 \begin_inset Text
18208
18209 \layout Standard
18210
18211 sdcc/Changelog
18212 \end_inset
18213 </cell>
18214 </row>
18215 <row topline="true">
18216 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18217 \begin_inset Text
18218
18219 \layout Standard
18220
18221 ASXXXX
18222 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
18223
18224 \end_inset
18225
18226
18227 \begin_inset LatexCommand \index{Assembler documentation}
18228
18229 \end_inset
18230
18231  Assemblers and ASLINK
18232 \begin_inset LatexCommand \index{aslink}
18233
18234 \end_inset
18235
18236
18237 \begin_inset LatexCommand \index{Linker documentation}
18238
18239 \end_inset
18240
18241  Relocating Linker
18242 \end_inset
18243 </cell>
18244 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18245 \begin_inset Text
18246
18247 \layout Standard
18248
18249 sdcc/as/doc/asxhtm.html
18250 \end_inset
18251 </cell>
18252 </row>
18253 <row topline="true">
18254 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18255 \begin_inset Text
18256
18257 \layout Standard
18258
18259 SDCC regression test
18260 \begin_inset LatexCommand \index{Regression test}
18261
18262 \end_inset
18263
18264
18265 \end_inset
18266 </cell>
18267 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18268 \begin_inset Text
18269
18270 \layout Standard
18271
18272 sdcc/doc/test_suite_spec.pdf
18273 \end_inset
18274 </cell>
18275 </row>
18276 <row topline="true">
18277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18278 \begin_inset Text
18279
18280 \layout Standard
18281
18282 Various notes
18283 \end_inset
18284 </cell>
18285 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18286 \begin_inset Text
18287
18288 \layout Standard
18289
18290 sdcc/doc/*
18291 \end_inset
18292 </cell>
18293 </row>
18294 <row topline="true">
18295 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18296 \begin_inset Text
18297
18298 \layout Standard
18299
18300 Notes on debugging with sdcdb
18301 \begin_inset LatexCommand \index{sdcdb (debugger)}
18302
18303 \end_inset
18304
18305
18306 \end_inset
18307 </cell>
18308 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18309 \begin_inset Text
18310
18311 \layout Standard
18312
18313 sdcc/debugger/README
18314 \end_inset
18315 </cell>
18316 </row>
18317 <row topline="true">
18318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18319 \begin_inset Text
18320
18321 \layout Standard
18322
18323 Software simulator for microcontrollers
18324 \end_inset
18325 </cell>
18326 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18327 \begin_inset Text
18328
18329 \layout Standard
18330
18331
18332 \family roman
18333 \series medium
18334 \shape up
18335 \size normal
18336 \emph off
18337 \bar no
18338 \noun off
18339 \color none
18340 sdcc/sim/ucsim/doc
18341 \family default
18342 \series default
18343 \shape default
18344 \size default
18345 \emph default
18346 \bar default
18347 \noun default
18348 \color default
18349 /index.html
18350 \end_inset
18351 </cell>
18352 </row>
18353 <row topline="true">
18354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18355 \begin_inset Text
18356
18357 \layout Standard
18358
18359 Temporary notes on the pic16
18360 \begin_inset LatexCommand \index{PIC16}
18361
18362 \end_inset
18363
18364  port
18365 \end_inset
18366 </cell>
18367 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18368 \begin_inset Text
18369
18370 \layout Standard
18371
18372 sdcc/src/pic16/NOTES
18373 \end_inset
18374 </cell>
18375 </row>
18376 <row topline="true" bottomline="true">
18377 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18378 \begin_inset Text
18379
18380 \layout Standard
18381
18382 SDCC internal documentation (debugging file format)
18383 \end_inset
18384 </cell>
18385 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18386 \begin_inset Text
18387
18388 \layout Standard
18389
18390 sdcc/doc/
18391 \family roman
18392 \series medium
18393 \shape up
18394 \size normal
18395 \emph off
18396 \bar no
18397 \noun off
18398 \color none
18399 cdbfileformat.pd
18400 \family default
18401 \series default
18402 \shape default
18403 \size default
18404 \emph default
18405 \bar default
18406 \noun default
18407 \color default
18408 f
18409 \end_inset
18410 </cell>
18411 </row>
18412 </lyxtabular>
18413
18414 \end_inset
18415
18416
18417 \newline
18418
18419 \layout Section
18420
18421 Related open source tools
18422 \begin_inset LatexCommand \index{Related tools}
18423
18424 \end_inset
18425
18426
18427 \layout Standard
18428 \align center
18429
18430 \begin_inset  Tabular
18431 <lyxtabular version="3" rows="11" columns="3">
18432 <features>
18433 <column alignment="center" valignment="top" leftline="true" width="0pt">
18434 <column alignment="block" valignment="top" leftline="true" width="30line%">
18435 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18436 <row topline="true" bottomline="true">
18437 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18438 \begin_inset Text
18439
18440 \layout Standard
18441
18442 Name
18443 \end_inset
18444 </cell>
18445 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18446 \begin_inset Text
18447
18448 \layout Standard
18449
18450 Purpose
18451 \end_inset
18452 </cell>
18453 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18454 \begin_inset Text
18455
18456 \layout Standard
18457
18458 Where to get
18459 \end_inset
18460 </cell>
18461 </row>
18462 <row topline="true">
18463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18464 \begin_inset Text
18465
18466 \layout Standard
18467
18468 gpsim
18469 \begin_inset LatexCommand \index{gpsim (pic simulator)}
18470
18471 \end_inset
18472
18473
18474 \end_inset
18475 </cell>
18476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18477 \begin_inset Text
18478
18479 \layout Standard
18480
18481 PIC simulator
18482 \end_inset
18483 </cell>
18484 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18485 \begin_inset Text
18486
18487 \layout Standard
18488
18489
18490 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
18491
18492 \end_inset
18493
18494
18495 \end_inset
18496 </cell>
18497 </row>
18498 <row topline="true">
18499 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18500 \begin_inset Text
18501
18502 \layout Standard
18503
18504 gputils
18505 \begin_inset LatexCommand \index{gputils (pic tools)}
18506
18507 \end_inset
18508
18509
18510 \end_inset
18511 </cell>
18512 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18513 \begin_inset Text
18514
18515 \layout Standard
18516
18517 GNU PIC utilities
18518 \end_inset
18519 </cell>
18520 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18521 \begin_inset Text
18522
18523 \layout Standard
18524
18525
18526 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
18527
18528 \end_inset
18529
18530
18531 \end_inset
18532 </cell>
18533 </row>
18534 <row topline="true">
18535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18536 \begin_inset Text
18537
18538 \layout Standard
18539
18540 flP5
18541 \end_inset
18542 </cell>
18543 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18544 \begin_inset Text
18545
18546 \layout Standard
18547
18548 PIC programmer
18549 \end_inset
18550 </cell>
18551 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18552 \begin_inset Text
18553
18554 \layout Standard
18555
18556
18557 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
18558
18559 \end_inset
18560
18561
18562 \end_inset
18563 </cell>
18564 </row>
18565 <row topline="true">
18566 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18567 \begin_inset Text
18568
18569 \layout Standard
18570
18571 indent
18572 \begin_inset LatexCommand \index{indent (source formatting tool)}
18573
18574 \end_inset
18575
18576
18577 \end_inset
18578 </cell>
18579 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18580 \begin_inset Text
18581
18582 \layout Standard
18583
18584 Formats C source - Master of the white spaces
18585 \end_inset
18586 </cell>
18587 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18588 \begin_inset Text
18589
18590 \layout Standard
18591
18592
18593 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
18594
18595 \end_inset
18596
18597
18598 \end_inset
18599 </cell>
18600 </row>
18601 <row topline="true">
18602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18603 \begin_inset Text
18604
18605 \layout Standard
18606
18607 srecord
18608 \begin_inset LatexCommand \index{srecord (tool)}
18609
18610 \end_inset
18611
18612
18613 \end_inset
18614 </cell>
18615 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18616 \begin_inset Text
18617
18618 \layout Standard
18619
18620 Object file conversion, checksumming, ...
18621 \end_inset
18622 </cell>
18623 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18624 \begin_inset Text
18625
18626 \layout Standard
18627
18628
18629 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
18630
18631 \end_inset
18632
18633
18634 \end_inset
18635 </cell>
18636 </row>
18637 <row topline="true">
18638 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18639 \begin_inset Text
18640
18641 \layout Standard
18642
18643 objdump
18644 \begin_inset LatexCommand \index{objdump (tool)}
18645
18646 \end_inset
18647
18648
18649 \end_inset
18650 </cell>
18651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18652 \begin_inset Text
18653
18654 \layout Standard
18655
18656 Object file conversion, ...
18657 \end_inset
18658 </cell>
18659 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18660 \begin_inset Text
18661
18662 \layout Standard
18663
18664 Part of binutils (should be there anyway)
18665 \end_inset
18666 </cell>
18667 </row>
18668 <row topline="true">
18669 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18670 \begin_inset Text
18671
18672 \layout Standard
18673
18674 doxygen
18675 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
18676
18677 \end_inset
18678
18679
18680 \end_inset
18681 </cell>
18682 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18683 \begin_inset Text
18684
18685 \layout Standard
18686
18687 Source code documentation system
18688 \end_inset
18689 </cell>
18690 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18691 \begin_inset Text
18692
18693 \layout Standard
18694
18695
18696 \begin_inset LatexCommand \url{http://www.doxygen.org}
18697
18698 \end_inset
18699
18700
18701 \end_inset
18702 </cell>
18703 </row>
18704 <row topline="true">
18705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18706 \begin_inset Text
18707
18708 \layout Standard
18709
18710 kdevelop
18711 \end_inset
18712 </cell>
18713 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18714 \begin_inset Text
18715
18716 \layout Standard
18717
18718 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
18719 \end_inset
18720 </cell>
18721 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18722 \begin_inset Text
18723
18724 \layout Standard
18725
18726
18727 \begin_inset LatexCommand \url{http://www.kdevelop.org}
18728
18729 \end_inset
18730
18731
18732 \end_inset
18733 </cell>
18734 </row>
18735 <row topline="true">
18736 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18737 \begin_inset Text
18738
18739 \layout Standard
18740
18741 splint
18742 \begin_inset LatexCommand \index{splint (syntax checking tool)}
18743
18744 \end_inset
18745
18746
18747 \end_inset
18748 </cell>
18749 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18750 \begin_inset Text
18751
18752 \layout Standard
18753
18754 Statically checks c sources (has anyone adapted splint for SDCC?)
18755 \end_inset
18756 </cell>
18757 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18758 \begin_inset Text
18759
18760 \layout Standard
18761
18762
18763 \begin_inset LatexCommand \url{http://www.splint.org}
18764
18765 \end_inset
18766
18767
18768 \end_inset
18769 </cell>
18770 </row>
18771 <row topline="true" bottomline="true">
18772 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18773 \begin_inset Text
18774
18775 \layout Standard
18776
18777 ddd
18778 \begin_inset LatexCommand \index{ddd (debugger)}
18779
18780 \end_inset
18781
18782
18783 \end_inset
18784 </cell>
18785 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18786 \begin_inset Text
18787
18788 \layout Standard
18789
18790 Debugger, serves nicely as GUI to sdcdb
18791 \begin_inset LatexCommand \index{sdcdb (debugger)}
18792
18793 \end_inset
18794
18795  (Unix only)
18796 \end_inset
18797 </cell>
18798 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18799 \begin_inset Text
18800
18801 \layout Standard
18802
18803
18804 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
18805
18806 \end_inset
18807
18808
18809 \end_inset
18810 </cell>
18811 </row>
18812 </lyxtabular>
18813
18814 \end_inset
18815
18816
18817 \newline
18818
18819 \layout Section
18820
18821 Related documentation / recommended reading
18822 \layout Standard
18823 \align center
18824
18825 \begin_inset  Tabular
18826 <lyxtabular version="3" rows="6" columns="3">
18827 <features>
18828 <column alignment="center" valignment="top" leftline="true" width="0pt">
18829 <column alignment="block" valignment="top" leftline="true" width="30line%">
18830 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18831 <row topline="true" bottomline="true">
18832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18833 \begin_inset Text
18834
18835 \layout Standard
18836
18837 Name
18838 \end_inset
18839 </cell>
18840 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18841 \begin_inset Text
18842
18843 \layout Standard
18844
18845 Subject / Title
18846 \end_inset
18847 </cell>
18848 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18849 \begin_inset Text
18850
18851 \layout Standard
18852
18853 Where to get
18854 \end_inset
18855 </cell>
18856 </row>
18857 <row topline="true">
18858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18859 \begin_inset Text
18860
18861 \layout Standard
18862
18863
18864 \family roman
18865 \series medium
18866 \shape up
18867 \size normal
18868 \emph off
18869 \bar no
18870 \noun off
18871 \color none
18872 c-refcard.pdf
18873 \end_inset
18874 </cell>
18875 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18876 \begin_inset Text
18877
18878 \layout Standard
18879
18880 C Reference Card
18881 \begin_inset LatexCommand \index{C Reference card}
18882
18883 \end_inset
18884
18885 , 2 pages
18886 \end_inset
18887 </cell>
18888 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18889 \begin_inset Text
18890
18891 \layout Standard
18892
18893
18894 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
18895
18896 \end_inset
18897
18898
18899 \end_inset
18900 </cell>
18901 </row>
18902 <row topline="true">
18903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18904 \begin_inset Text
18905
18906 \layout Standard
18907
18908 c-faq
18909 \end_inset
18910 </cell>
18911 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18912 \begin_inset Text
18913
18914 \layout Standard
18915
18916 C-FAQ-list
18917 \end_inset
18918 </cell>
18919 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18920 \begin_inset Text
18921
18922 \layout Standard
18923
18924
18925 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
18926
18927 \end_inset
18928
18929
18930 \end_inset
18931 </cell>
18932 </row>
18933 <row topline="true">
18934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18935 \begin_inset Text
18936
18937 \layout Standard
18938
18939 \end_inset
18940 </cell>
18941 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18942 \begin_inset Text
18943
18944 \layout Standard
18945
18946 Latest datasheet of the target CPU
18947 \end_inset
18948 </cell>
18949 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18950 \begin_inset Text
18951
18952 \layout Standard
18953
18954 vendor
18955 \end_inset
18956 </cell>
18957 </row>
18958 <row topline="true">
18959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18960 \begin_inset Text
18961
18962 \layout Standard
18963
18964 \end_inset
18965 </cell>
18966 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18967 \begin_inset Text
18968
18969 \layout Standard
18970
18971 Revision history of datasheet
18972 \end_inset
18973 </cell>
18974 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18975 \begin_inset Text
18976
18977 \layout Standard
18978
18979 vendor
18980 \end_inset
18981 </cell>
18982 </row>
18983 <row topline="true" bottomline="true">
18984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18985 \begin_inset Text
18986
18987 \layout Standard
18988
18989 S.
18990  S.
18991  Muchnick
18992 \end_inset
18993 </cell>
18994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18995 \begin_inset Text
18996
18997 \layout Standard
18998
18999 Advanced Compiler Design and Implementation
19000 \end_inset
19001 </cell>
19002 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19003 \begin_inset Text
19004
19005 \layout Standard
19006
19007 bookstore (very dedicated, probably read other books first)
19008 \end_inset
19009 </cell>
19010 </row>
19011 </lyxtabular>
19012
19013 \end_inset
19014
19015
19016 \newline
19017
19018 \layout Section
19019
19020 Some Questions
19021 \layout Standard
19022
19023 Some questions answered, some pointers given - it might be time to in turn
19024  ask
19025 \emph on
19026 you
19027 \emph default
19028  some questions:
19029 \layout Itemize
19030
19031 can you solve your project with the selected microcontroller? Would you
19032  find out early or rather late that your target is too small/slow/whatever?
19033  Can you switch to a slightly better device if it doesn't fit?
19034 \layout Itemize
19035
19036 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
19037  and/or another programming language be more adequate? Would an operating
19038  system on the target device help?
19039 \layout Itemize
19040
19041 if you solved the problem, will the marketing department be happy?
19042 \layout Itemize
19043
19044 if the marketing department is happy, will customers be happy?
19045 \layout Itemize
19046
19047 if you're the project manager, marketing department and maybe even the customer
19048  in one person, have you tried to see the project from the outside?
19049 \layout Itemize
19050
19051 is the project done if you think it is done? Or is just that other interface/pro
19052 tocol/feature/configuration/option missing? How about website, manual(s),
19053  internationali(z|s)ation, packaging, labels, 2nd source for components,
19054  electromagnetic compatability/interference, documentation for production,
19055  production test software, update mechanism, patent issues?
19056 \layout Itemize
19057
19058 is your project adequately positioned in that magic triangle: fame, fortune,
19059  fun?
19060 \layout Standard
19061
19062 Maybe not all answers to these questions are known and some answers may
19063  even be
19064 \emph on
19065 no
19066 \emph default
19067 , nevertheless knowing these questions may help you to avoid burnout
19068 \begin_inset Foot
19069 collapsed false
19070
19071 \layout Standard
19072
19073 burnout is bad for electronic devices, programmers and motorcycle tyres
19074 \end_inset
19075
19076 .
19077  Chances are you didn't want to hear some of them...
19078 \layout Chapter
19079
19080 Support
19081 \begin_inset LatexCommand \index{Support}
19082
19083 \end_inset
19084
19085
19086 \layout Standard
19087
19088 SDCC has grown to be a large project.
19089  The compiler alone (without the preprocessor, assembler and linker) is
19090  well over 100,000 lines of code (blank stripped).
19091  The open source nature of this project is a key to its continued growth
19092  and support.
19093  You gain the benefit and support of many active software developers and
19094  end users.
19095  Is SDCC perfect? No, that's why we need your help.
19096  The developers take pride in fixing reported bugs.
19097  You can help by reporting the bugs and helping other SDCC users.
19098  There are lots of ways to contribute, and we encourage you to take part
19099  in making SDCC a great software package.
19100
19101 \layout Standard
19102
19103 The SDCC project is hosted on the SDCC sourceforge site at
19104 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
19105
19106 \end_inset
19107
19108 .
19109  You'll find the complete set of mailing lists
19110 \begin_inset LatexCommand \index{Mailing list(s)}
19111
19112 \end_inset
19113
19114 , forums, bug reporting system, patch submission
19115 \begin_inset LatexCommand \index{Patch submission}
19116
19117 \end_inset
19118
19119  system, download
19120 \begin_inset LatexCommand \index{download}
19121
19122 \end_inset
19123
19124  area and cvs code repository
19125 \begin_inset LatexCommand \index{cvs code repository}
19126
19127 \end_inset
19128
19129  there.
19130 \layout Section
19131
19132 Reporting Bugs
19133 \begin_inset LatexCommand \index{Bug reporting}
19134
19135 \end_inset
19136
19137
19138 \begin_inset LatexCommand \index{Reporting bugs}
19139
19140 \end_inset
19141
19142
19143 \layout Standard
19144
19145 The recommended way of reporting bugs is using the infrastructure of the
19146  sourceforge site.
19147  You can follow the status of bug reports there and have an overview about
19148  the known bugs.
19149 \layout Standard
19150
19151 Bug reports are automatically forwarded to the developer mailing list and
19152  will be fixed ASAP.
19153  When reporting a bug, it is very useful to include a small test program
19154  (the smaller the better) which reproduces the problem.
19155  If you can isolate the problem by looking at the generated assembly code,
19156  this can be very helpful.
19157  Compiling your program with the -
19158 \begin_inset ERT
19159 status Collapsed
19160
19161 \layout Standard
19162
19163 \backslash
19164 /
19165 \end_inset
19166
19167 -dumpall
19168 \begin_inset LatexCommand \index{-\/-dumpall}
19169
19170 \end_inset
19171
19172  option can sometimes be useful in locating optimization problems.
19173  When reporting a bug please maker sure you:
19174 \layout Enumerate
19175
19176 Attach the code you are compiling with SDCC.
19177
19178 \layout Enumerate
19179
19180 Specify the exact command you use to run SDCC, or attach your Makefile.
19181
19182 \layout Enumerate
19183
19184 Specify the SDCC version (type "
19185 \family sans
19186 \series bold
19187 sdcc -v
19188 \family default
19189 \series default
19190 "), your platform, and operating system.
19191
19192 \layout Enumerate
19193
19194 Provide an exact copy of any error message or incorrect output.
19195
19196 \layout Enumerate
19197
19198 Put something meaningful in the subject of your message.
19199 \layout Standard
19200
19201 Please attempt to include these 5 important parts, as applicable, in all
19202  requests for support or when reporting any problems or bugs with SDCC.
19203  Though this will make your message lengthy, it will greatly improve your
19204  chance that SDCC users and developers will be able to help you.
19205  Some SDCC developers are frustrated by bug reports without code provided
19206  that they can use to reproduce and ultimately fix the problem, so please
19207  be sure to provide sample code if you are reporting a bug!
19208 \layout Standard
19209
19210 Please have a short check that you are using a recent version of SDCC and
19211  the bug is not yet known.
19212  This is the link for reporting bugs:
19213 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
19214
19215 \end_inset
19216
19217 .
19218 \layout Section
19219
19220 Requesting Features
19221 \begin_inset LatexCommand \label{sub:Requesting-Features}
19222
19223 \end_inset
19224
19225
19226 \begin_inset LatexCommand \index{Feature request}
19227
19228 \end_inset
19229
19230
19231 \begin_inset LatexCommand \index{Requesting features}
19232
19233 \end_inset
19234
19235
19236 \layout Standard
19237
19238 Like bug reports feature requests are forwarded to the developer mailing
19239  list.
19240  This is the link for requesting features:
19241 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
19242
19243 \end_inset
19244
19245 .
19246 \layout Section
19247
19248 Submitting patches
19249 \layout Standard
19250
19251 Like bug reports contributed patches are forwarded to the developer mailing
19252  list.
19253  This is the link for submitting patches
19254 \begin_inset LatexCommand \index{Patch submission}
19255
19256 \end_inset
19257
19258 :
19259 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
19260
19261 \end_inset
19262
19263 .
19264 \layout Standard
19265
19266 You need to specify some parameters to the
19267 \family typewriter
19268 diff
19269 \family default
19270  command for the patches to be useful.
19271  If you modified more than one file a patch created f.e.
19272  with
19273 \family sans
19274 \series bold
19275
19276 \begin_inset Quotes sld
19277 \end_inset
19278
19279 diff -Naur unmodified_directory modified_directory >my_changes.patch
19280 \begin_inset Quotes srd
19281 \end_inset
19282
19283
19284 \family default
19285 \series default
19286  will be fine, otherwise
19287 \family sans
19288 \series bold
19289
19290 \begin_inset Quotes sld
19291 \end_inset
19292
19293 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
19294 \begin_inset Quotes srd
19295 \end_inset
19296
19297
19298 \series default
19299
19300 \family default
19301 will do.
19302 \layout Section
19303
19304 Getting Help
19305 \layout Standard
19306
19307 These links should take you directly to the
19308 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
19309
19310 \end_inset
19311
19312
19313 \begin_inset Foot
19314 collapsed false
19315
19316 \layout Standard
19317
19318 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
19319  automated messages (mid 2003)
19320 \end_inset
19321
19322  and the
19323 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
19324
19325 \end_inset
19326
19327 , lists
19328 \begin_inset LatexCommand \index{Mailing list(s)}
19329
19330 \end_inset
19331
19332  and forums are archived and searchable so if you are lucky someone already
19333  had a similar problem.
19334  While mails to the lists themselves are delivered promptly their web front
19335  end on sourceforge sometimes shows a severe time lag (up to several weeks),
19336  if you're seriously using SDCC please consider subscribing to the lists.
19337 \layout Section
19338
19339 ChangeLog
19340 \layout Standard
19341
19342 You can follow the status of the cvs version
19343 \begin_inset LatexCommand \index{version}
19344
19345 \end_inset
19346
19347  of SDCC by watching the Changelog
19348 \begin_inset LatexCommand \index{Changelog}
19349
19350 \end_inset
19351
19352  in the cvs-repository
19353 \newline
19354
19355 \size footnotesize
19356
19357 \begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
19358
19359 \end_inset
19360
19361 .
19362 \layout Section
19363
19364 Release policy
19365 \begin_inset LatexCommand \index{Release policy}
19366
19367 \end_inset
19368
19369
19370 \layout Standard
19371
19372 Historically there often were long delays between official releases and
19373  the sourceforge download area tends to get not updated at all.
19374  Excuses in the past might have referred to problems with live range analysis,
19375  but as this was fixed a while ago, the current problem is that another
19376  excuse has to be found.
19377  Kidding aside, we have to get better there! On the other hand there are
19378  daily snapshots available at
19379 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
19380
19381 \end_inset
19382
19383 , and you can always build the very last version (hopefully with many bugs
19384  fixed, and features added) from the source code available at
19385 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
19386
19387 \end_inset
19388
19389 .
19390 \layout Section
19391
19392 Examples
19393 \begin_inset LatexCommand \index{Examples}
19394
19395 \end_inset
19396
19397
19398 \layout Standard
19399
19400 You'll find some small examples in the directory
19401 \emph on
19402 sdcc/device/examples/.
19403
19404 \emph default
19405 More examples and libraries are available at
19406 \emph on
19407  The SDCC Open Knowledge Resource
19408 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
19409
19410 \end_inset
19411
19412
19413 \emph default
19414 web site or at
19415 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
19416
19417 \end_inset
19418
19419 .
19420 \layout Comment
19421
19422 I did insert a reference to Paul's web site here although it seems rather
19423  dedicated to a specific 8032 board (I think it's okay because it f.e.
19424  shows LCD/Harddisc interface and has a free 8051 monitor.
19425  Independent 8032 board vendors face hard competition of heavily subsidized
19426  development boards anyway).
19427 \layout Comment
19428
19429 Maybe we should include some links to real world applications.
19430  Preferably pointer to pointers (one for each architecture) so this stays
19431  manageable here?
19432 \layout Section
19433
19434 Quality control
19435 \begin_inset LatexCommand \index{Quality control}
19436
19437 \end_inset
19438
19439
19440 \layout Standard
19441
19442 The compiler is passed through nightly compile and build checks.
19443  The so called
19444 \shape italic
19445 regression tests
19446 \shape default
19447
19448 \begin_inset LatexCommand \index{Regression test}
19449
19450 \end_inset
19451
19452  check that SDCC itself compiles flawlessly on several platforms and checks
19453  the quality of the code generated by SDCC by running the code through simulator
19454 s.
19455  There is a separate document
19456 \shape italic
19457 test_suite.pdf
19458 \begin_inset LatexCommand \index{Test suite}
19459
19460 \end_inset
19461
19462
19463 \shape default
19464  about this.
19465 \layout Standard
19466
19467 You'll find the test code in the directory
19468 \shape italic
19469 sdcc/support/regression
19470 \shape default
19471 .
19472  You can run these tests manually by running
19473 \family sans
19474 make
19475 \family default
19476  in this directory (or f.e.
19477
19478 \family sans
19479 \series bold
19480
19481 \begin_inset Quotes sld
19482 \end_inset
19483
19484 make test-mcs51
19485 \begin_inset Quotes srd
19486 \end_inset
19487
19488
19489 \family default
19490 \series default
19491  if you don't want to run the complete tests).
19492  The test code might also be interesting if you want to look for examples
19493 \begin_inset LatexCommand \index{Examples}
19494
19495 \end_inset
19496
19497  checking corner cases of SDCC or if you plan to submit patches
19498 \begin_inset LatexCommand \index{Patch submission}
19499
19500 \end_inset
19501
19502 .
19503 \layout Standard
19504
19505 The pic port uses a different set of regression tests, you'll find them
19506  in the directory
19507 \shape italic
19508 sdcc/src/regression
19509 \shape default
19510 .
19511 \layout Chapter
19512 \pagebreak_top
19513 SDCC Technical Data
19514 \layout Section
19515
19516 Optimizations
19517 \begin_inset LatexCommand \index{Optimizations}
19518
19519 \end_inset
19520
19521
19522 \layout Standard
19523
19524 SDCC performs a host of standard optimizations in addition to some MCU specific
19525  optimizations.
19526
19527 \layout Subsection
19528
19529 Sub-expression Elimination
19530 \begin_inset LatexCommand \index{Subexpression elimination}
19531
19532 \end_inset
19533
19534
19535 \layout Standard
19536
19537 The compiler does local and
19538 \emph on
19539 g
19540 \emph default
19541 lobal
19542 \emph on
19543 c
19544 \emph default
19545 ommon
19546 \emph on
19547 s
19548 \emph default
19549 ubexpression
19550 \emph on
19551 e
19552 \emph default
19553 limination, e.g.:
19554 \layout Verse
19555
19556
19557 \family typewriter
19558 i = x + y + 1;
19559 \newline
19560 j = x + y;
19561 \layout Standard
19562
19563 will be translated to
19564 \layout Verse
19565
19566
19567 \family typewriter
19568 iTemp = x + y;
19569 \newline
19570 i = iTemp + 1;
19571 \newline
19572 j = iTemp;
19573 \layout Standard
19574
19575 Some subexpressions are not as obvious as the above example, e.g.:
19576 \layout Verse
19577
19578
19579 \family typewriter
19580 a->b[i].c = 10;
19581 \newline
19582 a->b[i].d = 11;
19583 \layout Standard
19584
19585 In this case the address arithmetic a->b[i] will be computed only once;
19586  the equivalent code in C would be.
19587 \layout Verse
19588
19589
19590 \family typewriter
19591 iTemp = a->b[i];
19592 \newline
19593 iTemp.c = 10;
19594 \newline
19595 iTemp.d = 11;
19596 \layout Standard
19597
19598 The compiler will try to keep these temporary variables in registers.
19599 \layout Subsection
19600
19601 Dead-Code Elimination
19602 \begin_inset LatexCommand \index{Dead-code elimination}
19603
19604 \end_inset
19605
19606
19607 \layout Verse
19608
19609
19610 \family typewriter
19611 int global;
19612 \newline
19613
19614 \newline
19615 void f () {
19616 \newline
19617 \SpecialChar ~
19618 \SpecialChar ~
19619 int i;
19620 \newline
19621 \SpecialChar ~
19622 \SpecialChar ~
19623 i = 1; \SpecialChar ~
19624 \SpecialChar ~
19625 \SpecialChar ~
19626 \SpecialChar ~
19627 \SpecialChar ~
19628 /* dead store */
19629 \newline
19630 \SpecialChar ~
19631 \SpecialChar ~
19632 global = 1;\SpecialChar ~
19633 /* dead store */
19634 \newline
19635 \SpecialChar ~
19636 \SpecialChar ~
19637 global = 2;
19638 \newline
19639 \SpecialChar ~
19640 \SpecialChar ~
19641 return;
19642 \newline
19643 \SpecialChar ~
19644 \SpecialChar ~
19645 global = 3;\SpecialChar ~
19646 /* unreachable */
19647 \newline
19648 }
19649 \layout Standard
19650
19651 will be changed to
19652 \layout Verse
19653
19654
19655 \family typewriter
19656 int global;
19657 \newline
19658
19659 \newline
19660 void f () {
19661 \newline
19662 \SpecialChar ~
19663 \SpecialChar ~
19664 global = 2;
19665 \newline
19666 }
19667 \layout Subsection
19668
19669 Copy-Propagation
19670 \begin_inset LatexCommand \index{Copy propagation}
19671
19672 \end_inset
19673
19674
19675 \layout Verse
19676
19677
19678 \family typewriter
19679 int f() {
19680 \newline
19681 \SpecialChar ~
19682 \SpecialChar ~
19683 int i, j;
19684 \newline
19685 \SpecialChar ~
19686 \SpecialChar ~
19687 i = 10;
19688 \newline
19689 \SpecialChar ~
19690 \SpecialChar ~
19691 j = i;
19692 \newline
19693 \SpecialChar ~
19694 \SpecialChar ~
19695 return j;
19696 \newline
19697 }
19698 \layout Standard
19699
19700 will be changed to
19701 \layout Verse
19702
19703
19704 \family typewriter
19705 int f() {
19706 \newline
19707 \SpecialChar ~
19708 \SpecialChar ~
19709 int i, j;
19710 \newline
19711 \SpecialChar ~
19712 \SpecialChar ~
19713 i = 10;
19714 \newline
19715 \SpecialChar ~
19716 \SpecialChar ~
19717 j = 10;
19718 \newline
19719 \SpecialChar ~
19720 \SpecialChar ~
19721 return 10;
19722 \newline
19723 }
19724 \layout Standard
19725
19726 Note: the dead stores created by this copy propagation will be eliminated
19727  by dead-code elimination.
19728 \layout Subsection
19729
19730 Loop Optimizations
19731 \begin_inset LatexCommand \index{Loop optimization}
19732
19733 \end_inset
19734
19735
19736 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
19737
19738 \end_inset
19739
19740
19741 \layout Standard
19742
19743 Two types of loop optimizations are done by SDCC
19744 \emph on
19745 loop invariant
19746 \emph default
19747  lifting and
19748 \emph on
19749  strength reduction
19750 \emph default
19751  of loop induction variables.
19752  In addition to the strength reduction the optimizer marks the induction
19753  variables and the register allocator tries to keep the induction variables
19754  in registers for the duration of the loop.
19755  Because of this preference of the register allocator
19756 \begin_inset LatexCommand \index{Register allocation}
19757
19758 \end_inset
19759
19760 , loop induction optimization causes an increase in register pressure, which
19761  may cause unwanted spilling of other temporary variables into the stack
19762 \begin_inset LatexCommand \index{stack}
19763
19764 \end_inset
19765
19766  / data space.
19767  The compiler will generate a warning message when it is forced to allocate
19768  extra space either on the stack or data space.
19769  If this extra space allocation is undesirable then induction optimization
19770  can be eliminated either for the entire source file (with -
19771 \begin_inset ERT
19772 status Collapsed
19773
19774 \layout Standard
19775
19776 \backslash
19777 /
19778 \end_inset
19779
19780 -noinduction option) or for a given function only using #pragma\SpecialChar ~
19781 noinduction
19782 \begin_inset LatexCommand \index{\#pragma noinduction}
19783
19784 \end_inset
19785
19786 .
19787 \newline
19788
19789 \newline
19790 Loop Invariant:
19791 \layout Verse
19792
19793
19794 \family typewriter
19795 for (i = 0 ; i < 100 ; i ++)
19796 \newline
19797 \SpecialChar ~
19798 \SpecialChar ~
19799 \SpecialChar ~
19800 \SpecialChar ~
19801 f += k + l;
19802 \layout Standard
19803
19804 changed to
19805 \layout Verse
19806
19807
19808 \family typewriter
19809 itemp = k + l;
19810 \newline
19811 for (i = 0; i < 100; i++)
19812 \newline
19813 \SpecialChar ~
19814 \SpecialChar ~
19815 \SpecialChar ~
19816 \SpecialChar ~
19817 f += itemp;
19818 \layout Standard
19819
19820 As mentioned previously some loop invariants are not as apparent, all static
19821  address computations are also moved out of the loop.
19822 \newline
19823
19824 \newline
19825 Strength Reduction
19826 \begin_inset LatexCommand \index{Strength reduction}
19827
19828 \end_inset
19829
19830 , this optimization substitutes an expression by a cheaper expression:
19831 \layout Verse
19832
19833
19834 \family typewriter
19835 for (i=0;i < 100; i++)
19836 \newline
19837 \SpecialChar ~
19838 \SpecialChar ~
19839 \SpecialChar ~
19840 \SpecialChar ~
19841 ar[i*5] = i*3;
19842 \layout Standard
19843
19844 changed to
19845 \layout Verse
19846
19847
19848 \family typewriter
19849 itemp1 = 0;
19850 \newline
19851 itemp2 = 0;
19852 \newline
19853 for (i=0;i< 100;i++) {
19854 \newline
19855 \SpecialChar ~
19856 \SpecialChar ~
19857 \SpecialChar ~
19858 \SpecialChar ~
19859 ar[itemp1] = itemp2;
19860 \newline
19861 \SpecialChar ~
19862 \SpecialChar ~
19863 \SpecialChar ~
19864 \SpecialChar ~
19865 itemp1 += 5;
19866 \newline
19867 \SpecialChar ~
19868 \SpecialChar ~
19869 \SpecialChar ~
19870 \SpecialChar ~
19871 itemp2 += 3;
19872 \newline
19873 }
19874 \layout Standard
19875
19876 The more expensive multiplication
19877 \begin_inset LatexCommand \index{Multiplication}
19878
19879 \end_inset
19880
19881  is changed to a less expensive addition.
19882 \layout Subsection
19883
19884 Loop Reversing
19885 \begin_inset LatexCommand \index{Loop reversing}
19886
19887 \end_inset
19888
19889
19890 \layout Standard
19891
19892 This optimization is done to reduce the overhead of checking loop boundaries
19893  for every iteration.
19894  Some simple loops can be reversed and implemented using a
19895 \begin_inset Quotes eld
19896 \end_inset
19897
19898 decrement and jump if not zero
19899 \begin_inset Quotes erd
19900 \end_inset
19901
19902  instruction.
19903  SDCC checks for the following criterion to determine if a loop is reversible
19904  (note: more sophisticated compilers use data-dependency analysis to make
19905  this determination, SDCC uses a more simple minded analysis).
19906 \layout Itemize
19907
19908 The 'for' loop is of the form
19909 \newline
19910
19911 \newline
19912
19913 \family typewriter
19914 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
19915  += 1])
19916 \newline
19917 \SpecialChar ~
19918 \SpecialChar ~
19919 \SpecialChar ~
19920 \SpecialChar ~
19921 <for body>
19922 \layout Itemize
19923
19924 The <for body> does not contain
19925 \begin_inset Quotes eld
19926 \end_inset
19927
19928 continue
19929 \begin_inset Quotes erd
19930 \end_inset
19931
19932  or 'break
19933 \begin_inset Quotes erd
19934 \end_inset
19935
19936 .
19937 \layout Itemize
19938
19939 All goto's are contained within the loop.
19940 \layout Itemize
19941
19942 No function calls within the loop.
19943 \layout Itemize
19944
19945 The loop control variable <sym> is not assigned any value within the loop
19946 \layout Itemize
19947
19948 The loop control variable does NOT participate in any arithmetic operation
19949  within the loop.
19950 \layout Itemize
19951
19952 There are NO switch statements in the loop.
19953 \layout Subsection
19954
19955 Algebraic Simplifications
19956 \layout Standard
19957
19958 SDCC does numerous algebraic simplifications, the following is a small sub-set
19959  of these optimizations.
19960 \layout Verse
19961
19962
19963 \family typewriter
19964 i = j + 0;\SpecialChar ~
19965 \SpecialChar ~
19966 \SpecialChar ~
19967 \SpecialChar ~
19968  /* changed to: */\SpecialChar ~
19969 \SpecialChar ~
19970 \SpecialChar ~
19971 \SpecialChar ~
19972  i = j;
19973 \newline
19974 i /= 2;\SpecialChar ~
19975 \SpecialChar ~
19976 \SpecialChar ~
19977 \SpecialChar ~
19978 \SpecialChar ~
19979 \SpecialChar ~
19980 \SpecialChar ~
19981  /* changed to: */\SpecialChar ~
19982 \SpecialChar ~
19983 \SpecialChar ~
19984 \SpecialChar ~
19985  i >>= 1;
19986 \newline
19987 i = j - j;\SpecialChar ~
19988 \SpecialChar ~
19989 \SpecialChar ~
19990 \SpecialChar ~
19991  /* changed to: */\SpecialChar ~
19992 \SpecialChar ~
19993 \SpecialChar ~
19994 \SpecialChar ~
19995  i = 0;
19996 \newline
19997 i = j / 1;\SpecialChar ~
19998 \SpecialChar ~
19999 \SpecialChar ~
20000 \SpecialChar ~
20001  /* changed to: */\SpecialChar ~
20002 \SpecialChar ~
20003 \SpecialChar ~
20004 \SpecialChar ~
20005  i = j;
20006 \layout Standard
20007
20008 Note the subexpressions
20009 \begin_inset LatexCommand \index{Subexpression}
20010
20011 \end_inset
20012
20013  given above are generally introduced by macro expansions or as a result
20014  of copy/constant propagation.
20015 \layout Subsection
20016
20017 'switch' Statements
20018 \begin_inset LatexCommand \label{sub:'switch'-Statements}
20019
20020 \end_inset
20021
20022
20023 \begin_inset LatexCommand \index{switch statement}
20024
20025 \end_inset
20026
20027
20028 \layout Standard
20029
20030 SDCC can optimize switch statements to jump tables
20031 \begin_inset LatexCommand \index{jump tables}
20032
20033 \end_inset
20034
20035 .
20036  It makes the decision based on an estimate of the generated code size.
20037  SDCC is quite liberal in the requirements for jump table generation:
20038 \layout Itemize
20039
20040 The labels need not be in order, and the starting number need not be one
20041  or zero, the case labels are in numerical sequence or not too many case
20042  labels are missing.
20043 \begin_deeper
20044 \layout Verse
20045
20046
20047 \family typewriter
20048 switch(i) {\SpecialChar ~
20049 \SpecialChar ~
20050 \SpecialChar ~
20051 \SpecialChar ~
20052 \SpecialChar ~
20053 \SpecialChar ~
20054 \SpecialChar ~
20055 \SpecialChar ~
20056 \SpecialChar ~
20057 \SpecialChar ~
20058 \SpecialChar ~
20059 \SpecialChar ~
20060 \SpecialChar ~
20061 \SpecialChar ~
20062 \SpecialChar ~
20063 \SpecialChar ~
20064 \SpecialChar ~
20065 \SpecialChar ~
20066 \SpecialChar ~
20067 \SpecialChar ~
20068 \SpecialChar ~
20069 \SpecialChar ~
20070 \SpecialChar ~
20071 \SpecialChar ~
20072 \SpecialChar ~
20073 \SpecialChar ~
20074 switch (i) {
20075 \newline
20076 \SpecialChar ~
20077 \SpecialChar ~
20078 \SpecialChar ~
20079 case 4: ...\SpecialChar ~
20080 \SpecialChar ~
20081 \SpecialChar ~
20082 \SpecialChar ~
20083 \SpecialChar ~
20084 \SpecialChar ~
20085 \SpecialChar ~
20086 \SpecialChar ~
20087 \SpecialChar ~
20088 \SpecialChar ~
20089 \SpecialChar ~
20090 \SpecialChar ~
20091 \SpecialChar ~
20092 \SpecialChar ~
20093 \SpecialChar ~
20094 \SpecialChar ~
20095 \SpecialChar ~
20096 \SpecialChar ~
20097 \SpecialChar ~
20098 \SpecialChar ~
20099 \SpecialChar ~
20100 \SpecialChar ~
20101 \SpecialChar ~
20102 \SpecialChar ~
20103 \SpecialChar ~
20104 \SpecialChar ~
20105 case 0: ...
20106
20107 \newline
20108 \SpecialChar ~
20109 \SpecialChar ~
20110 \SpecialChar ~
20111 case 5: ...\SpecialChar ~
20112 \SpecialChar ~
20113 \SpecialChar ~
20114 \SpecialChar ~
20115 \SpecialChar ~
20116 \SpecialChar ~
20117 \SpecialChar ~
20118 \SpecialChar ~
20119 \SpecialChar ~
20120 \SpecialChar ~
20121 \SpecialChar ~
20122 \SpecialChar ~
20123 \SpecialChar ~
20124 \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 case 1: ...
20138
20139 \newline
20140 \SpecialChar ~
20141 \SpecialChar ~
20142 \SpecialChar ~
20143 case 3: ...\SpecialChar ~
20144 \SpecialChar ~
20145 \SpecialChar ~
20146 \SpecialChar ~
20147 \SpecialChar ~
20148 \SpecialChar ~
20149 \SpecialChar ~
20150 \SpecialChar ~
20151 \SpecialChar ~
20152 \SpecialChar ~
20153 \SpecialChar ~
20154 \SpecialChar ~
20155 \SpecialChar ~
20156 \SpecialChar ~
20157 \SpecialChar ~
20158 \SpecialChar ~
20159 \SpecialChar ~
20160 \SpecialChar ~
20161 \SpecialChar ~
20162 \SpecialChar ~
20163 \SpecialChar ~
20164 \SpecialChar ~
20165 \SpecialChar ~
20166 \SpecialChar ~
20167 \SpecialChar ~
20168 \SpecialChar ~
20169
20170 \newline
20171 \SpecialChar ~
20172 \SpecialChar ~
20173 \SpecialChar ~
20174 case 6: ...\SpecialChar ~
20175 \SpecialChar ~
20176 \SpecialChar ~
20177 \SpecialChar ~
20178 \SpecialChar ~
20179 \SpecialChar ~
20180 \SpecialChar ~
20181 \SpecialChar ~
20182 \SpecialChar ~
20183 \SpecialChar ~
20184 \SpecialChar ~
20185 \SpecialChar ~
20186 \SpecialChar ~
20187 \SpecialChar ~
20188 \SpecialChar ~
20189 \SpecialChar ~
20190 \SpecialChar ~
20191 \SpecialChar ~
20192 \SpecialChar ~
20193 \SpecialChar ~
20194 \SpecialChar ~
20195 \SpecialChar ~
20196 \SpecialChar ~
20197 \SpecialChar ~
20198 \SpecialChar ~
20199 \SpecialChar ~
20200 case 3: ...
20201
20202 \newline
20203 \SpecialChar ~
20204 \SpecialChar ~
20205 \SpecialChar ~
20206 case 7: ...\SpecialChar ~
20207 \SpecialChar ~
20208 \SpecialChar ~
20209 \SpecialChar ~
20210 \SpecialChar ~
20211 \SpecialChar ~
20212 \SpecialChar ~
20213 \SpecialChar ~
20214 \SpecialChar ~
20215 \SpecialChar ~
20216 \SpecialChar ~
20217 \SpecialChar ~
20218 \SpecialChar ~
20219 \SpecialChar ~
20220 \SpecialChar ~
20221 \SpecialChar ~
20222 \SpecialChar ~
20223 \SpecialChar ~
20224 \SpecialChar ~
20225 \SpecialChar ~
20226 \SpecialChar ~
20227 \SpecialChar ~
20228 \SpecialChar ~
20229 \SpecialChar ~
20230 \SpecialChar ~
20231 \SpecialChar ~
20232 case 4: ...
20233
20234 \newline
20235 \SpecialChar ~
20236 \SpecialChar ~
20237 \SpecialChar ~
20238 case 8: ...\SpecialChar ~
20239 \SpecialChar ~
20240 \SpecialChar ~
20241 \SpecialChar ~
20242 \SpecialChar ~
20243 \SpecialChar ~
20244 \SpecialChar ~
20245 \SpecialChar ~
20246 \SpecialChar ~
20247 \SpecialChar ~
20248 \SpecialChar ~
20249 \SpecialChar ~
20250 \SpecialChar ~
20251 \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 case 5: ...
20265
20266 \newline
20267 \SpecialChar ~
20268 \SpecialChar ~
20269 \SpecialChar ~
20270 case 9: ...\SpecialChar ~
20271 \SpecialChar ~
20272 \SpecialChar ~
20273 \SpecialChar ~
20274 \SpecialChar ~
20275 \SpecialChar ~
20276 \SpecialChar ~
20277 \SpecialChar ~
20278 \SpecialChar ~
20279 \SpecialChar ~
20280 \SpecialChar ~
20281 \SpecialChar ~
20282 \SpecialChar ~
20283 \SpecialChar ~
20284 \SpecialChar ~
20285 \SpecialChar ~
20286 \SpecialChar ~
20287 \SpecialChar ~
20288 \SpecialChar ~
20289 \SpecialChar ~
20290 \SpecialChar ~
20291 \SpecialChar ~
20292 \SpecialChar ~
20293 \SpecialChar ~
20294 \SpecialChar ~
20295 \SpecialChar ~
20296 case 6: ...
20297
20298 \newline
20299 \SpecialChar ~
20300 \SpecialChar ~
20301 \SpecialChar ~
20302 case 10: ...\SpecialChar ~
20303 \SpecialChar ~
20304 \SpecialChar ~
20305 \SpecialChar ~
20306 \SpecialChar ~
20307 \SpecialChar ~
20308 \SpecialChar ~
20309 \SpecialChar ~
20310 \SpecialChar ~
20311 \SpecialChar ~
20312 \SpecialChar ~
20313 \SpecialChar ~
20314 \SpecialChar ~
20315 \SpecialChar ~
20316 \SpecialChar ~
20317 \SpecialChar ~
20318 \SpecialChar ~
20319 \SpecialChar ~
20320 \SpecialChar ~
20321 \SpecialChar ~
20322 \SpecialChar ~
20323 \SpecialChar ~
20324 \SpecialChar ~
20325 \SpecialChar ~
20326 \SpecialChar ~
20327 case 7: ...
20328
20329 \newline
20330 \SpecialChar ~
20331 \SpecialChar ~
20332 \SpecialChar ~
20333 case 11: ...\SpecialChar ~
20334 \SpecialChar ~
20335 \SpecialChar ~
20336 \SpecialChar ~
20337 \SpecialChar ~
20338 \SpecialChar ~
20339 \SpecialChar ~
20340 \SpecialChar ~
20341 \SpecialChar ~
20342 \SpecialChar ~
20343 \SpecialChar ~
20344 \SpecialChar ~
20345 \SpecialChar ~
20346 \SpecialChar ~
20347 \SpecialChar ~
20348 \SpecialChar ~
20349 \SpecialChar ~
20350 \SpecialChar ~
20351 \SpecialChar ~
20352 \SpecialChar ~
20353 \SpecialChar ~
20354 \SpecialChar ~
20355 \SpecialChar ~
20356 \SpecialChar ~
20357 \SpecialChar ~
20358 case 8: ...
20359
20360 \newline
20361 }\SpecialChar ~
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 }
20398 \layout Standard
20399
20400 Both the above switch statements will be implemented using a jump-table.
20401  The example to the right side is slightly more efficient as the check for
20402  the lower boundary of the jump-table is not needed.
20403 \end_deeper
20404 \layout Itemize
20405
20406 The number of case labels is not larger than supported by the target architectur
20407 e.
20408 \layout Itemize
20409
20410 If the case labels are not in numerical sequence ('gaps' between cases)
20411  SDCC checks whether a jump table with additionally inserted dummy cases
20412  is still attractive.
20413
20414 \layout Itemize
20415
20416 If the starting number is not zero and a check for the lower boundary of
20417  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
20418  ...
20419  .
20420 \layout Standard
20421
20422 Switch statements which have large gaps in the numeric sequence or those
20423  that have too many case labels can be split into more than one switch statement
20424  for efficient code generation, e.g.:
20425 \layout Verse
20426
20427
20428 \family typewriter
20429 switch (i) {
20430 \newline
20431 \SpecialChar ~
20432 \SpecialChar ~
20433 case 1: ...
20434
20435 \newline
20436 \SpecialChar ~
20437 \SpecialChar ~
20438 case 2: ...
20439
20440 \newline
20441 \SpecialChar ~
20442 \SpecialChar ~
20443 case 3: ...
20444
20445 \newline
20446 \SpecialChar ~
20447 \SpecialChar ~
20448 case 4: ...
20449
20450 \newline
20451 \SpecialChar ~
20452 \SpecialChar ~
20453 case 5: ...
20454
20455 \newline
20456 \SpecialChar ~
20457 \SpecialChar ~
20458 case 6: ...
20459
20460 \newline
20461 \SpecialChar ~
20462 \SpecialChar ~
20463 case 7: ...
20464
20465 \newline
20466 \SpecialChar ~
20467 \SpecialChar ~
20468 case 101: ...
20469
20470 \newline
20471 \SpecialChar ~
20472 \SpecialChar ~
20473 case 102: ...
20474
20475 \newline
20476 \SpecialChar ~
20477 \SpecialChar ~
20478 case 103: ...
20479
20480 \newline
20481 \SpecialChar ~
20482 \SpecialChar ~
20483 case 104: ...
20484
20485 \newline
20486 \SpecialChar ~
20487 \SpecialChar ~
20488 case 105: ...
20489
20490 \newline
20491 \SpecialChar ~
20492 \SpecialChar ~
20493 case 106: ...
20494
20495 \newline
20496 \SpecialChar ~
20497 \SpecialChar ~
20498 case 107: ...
20499
20500 \newline
20501 }
20502 \layout Standard
20503
20504 If the above switch statement is broken down into two switch statements
20505 \layout Verse
20506
20507
20508 \family typewriter
20509 switch (i) {
20510 \newline
20511 \SpecialChar ~
20512 \SpecialChar ~
20513 case 1: ...
20514
20515 \newline
20516 \SpecialChar ~
20517 \SpecialChar ~
20518 case 2: ...
20519
20520 \newline
20521 \SpecialChar ~
20522 \SpecialChar ~
20523 case 3: ...
20524
20525 \newline
20526 \SpecialChar ~
20527 \SpecialChar ~
20528 case 4: ...
20529
20530 \newline
20531 \SpecialChar ~
20532 \SpecialChar ~
20533 case 5: ...
20534
20535 \newline
20536 \SpecialChar ~
20537 \SpecialChar ~
20538 case 6: ...
20539
20540 \newline
20541 \SpecialChar ~
20542 \SpecialChar ~
20543 case 7: ...
20544
20545 \newline
20546 }
20547 \layout Standard
20548
20549 and
20550 \layout Verse
20551
20552
20553 \family typewriter
20554 switch (i) {
20555 \newline
20556 \SpecialChar ~
20557 \SpecialChar ~
20558 case 101: ...
20559
20560 \newline
20561 \SpecialChar ~
20562 \SpecialChar ~
20563 case 102: ...
20564
20565 \newline
20566 \SpecialChar ~
20567 \SpecialChar ~
20568 case 103: ...
20569
20570 \newline
20571 \SpecialChar ~
20572 \SpecialChar ~
20573 case 104: ...
20574
20575 \newline
20576 \SpecialChar ~
20577 \SpecialChar ~
20578 case 105: ...
20579
20580 \newline
20581 \SpecialChar ~
20582 \SpecialChar ~
20583 case 106: ...
20584
20585 \newline
20586 \SpecialChar ~
20587 \SpecialChar ~
20588 case 107: ...
20589
20590 \newline
20591 }
20592 \layout Standard
20593
20594 then both the switch statements will be implemented using jump-tables whereas
20595  the unmodified switch statement will not be.
20596 \layout Comment
20597
20598 There might be reasons which SDCC cannot know about to either favour or
20599  not favour jump tables.
20600  If the target system has to be as quick for the last switch case as for
20601  the first (pro jump table), or if the switch argument is known to be zero
20602  in the majority of the cases (contra jump table).
20603 \layout Standard
20604
20605 The pragma nojtbound
20606 \begin_inset LatexCommand \index{\#pragma nojtbound}
20607
20608 \end_inset
20609
20610  can be used to turn off checking the
20611 \emph on
20612 j
20613 \emph default
20614 ump
20615 \emph on
20616 t
20617 \emph default
20618 able
20619 \emph on
20620 bound
20621 \emph default
20622 aries.
20623  It has no effect if a default label is supplied.
20624  Use of this pragma is dangerous: if the switch argument is not matched
20625  by a case statement the processor will happily jump into Nirvana.
20626 \layout Subsection
20627
20628 Bit-shifting Operations
20629 \begin_inset LatexCommand \index{Bit shifting}
20630
20631 \end_inset
20632
20633 .
20634 \layout Standard
20635
20636 Bit shifting is one of the most frequently used operation in embedded programmin
20637 g.
20638  SDCC tries to implement bit-shift operations in the most efficient way
20639  possible, e.g.:
20640 \layout Verse
20641
20642
20643 \family typewriter
20644 unsigned char i;
20645 \newline
20646 ...
20647
20648 \newline
20649 i >>= 4;
20650 \newline
20651 ...
20652 \layout Standard
20653
20654 generates the following code:
20655 \layout Verse
20656
20657
20658 \family typewriter
20659 mov\SpecialChar ~
20660  a,_i
20661 \newline
20662 swap a
20663 \newline
20664 anl\SpecialChar ~
20665  a,#0x0f
20666 \newline
20667 mov\SpecialChar ~
20668  _i,a
20669 \layout Standard
20670
20671 In general SDCC will never setup a loop if the shift count is known.
20672  Another example:
20673 \layout Verse
20674
20675
20676 \family typewriter
20677 unsigned int i;
20678 \newline
20679 ...
20680
20681 \newline
20682 i >>= 9;
20683 \newline
20684 ...
20685 \layout Standard
20686
20687 will generate:
20688 \layout Verse
20689
20690
20691 \family typewriter
20692 mov\SpecialChar ~
20693 \SpecialChar ~
20694 a,(_i + 1)
20695 \newline
20696 mov\SpecialChar ~
20697 \SpecialChar ~
20698 (_i + 1),#0x00
20699 \newline
20700 clr\SpecialChar ~
20701 \SpecialChar ~
20702 c
20703 \newline
20704 rrc\SpecialChar ~
20705 \SpecialChar ~
20706 a
20707 \newline
20708 mov\SpecialChar ~
20709 \SpecialChar ~
20710 _i,a
20711 \layout Subsection
20712
20713 Bit-rotation
20714 \begin_inset LatexCommand \index{Bit rotation}
20715
20716 \end_inset
20717
20718
20719 \layout Standard
20720
20721 A special case of the bit-shift operation is bit rotation
20722 \begin_inset LatexCommand \index{rotating bits}
20723
20724 \end_inset
20725
20726 , SDCC recognizes the following expression to be a left bit-rotation:
20727 \layout Verse
20728
20729
20730 \family typewriter
20731 \series bold
20732 unsigned
20733 \series default
20734 \SpecialChar ~
20735 \SpecialChar ~
20736 char i;\SpecialChar ~
20737 \SpecialChar ~
20738 \SpecialChar ~
20739 \SpecialChar ~
20740 \SpecialChar ~
20741 \SpecialChar ~
20742 \SpecialChar ~
20743 \SpecialChar ~
20744 \SpecialChar ~
20745 \SpecialChar ~
20746 \SpecialChar ~
20747 /* unsigned is needed for rotation */
20748 \newline
20749 ...
20750
20751 \newline
20752 i = ((i << 1) | (i >> 7));
20753 \family default
20754
20755 \newline
20756
20757 \family typewriter
20758 ...
20759 \layout Standard
20760
20761 will generate the following code:
20762 \layout Verse
20763
20764
20765 \family typewriter
20766 mov\SpecialChar ~
20767 \SpecialChar ~
20768 a,_i
20769 \newline
20770 rl\SpecialChar ~
20771 \SpecialChar ~
20772 \SpecialChar ~
20773 a
20774 \newline
20775 mov\SpecialChar ~
20776 \SpecialChar ~
20777 _i,a
20778 \layout Standard
20779
20780 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
20781 ns of this case will also be recognized as bit-rotation, i.e.:
20782 \layout Verse
20783
20784
20785 \family typewriter
20786 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
20787 \layout Subsection
20788
20789 Nibble and Byte Swapping
20790 \layout Standard
20791
20792 Other special cases of the bit-shift operations are nibble or byte swapping
20793 \begin_inset LatexCommand \index{swapping nibbles/bytes}
20794
20795 \end_inset
20796
20797 , SDCC recognizes the following expressions:
20798 \layout Verse
20799
20800
20801 \family typewriter
20802 \series bold
20803 unsigned
20804 \series default
20805 \SpecialChar ~
20806 \SpecialChar ~
20807 char i;
20808 \newline
20809
20810 \series bold
20811 unsigned
20812 \series default
20813 \SpecialChar ~
20814 \SpecialChar ~
20815 int j;
20816 \newline
20817 ...
20818
20819 \newline
20820 i = ((i << 4) | (i >> 4));
20821 \family default
20822
20823 \newline
20824
20825 \family typewriter
20826 j = ((j << 8) | (j >> 8));
20827 \layout Standard
20828
20829 and generates a swap instruction for the nibble swapping
20830 \begin_inset LatexCommand \index{Nibble swapping}
20831
20832 \end_inset
20833
20834  or move instructions for the byte swapping
20835 \begin_inset LatexCommand \index{Byte swapping}
20836
20837 \end_inset
20838
20839 .
20840  The
20841 \begin_inset Quotes sld
20842 \end_inset
20843
20844 j
20845 \begin_inset Quotes srd
20846 \end_inset
20847
20848  example can be used to convert from little to big-endian or vice versa.
20849  If you want to change the endianness of a
20850 \emph on
20851 signed
20852 \emph default
20853  integer you have to cast to
20854 \family typewriter
20855 (unsigned int)
20856 \family default
20857  first.
20858 \layout Standard
20859
20860 Note that SDCC stores numbers in little-endian
20861 \begin_inset Foot
20862 collapsed false
20863
20864 \layout Standard
20865
20866 Usually 8-bit processors don't care much about endianness.
20867  This is not the case for the standard 8051 which only has an instruction
20868  to increment its
20869 \emph on
20870 dptr
20871 \emph default
20872
20873 \begin_inset LatexCommand \index{DPTR}
20874
20875 \end_inset
20876
20877 -datapointer
20878 \emph on
20879
20880 \emph default
20881 so little-endian is the more efficient byte order.
20882 \end_inset
20883
20884
20885 \begin_inset LatexCommand \index{little-endian}
20886
20887 \end_inset
20888
20889
20890 \begin_inset LatexCommand \index{Endianness}
20891
20892 \end_inset
20893
20894  format (i.e.
20895  lowest order first).
20896 \layout Subsection
20897
20898 Highest Order Bit
20899 \begin_inset LatexCommand \index{Highest Order Bit}
20900
20901 \end_inset
20902
20903
20904 \layout Standard
20905
20906 It is frequently required to obtain the highest order bit of an integral
20907  type (long, int, short or char types).
20908  SDCC recognizes the following expression to yield the highest order bit
20909  and generates optimized code for it, e.g.:
20910 \layout Verse
20911
20912
20913 \family typewriter
20914 unsigned int gint;
20915 \newline
20916
20917 \newline
20918 foo () {
20919 \newline
20920 \SpecialChar ~
20921 \SpecialChar ~
20922 unsigned char hob;
20923 \newline
20924 \SpecialChar ~
20925 \SpecialChar ~
20926 ...
20927
20928 \newline
20929 \SpecialChar ~
20930 \SpecialChar ~
20931 hob = (gint >> 15) & 1;
20932 \newline
20933 \SpecialChar ~
20934 \SpecialChar ~
20935 ..
20936
20937 \newline
20938 }
20939 \layout Standard
20940
20941 will generate the following code:
20942 \layout Verse
20943
20944
20945 \family typewriter
20946 \SpecialChar ~
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  61 ;\SpecialChar ~
20972  hob.c 7
20973 \newline
20974 000A E5*01\SpecialChar ~
20975 \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  62\SpecialChar ~
20990 \SpecialChar ~
20991 \SpecialChar ~
20992 \SpecialChar ~
20993 \SpecialChar ~
20994 \SpecialChar ~
20995 \SpecialChar ~
20996 \SpecialChar ~
20997  mov\SpecialChar ~
20998 \SpecialChar ~
20999  a,(_gint + 1)
21000 \newline
21001 000C 23\SpecialChar ~
21002 \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  63\SpecialChar ~
21020 \SpecialChar ~
21021 \SpecialChar ~
21022 \SpecialChar ~
21023 \SpecialChar ~
21024 \SpecialChar ~
21025 \SpecialChar ~
21026 \SpecialChar ~
21027  rl\SpecialChar ~
21028 \SpecialChar ~
21029 \SpecialChar ~
21030  a
21031 \newline
21032 000D 54 01\SpecialChar ~
21033 \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  64\SpecialChar ~
21048 \SpecialChar ~
21049 \SpecialChar ~
21050 \SpecialChar ~
21051 \SpecialChar ~
21052 \SpecialChar ~
21053 \SpecialChar ~
21054 \SpecialChar ~
21055  anl\SpecialChar ~
21056 \SpecialChar ~
21057  a,#0x01
21058 \newline
21059 000F F5*02\SpecialChar ~
21060 \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  65\SpecialChar ~
21075 \SpecialChar ~
21076 \SpecialChar ~
21077 \SpecialChar ~
21078 \SpecialChar ~
21079 \SpecialChar ~
21080 \SpecialChar ~
21081 \SpecialChar ~
21082  mov\SpecialChar ~
21083 \SpecialChar ~
21084  _foo_hob_1_1,a
21085 \layout Standard
21086
21087 Variations of this case however will
21088 \emph on
21089 not
21090 \emph default
21091  be recognized.
21092  It is a standard C expression, so I heartily recommend this be the only
21093  way to get the highest order bit, (it is portable).
21094  Of course it will be recognized even if it is embedded in other expressions,
21095  e.g.:
21096 \layout Verse
21097
21098
21099 \family typewriter
21100 xyz = gint + ((gint >> 15) & 1);
21101 \layout Standard
21102
21103 will still be recognized.
21104 \layout Subsection
21105
21106 Peephole Optimizer
21107 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
21108
21109 \end_inset
21110
21111
21112 \begin_inset LatexCommand \index{Peephole optimizer}
21113
21114 \end_inset
21115
21116
21117 \layout Standard
21118
21119 The compiler uses a rule based, pattern matching and re-writing mechanism
21120  for peep-hole optimization.
21121  It is inspired by
21122 \emph on
21123 copt
21124 \emph default
21125  a peep-hole optimizer by Christopher W.
21126  Fraser (cwfraser@microsoft.com).
21127  A default set of rules are compiled into the compiler, additional rules
21128  may be added with the
21129 \emph on
21130 -
21131 \begin_inset ERT
21132 status Collapsed
21133
21134 \layout Standard
21135
21136 \backslash
21137 /
21138 \end_inset
21139
21140 -peep-file
21141 \begin_inset LatexCommand \index{-\/-peep-file}
21142
21143 \end_inset
21144
21145  <filename>
21146 \emph default
21147  option.
21148  The rule language is best illustrated with examples.
21149 \layout Verse
21150
21151
21152 \family typewriter
21153 replace {
21154 \newline
21155 \SpecialChar ~
21156 \SpecialChar ~
21157 mov %1,a
21158 \newline
21159 \SpecialChar ~
21160 \SpecialChar ~
21161 mov a,%1
21162 \newline
21163 } by {
21164 \newline
21165 \SpecialChar ~
21166 \SpecialChar ~
21167 mov %1,a
21168 \newline
21169 }
21170 \layout Standard
21171
21172 The above rule will change the following assembly
21173 \begin_inset LatexCommand \index{Assembler routines}
21174
21175 \end_inset
21176
21177  sequence:
21178 \layout Verse
21179
21180
21181 \family typewriter
21182 mov r1,a
21183 \newline
21184 mov a,r1
21185 \layout Standard
21186
21187 to
21188 \layout Verse
21189
21190
21191 \family typewriter
21192 mov r1,a
21193 \layout Standard
21194
21195 Note: All occurrences of a
21196 \emph on
21197 %n
21198 \emph default
21199  (pattern variable) must denote the same string.
21200  With the above rule, the assembly sequence:
21201 \layout Verse
21202
21203
21204 \family typewriter
21205 mov r1,a
21206 \newline
21207 mov a,r2
21208 \layout Standard
21209
21210 will remain unmodified.
21211 \newline
21212
21213 \newline
21214 Other special case optimizations may be added by the user (via
21215 \emph on
21216 -
21217 \begin_inset ERT
21218 status Collapsed
21219
21220 \layout Standard
21221
21222 \backslash
21223 /
21224 \end_inset
21225
21226 -peep-file option
21227 \emph default
21228 ).
21229  E.g.
21230  some variants of the 8051 MCU
21231 \begin_inset LatexCommand \index{MCS51 variants}
21232
21233 \end_inset
21234
21235  allow only
21236 \family typewriter
21237 ajmp
21238 \family default
21239  and
21240 \family typewriter
21241 acall
21242 \family default
21243 .
21244  The following two rules will change all
21245 \family typewriter
21246 ljmp
21247 \family default
21248  and
21249 \family typewriter
21250 lcall
21251 \family default
21252  to
21253 \family typewriter
21254 ajmp
21255 \family default
21256  and
21257 \family typewriter
21258 acall
21259 \layout Verse
21260
21261
21262 \family typewriter
21263 replace { lcall %1 } by { acall %1 }
21264 \newline
21265 replace { ljmp %1 } by { ajmp %1 }
21266 \layout Standard
21267
21268 The
21269 \emph on
21270 inline-assembler code
21271 \emph default
21272  is also passed through the peep hole optimizer, thus the peephole optimizer
21273  can also be used as an assembly level macro expander.
21274  The rules themselves are MCU dependent whereas the rule language infra-structur
21275 e is MCU independent.
21276  Peephole optimization rules for other MCU can be easily programmed using
21277  the rule language.
21278 \newline
21279
21280 \newline
21281 The syntax for a rule is as follows:
21282 \layout Verse
21283
21284
21285 \family typewriter
21286 rule := replace [ restart ] '{' <assembly sequence> '
21287 \backslash
21288 n'
21289 \newline
21290 \SpecialChar ~
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  '}' by '{' '
21305 \backslash
21306 n'
21307 \newline
21308 \SpecialChar ~
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  <assembly sequence> '
21325 \backslash
21326 n'
21327 \newline
21328 \SpecialChar ~
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  '}' [if <functionName> ] '
21343 \backslash
21344 n'
21345 \layout Standard
21346
21347 <assembly sequence> := assembly instruction (each instruction including
21348  labels must be on a separate line).
21349 \newline
21350
21351 \newline
21352 The optimizer will apply to the rules one by one from the top in the sequence
21353  of their appearance, it will terminate when all rules are exhausted.
21354  If the 'restart' option is specified, then the optimizer will start matching
21355  the rules again from the top, this option for a rule is expensive (performance)
21356 , it is intended to be used in situations where a transformation will trigger
21357  the same rule again.
21358  An example of this (not a good one, it has side effects) is the following
21359  rule:
21360 \layout Verse
21361
21362
21363 \family typewriter
21364 replace restart {
21365 \newline
21366 \SpecialChar ~
21367 \SpecialChar ~
21368 pop %1
21369 \newline
21370 \SpecialChar ~
21371 \SpecialChar ~
21372 push %1 } by {
21373 \newline
21374 \SpecialChar ~
21375 \SpecialChar ~
21376 ; nop
21377 \newline
21378 }
21379 \layout Standard
21380
21381 Note that the replace pattern cannot be a blank, but can be a comment line.
21382  Without the 'restart' option only the innermost 'pop' 'push' pair would
21383  be eliminated, i.e.:
21384 \layout Verse
21385
21386
21387 \family typewriter
21388 pop ar1
21389 \newline
21390 pop ar2
21391 \newline
21392 push ar2
21393 \newline
21394 push ar1
21395 \layout Standard
21396
21397 would result in:
21398 \layout Verse
21399
21400
21401 \family typewriter
21402 pop ar1
21403 \newline
21404 ; nop
21405 \newline
21406 push ar1
21407 \layout Standard
21408
21409
21410 \emph on
21411 with
21412 \emph default
21413  the restart option the rule will be applied again to the resulting code
21414  and then all the pop-push pairs will be eliminated to yield:
21415 \layout Verse
21416
21417
21418 \family typewriter
21419 ; nop
21420 \newline
21421 ; nop
21422 \layout Standard
21423
21424 A conditional function can be attached to a rule.
21425  Attaching rules are somewhat more involved, let me illustrate this with
21426  an example.
21427 \layout Verse
21428
21429
21430 \family typewriter
21431 replace {
21432 \newline
21433 \SpecialChar ~
21434  \SpecialChar ~
21435  \SpecialChar ~
21436 ljmp %5
21437 \newline
21438 %2:
21439 \newline
21440 } by {
21441 \newline
21442 \SpecialChar ~
21443  \SpecialChar ~
21444  \SpecialChar ~
21445 sjmp %5
21446 \newline
21447 %2:
21448 \newline
21449 } if labelInRange
21450 \layout Standard
21451
21452 The optimizer does a look-up of a function name table defined in function
21453
21454 \emph on
21455 callFuncByName
21456 \emph default
21457  in the source file SDCCpeeph.c, with the name
21458 \emph on
21459 labelInRange
21460 \emph default
21461 .
21462  If it finds a corresponding entry the function is called.
21463  Note there can be no parameters specified for these functions, in this
21464  case the use of
21465 \emph on
21466 %5
21467 \emph default
21468  is crucial, since the function
21469 \emph on
21470 labelInRange
21471 \emph default
21472  expects to find the label in that particular variable (the hash table containin
21473 g the variable bindings is passed as a parameter).
21474  If you want to code more such functions, take a close look at the function
21475  labelInRange and the calling mechanism in source file SDCCpeeph.c.
21476  Currently implemented are
21477 \emph on
21478 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
21479  24bitMode, portIsDS390, 24bitModeAndPortDS390
21480 \emph default
21481 and
21482 \emph on
21483  notVolatile
21484 \emph default
21485 .
21486 \layout Standard
21487
21488 I know this whole thing is a little kludgey, but maybe some day we will
21489  have some better means.
21490  If you are looking at this file, you will see the default rules that are
21491  compiled into the compiler, you can add your own rules in the default set
21492  there if you get tired of specifying the -
21493 \begin_inset ERT
21494 status Collapsed
21495
21496 \layout Standard
21497
21498 \backslash
21499 /
21500 \end_inset
21501
21502 -peep-file option.
21503 \layout Section
21504
21505 ANSI-Compliance
21506 \begin_inset LatexCommand \index{ANSI-compliance}
21507
21508 \end_inset
21509
21510
21511 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
21512
21513 \end_inset
21514
21515
21516 \layout Standard
21517
21518 Deviations from the compliance:
21519 \layout Itemize
21520
21521 functions are not always reentrant
21522 \begin_inset LatexCommand \index{reentrant}
21523
21524 \end_inset
21525
21526 .
21527 \layout Itemize
21528
21529 structures cannot be assigned values directly, cannot be passed as function
21530  parameters or assigned to each other and cannot be a return value from
21531  a function, e.g.:
21532 \begin_deeper
21533 \layout Verse
21534
21535
21536 \family typewriter
21537 struct s { ...
21538  };
21539 \newline
21540 struct s s1, s2;
21541 \newline
21542 foo()
21543 \newline
21544 {
21545 \newline
21546 \SpecialChar ~
21547 \SpecialChar ~
21548 \SpecialChar ~
21549 \SpecialChar ~
21550 ...
21551
21552 \newline
21553 \SpecialChar ~
21554 \SpecialChar ~
21555 \SpecialChar ~
21556 \SpecialChar ~
21557 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
21558 \newline
21559 \SpecialChar ~
21560 \SpecialChar ~
21561 \SpecialChar ~
21562 \SpecialChar ~
21563 ...
21564
21565 \newline
21566 }
21567 \newline
21568 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
21569  */
21570 \newline
21571 {
21572 \newline
21573 \SpecialChar ~
21574 \SpecialChar ~
21575 \SpecialChar ~
21576 \SpecialChar ~
21577 struct s rets;
21578 \newline
21579 \SpecialChar ~
21580 \SpecialChar ~
21581 \SpecialChar ~
21582 \SpecialChar ~
21583 ...
21584
21585 \newline
21586 \SpecialChar ~
21587 \SpecialChar ~
21588 \SpecialChar ~
21589 \SpecialChar ~
21590 return rets;/* is invalid in SDCC although allowed in ANSI */
21591 \newline
21592 }
21593 \end_deeper
21594 \layout Itemize
21595
21596 'long long
21597 \begin_inset LatexCommand \index{long long (not supported)}
21598
21599 \end_inset
21600
21601 ' (64 bit integers
21602 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
21603
21604 \end_inset
21605
21606 ) not supported.
21607 \layout Itemize
21608
21609 'double
21610 \begin_inset LatexCommand \index{double (not supported)}
21611
21612 \end_inset
21613
21614 ' precision floating point
21615 \begin_inset LatexCommand \index{Floating point support}
21616
21617 \end_inset
21618
21619 not supported.
21620 \layout Itemize
21621
21622 No support for setjmp
21623 \begin_inset LatexCommand \index{setjmp (not supported)}
21624
21625 \end_inset
21626
21627  and longjmp
21628 \begin_inset LatexCommand \index{longjmp (not supported)}
21629
21630 \end_inset
21631
21632  (for now).
21633 \layout Itemize
21634
21635 Old K&R style
21636 \begin_inset LatexCommand \index{K\&R style}
21637
21638 \end_inset
21639
21640  function declarations are NOT allowed.
21641 \begin_deeper
21642 \layout Verse
21643
21644
21645 \family typewriter
21646 foo(i,j) /* this old style of function declarations */
21647 \newline
21648 int i,j; /* are valid in ANSI but not valid in SDCC */
21649 \newline
21650 {
21651 \newline
21652 \SpecialChar ~
21653 \SpecialChar ~
21654 \SpecialChar ~
21655 \SpecialChar ~
21656 ...
21657
21658 \newline
21659 }
21660 \end_deeper
21661 \layout Section
21662
21663 Cyclomatic Complexity
21664 \begin_inset LatexCommand \index{Cyclomatic complexity}
21665
21666 \end_inset
21667
21668
21669 \layout Standard
21670
21671 Cyclomatic complexity of a function is defined as the number of independent
21672  paths the program can take during execution of the function.
21673  This is an important number since it defines the number test cases you
21674  have to generate to validate the function.
21675  The accepted industry standard for complexity number is 10, if the cyclomatic
21676  complexity reported by SDCC exceeds 10 you should think about simplification
21677  of the function logic.
21678  Note that the complexity level is not related to the number of lines of
21679  code in a function.
21680  Large functions can have low complexity, and small functions can have large
21681  complexity levels.
21682
21683 \newline
21684
21685 \newline
21686 SDCC uses the following formula to compute the complexity:
21687 \newline
21688
21689 \layout Standard
21690
21691 complexity = (number of edges in control flow graph) - (number of nodes
21692  in control flow graph) + 2;
21693 \newline
21694
21695 \newline
21696 Having said that the industry standard is 10, you should be aware that in
21697  some cases it be may unavoidable to have a complexity level of less than
21698  10.
21699  For example if you have switch statement with more than 10 case labels,
21700  each case label adds one to the complexity level.
21701  The complexity level is by no means an absolute measure of the algorithmic
21702  complexity of the function, it does however provide a good starting point
21703  for which functions you might look at for further optimization.
21704 \layout Section
21705
21706 Retargetting for other Processors
21707 \layout Standard
21708
21709 The issues for retargetting the compiler are far too numerous to be covered
21710  by this document.
21711  What follows is a brief description of each of the seven phases of the
21712  compiler and its MCU dependency.
21713 \layout Itemize
21714
21715 Parsing the source and building the annotated parse tree.
21716  This phase is largely MCU independent (except for the language extensions).
21717  Syntax & semantic checks are also done in this phase, along with some initial
21718  optimizations like back patching labels and the pattern matching optimizations
21719  like bit-rotation etc.
21720 \layout Itemize
21721
21722 The second phase involves generating an intermediate code which can be easy
21723  manipulated during the later phases.
21724  This phase is entirely MCU independent.
21725  The intermediate code generation assumes the target machine has unlimited
21726  number of registers, and designates them with the name iTemp.
21727  The compiler can be made to dump a human readable form of the code generated
21728  by using the -
21729 \begin_inset ERT
21730 status Collapsed
21731
21732 \layout Standard
21733
21734 \backslash
21735 /
21736 \end_inset
21737
21738 -dumpraw option.
21739 \layout Itemize
21740
21741 This phase does the bulk of the standard optimizations and is also MCU independe
21742 nt.
21743  This phase can be broken down into several sub-phases:
21744 \newline
21745
21746 \newline
21747 Break down intermediate code (iCode) into basic blocks.
21748 \newline
21749 Do control flow & data flow analysis on the basic blocks.
21750 \newline
21751 Do local common subexpression elimination, then global subexpression elimination
21752 \newline
21753 Dead code elimination
21754 \newline
21755 Loop optimizations
21756 \newline
21757 If loop optimizations caused any changes then do 'global subexpression eliminati
21758 on' and 'dead code elimination' again.
21759 \layout Itemize
21760
21761 This phase determines the live-ranges; by live range I mean those iTemp
21762  variables defined by the compiler that still survive after all the optimization
21763 s.
21764  Live range analysis
21765 \begin_inset LatexCommand \index{Live range analysis}
21766
21767 \end_inset
21768
21769  is essential for register allocation, since these computation determines
21770  which of these iTemps will be assigned to registers, and for how long.
21771 \layout Itemize
21772
21773 Phase five is register allocation.
21774  There are two parts to this process.
21775 \newline
21776
21777 \newline
21778 The first part I call 'register packing' (for lack of a better term).
21779  In this case several MCU specific expression folding is done to reduce
21780  register pressure.
21781 \newline
21782
21783 \newline
21784 The second part is more MCU independent and deals with allocating registers
21785  to the remaining live ranges.
21786  A lot of MCU specific code does creep into this phase because of the limited
21787  number of index registers available in the 8051.
21788 \layout Itemize
21789
21790 The Code generation phase is (unhappily), entirely MCU dependent and very
21791  little (if any at all) of this code can be reused for other MCU.
21792  However the scheme for allocating a homogenized assembler operand for each
21793  iCode operand may be reused.
21794 \layout Itemize
21795
21796 As mentioned in the optimization section the peep-hole optimizer is rule
21797  based system, which can reprogrammed for other MCUs.
21798 \layout Chapter
21799
21800 Compiler internals
21801 \begin_inset LatexCommand \index{Compiler internals}
21802
21803 \end_inset
21804
21805
21806 \layout Section
21807
21808 The anatomy of the compiler
21809 \begin_inset LatexCommand \label{sub:The-anatomy-of}
21810
21811 \end_inset
21812
21813
21814 \layout Standard
21815
21816
21817 \shape italic
21818 This is an excerpt from an article published in Circuit Cellar Magazine
21819  in august 2000.
21820  It's a little outdated (the compiler is much more efficient now and user/develo
21821 per friendly), but pretty well exposes the guts of it all.
21822 \shape default
21823
21824 \newline
21825
21826 \newline
21827 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
21828  It is fairly easy to retarget for other 8-bit MCU.
21829  Here we take a look at some of the internals of the compiler.
21830
21831 \layout Paragraph*
21832
21833 Parsing
21834 \begin_inset LatexCommand \index{Parsing}
21835
21836 \end_inset
21837
21838
21839 \layout Standard
21840
21841 Parsing the input source file and creating an AST (Annotated Syntax Tree
21842 \begin_inset LatexCommand \index{Annotated syntax tree}
21843
21844 \end_inset
21845
21846 ).
21847  This phase also involves propagating types (annotating each node of the
21848  parse tree with type information) and semantic analysis.
21849  There are some MCU specific parsing rules.
21850  For example the storage classes, the extended storage classes are MCU specific
21851  while there may be a xdata storage class for 8051 there is no such storage
21852  class for z80 or Atmel AVR.
21853  SDCC allows MCU specific storage class extensions, i.e.
21854  xdata will be treated as a storage class specifier when parsing 8051 C
21855  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
21856  C code.
21857 \layout Paragraph*
21858
21859 Generating iCode
21860 \begin_inset LatexCommand \index{iCode}
21861
21862 \end_inset
21863
21864
21865 \layout Standard
21866
21867 Intermediate code generation.
21868  In this phase the AST is broken down into three-operand form (iCode).
21869  These three operand forms are represented as doubly linked lists.
21870  ICode is the term given to the intermediate form generated by the compiler.
21871  ICode example section shows some examples of iCode generated for some simple
21872  C source functions.
21873 \layout Paragraph*
21874
21875 Optimizations
21876 \begin_inset LatexCommand \index{Optimizations}
21877
21878 \end_inset
21879
21880 .
21881 \layout Standard
21882
21883 Bulk of the target independent optimizations is performed in this phase.
21884  The optimizations include constant propagation, common sub-expression eliminati
21885 on, loop invariant code movement, strength reduction of loop induction variables
21886  and dead-code elimination.
21887 \layout Paragraph*
21888
21889 Live range analysis
21890 \begin_inset LatexCommand \index{Live range analysis}
21891
21892 \end_inset
21893
21894
21895 \layout Standard
21896
21897 During intermediate code generation phase, the compiler assumes the target
21898  machine has infinite number of registers and generates a lot of temporary
21899  variables.
21900  The live range computation determines the lifetime of each of these compiler-ge
21901 nerated temporaries.
21902  A picture speaks a thousand words.
21903  ICode example sections show the live range annotations for each of the
21904  operand.
21905  It is important to note here, each iCode is assigned a number in the order
21906  of its execution in the function.
21907  The live ranges are computed in terms of these numbers.
21908  The from number is the number of the iCode which first defines the operand
21909  and the to number signifies the iCode which uses this operand last.
21910 \layout Paragraph*
21911
21912 Register Allocation
21913 \begin_inset LatexCommand \index{Register allocation}
21914
21915 \end_inset
21916
21917
21918 \layout Standard
21919
21920 The register allocation determines the type and number of registers needed
21921  by each operand.
21922  In most MCUs only a few registers can be used for indirect addressing.
21923  In case of 8051 for example the registers R0 & R1 can be used to indirectly
21924  address the internal ram and DPTR to indirectly address the external ram.
21925  The compiler will try to allocate the appropriate register to pointer variables
21926  if it can.
21927  ICode example section shows the operands annotated with the registers assigned
21928  to them.
21929  The compiler will try to keep operands in registers as much as possible;
21930  there are several schemes the compiler uses to do achieve this.
21931  When the compiler runs out of registers the compiler will check to see
21932  if there are any live operands which is not used or defined in the current
21933  basic block being processed, if there are any found then it will push that
21934  operand and use the registers in this block, the operand will then be popped
21935  at the end of the basic block.
21936
21937 \layout Standard
21938
21939 There are other MCU specific considerations in this phase.
21940  Some MCUs have an accumulator; very short-lived operands could be assigned
21941  to the accumulator instead of a general-purpose register.
21942 \layout Paragraph*
21943
21944 Code generation
21945 \layout Standard
21946
21947 Figure II gives a table of iCode operations supported by the compiler.
21948  The code generation involves translating these operations into corresponding
21949  assembly code for the processor.
21950  This sounds overly simple but that is the essence of code generation.
21951  Some of the iCode operations are generated on a MCU specific manner for
21952  example, the z80 port does not use registers to pass parameters so the
21953  SEND and RECV iCode operations will not be generated, and it also does
21954  not support JUMPTABLES.
21955
21956 \newline
21957
21958 \series bold
21959 \shape italic
21960 \color red
21961 <Where is Figure II?>
21962 \layout Comment
21963
21964 In the original article Figure II was announced to be downloadable on
21965 \shape italic
21966 Circuit Cellar
21967 \shape default
21968 's web site.
21969  Unfortunately it never seemed to have shown up there, so: where is Figure
21970  II?
21971 \layout Paragraph*
21972
21973 ICode Example
21974 \begin_inset LatexCommand \index{iCode}
21975
21976 \end_inset
21977
21978
21979 \layout Standard
21980
21981 This section shows some details of iCode.
21982  The example C code does not do anything useful; it is used as an example
21983  to illustrate the intermediate code generated by the compiler.
21984 \layout Verse
21985
21986
21987 \family typewriter
21988 1.\SpecialChar ~
21989 xdata int * p;
21990 \newline
21991 2.\SpecialChar ~
21992 int gint;
21993 \newline
21994 3.\SpecialChar ~
21995 /* This function does nothing useful.
21996  It is used
21997 \newline
21998 4.\SpecialChar ~
21999 \SpecialChar ~
22000 \SpecialChar ~
22001 \SpecialChar ~
22002 for the purpose of explaining iCode */
22003 \newline
22004 5.\SpecialChar ~
22005 short function (data int *x)
22006 \newline
22007 6.\SpecialChar ~
22008 {
22009 \newline
22010 7.\SpecialChar ~
22011 \SpecialChar ~
22012 \SpecialChar ~
22013 short i=10; \SpecialChar ~
22014 \SpecialChar ~
22015 /* dead initialization eliminated */
22016 \newline
22017 8.\SpecialChar ~
22018 \SpecialChar ~
22019 \SpecialChar ~
22020 short sum=10; /* dead initialization eliminated */
22021 \newline
22022 9.\SpecialChar ~
22023 \SpecialChar ~
22024 \SpecialChar ~
22025 short mul;
22026 \newline
22027 10.\SpecialChar ~
22028 \SpecialChar ~
22029 int j ;
22030 \newline
22031 11.\SpecialChar ~
22032 \SpecialChar ~
22033 while (*x) *x++ = *p++;
22034 \newline
22035 12.\SpecialChar ~
22036 \SpecialChar ~
22037 \SpecialChar ~
22038 \SpecialChar ~
22039 sum = 0 ;
22040 \newline
22041 13.\SpecialChar ~
22042 \SpecialChar ~
22043 mul = 0;
22044 \newline
22045 14.\SpecialChar ~
22046 \SpecialChar ~
22047 /* compiler detects i,j to be induction variables */
22048 \newline
22049 15.\SpecialChar ~
22050 \SpecialChar ~
22051 for (i = 0, j = 10 ; i < 10 ; i++, j
22052 \family default
22053 -
22054 \begin_inset ERT
22055 status Collapsed
22056
22057 \layout Standard
22058
22059 \backslash
22060 /
22061 \end_inset
22062
22063 -
22064 \family typewriter
22065 ) {
22066 \newline
22067 16.\SpecialChar ~
22068 \SpecialChar ~
22069 \SpecialChar ~
22070 \SpecialChar ~
22071 sum += i;
22072 \newline
22073 17.\SpecialChar ~
22074 \SpecialChar ~
22075 \SpecialChar ~
22076 \SpecialChar ~
22077 mul += i * 3; \SpecialChar ~
22078 \SpecialChar ~
22079 /* this multiplication remains */
22080 \newline
22081 18.\SpecialChar ~
22082 \SpecialChar ~
22083 \SpecialChar ~
22084 \SpecialChar ~
22085 gint += j * 3;\SpecialChar ~
22086 \SpecialChar ~
22087 /* this multiplication changed to addition */
22088 \newline
22089 19.\SpecialChar ~
22090 \SpecialChar ~
22091 }
22092 \newline
22093 20.\SpecialChar ~
22094 \SpecialChar ~
22095 return sum+mul;
22096 \newline
22097 21.\SpecialChar ~
22098 }
22099 \layout Standard
22100
22101 In addition to the operands each iCode contains information about the filename
22102  and line it corresponds to in the source file.
22103  The first field in the listing should be interpreted as follows:
22104 \newline
22105
22106 \shape italic
22107 \size footnotesize
22108 Filename(linenumber: iCode Execution sequence number : ICode hash table
22109  key : loop depth of the iCode).
22110 \shape default
22111 \size default
22112
22113 \newline
22114 Then follows the human readable form of the ICode operation.
22115  Each operand of this triplet form can be of three basic types a) compiler
22116  generated temporary b) user defined variable c) a constant value.
22117  Note that local variables and parameters are replaced by compiler generated
22118  temporaries.
22119  Live ranges
22120 \begin_inset LatexCommand \index{Live range analysis}
22121
22122 \end_inset
22123
22124  are computed only for temporaries (i.e.
22125  live ranges are not computed for global variables).
22126  Registers
22127 \begin_inset LatexCommand \index{Register allocation}
22128
22129 \end_inset
22130
22131  are allocated for temporaries only.
22132  Operands are formatted in the following manner:
22133 \newline
22134
22135 \shape italic
22136 \size footnotesize
22137 Operand Name [lr live-from : live-to ] { type information } [ registers
22138  allocated ].
22139 \shape default
22140 \size default
22141
22142 \newline
22143 As mentioned earlier the live ranges are computed in terms of the execution
22144  sequence number of the iCodes, for example
22145 \newline
22146 the iTemp0 is live from (i.e.
22147  first defined in iCode with execution sequence number 3, and is last used
22148  in the iCode with sequence number 5).
22149  For induction variables such as iTemp21 the live range computation extends
22150  the lifetime from the start to the end of the loop.
22151 \newline
22152 The register allocator used the live range information to allocate registers,
22153  the same registers may be used for different temporaries if their live
22154  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
22155  iTemp17 since their live ranges do not overlap.
22156  In addition the allocator also takes into consideration the type and usage
22157  of a temporary, for example itemp6 is a pointer to near space and is used
22158  as to fetch data from (i.e.
22159  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
22160  Some short lived temporaries are allocated to special registers which have
22161  meaning to the code generator e.g.
22162  iTemp13 is allocated to a pseudo register CC which tells the back end that
22163  the temporary is used only for a conditional jump the code generation makes
22164  use of this information to optimize a compare and jump ICode.
22165 \newline
22166 There are several loop optimizations
22167 \begin_inset LatexCommand \index{Loop optimization}
22168
22169 \end_inset
22170
22171  performed by the compiler.
22172  It can detect induction variables iTemp21(i) and iTemp23(j).
22173  Also note the compiler does selective strength reduction
22174 \begin_inset LatexCommand \index{Strength reduction}
22175
22176 \end_inset
22177
22178 , i.e.
22179  the multiplication of an induction variable in line 18 (gint = j * 3) is
22180  changed to addition, a new temporary iTemp17 is allocated and assigned
22181  a initial value, a constant 3 is then added for each iteration of the loop.
22182  The compiler does not change the multiplication
22183 \begin_inset LatexCommand \index{Multiplication}
22184
22185 \end_inset
22186
22187  in line 17 however since the processor does support an 8 * 8 bit multiplication.
22188 \newline
22189 Note the dead code elimination
22190 \begin_inset LatexCommand \index{Dead-code elimination}
22191
22192 \end_inset
22193
22194  optimization eliminated the dead assignments in line 7 & 8 to I and sum
22195  respectively.
22196 \newline
22197
22198 \layout Standard
22199
22200
22201 \size footnotesize
22202 Sample.c (5:1:0:0) _entry($9) :
22203 \layout Standard
22204
22205
22206 \size footnotesize
22207 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
22208 \layout Standard
22209
22210
22211 \size footnotesize
22212 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
22213 \layout Standard
22214
22215
22216 \size footnotesize
22217 Sample.c(11:4:53:0) preHeaderLbl0($11) :
22218 \layout Standard
22219
22220
22221 \size footnotesize
22222 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
22223  * int}[r2]
22224 \layout Standard
22225
22226
22227 \size footnotesize
22228 Sample.c(11:6:5:1) _whilecontinue_0($1) :
22229 \layout Standard
22230
22231
22232 \size footnotesize
22233 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
22234  int}[r0]]
22235 \layout Standard
22236
22237
22238 \size footnotesize
22239 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
22240 \layout Standard
22241
22242
22243 \size footnotesize
22244 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
22245  * int}
22246 \layout Standard
22247
22248
22249 \size footnotesize
22250 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
22251  {short}
22252 \layout Standard
22253
22254
22255 \size footnotesize
22256 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
22257  * int}[DPTR]]
22258 \layout Standard
22259
22260
22261 \size footnotesize
22262 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
22263 }[r2 r3]
22264 \layout Standard
22265
22266
22267 \size footnotesize
22268 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
22269  * int}[r0] + 0x2 {short}
22270 \layout Standard
22271
22272
22273 \size footnotesize
22274 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
22275 \layout Standard
22276
22277
22278 \size footnotesize
22279 Sample.c(11:17:21:0)_whilebreak_0($3) :
22280 \layout Standard
22281
22282
22283 \size footnotesize
22284 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
22285 \layout Standard
22286
22287
22288 \size footnotesize
22289 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
22290 \layout Standard
22291
22292
22293 \size footnotesize
22294 Sample.c(15:20:54:0)preHeaderLbl1($13) :
22295 \layout Standard
22296
22297
22298 \size footnotesize
22299 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
22300 \layout Standard
22301
22302
22303 \size footnotesize
22304 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
22305 \layout Standard
22306
22307
22308 \size footnotesize
22309 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
22310 \layout Standard
22311
22312
22313 \size footnotesize
22314 Sample.c(15:24:26:1)_forcond_0($4) :
22315 \layout Standard
22316
22317
22318 \size footnotesize
22319 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
22320  < 0xa {short}
22321 \layout Standard
22322
22323
22324 \size footnotesize
22325 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
22326 \layout Standard
22327
22328
22329 \size footnotesize
22330 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
22331  + ITemp21 [lr21:38]{short}[r4]
22332 \layout Standard
22333
22334
22335 \size footnotesize
22336 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
22337  * 0x3 {short}
22338 \layout Standard
22339
22340
22341 \size footnotesize
22342 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
22343  + iTemp15 [lr29:30]{short}[r1]
22344 \layout Standard
22345
22346
22347 \size footnotesize
22348 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
22349  r0]- 0x3 {short}
22350 \layout Standard
22351
22352
22353 \size footnotesize
22354 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
22355 int}[r7 r0]
22356 \layout Standard
22357
22358
22359 \size footnotesize
22360 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
22361  + 0x1 {short}
22362 \layout Standard
22363
22364
22365 \size footnotesize
22366 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
22367  r6]- 0x1 {short}
22368 \layout Standard
22369
22370
22371 \size footnotesize
22372 Sample.c(19:38:47:1) goto _forcond_0($4)
22373 \layout Standard
22374
22375
22376 \size footnotesize
22377 Sample.c(19:39:48:0)_forbreak_0($7) :
22378 \layout Standard
22379
22380
22381 \size footnotesize
22382 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
22383  + ITemp11 [lr19:40]{short}[r3]
22384 \layout Standard
22385
22386
22387 \size footnotesize
22388 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
22389 \layout Standard
22390
22391
22392 \size footnotesize
22393 Sample.c(20:42:51:0)_return($8) :
22394 \layout Standard
22395
22396
22397 \size footnotesize
22398 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
22399 \size default
22400
22401 \newline
22402
22403 \newline
22404 Finally the code generated for this function:
22405 \newline
22406
22407 \layout Standard
22408
22409
22410 \size footnotesize
22411 .area DSEG (DATA)
22412 \layout Standard
22413
22414
22415 \size footnotesize
22416 _p::
22417 \layout Standard
22418
22419
22420 \size footnotesize
22421 \SpecialChar ~
22422 \SpecialChar ~
22423 .ds 2
22424 \layout Standard
22425
22426
22427 \size footnotesize
22428 _gint::
22429 \layout Standard
22430
22431
22432 \size footnotesize
22433 \SpecialChar ~
22434 \SpecialChar ~
22435 .ds 2
22436 \layout Standard
22437
22438
22439 \size footnotesize
22440 ; sample.c 5
22441 \layout Standard
22442
22443
22444 \size footnotesize
22445 ; ----------------------------------------------
22446 \layout Standard
22447
22448
22449 \size footnotesize
22450 ; function function
22451 \layout Standard
22452
22453
22454 \size footnotesize
22455 ; ----------------------------------------------
22456 \layout Standard
22457
22458
22459 \size footnotesize
22460 _function:
22461 \layout Standard
22462
22463
22464 \size footnotesize
22465 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
22466 \layout Standard
22467
22468
22469 \size footnotesize
22470 \SpecialChar ~
22471 \SpecialChar ~
22472 mov r2,dpl
22473 \layout Standard
22474
22475
22476 \size footnotesize
22477 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
22478 \layout Standard
22479
22480
22481 \size footnotesize
22482 \SpecialChar ~
22483 \SpecialChar ~
22484 mov ar0,r2
22485 \layout Standard
22486
22487
22488 \size footnotesize
22489 ;_whilecontinue_0($1) :
22490 \layout Standard
22491
22492
22493 \size footnotesize
22494 00101$:
22495 \layout Standard
22496
22497
22498 \size footnotesize
22499 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
22500 \layout Standard
22501
22502
22503 \size footnotesize
22504 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
22505 \layout Standard
22506
22507
22508 \size footnotesize
22509 \SpecialChar ~
22510 \SpecialChar ~
22511 mov ar2,@r0
22512 \layout Standard
22513
22514
22515 \size footnotesize
22516 \SpecialChar ~
22517 \SpecialChar ~
22518 inc r0
22519 \layout Standard
22520
22521
22522 \size footnotesize
22523 \SpecialChar ~
22524 \SpecialChar ~
22525 mov ar3,@r0
22526 \layout Standard
22527
22528
22529 \size footnotesize
22530 \SpecialChar ~
22531 \SpecialChar ~
22532 dec r0
22533 \layout Standard
22534
22535
22536 \size footnotesize
22537 \SpecialChar ~
22538 \SpecialChar ~
22539 mov a,r2
22540 \layout Standard
22541
22542
22543 \size footnotesize
22544 \SpecialChar ~
22545 \SpecialChar ~
22546 orl a,r3
22547 \layout Standard
22548
22549
22550 \size footnotesize
22551 \SpecialChar ~
22552 \SpecialChar ~
22553 jz 00103$
22554 \layout Standard
22555
22556
22557 \size footnotesize
22558 00114$:
22559 \layout Standard
22560
22561
22562 \size footnotesize
22563 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
22564 \layout Standard
22565
22566
22567 \size footnotesize
22568 \SpecialChar ~
22569 \SpecialChar ~
22570 mov dpl,_p
22571 \layout Standard
22572
22573
22574 \size footnotesize
22575 \SpecialChar ~
22576 \SpecialChar ~
22577 mov dph,(_p + 1)
22578 \layout Standard
22579
22580
22581 \size footnotesize
22582 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
22583 \layout Standard
22584
22585
22586 \size footnotesize
22587 \SpecialChar ~
22588 \SpecialChar ~
22589 mov a,#0x02
22590 \layout Standard
22591
22592
22593 \size footnotesize
22594 \SpecialChar ~
22595 \SpecialChar ~
22596 add a,_p
22597 \layout Standard
22598
22599
22600 \size footnotesize
22601 \SpecialChar ~
22602 \SpecialChar ~
22603 mov _p,a
22604 \layout Standard
22605
22606
22607 \size footnotesize
22608 \SpecialChar ~
22609 \SpecialChar ~
22610 clr a
22611 \layout Standard
22612
22613
22614 \size footnotesize
22615 \SpecialChar ~
22616 \SpecialChar ~
22617 addc a,(_p + 1)
22618 \layout Standard
22619
22620
22621 \size footnotesize
22622 \SpecialChar ~
22623 \SpecialChar ~
22624 mov (_p + 1),a
22625 \layout Standard
22626
22627
22628 \size footnotesize
22629 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
22630 \layout Standard
22631
22632
22633 \size footnotesize
22634 \SpecialChar ~
22635 \SpecialChar ~
22636 movx a,@dptr
22637 \layout Standard
22638
22639
22640 \size footnotesize
22641 \SpecialChar ~
22642 \SpecialChar ~
22643 mov r2,a
22644 \layout Standard
22645
22646
22647 \size footnotesize
22648 \SpecialChar ~
22649 \SpecialChar ~
22650 inc dptr
22651 \layout Standard
22652
22653
22654 \size footnotesize
22655 \SpecialChar ~
22656 \SpecialChar ~
22657 movx a,@dptr
22658 \layout Standard
22659
22660
22661 \size footnotesize
22662 \SpecialChar ~
22663 \SpecialChar ~
22664 mov r3,a
22665 \layout Standard
22666
22667
22668 \size footnotesize
22669 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
22670 \layout Standard
22671
22672
22673 \size footnotesize
22674 \SpecialChar ~
22675 \SpecialChar ~
22676 mov @r0,ar2
22677 \layout Standard
22678
22679
22680 \size footnotesize
22681 \SpecialChar ~
22682 \SpecialChar ~
22683 inc r0
22684 \layout Standard
22685
22686
22687 \size footnotesize
22688 \SpecialChar ~
22689 \SpecialChar ~
22690 mov @r0,ar3
22691 \layout Standard
22692
22693
22694 \size footnotesize
22695 ; iTemp6 [lr5:16]{_near * int}[r0] =
22696 \layout Standard
22697
22698
22699 \size footnotesize
22700 ; iTemp6 [lr5:16]{_near * int}[r0] +
22701 \layout Standard
22702
22703
22704 \size footnotesize
22705 ; 0x2 {short}
22706 \layout Standard
22707
22708
22709 \size footnotesize
22710 \SpecialChar ~
22711 \SpecialChar ~
22712 inc r0
22713 \layout Standard
22714
22715
22716 \size footnotesize
22717 ; goto _whilecontinue_0($1)
22718 \layout Standard
22719
22720
22721 \size footnotesize
22722 \SpecialChar ~
22723 \SpecialChar ~
22724 sjmp 00101$
22725 \layout Standard
22726
22727
22728 \size footnotesize
22729 ; _whilebreak_0($3) :
22730 \layout Standard
22731
22732
22733 \size footnotesize
22734 00103$:
22735 \layout Standard
22736
22737
22738 \size footnotesize
22739 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
22740 \layout Standard
22741
22742
22743 \size footnotesize
22744 \SpecialChar ~
22745 \SpecialChar ~
22746 mov r2,#0x00
22747 \layout Standard
22748
22749
22750 \size footnotesize
22751 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
22752 \layout Standard
22753
22754
22755 \size footnotesize
22756 \SpecialChar ~
22757 \SpecialChar ~
22758 mov r3,#0x00
22759 \layout Standard
22760
22761
22762 \size footnotesize
22763 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
22764 \layout Standard
22765
22766
22767 \size footnotesize
22768 \SpecialChar ~
22769 \SpecialChar ~
22770 mov r4,#0x00
22771 \layout Standard
22772
22773
22774 \size footnotesize
22775 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
22776 \layout Standard
22777
22778
22779 \size footnotesize
22780 \SpecialChar ~
22781 \SpecialChar ~
22782 mov r5,#0x0A
22783 \layout Standard
22784
22785
22786 \size footnotesize
22787 \SpecialChar ~
22788 \SpecialChar ~
22789 mov r6,#0x00
22790 \layout Standard
22791
22792
22793 \size footnotesize
22794 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
22795 \layout Standard
22796
22797
22798 \size footnotesize
22799 \SpecialChar ~
22800 \SpecialChar ~
22801 mov r7,#0x1E
22802 \layout Standard
22803
22804
22805 \size footnotesize
22806 \SpecialChar ~
22807 \SpecialChar ~
22808 mov r0,#0x00
22809 \layout Standard
22810
22811
22812 \size footnotesize
22813 ; _forcond_0($4) :
22814 \layout Standard
22815
22816
22817 \size footnotesize
22818 00104$:
22819 \layout Standard
22820
22821
22822 \size footnotesize
22823 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
22824 \layout Standard
22825
22826
22827 \size footnotesize
22828 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
22829 \layout Standard
22830
22831
22832 \size footnotesize
22833 \SpecialChar ~
22834 \SpecialChar ~
22835 clr c
22836 \layout Standard
22837
22838
22839 \size footnotesize
22840 \SpecialChar ~
22841 \SpecialChar ~
22842 mov a,r4
22843 \layout Standard
22844
22845
22846 \size footnotesize
22847 \SpecialChar ~
22848 \SpecialChar ~
22849 xrl a,#0x80
22850 \layout Standard
22851
22852
22853 \size footnotesize
22854 \SpecialChar ~
22855 \SpecialChar ~
22856 subb a,#0x8a
22857 \layout Standard
22858
22859
22860 \size footnotesize
22861 \SpecialChar ~
22862 \SpecialChar ~
22863 jnc 00107$
22864 \layout Standard
22865
22866
22867 \size footnotesize
22868 00115$:
22869 \layout Standard
22870
22871
22872 \size footnotesize
22873 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
22874 \layout Standard
22875
22876
22877 \size footnotesize
22878 ; iTemp21 [lr21:38]{short}[r4]
22879 \layout Standard
22880
22881
22882 \size footnotesize
22883 \SpecialChar ~
22884 \SpecialChar ~
22885 mov a,r4
22886 \layout Standard
22887
22888
22889 \size footnotesize
22890 \SpecialChar ~
22891 \SpecialChar ~
22892 add a,r2
22893 \layout Standard
22894
22895
22896 \size footnotesize
22897 \SpecialChar ~
22898 \SpecialChar ~
22899 mov r2,a
22900 \layout Standard
22901
22902
22903 \size footnotesize
22904 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
22905 \layout Standard
22906
22907
22908 \size footnotesize
22909 \SpecialChar ~
22910 \SpecialChar ~
22911 mov b,#0x03
22912 \layout Standard
22913
22914
22915 \size footnotesize
22916 \SpecialChar ~
22917 \SpecialChar ~
22918 mov a,r4
22919 \layout Standard
22920
22921
22922 \size footnotesize
22923 \SpecialChar ~
22924 \SpecialChar ~
22925 mul ab
22926 \layout Standard
22927
22928
22929 \size footnotesize
22930 \SpecialChar ~
22931 \SpecialChar ~
22932 mov r1,a
22933 \layout Standard
22934
22935
22936 \size footnotesize
22937 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
22938 \layout Standard
22939
22940
22941 \size footnotesize
22942 ; iTemp15 [lr29:30]{short}[r1]
22943 \layout Standard
22944
22945
22946 \size footnotesize
22947 \SpecialChar ~
22948 \SpecialChar ~
22949 add a,r3
22950 \layout Standard
22951
22952
22953 \size footnotesize
22954 \SpecialChar ~
22955 \SpecialChar ~
22956 mov r3,a
22957 \layout Standard
22958
22959
22960 \size footnotesize
22961 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
22962 \layout Standard
22963
22964
22965 \size footnotesize
22966 \SpecialChar ~
22967 \SpecialChar ~
22968 mov a,r7
22969 \layout Standard
22970
22971
22972 \size footnotesize
22973 \SpecialChar ~
22974 \SpecialChar ~
22975 add a,#0xfd
22976 \layout Standard
22977
22978
22979 \size footnotesize
22980 \SpecialChar ~
22981 \SpecialChar ~
22982 mov r7,a
22983 \layout Standard
22984
22985
22986 \size footnotesize
22987 \SpecialChar ~
22988 \SpecialChar ~
22989 mov a,r0
22990 \layout Standard
22991
22992
22993 \size footnotesize
22994 \SpecialChar ~
22995 \SpecialChar ~
22996 addc a,#0xff
22997 \layout Standard
22998
22999
23000 \size footnotesize
23001 \SpecialChar ~
23002 \SpecialChar ~
23003 mov r0,a
23004 \layout Standard
23005
23006
23007 \size footnotesize
23008 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
23009 \layout Standard
23010
23011
23012 \size footnotesize
23013 \SpecialChar ~
23014 \SpecialChar ~
23015 mov a,r7
23016 \layout Standard
23017
23018
23019 \size footnotesize
23020 \SpecialChar ~
23021 \SpecialChar ~
23022 add a,_gint
23023 \layout Standard
23024
23025
23026 \size footnotesize
23027 \SpecialChar ~
23028 \SpecialChar ~
23029 mov _gint,a
23030 \layout Standard
23031
23032
23033 \size footnotesize
23034 \SpecialChar ~
23035 \SpecialChar ~
23036 mov a,r0
23037 \layout Standard
23038
23039
23040 \size footnotesize
23041 \SpecialChar ~
23042 \SpecialChar ~
23043 addc a,(_gint + 1)
23044 \layout Standard
23045
23046
23047 \size footnotesize
23048 \SpecialChar ~
23049 \SpecialChar ~
23050 mov (_gint + 1),a
23051 \layout Standard
23052
23053
23054 \size footnotesize
23055 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
23056 \layout Standard
23057
23058
23059 \size footnotesize
23060 \SpecialChar ~
23061 \SpecialChar ~
23062 inc r4
23063 \layout Standard
23064
23065
23066 \size footnotesize
23067 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
23068 \layout Standard
23069
23070
23071 \size footnotesize
23072 \SpecialChar ~
23073 \SpecialChar ~
23074 dec r5
23075 \layout Standard
23076
23077
23078 \size footnotesize
23079 \SpecialChar ~
23080 \SpecialChar ~
23081 cjne r5,#0xff,00104$
23082 \layout Standard
23083
23084
23085 \size footnotesize
23086 \SpecialChar ~
23087 \SpecialChar ~
23088 dec r6
23089 \layout Standard
23090
23091
23092 \size footnotesize
23093 ; goto _forcond_0($4)
23094 \layout Standard
23095
23096
23097 \size footnotesize
23098 \SpecialChar ~
23099 \SpecialChar ~
23100 sjmp 00104$
23101 \layout Standard
23102
23103
23104 \size footnotesize
23105 ; _forbreak_0($7) :
23106 \layout Standard
23107
23108
23109 \size footnotesize
23110 00107$:
23111 \layout Standard
23112
23113
23114 \size footnotesize
23115 ; ret iTemp24 [lr40:41]{short}
23116 \layout Standard
23117
23118
23119 \size footnotesize
23120 \SpecialChar ~
23121 \SpecialChar ~
23122 mov a,r3
23123 \layout Standard
23124
23125
23126 \size footnotesize
23127 \SpecialChar ~
23128 \SpecialChar ~
23129 add a,r2
23130 \layout Standard
23131
23132
23133 \size footnotesize
23134 \SpecialChar ~
23135 \SpecialChar ~
23136 mov dpl,a
23137 \layout Standard
23138
23139
23140 \size footnotesize
23141 ; _return($8) :
23142 \layout Standard
23143
23144
23145 \size footnotesize
23146 00108$:
23147 \layout Standard
23148
23149
23150 \size footnotesize
23151 \SpecialChar ~
23152 \SpecialChar ~
23153 ret
23154 \newline
23155
23156 \layout Section
23157
23158 A few words about basic block successors, predecessors and dominators
23159 \layout Standard
23160
23161 Successors are basic blocks
23162 \begin_inset LatexCommand \index{Basic blocks}
23163
23164 \end_inset
23165
23166  that might execute after this basic block.
23167 \newline
23168 Predecessors are basic blocks that might execute before reaching this basic
23169  block.
23170 \newline
23171 Dominators are basic blocks that WILL execute before reaching this basic
23172  block.
23173 \newline
23174
23175 \layout Standard
23176
23177 [basic block 1]
23178 \layout Standard
23179
23180 if (something)
23181 \layout Standard
23182
23183 \SpecialChar ~
23184 \SpecialChar ~
23185 \SpecialChar ~
23186 \SpecialChar ~
23187 [basic block 2]
23188 \layout Standard
23189
23190 else
23191 \layout Standard
23192
23193 \SpecialChar ~
23194 \SpecialChar ~
23195 \SpecialChar ~
23196 \SpecialChar ~
23197 [basic block 3]
23198 \layout Standard
23199
23200 [basic block 4]
23201 \newline
23202
23203 \layout Standard
23204
23205 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
23206 \layout Standard
23207
23208 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
23209 \layout Standard
23210
23211 c) domVect of [BB4] = BB1 ...
23212  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
23213  was executed.
23214 \layout Chapter
23215
23216 Acknowledgments
23217 \layout Standard
23218
23219
23220 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
23221
23222 \end_inset
23223
23224
23225 \newline
23226
23227 \newline
23228
23229 \emph on
23230 Thanks to all the other volunteer developers who have helped with coding,
23231  testing, web-page creation, distribution sets, etc.
23232  You know who you are :-)
23233 \emph default
23234
23235 \newline
23236
23237 \layout Standard
23238
23239 This document was initially written by Sandeep Dutta
23240 \layout Standard
23241
23242 All product names mentioned herein may be trademarks
23243 \begin_inset LatexCommand \index{Trademarks}
23244
23245 \end_inset
23246
23247  of their respective companies.
23248
23249 \layout Section*
23250
23251 Alphabetical index
23252 \layout Standard
23253
23254 To avoid confusion, the installation and building options for SDCC itself
23255  (chapter 2) are not part of the index.
23256 \layout Standard
23257
23258
23259 \begin_inset LatexCommand \printindex{}
23260
23261 \end_inset
23262
23263
23264 \the_end