git.gag.com Git - fw/sdcc/blob - doc/sdccman.lyx

   1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 221
   3 \textclass book
   4 \begin_preamble
   5
   6
   7 \usepackage[
   8   pdftitle={SDCC Compiler User Guide},
   9   pdfauthor={SDCC development team},
  10   pdfsubject={installation, user manual},
  11   pdfkeywords={8032, 8051, ansi, c, compiler, CPU, DS390,
  12                embedded, GPL, HC08, manual, mcs51, PIC, Z80},
  13   colorlinks=true,
  14   linkcolor=blue] {hyperref}
  15 %
  16 \sloppy
  17 \tolerance=500
  18 \emergencystretch=30pt
  19 %
  20 \date{}
  21 \end_preamble
  22 \language english
  23 \inputencoding default
  24 \fontscheme pslatex
  25 \graphics default
  26 \paperfontsize default
  27 \spacing single
  28 \papersize letterpaper
  29 \paperpackage a4
  30 \use_geometry 1
  31 \use_amsmath 0
  32 \use_natbib 0
  33 \use_numerical_citations 0
  34 \paperorientation portrait
  35 \leftmargin 30mm
  36 \topmargin 20mm
  37 \rightmargin 25mm
  38 \bottommargin 20mm
  39 \secnumdepth 3
  40 \tocdepth 3
  41 \paragraph_separation indent
  42 \defskip medskip
  43 \quotes_language swedish
  44 \quotes_times 2
  45 \papercolumns 1
  46 \papersides 1
  47 \paperpagestyle fancy
  48
  49 \layout Comment
  50
  51 Please note: double dashed longoptions (e.g.
  52  --version) are written this way: -
  53 \begin_inset ERT
  54 status Collapsed
  55
  56 \layout Standard
  57
  58 \backslash
  59 /
  60 \end_inset
  61
  62 -
  63 \layout Comment
  64
  65 Two resp.
  66  three consecutive dashes simply result in a long resp.
  67  extra long dash.
  68 \layout Comment
  69
  70 Architecture specific stuff (like memory models, code examples) should maybe
  71  later go
  72 \layout Comment
  73
  74 into seperate sections/chapters/appendices (it is hard to document PIC or
  75  Z80 in
  76 \layout Comment
  77
  78 a 8051 centered document) - for now simply add.
  79 \layout Title
  80
  81 SDCC Compiler User Guide
  82 \layout Date
  83
  84
  85 \size normal
  86 SDCC 2.4.5
  87 \size footnotesize
  88
  89 \newline
  90 $Date$
  91 \newline
  92 $Revision$
  93 \layout Comment
  94
  95 The above strings enclosed in $ are automatically updated by cvs
  96 \layout Standard
  97
  98
  99 \begin_inset LatexCommand \tableofcontents{}
 100
 101 \end_inset
 102
 103
 104 \layout Chapter
 105
 106 Introduction
 107 \layout Section
 108
 109 About SDCC
 110 \layout Standard
 111
 112
 113 \series bold
 114 SDCC
 115 \series default
 116  (
 117 \emph on
 118 S
 119 \emph default
 120 mall
 121 \emph on
 122 D
 123 \emph default
 124 evice
 125 \emph on
 126 C
 127 \emph default
 128
 129 \emph on
 130 C
 131 \emph default
 132 ompiler) is an open source, retargettable, optimizing ANSI-C compiler by
 133
 134 \series bold
 135 Sandeep Dutta
 136 \series default
 137  designed for 8 bit Microprocessors.
 138  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 139  8051, 8052
 140 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
 141
 142 \end_inset
 143
 144 , etc.), Dallas DS80C390 variants, Motorola HC08 and Zilog Z80 based MCUs.
 145  It can be retargetted for other microprocessors, support for Microchip
 146  PIC, Atmel AVR is under development.
 147  The entire source code for the compiler is distributed under GPL.
 148  SDCC uses ASXXXX
 149 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
 150
 151 \end_inset
 152
 153  & ASLINK
 154 \begin_inset LatexCommand \index{aslink}
 155
 156 \end_inset
 157
 158 , an open source retargettable assembler & linker.
 159  SDCC has extensive language extensions suitable for utilizing various microcont
 160 rollers and underlying hardware effectively.
 161
 162 \newline
 163
 164 \newline
 165 In addition to the MCU specific optimizations SDCC also does a host of standard
 166  optimizations like:
 167 \layout Itemize
 168
 169 global sub expression elimination,
 170 \layout Itemize
 171
 172 loop optimizations (loop invariant, strength reduction of induction variables
 173  and loop reversing),
 174 \layout Itemize
 175
 176 constant folding & propagation,
 177 \layout Itemize
 178
 179 copy propagation,
 180 \layout Itemize
 181
 182 dead code elimination
 183 \layout Itemize
 184
 185 jump tables for
 186 \emph on
 187 switch
 188 \emph default
 189  statements.
 190 \layout Standard
 191
 192 For the back-end SDCC uses a global register allocation scheme which should
 193  be well suited for other 8 bit MCUs.
 194
 195 \newline
 196
 197 \newline
 198 The peep hole optimizer uses a rule based substitution mechanism which is
 199  MCU independent.
 200
 201 \newline
 202
 203 \newline
 204 Supported data-types are:
 205 \layout Itemize
 206
 207 char (8 bits, 1 byte),
 208 \layout Itemize
 209
 210 short and int (16 bits, 2 bytes),
 211 \layout Itemize
 212
 213 long (32 bit, 4 bytes)
 214 \layout Itemize
 215
 216 float (4 byte IEEE).
 217
 218 \layout Standard
 219
 220 The compiler also allows
 221 \emph on
 222 inline assembler code
 223 \emph default
 224  to be embedded anywhere in a function.
 225  In addition, routines developed in assembly can also be called.
 226 \newline
 227
 228 \newline
 229 SDCC also provides an option (-
 230 \begin_inset ERT
 231 status Collapsed
 232
 233 \layout Standard
 234
 235 \backslash
 236 /
 237 \end_inset
 238
 239 -cyclomatic) to report the relative complexity of a function.
 240  These functions can then be further optimized, or hand coded in assembly
 241  if needed.
 242
 243 \newline
 244
 245 \newline
 246 SDCC also comes with a companion source level debugger SDCDB, the debugger
 247  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 248
 249 \newline
 250
 251 \newline
 252 The latest version can be downloaded from
 253 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 254
 255 \end_inset
 256
 257 .
 258
 259 \series bold
 260
 261 \series default
 262 \emph on
 263 Please note: the compiler will probably always be some steps ahead of this
 264  documentation
 265 \series bold
 266 \emph default
 267
 268 \begin_inset LatexCommand \index{Status of documentation}
 269
 270 \end_inset
 271
 272
 273 \begin_inset Foot
 274 collapsed false
 275
 276 \layout Standard
 277
 278 Obviously this has pros and cons
 279 \end_inset
 280
 281 .
 282 \layout Section
 283
 284 Open Source
 285 \layout Standard
 286
 287 All packages used in this compiler system are
 288 \emph on
 289 open source
 290 \emph default
 291  and
 292 \emph on
 293 freeware
 294 \emph default
 295 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 296  etc) is distributed with the package.
 297  This documentation is maintained using a freeware word processor (LyX).
 298 \newline
 299 This program is free software; you can redistribute it and/or modify it
 300  under the terms of the GNU General Public License
 301 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 302
 303 \end_inset
 304
 305  as published by the Free Software Foundation; either version 2, or (at
 306  your option) any later version.
 307  This program is distributed in the hope that it will be useful, but WITHOUT
 308  ANY WARRANTY; without even the implied warranty
 309 \begin_inset LatexCommand \index{warranty}
 310
 311 \end_inset
 312
 313  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 314  See the GNU General Public License for more details.
 315  You should have received a copy of the GNU General Public License along
 316  with this program; if not, write to the Free Software Foundation, 59 Temple
 317  Place - Suite 330, Boston, MA 02111-1307, USA.
 318  In other words, you are welcome to use, share and improve this program.
 319  You are forbidden to forbid anyone else to use, share and improve what
 320  you give them.
 321  Help stamp out software-hoarding!
 322 \layout Section
 323
 324 Typographic conventions
 325 \begin_inset LatexCommand \index{Typographic conventions}
 326
 327 \end_inset
 328
 329
 330 \layout Standard
 331
 332 Throughout this manual, we will use the following convention.
 333  Commands you have to type in are printed in
 334 \family sans
 335 \series bold
 336 "sans serif"
 337 \series default
 338 .
 339
 340 \family default
 341  Code samples are printed in
 342 \family typewriter
 343 typewriter font.
 344
 345 \family default
 346  Interesting items and new terms are printed in
 347 \emph on
 348 italic.
 349 \layout Section
 350
 351 Compatibility with previous versions
 352 \layout Standard
 353
 354 This version has numerous bug fixes compared with the previous version.
 355  But we also introduced some incompatibilities with older versions.
 356  Not just for the fun of it, but to make the compiler more stable, efficient
 357  and ANSI compliant
 358 \begin_inset LatexCommand \index{ANSI-compliance}
 359
 360 \end_inset
 361
 362  (see section
 363 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 364
 365 \end_inset
 366
 367  for ANSI-Compliance).
 368
 369 \newline
 370
 371 \layout Itemize
 372
 373 short is now equivalent to int (16 bits), it used to be equivalent to char
 374  (8 bits) which is not ANSI compliant
 375 \layout Itemize
 376
 377 the default directory for gcc-builds where include, library and documentation
 378  files are stored is now in /usr/local/share
 379 \layout Itemize
 380
 381 char type parameters to vararg functions are casted to int unless explicitly
 382  casted, e.g.:
 383 \newline
 384
 385 \family typewriter
 386 \SpecialChar ~
 387 \SpecialChar ~
 388 char a=3;
 389 \newline
 390 \SpecialChar ~
 391 \SpecialChar ~
 392 printf ("%d %c
 393 \backslash
 394 n", a, (char)a);
 395 \family default
 396
 397 \newline
 398  will push a as an int and as a char resp.
 399 \layout Itemize
 400
 401 option -
 402 \begin_inset ERT
 403 status Collapsed
 404
 405 \layout Standard
 406
 407 \backslash
 408 /
 409 \end_inset
 410
 411 -regextend has been removed
 412 \layout Itemize
 413
 414 option -
 415 \begin_inset ERT
 416 status Collapsed
 417
 418 \layout Standard
 419
 420 \backslash
 421 /
 422 \end_inset
 423
 424 -noregparms has been removed
 425 \layout Itemize
 426
 427 option -
 428 \begin_inset ERT
 429 status Collapsed
 430
 431 \layout Standard
 432
 433 \backslash
 434 /
 435 \end_inset
 436
 437 -stack-after-data has been removed
 438 \layout Standard
 439
 440
 441 \emph on
 442 <pending: more incompatibilities?>
 443 \layout Section
 444
 445 System Requirements
 446 \layout Standard
 447
 448 What do you need before you start installation of SDCC? A computer, and
 449  a desire to compute.
 450  The preferred method of installation is to compile SDCC from source using
 451  GNU gcc and make.
 452  For Windows some pre-compiled binary distributions are available for your
 453  convenience.
 454  You should have some experience with command line tools and compiler use.
 455 \layout Section
 456
 457 Other Resources
 458 \layout Standard
 459
 460 The SDCC home page at
 461 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 462
 463 \end_inset
 464
 465  is a great place to find distribution sets.
 466  You can also find links to the user mailing lists that offer help or discuss
 467  SDCC with other SDCC users.
 468  Web links to other SDCC related sites can also be found here.
 469  This document can be found in the DOC directory of the source package as
 470  a text or HTML file.
 471  A pdf version of this document is available at
 472 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 473
 474 \end_inset
 475
 476 .
 477  Some of the other tools (simulator and assembler) included with SDCC contain
 478  their own documentation and can be found in the source distribution.
 479  If you want the latest unreleased software, the complete source package
 480  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 481 \layout Section
 482
 483 Wishes for the future
 484 \layout Standard
 485
 486 There are (and always will be) some things that could be done.
 487  Here are some I can think of:
 488 \newline
 489
 490 \layout Standard
 491
 492
 493 \family typewriter
 494 char KernelFunction3(char p) at 0x340;
 495 \newline
 496
 497 \layout Standard
 498
 499
 500 \family typewriter
 501 code banking
 502 \begin_inset LatexCommand \index{code banking (not supported)}
 503
 504 \end_inset
 505
 506  support for mcs51
 507 \newline
 508
 509 \newline
 510
 511 \family default
 512 If you can think of some more, please see the section
 513 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 514
 515 \end_inset
 516
 517  about filing feature requests
 518 \begin_inset LatexCommand \index{Requesting features}
 519
 520 \end_inset
 521
 522
 523 \begin_inset LatexCommand \index{Feature request}
 524
 525 \end_inset
 526
 527 .
 528 \newline
 529
 530 \layout Chapter
 531
 532 Installing SDCC
 533 \begin_inset LatexCommand \index{Installation}
 534
 535 \end_inset
 536
 537
 538 \layout Standard
 539
 540 For most users it is sufficient to skip to either section
 541 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 542
 543 \end_inset
 544
 545  or section
 546 \begin_inset LatexCommand \ref{sub:Windows-Install}
 547
 548 \end_inset
 549
 550 .
 551  More detailled instructions follow below.
 552 \layout Section
 553
 554 Configure Options
 555 \begin_inset LatexCommand \index{Options SDCC configuration}
 556
 557 \end_inset
 558
 559
 560 \layout Standard
 561
 562 The install paths, search paths and other options are defined when running
 563  'configure'.
 564  The defaults can be overridden by:
 565 \layout List
 566 \labelwidthstring 00.00.0000
 567
 568 -
 569 \begin_inset ERT
 570 status Collapsed
 571
 572 \layout Standard
 573
 574 \backslash
 575 /
 576 \end_inset
 577
 578 -prefix see table below
 579 \layout List
 580 \labelwidthstring 00.00.0000
 581
 582 -
 583 \begin_inset ERT
 584 status Collapsed
 585
 586 \layout Standard
 587
 588 \backslash
 589 /
 590 \end_inset
 591
 592 -exec_prefix see table below
 593 \layout List
 594 \labelwidthstring 00.00.0000
 595
 596 -
 597 \begin_inset ERT
 598 status Collapsed
 599
 600 \layout Standard
 601
 602 \backslash
 603 /
 604 \end_inset
 605
 606 -bindir see table below
 607 \layout List
 608 \labelwidthstring 00.00.0000
 609
 610 -
 611 \begin_inset ERT
 612 status Collapsed
 613
 614 \layout Standard
 615
 616 \backslash
 617 /
 618 \end_inset
 619
 620 -datadir see table below
 621 \layout List
 622 \labelwidthstring 00.00.0000
 623
 624 docdir environment variable, see table below
 625 \layout List
 626 \labelwidthstring 00.00.0000
 627
 628 include_dir_suffix environment variable, see table below
 629 \layout List
 630 \labelwidthstring 00.00.0000
 631
 632 lib_dir_suffix environment variable, see table below
 633 \layout List
 634 \labelwidthstring 00.00.0000
 635
 636 sdccconf_h_dir_separator environment variable, either / or
 637 \backslash
 638
 639 \backslash
 640  makes sense here.
 641  This character will only be used in sdccconf.h; don't forget it's a C-header,
 642  therefore a double-backslash is needed there.
 643 \layout List
 644 \labelwidthstring 00.00.0000
 645
 646 -
 647 \begin_inset ERT
 648 status Collapsed
 649
 650 \layout Standard
 651
 652 \backslash
 653 /
 654 \end_inset
 655
 656 -disable-mcs51-port Excludes the Intel mcs51 port
 657 \layout List
 658 \labelwidthstring 00.00.0000
 659
 660 -
 661 \begin_inset ERT
 662 status Collapsed
 663
 664 \layout Standard
 665
 666 \backslash
 667 /
 668 \end_inset
 669
 670 -disable-gbz80-port Excludes the Gameboy gbz80 port
 671 \layout List
 672 \labelwidthstring 00.00.0000
 673
 674 -
 675 \begin_inset ERT
 676 status Collapsed
 677
 678 \layout Standard
 679
 680 \backslash
 681 /
 682 \end_inset
 683
 684 -disable-z80-port Excludes the z80 port
 685 \layout List
 686 \labelwidthstring 00.00.0000
 687
 688 -
 689 \begin_inset ERT
 690 status Collapsed
 691
 692 \layout Standard
 693
 694 \backslash
 695 /
 696 \end_inset
 697
 698 -disable-avr-port Excludes the AVR port
 699 \layout List
 700 \labelwidthstring 00.00.0000
 701
 702 -
 703 \begin_inset ERT
 704 status Collapsed
 705
 706 \layout Standard
 707
 708 \backslash
 709 /
 710 \end_inset
 711
 712 -disable-ds390-port Excludes the DS390 port
 713 \layout List
 714 \labelwidthstring 00.00.0000
 715
 716 -
 717 \begin_inset ERT
 718 status Collapsed
 719
 720 \layout Standard
 721
 722 \backslash
 723 /
 724 \end_inset
 725
 726 -disable-hc08-port Excludes the HC08 port
 727 \layout List
 728 \labelwidthstring 00.00.0000
 729
 730 -
 731 \begin_inset ERT
 732 status Collapsed
 733
 734 \layout Standard
 735
 736 \backslash
 737 /
 738 \end_inset
 739
 740 -disable-pic-port Excludes the PIC port
 741 \layout List
 742 \labelwidthstring 00.00.0000
 743
 744 -
 745 \begin_inset ERT
 746 status Collapsed
 747
 748 \layout Standard
 749
 750 \backslash
 751 /
 752 \end_inset
 753
 754 -disable-xa51-port Excludes the XA51 port
 755 \layout List
 756 \labelwidthstring 00.00.0000
 757
 758 -
 759 \begin_inset ERT
 760 status Collapsed
 761
 762 \layout Standard
 763
 764 \backslash
 765 /
 766 \end_inset
 767
 768 -disable-ucsim Disables configuring and building of ucsim
 769 \layout List
 770 \labelwidthstring 00.00.0000
 771
 772 -
 773 \begin_inset ERT
 774 status Collapsed
 775
 776 \layout Standard
 777
 778 \backslash
 779 /
 780 \end_inset
 781
 782 -disable-device-lib-build Disables automatically building device libraries
 783 \layout List
 784 \labelwidthstring 00.00.0000
 785
 786 -
 787 \begin_inset ERT
 788 status Collapsed
 789
 790 \layout Standard
 791
 792 \backslash
 793 /
 794 \end_inset
 795
 796 -disable-packihx Disables building packihx
 797 \layout List
 798 \labelwidthstring 00.00.0000
 799
 800 -
 801 \begin_inset ERT
 802 status Collapsed
 803
 804 \layout Standard
 805
 806 \backslash
 807 /
 808 \end_inset
 809
 810 -enable-libgc Use the Bohem memory allocator.
 811  Lower runtime footprint.
 812 \layout Standard
 813
 814 Furthermore the environment variables CC, CFLAGS, ...
 815  the tools and their arguments can be influenced.
 816  Please see `configure -
 817 \begin_inset ERT
 818 status Collapsed
 819
 820 \layout Standard
 821
 822 \backslash
 823 /
 824 \end_inset
 825
 826 -help` and the man/info pages of `configure` for details.
 827 \newline
 828
 829 \newline
 830 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 831  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 832 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 833  At the moment it's not possible to change the default settings (it was
 834  simply never required).
 835 \newline
 836
 837 \newline
 838 These configure options are compiled into the binaries, and can only be
 839  changed by rerunning 'configure' and recompiling SDCC.
 840  The configure options are written in
 841 \emph on
 842 italics
 843 \emph default
 844  to distinguish them from run time environment variables (see section search
 845  paths).
 846 \newline
 847
 848 \newline
 849 The settings for
 850 \begin_inset Quotes sld
 851 \end_inset
 852
 853 Win32 builds
 854 \begin_inset Quotes srd
 855 \end_inset
 856
 857  are used by the SDCC team to build the official Win32 binaries.
 858  The SDCC team uses Mingw32 to build the official Windows binaries, because
 859  it's
 860 \layout Enumerate
 861
 862 open source,
 863 \layout Enumerate
 864
 865 a gcc compiler and last but not least
 866 \layout Enumerate
 867
 868 the binaries can be built by cross compiling on Sourceforge's compile farm.
 869 \layout Standard
 870
 871 See the examples, how to pass the Win32 settings to 'configure'.
 872  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 873  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 874  for Win32.
 875 \newline
 876
 877 \newline
 878 These defaults are:
 879 \newline
 880
 881 \layout Standard
 882 \align center
 883
 884 \begin_inset  Tabular
 885 <lyxtabular version="3" rows="8" columns="3">
 886 <features>
 887 <column alignment="block" valignment="top" leftline="true" width="0in">
 888 <column alignment="block" valignment="top" leftline="true" width="0in">
 889 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 890 <row topline="true" bottomline="true">
 891 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 892 \begin_inset Text
 893
 894 \layout Standard
 895
 896 Variable
 897 \end_inset
 898 </cell>
 899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 900 \begin_inset Text
 901
 902 \layout Standard
 903
 904 default
 905 \end_inset
 906 </cell>
 907 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 908 \begin_inset Text
 909
 910 \layout Standard
 911
 912 Win32 builds
 913 \end_inset
 914 </cell>
 915 </row>
 916 <row topline="true">
 917 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 918 \begin_inset Text
 919
 920 \layout Standard
 921
 922
 923 \emph on
 924 PREFIX
 925 \end_inset
 926 </cell>
 927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 928 \begin_inset Text
 929
 930 \layout Standard
 931
 932 /usr/local
 933 \end_inset
 934 </cell>
 935 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 936 \begin_inset Text
 937
 938 \layout Standard
 939
 940
 941 \backslash
 942 sdcc
 943 \end_inset
 944 </cell>
 945 </row>
 946 <row topline="true">
 947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 948 \begin_inset Text
 949
 950 \layout Standard
 951
 952
 953 \emph on
 954 EXEC_PREFIX
 955 \end_inset
 956 </cell>
 957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 958 \begin_inset Text
 959
 960 \layout Standard
 961
 962
 963 \emph on
 964 $PREFIX
 965 \end_inset
 966 </cell>
 967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 968 \begin_inset Text
 969
 970 \layout Standard
 971
 972
 973 \emph on
 974 $PREFIX
 975 \end_inset
 976 </cell>
 977 </row>
 978 <row topline="true">
 979 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 980 \begin_inset Text
 981
 982 \layout Standard
 983
 984
 985 \emph on
 986 BINDIR
 987 \end_inset
 988 </cell>
 989 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 990 \begin_inset Text
 991
 992 \layout Standard
 993
 994
 995 \emph on
 996 $EXECPREFIX
 997 \emph default
 998 /bin
 999 \end_inset
1000 </cell>
1001 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1002 \begin_inset Text
1003
1004 \layout Standard
1005
1006
1007 \emph on
1008 $EXECPREFIX
1009 \emph default
1010
1011 \backslash
1012 bin
1013 \end_inset
1014 </cell>
1015 </row>
1016 <row topline="true">
1017 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1018 \begin_inset Text
1019
1020 \layout Standard
1021
1022
1023 \emph on
1024 DATADIR
1025 \end_inset
1026 </cell>
1027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1028 \begin_inset Text
1029
1030 \layout Standard
1031
1032
1033 \emph on
1034 $PREFIX
1035 \emph default
1036 /share
1037 \end_inset
1038 </cell>
1039 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1040 \begin_inset Text
1041
1042 \layout Standard
1043
1044
1045 \emph on
1046 $PREFIX
1047 \end_inset
1048 </cell>
1049 </row>
1050 <row topline="true">
1051 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1052 \begin_inset Text
1053
1054 \layout Standard
1055
1056
1057 \emph on
1058 DOCDIR
1059 \end_inset
1060 </cell>
1061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1062 \begin_inset Text
1063
1064 \layout Standard
1065
1066
1067 \emph on
1068 $DATADIR
1069 \emph default
1070 /sdcc/doc
1071 \end_inset
1072 </cell>
1073 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1074 \begin_inset Text
1075
1076 \layout Standard
1077
1078
1079 \emph on
1080 $DATADIR
1081 \emph default
1082
1083 \backslash
1084 doc
1085 \end_inset
1086 </cell>
1087 </row>
1088 <row topline="true">
1089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1090 \begin_inset Text
1091
1092 \layout Standard
1093
1094
1095 \emph on
1096 INCLUDE_DIR_SUFFIX
1097 \end_inset
1098 </cell>
1099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1100 \begin_inset Text
1101
1102 \layout Standard
1103
1104 sdcc/include
1105 \end_inset
1106 </cell>
1107 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1108 \begin_inset Text
1109
1110 \layout Standard
1111
1112 include
1113 \end_inset
1114 </cell>
1115 </row>
1116 <row topline="true" bottomline="true">
1117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1118 \begin_inset Text
1119
1120 \layout Standard
1121
1122
1123 \emph on
1124 LIB_DIR_SUFFIX
1125 \end_inset
1126 </cell>
1127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1128 \begin_inset Text
1129
1130 \layout Standard
1131
1132 sdcc/lib
1133 \end_inset
1134 </cell>
1135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1136 \begin_inset Text
1137
1138 \layout Standard
1139
1140 lib
1141 \end_inset
1142 </cell>
1143 </row>
1144 </lyxtabular>
1145
1146 \end_inset
1147
1148
1149 \newline
1150
1151 \layout Standard
1152 \noindent
1153 'configure' also computes relative paths.
1154  This is needed for full relocatability of a binary package and to complete
1155  search paths (see section search paths below):
1156 \newline
1157
1158 \layout Standard
1159 \align center
1160
1161 \begin_inset  Tabular
1162 <lyxtabular version="3" rows="4" columns="3">
1163 <features>
1164 <column alignment="block" valignment="top" leftline="true" width="0in">
1165 <column alignment="block" valignment="top" leftline="true" width="0in">
1166 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1167 <row topline="true" bottomline="true">
1168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1169 \begin_inset Text
1170
1171 \layout Standard
1172
1173 Variable (computed)
1174 \end_inset
1175 </cell>
1176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1177 \begin_inset Text
1178
1179 \layout Standard
1180
1181 default
1182 \end_inset
1183 </cell>
1184 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1185 \begin_inset Text
1186
1187 \layout Standard
1188
1189 Win32 builds
1190 \end_inset
1191 </cell>
1192 </row>
1193 <row topline="true" bottomline="true">
1194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1195 \begin_inset Text
1196
1197 \layout Standard
1198
1199
1200 \emph on
1201 BIN2DATA_DIR
1202 \end_inset
1203 </cell>
1204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1205 \begin_inset Text
1206
1207 \layout Standard
1208
1209 ../share
1210 \end_inset
1211 </cell>
1212 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1213 \begin_inset Text
1214
1215 \layout Standard
1216
1217 ..
1218 \end_inset
1219 </cell>
1220 </row>
1221 <row bottomline="true">
1222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1223 \begin_inset Text
1224
1225 \layout Standard
1226
1227
1228 \emph on
1229 PREFIX2BIN_DIR
1230 \end_inset
1231 </cell>
1232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1233 \begin_inset Text
1234
1235 \layout Standard
1236
1237 bin
1238 \end_inset
1239 </cell>
1240 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1241 \begin_inset Text
1242
1243 \layout Standard
1244
1245 bin
1246 \end_inset
1247 </cell>
1248 </row>
1249 <row bottomline="true">
1250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1251 \begin_inset Text
1252
1253 \layout Standard
1254
1255
1256 \emph on
1257 PREFIX2DATA_DIR
1258 \end_inset
1259 </cell>
1260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1261 \begin_inset Text
1262
1263 \layout Standard
1264
1265 share/sdcc
1266 \end_inset
1267 </cell>
1268 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1269 \begin_inset Text
1270
1271 \layout Standard
1272
1273 \end_inset
1274 </cell>
1275 </row>
1276 </lyxtabular>
1277
1278 \end_inset
1279
1280
1281 \newline
1282
1283 \layout Standard
1284 \noindent
1285 Examples:
1286 \layout LyX-Code
1287
1288 ./configure
1289 \newline
1290 ./configure -
1291 \begin_inset ERT
1292 status Collapsed
1293
1294 \layout Standard
1295
1296 \backslash
1297 /
1298 \end_inset
1299
1300 -prefix=
1301 \begin_inset Quotes srd
1302 \end_inset
1303
1304 /usr/bin
1305 \begin_inset Quotes srd
1306 \end_inset
1307
1308  -
1309 \begin_inset ERT
1310 status Collapsed
1311
1312 \layout Standard
1313
1314 \backslash
1315 /
1316 \end_inset
1317
1318 -datadir=
1319 \begin_inset Quotes srd
1320 \end_inset
1321
1322 /usr/share
1323 \begin_inset Quotes srd
1324 \end_inset
1325
1326
1327 \newline
1328 ./configure -
1329 \begin_inset ERT
1330 status Collapsed
1331
1332 \layout Standard
1333
1334 \backslash
1335 /
1336 \end_inset
1337
1338 -disable-avr-port -
1339 \begin_inset ERT
1340 status Collapsed
1341
1342 \layout Standard
1343
1344 \backslash
1345 /
1346 \end_inset
1347
1348 -disable-xa51-port
1349 \layout Standard
1350
1351 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1352 32'):
1353 \layout LyX-Code
1354
1355 ./configure
1356 \backslash
1357
1358 \newline
1359 CC=
1360 \begin_inset Quotes srd
1361 \end_inset
1362
1363 i586-mingw32msvc-gcc
1364 \begin_inset Quotes srd
1365 \end_inset
1366
1367  CXX=
1368 \begin_inset Quotes srd
1369 \end_inset
1370
1371 i586-mingw32msvc-g++
1372 \begin_inset Quotes srd
1373 \end_inset
1374
1375
1376 \backslash
1377
1378 \newline
1379 RANLIB=
1380 \begin_inset Quotes srd
1381 \end_inset
1382
1383 i586-mingw32msvc-ranlib
1384 \begin_inset Quotes srd
1385 \end_inset
1386
1387
1388 \backslash
1389
1390 \newline
1391 STRIP=
1392 \begin_inset Quotes srd
1393 \end_inset
1394
1395 i586-mingw32msvc-strip
1396 \begin_inset Quotes srd
1397 \end_inset
1398
1399
1400 \backslash
1401
1402 \newline
1403 -
1404 \begin_inset ERT
1405 status Collapsed
1406
1407 \layout Standard
1408
1409 \backslash
1410 /
1411 \end_inset
1412
1413 -prefix=
1414 \begin_inset Quotes srd
1415 \end_inset
1416
1417 /sdcc
1418 \begin_inset Quotes srd
1419 \end_inset
1420
1421
1422 \backslash
1423
1424 \newline
1425 -
1426 \begin_inset ERT
1427 status Collapsed
1428
1429 \layout Standard
1430
1431 \backslash
1432 /
1433 \end_inset
1434
1435 -datadir=
1436 \begin_inset Quotes srd
1437 \end_inset
1438
1439 /sdcc
1440 \begin_inset Quotes srd
1441 \end_inset
1442
1443
1444 \backslash
1445
1446 \newline
1447 docdir=
1448 \begin_inset Quotes srd
1449 \end_inset
1450
1451 /sdcc/doc
1452 \begin_inset Quotes srd
1453 \end_inset
1454
1455
1456 \backslash
1457
1458 \newline
1459 include_dir_suffix=
1460 \begin_inset Quotes srd
1461 \end_inset
1462
1463 include
1464 \begin_inset Quotes srd
1465 \end_inset
1466
1467
1468 \backslash
1469
1470 \newline
1471 lib_dir_suffix=
1472 \begin_inset Quotes srd
1473 \end_inset
1474
1475 lib
1476 \begin_inset Quotes srd
1477 \end_inset
1478
1479
1480 \backslash
1481
1482 \newline
1483 sdccconf_h_dir_separator=
1484 \begin_inset Quotes srd
1485 \end_inset
1486
1487
1488 \backslash
1489
1490 \backslash
1491
1492 \backslash
1493
1494 \backslash
1495
1496 \begin_inset Quotes srd
1497 \end_inset
1498
1499
1500 \backslash
1501
1502 \newline
1503 -
1504 \begin_inset ERT
1505 status Collapsed
1506
1507 \layout Standard
1508
1509 \backslash
1510 /
1511 \end_inset
1512
1513 -disable-device-lib-build
1514 \backslash
1515
1516 \newline
1517 -
1518 \begin_inset ERT
1519 status Collapsed
1520
1521 \layout Standard
1522
1523 \backslash
1524 /
1525 \end_inset
1526
1527 -disable-ucsim
1528 \backslash
1529
1530 \newline
1531 -
1532 \begin_inset ERT
1533 status Collapsed
1534
1535 \layout Standard
1536
1537 \backslash
1538 /
1539 \end_inset
1540
1541 -host=i586-mingw32msvc -
1542 \begin_inset ERT
1543 status Collapsed
1544
1545 \layout Standard
1546
1547 \backslash
1548 /
1549 \end_inset
1550
1551 -build=unknown-unknown-linux-gnu
1552 \layout Standard
1553
1554 To
1555 \begin_inset Quotes sld
1556 \end_inset
1557
1558 cross
1559 \begin_inset Quotes srd
1560 \end_inset
1561
1562 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1563 ):
1564 \layout LyX-Code
1565
1566 ./configure -C
1567 \backslash
1568
1569 \newline
1570 CFLAGS=
1571 \begin_inset Quotes srd
1572 \end_inset
1573
1574 -mno-cygwin -O2
1575 \begin_inset Quotes srd
1576 \end_inset
1577
1578
1579 \backslash
1580
1581 \newline
1582 LDFLAGS=
1583 \begin_inset Quotes srd
1584 \end_inset
1585
1586 -mno-cygwin
1587 \begin_inset Quotes srd
1588 \end_inset
1589
1590
1591 \backslash
1592
1593 \newline
1594 -
1595 \begin_inset ERT
1596 status Collapsed
1597
1598 \layout Standard
1599
1600 \backslash
1601 /
1602 \end_inset
1603
1604 -prefix=
1605 \begin_inset Quotes srd
1606 \end_inset
1607
1608 /sdcc
1609 \begin_inset Quotes srd
1610 \end_inset
1611
1612
1613 \backslash
1614
1615 \newline
1616 -
1617 \begin_inset ERT
1618 status Collapsed
1619
1620 \layout Standard
1621
1622 \backslash
1623 /
1624 \end_inset
1625
1626 -datadir=
1627 \begin_inset Quotes srd
1628 \end_inset
1629
1630 /sdcc
1631 \begin_inset Quotes srd
1632 \end_inset
1633
1634
1635 \backslash
1636
1637 \newline
1638 docdir=
1639 \begin_inset Quotes srd
1640 \end_inset
1641
1642 /sdcc/doc
1643 \begin_inset Quotes srd
1644 \end_inset
1645
1646
1647 \backslash
1648
1649 \newline
1650 include_dir_suffix=
1651 \begin_inset Quotes srd
1652 \end_inset
1653
1654 include
1655 \begin_inset Quotes srd
1656 \end_inset
1657
1658
1659 \backslash
1660
1661 \newline
1662 lib_dir_suffix=
1663 \begin_inset Quotes srd
1664 \end_inset
1665
1666 lib
1667 \begin_inset Quotes srd
1668 \end_inset
1669
1670
1671 \backslash
1672
1673 \newline
1674 sdccconf_h_dir_separator=
1675 \begin_inset Quotes srd
1676 \end_inset
1677
1678
1679 \backslash
1680
1681 \backslash
1682
1683 \backslash
1684
1685 \backslash
1686
1687 \begin_inset Quotes srd
1688 \end_inset
1689
1690
1691 \backslash
1692
1693 \newline
1694 -
1695 \begin_inset ERT
1696 status Collapsed
1697
1698 \layout Standard
1699
1700 \backslash
1701 /
1702 \end_inset
1703
1704 -disable-ucsim
1705 \layout Standard
1706
1707 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1708  The option '-
1709 \begin_inset ERT
1710 status Collapsed
1711
1712 \layout Standard
1713
1714 \backslash
1715 /
1716 \end_inset
1717
1718 -C' turns on caching, which gives a little bit extra speed.
1719  However if options are changed, it can be necessary to delete the config.cache
1720  file.
1721 \layout Section
1722
1723 Install paths
1724 \begin_inset LatexCommand \label{sub:Install-paths}
1725
1726 \end_inset
1727
1728
1729 \begin_inset LatexCommand \index{Install paths}
1730
1731 \end_inset
1732
1733
1734 \layout Standard
1735 \added_space_top medskip \align center
1736
1737 \begin_inset  Tabular
1738 <lyxtabular version="3" rows="5" columns="4">
1739 <features>
1740 <column alignment="center" valignment="top" leftline="true" width="0">
1741 <column alignment="center" valignment="top" leftline="true" width="0">
1742 <column alignment="center" valignment="top" leftline="true" width="0">
1743 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1744 <row topline="true" bottomline="true">
1745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1746 \begin_inset Text
1747
1748 \layout Standard
1749
1750
1751 \series bold
1752 Description
1753 \end_inset
1754 </cell>
1755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1756 \begin_inset Text
1757
1758 \layout Standard
1759
1760
1761 \series bold
1762 Path
1763 \end_inset
1764 </cell>
1765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1766 \begin_inset Text
1767
1768 \layout Standard
1769
1770
1771 \series bold
1772 Default
1773 \end_inset
1774 </cell>
1775 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1776 \begin_inset Text
1777
1778 \layout Standard
1779
1780
1781 \series bold
1782 Win32 builds
1783 \end_inset
1784 </cell>
1785 </row>
1786 <row topline="true">
1787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1788 \begin_inset Text
1789
1790 \layout Standard
1791
1792 Binary files*
1793 \end_inset
1794 </cell>
1795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1796 \begin_inset Text
1797
1798 \layout Standard
1799
1800
1801 \emph on
1802 $EXEC_PREFIX
1803 \end_inset
1804 </cell>
1805 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1806 \begin_inset Text
1807
1808 \layout Standard
1809
1810 /usr/local/bin
1811 \end_inset
1812 </cell>
1813 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1814 \begin_inset Text
1815
1816 \layout Standard
1817
1818
1819 \backslash
1820 sdcc
1821 \backslash
1822 bin
1823 \end_inset
1824 </cell>
1825 </row>
1826 <row topline="true">
1827 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1828 \begin_inset Text
1829
1830 \layout Standard
1831
1832 Include files
1833 \end_inset
1834 </cell>
1835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1836 \begin_inset Text
1837
1838 \layout Standard
1839
1840
1841 \emph on
1842 $DATADIR/ $INCLUDE_DIR_SUFFIX
1843 \end_inset
1844 </cell>
1845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1846 \begin_inset Text
1847
1848 \layout Standard
1849
1850 /usr/local/share/sdcc/include
1851 \end_inset
1852 </cell>
1853 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1854 \begin_inset Text
1855
1856 \layout Standard
1857
1858
1859 \backslash
1860 sdcc
1861 \backslash
1862 include
1863 \end_inset
1864 </cell>
1865 </row>
1866 <row topline="true">
1867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1868 \begin_inset Text
1869
1870 \layout Standard
1871
1872 Library file**
1873 \end_inset
1874 </cell>
1875 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1876 \begin_inset Text
1877
1878 \layout Standard
1879
1880
1881 \emph on
1882 $DATADIR/$LIB_DIR_SUFFIX
1883 \end_inset
1884 </cell>
1885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1886 \begin_inset Text
1887
1888 \layout Standard
1889
1890 /usr/local/share/sdcc/lib
1891 \end_inset
1892 </cell>
1893 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1894 \begin_inset Text
1895
1896 \layout Standard
1897
1898
1899 \backslash
1900 sdcc
1901 \backslash
1902 lib
1903 \end_inset
1904 </cell>
1905 </row>
1906 <row topline="true" bottomline="true">
1907 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1908 \begin_inset Text
1909
1910 \layout Standard
1911
1912 Documentation
1913 \end_inset
1914 </cell>
1915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1916 \begin_inset Text
1917
1918 \layout Standard
1919
1920
1921 \emph on
1922 $DOCDIR
1923 \end_inset
1924 </cell>
1925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1926 \begin_inset Text
1927
1928 \layout Standard
1929
1930 /usr/local/share/sdcc/doc
1931 \end_inset
1932 </cell>
1933 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1934 \begin_inset Text
1935
1936 \layout Standard
1937
1938
1939 \backslash
1940 sdcc
1941 \backslash
1942 doc
1943 \end_inset
1944 </cell>
1945 </row>
1946 </lyxtabular>
1947
1948 \end_inset
1949
1950
1951 \layout Verse
1952
1953
1954 \size footnotesize
1955 *compiler, preprocessor, assembler, and linker
1956 \newline
1957 **the
1958 \shape italic
1959 model
1960 \shape default
1961  is auto-appended by the compiler, e.g.
1962  small, large, z80, ds390 etc
1963 \layout Standard
1964 \noindent
1965 The install paths can still be changed during `make install` with e.g.:
1966 \layout LyX-Code
1967
1968 make install prefix=$(HOME)/local/sdcc
1969 \layout Standard
1970
1971 Of course this doesn't change the search paths compiled into the binaries.
1972 \newline
1973
1974 \newline
1975 Moreover the install path can be changed by defining DESTDIR
1976 \begin_inset LatexCommand \index{DESTDIR}
1977
1978 \end_inset
1979
1980 :
1981 \layout LyX-Code
1982
1983 make install DESTDIR=$(HOME)/sdcc.rpm/
1984 \layout Standard
1985
1986 Please note that DESTDIR must have a trailing slash!
1987 \layout Section
1988
1989 Search Paths
1990 \begin_inset LatexCommand \label{sub:Search-Paths}
1991
1992 \end_inset
1993
1994
1995 \begin_inset LatexCommand \index{Search path}
1996
1997 \end_inset
1998
1999
2000 \layout Standard
2001
2002 Some search paths or parts of them are determined by configure variables
2003  (in
2004 \emph on
2005 italics
2006 \emph default
2007 , see section above).
2008  Further search paths are determined by environment variables during runtime.
2009
2010 \newline
2011 The paths searched when running the compiler are as follows (the first catch
2012  wins):
2013 \newline
2014
2015 \newline
2016 1.
2017  Binary files (preprocessor, assembler and linker)
2018 \newline
2019
2020 \layout Standard
2021 \align center
2022
2023 \begin_inset  Tabular
2024 <lyxtabular version="3" rows="4" columns="3">
2025 <features>
2026 <column alignment="block" valignment="top" leftline="true" width="0in">
2027 <column alignment="block" valignment="top" leftline="true" width="0in">
2028 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2029 <row topline="true" bottomline="true">
2030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2031 \begin_inset Text
2032
2033 \layout Standard
2034
2035 Search path
2036 \end_inset
2037 </cell>
2038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2039 \begin_inset Text
2040
2041 \layout Standard
2042
2043 default
2044 \end_inset
2045 </cell>
2046 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2047 \begin_inset Text
2048
2049 \layout Standard
2050
2051 Win32 builds
2052 \end_inset
2053 </cell>
2054 </row>
2055 <row topline="true">
2056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2057 \begin_inset Text
2058
2059 \layout Standard
2060
2061 $SDCC_HOME/
2062 \emph on
2063 $PPREFIX2BIN_DIR
2064 \end_inset
2065 </cell>
2066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2067 \begin_inset Text
2068
2069 \layout Standard
2070
2071 $SDCC_HOME/bin
2072 \end_inset
2073 </cell>
2074 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2075 \begin_inset Text
2076
2077 \layout Standard
2078
2079 $SDCC_HOME
2080 \backslash
2081 bin
2082 \end_inset
2083 </cell>
2084 </row>
2085 <row topline="true">
2086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2087 \begin_inset Text
2088
2089 \layout Standard
2090
2091 Path of argv[0] (if available)
2092 \end_inset
2093 </cell>
2094 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2095 \begin_inset Text
2096
2097 \layout Standard
2098
2099 Path of argv[0]
2100 \end_inset
2101 </cell>
2102 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2103 \begin_inset Text
2104
2105 \layout Standard
2106
2107 Path of argv[0]
2108 \end_inset
2109 </cell>
2110 </row>
2111 <row topline="true" bottomline="true">
2112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2113 \begin_inset Text
2114
2115 \layout Standard
2116
2117 $PATH
2118 \end_inset
2119 </cell>
2120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2121 \begin_inset Text
2122
2123 \layout Standard
2124
2125 $PATH
2126 \end_inset
2127 </cell>
2128 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2129 \begin_inset Text
2130
2131 \layout Standard
2132
2133 $PATH
2134 \end_inset
2135 </cell>
2136 </row>
2137 </lyxtabular>
2138
2139 \end_inset
2140
2141
2142 \newline
2143
2144 \layout Standard
2145 \noindent
2146 2.
2147  Include files
2148 \newline
2149
2150 \layout Standard
2151 \align center
2152
2153 \begin_inset  Tabular
2154 <lyxtabular version="3" rows="6" columns="3">
2155 <features>
2156 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2157 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2158 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2159 <row topline="true" bottomline="true">
2160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2161 \begin_inset Text
2162
2163 \layout Standard
2164
2165 Search path
2166 \end_inset
2167 </cell>
2168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2169 \begin_inset Text
2170
2171 \layout Standard
2172
2173 default
2174 \end_inset
2175 </cell>
2176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2177 \begin_inset Text
2178
2179 \layout Standard
2180
2181 Win32 builds
2182 \end_inset
2183 </cell>
2184 </row>
2185 <row topline="true">
2186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2187 \begin_inset Text
2188
2189 \layout Standard
2190
2191 -
2192 \begin_inset ERT
2193 status Collapsed
2194
2195 \layout Standard
2196
2197 \backslash
2198 /
2199 \end_inset
2200
2201 -I dir
2202 \end_inset
2203 </cell>
2204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2205 \begin_inset Text
2206
2207 \layout Standard
2208
2209 -
2210 \begin_inset ERT
2211 status Collapsed
2212
2213 \layout Standard
2214
2215 \backslash
2216 /
2217 \end_inset
2218
2219 -I dir
2220 \end_inset
2221 </cell>
2222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2223 \begin_inset Text
2224
2225 \layout Standard
2226
2227 -
2228 \begin_inset ERT
2229 status Collapsed
2230
2231 \layout Standard
2232
2233 \backslash
2234 /
2235 \end_inset
2236
2237 -I dir
2238 \end_inset
2239 </cell>
2240 </row>
2241 <row topline="true">
2242 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2243 \begin_inset Text
2244
2245 \layout Standard
2246
2247 $SDCC_INCLUDE
2248 \end_inset
2249 </cell>
2250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2251 \begin_inset Text
2252
2253 \layout Standard
2254
2255 $SDCC_INCLUDE
2256 \end_inset
2257 </cell>
2258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2259 \begin_inset Text
2260
2261 \layout Standard
2262
2263 $SDCC_INCLUDE
2264 \end_inset
2265 </cell>
2266 </row>
2267 <row topline="true">
2268 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2269 \begin_inset Text
2270
2271 \layout Standard
2272
2273 $SDCC_HOME/
2274 \newline
2275
2276 \emph on
2277 $PREFIX2DATA_DIR/
2278 \newline
2279 $INCLUDE_DIR_SUFFIX
2280 \end_inset
2281 </cell>
2282 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2283 \begin_inset Text
2284
2285 \layout Standard
2286
2287 $SDCC_ HOME/
2288 \newline
2289 share/sdcc/
2290 \newline
2291 include
2292 \end_inset
2293 </cell>
2294 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2295 \begin_inset Text
2296
2297 \layout Standard
2298
2299 $SDCC_HOME
2300 \backslash
2301 include
2302 \end_inset
2303 </cell>
2304 </row>
2305 <row topline="true">
2306 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2307 \begin_inset Text
2308
2309 \layout Standard
2310
2311 path(argv[0])/
2312 \newline
2313
2314 \emph on
2315 $BIN2DATADIR/
2316 \emph default
2317
2318 \newline
2319
2320 \emph on
2321 $INCLUDE_DIR_SUFFIX
2322 \end_inset
2323 </cell>
2324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2325 \begin_inset Text
2326
2327 \layout Standard
2328
2329 path(argv[0])/
2330 \newline
2331 ../sdcc/include
2332 \newline
2333 \SpecialChar ~
2334 \SpecialChar ~
2335 \SpecialChar ~
2336 \SpecialChar ~
2337 \SpecialChar ~
2338 \SpecialChar ~
2339 \SpecialChar ~
2340 \SpecialChar ~
2341 \SpecialChar ~
2342 \SpecialChar ~
2343 \SpecialChar ~
2344 \SpecialChar ~
2345 \SpecialChar ~
2346 \SpecialChar ~
2347 \SpecialChar ~
2348 \SpecialChar ~
2349 \SpecialChar ~
2350 \SpecialChar ~
2351 \SpecialChar ~
2352 \SpecialChar ~
2353 \SpecialChar ~
2354 \SpecialChar ~
2355 \SpecialChar ~
2356 \SpecialChar ~
2357 \SpecialChar ~
2358 \SpecialChar ~
2359 \SpecialChar ~
2360 \SpecialChar ~
2361 \SpecialChar ~
2362 \SpecialChar ~
2363 \SpecialChar ~
2364 \SpecialChar ~
2365 \SpecialChar ~
2366 \SpecialChar ~
2367 \SpecialChar ~
2368 \SpecialChar ~
2369 \SpecialChar ~
2370 \SpecialChar ~
2371
2372 \end_inset
2373 </cell>
2374 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2375 \begin_inset Text
2376
2377 \layout Standard
2378
2379 path(argv[0])
2380 \backslash
2381 ..
2382 \backslash
2383 include
2384 \end_inset
2385 </cell>
2386 </row>
2387 <row topline="true" bottomline="true">
2388 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2389 \begin_inset Text
2390
2391 \layout Standard
2392
2393
2394 \emph on
2395 $DATADIR/
2396 \emph default
2397
2398 \newline
2399
2400 \emph on
2401 $INCLUDE_DIR_SUFFIX
2402 \end_inset
2403 </cell>
2404 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2405 \begin_inset Text
2406
2407 \layout Standard
2408
2409 /usr/local/share/sdcc/
2410 \newline
2411 include
2412 \end_inset
2413 </cell>
2414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2415 \begin_inset Text
2416
2417 \layout Standard
2418
2419 (not on Win32)
2420 \end_inset
2421 </cell>
2422 </row>
2423 </lyxtabular>
2424
2425 \end_inset
2426
2427
2428 \newline
2429
2430 \layout Standard
2431 \noindent
2432 The option -
2433 \begin_inset ERT
2434 status Collapsed
2435
2436 \layout Standard
2437
2438 \backslash
2439 /
2440 \end_inset
2441
2442 -nostdinc disables the last two search paths.
2443 \newline
2444
2445 \newline
2446 3.
2447  Library files
2448 \newline
2449
2450 \layout Standard
2451
2452 With the exception of
2453 \begin_inset Quotes sld
2454 \end_inset
2455
2456 -
2457 \begin_inset ERT
2458 status Collapsed
2459
2460 \layout Standard
2461
2462 \backslash
2463 /
2464 \end_inset
2465
2466 -L dir
2467 \begin_inset Quotes srd
2468 \end_inset
2469
2470  the
2471 \shape italic
2472 model
2473 \shape default
2474  is auto-appended by the compiler (e.g.
2475  small, large, z80, ds390 etc.).
2476
2477 \newline
2478
2479 \layout Standard
2480 \align center
2481
2482 \begin_inset  Tabular
2483 <lyxtabular version="3" rows="6" columns="3">
2484 <features>
2485 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2486 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2487 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2488 <row topline="true" bottomline="true">
2489 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2490 \begin_inset Text
2491
2492 \layout Standard
2493
2494 Search path
2495 \end_inset
2496 </cell>
2497 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2498 \begin_inset Text
2499
2500 \layout Standard
2501
2502 default
2503 \end_inset
2504 </cell>
2505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2506 \begin_inset Text
2507
2508 \layout Standard
2509
2510 Win32 builds
2511 \end_inset
2512 </cell>
2513 </row>
2514 <row topline="true">
2515 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2516 \begin_inset Text
2517
2518 \layout Standard
2519
2520 -
2521 \begin_inset ERT
2522 status Collapsed
2523
2524 \layout Standard
2525
2526 \backslash
2527 /
2528 \end_inset
2529
2530 -L dir
2531 \end_inset
2532 </cell>
2533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2534 \begin_inset Text
2535
2536 \layout Standard
2537
2538 -
2539 \begin_inset ERT
2540 status Collapsed
2541
2542 \layout Standard
2543
2544 \backslash
2545 /
2546 \end_inset
2547
2548 -L dir
2549 \end_inset
2550 </cell>
2551 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2552 \begin_inset Text
2553
2554 \layout Standard
2555
2556 -
2557 \begin_inset ERT
2558 status Collapsed
2559
2560 \layout Standard
2561
2562 \backslash
2563 /
2564 \end_inset
2565
2566 -L dir
2567 \end_inset
2568 </cell>
2569 </row>
2570 <row topline="true">
2571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2572 \begin_inset Text
2573
2574 \layout Standard
2575
2576 $SDCC_LIB/
2577 \newline
2578
2579 \emph on
2580 <model>
2581 \end_inset
2582 </cell>
2583 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2584 \begin_inset Text
2585
2586 \layout Standard
2587
2588 $SDCC_LIB/
2589 \newline
2590
2591 \emph on
2592 <model>
2593 \end_inset
2594 </cell>
2595 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2596 \begin_inset Text
2597
2598 \layout Standard
2599
2600 $SDCC_LIB
2601 \backslash
2602
2603 \newline
2604
2605 \emph on
2606 <model>
2607 \end_inset
2608 </cell>
2609 </row>
2610 <row topline="true">
2611 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2612 \begin_inset Text
2613
2614 \layout Standard
2615
2616 $SDCC_HOME/
2617 \newline
2618
2619 \emph on
2620 $PREFIX2DATA_DIR/
2621 \newline
2622 $LIB_DIR_SUFFIX/<model>
2623 \end_inset
2624 </cell>
2625 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2626 \begin_inset Text
2627
2628 \layout Standard
2629
2630 $SDCC_HOME/
2631 \newline
2632 share/sdcc/
2633 \newline
2634 lib/
2635 \emph on
2636 <model>
2637 \end_inset
2638 </cell>
2639 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2640 \begin_inset Text
2641
2642 \layout Standard
2643
2644 $SDCC_HOME
2645 \backslash
2646 lib
2647 \backslash
2648
2649 \emph on
2650
2651 \newline
2652 <model>
2653 \end_inset
2654 </cell>
2655 </row>
2656 <row topline="true">
2657 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2658 \begin_inset Text
2659
2660 \layout Standard
2661
2662 path(argv[0])/
2663 \newline
2664
2665 \emph on
2666 $BIN2DATADIR/
2667 \emph default
2668
2669 \newline
2670
2671 \emph on
2672 $LIB_DIR_SUFFIX/<model>
2673 \end_inset
2674 </cell>
2675 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2676 \begin_inset Text
2677
2678 \layout Standard
2679
2680 path(argv[0])/
2681 \newline
2682 ../sdcc/lib/
2683 \emph on
2684 <model>
2685 \newline
2686 \SpecialChar ~
2687 \SpecialChar ~
2688 \SpecialChar ~
2689 \SpecialChar ~
2690 \SpecialChar ~
2691 \SpecialChar ~
2692 \SpecialChar ~
2693 \SpecialChar ~
2694 \SpecialChar ~
2695 \SpecialChar ~
2696 \SpecialChar ~
2697 \SpecialChar ~
2698 \SpecialChar ~
2699 \SpecialChar ~
2700 \SpecialChar ~
2701 \SpecialChar ~
2702 \SpecialChar ~
2703 \SpecialChar ~
2704 \SpecialChar ~
2705 \SpecialChar ~
2706 \SpecialChar ~
2707 \SpecialChar ~
2708 \SpecialChar ~
2709 \SpecialChar ~
2710 \SpecialChar ~
2711 \SpecialChar ~
2712 \SpecialChar ~
2713 \SpecialChar ~
2714 \SpecialChar ~
2715 \SpecialChar ~
2716 \SpecialChar ~
2717 \SpecialChar ~
2718 \SpecialChar ~
2719 \SpecialChar ~
2720 \SpecialChar ~
2721 \SpecialChar ~
2722 \SpecialChar ~
2723 \SpecialChar ~
2724 \SpecialChar ~
2725
2726 \end_inset
2727 </cell>
2728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2729 \begin_inset Text
2730
2731 \layout Standard
2732
2733 path(argv[0])
2734 \backslash
2735
2736 \newline
2737 ..
2738 \backslash
2739 lib
2740 \backslash
2741
2742 \emph on
2743 <model>
2744 \newline
2745 \SpecialChar ~
2746 \SpecialChar ~
2747 \SpecialChar ~
2748 \SpecialChar ~
2749 \SpecialChar ~
2750 \SpecialChar ~
2751 \SpecialChar ~
2752 \SpecialChar ~
2753 \SpecialChar ~
2754 \SpecialChar ~
2755 \SpecialChar ~
2756 \SpecialChar ~
2757 \SpecialChar ~
2758 \SpecialChar ~
2759 \SpecialChar ~
2760 \SpecialChar ~
2761 \SpecialChar ~
2762 \SpecialChar ~
2763 \SpecialChar ~
2764 \SpecialChar ~
2765 \SpecialChar ~
2766 \SpecialChar ~
2767 \SpecialChar ~
2768 \SpecialChar ~
2769 \SpecialChar ~
2770 \SpecialChar ~
2771 \SpecialChar ~
2772 \SpecialChar ~
2773 \SpecialChar ~
2774 \SpecialChar ~
2775 \SpecialChar ~
2776 \SpecialChar ~
2777 \SpecialChar ~
2778 \SpecialChar ~
2779 \SpecialChar ~
2780
2781 \end_inset
2782 </cell>
2783 </row>
2784 <row topline="true" bottomline="true">
2785 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2786 \begin_inset Text
2787
2788 \layout Standard
2789
2790
2791 \emph on
2792 $DATADIR/
2793 \newline
2794 $LIB_DIR_SUFFIX/<model>
2795 \end_inset
2796 </cell>
2797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2798 \begin_inset Text
2799
2800 \layout Standard
2801
2802 /usr/local/share/sdcc/
2803 \newline
2804 lib/
2805 \emph on
2806 <model>
2807 \end_inset
2808 </cell>
2809 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2810 \begin_inset Text
2811
2812 \layout Standard
2813
2814 (not on Win32)
2815 \end_inset
2816 </cell>
2817 </row>
2818 </lyxtabular>
2819
2820 \end_inset
2821
2822
2823 \newline
2824
2825 \layout Comment
2826
2827 Don't delete any of the stray spaces in the table above without checking
2828  the HTML output (last line)!
2829 \layout Standard
2830
2831 \SpecialChar ~
2832
2833 \newline
2834 The option -
2835 \begin_inset ERT
2836 status Collapsed
2837
2838 \layout Standard
2839
2840 \backslash
2841 /
2842 \end_inset
2843
2844 -nostdlib disables the last two search paths.
2845 \layout Section
2846
2847 Building SDCC
2848 \begin_inset LatexCommand \index{Building SDCC}
2849
2850 \end_inset
2851
2852
2853 \layout Subsection
2854
2855 Building SDCC on Linux
2856 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2857
2858 \end_inset
2859
2860
2861 \layout Enumerate
2862
2863
2864 \series medium
2865 Download the source package
2866 \series default
2867  either from the SDCC CVS repository or from the nightly snapshots
2868 \series medium
2869 , it will be named something like sdcc
2870 \series default
2871 .src
2872 \series medium
2873 .t
2874 \series default
2875 ar.
2876 \series medium
2877 gz
2878 \series default
2879
2880 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2881
2882 \end_inset
2883
2884 .
2885 \layout Enumerate
2886
2887
2888 \series medium
2889 Bring up a command line terminal, such as xterm.
2890 \layout Enumerate
2891
2892
2893 \series medium
2894 Unpack the file using a command like:
2895 \family sans
2896 \series bold
2897 "tar -xvzf sdcc.src.tar.gz
2898 \family default
2899 \series default
2900 "
2901 \series medium
2902 , this will create a sub-directory called sdcc with all of the sources.
2903 \layout Enumerate
2904
2905 Change directory into the main SDCC directory, for example type:
2906 \family sans
2907 \series bold
2908 "cd sdcc
2909 \series default
2910 ".
2911 \layout Enumerate
2912
2913
2914 \series medium
2915 Type
2916 \family sans
2917 \series bold
2918 "./configure
2919 \family default
2920 \series default
2921 ".
2922  This configures the package for compilation on your system.
2923 \layout Enumerate
2924
2925
2926 \series medium
2927 Type
2928 \family sans
2929 \series bold
2930 "make
2931 \family default
2932 \series default
2933 "
2934 \series medium
2935 .
2936
2937 \series default
2938  All of the source packages will compile, this can take a while.
2939 \layout Enumerate
2940
2941
2942 \series medium
2943 Type
2944 \family sans
2945 \series bold
2946 "make install"
2947 \family default
2948 \series default
2949  as root
2950 \series medium
2951 .
2952
2953 \series default
2954  This copies the binary executables, the include files, the libraries and
2955  the documentation to the install directories.
2956  Proceed with section
2957 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
2958
2959 \end_inset
2960
2961 .
2962 \layout Subsection
2963
2964 Building SDCC on OSX 2.x
2965 \layout Standard
2966
2967 Follow the instruction for Linux.
2968 \newline
2969
2970 \newline
2971 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
2972 )) fails to compile SDCC.
2973  Fortunately there's also gcc 2.9.x installed, which works fine.
2974  This compiler can be selected by running 'configure' with:
2975 \layout LyX-Code
2976
2977 ./configure CC=gcc2 CXX=g++2
2978 \layout Subsection
2979
2980 Cross compiling SDCC on Linux for Windows
2981 \layout Standard
2982
2983 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
2984  See section 'Configure Options'.
2985 \layout Subsection
2986
2987 Building SDCC on Windows
2988 \layout Standard
2989
2990 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
2991  built on Windows.
2992  They use Unix-sockets, which are not available on Win32.
2993 \layout Subsection
2994
2995 Building SDCC using Cygwin and Mingw32
2996 \layout Standard
2997
2998 For building and installing a Cygwin executable follow the instructions
2999  for Linux.
3000 \newline
3001
3002 \newline
3003 On Cygwin a
3004 \begin_inset Quotes sld
3005 \end_inset
3006
3007 native
3008 \begin_inset Quotes srd
3009 \end_inset
3010
3011  Win32-binary can be built, which will not need the Cygwin-DLL.
3012  For the necessary 'configure' options see section 'configure options' or
3013  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3014 \newline
3015
3016 \newline
3017 In order to install Cygwin on Windows download setup.exe from
3018 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3019
3020 \end_inset
3021
3022 .
3023  Run it, set the
3024 \begin_inset Quotes sld
3025 \end_inset
3026
3027 default text file type
3028 \begin_inset Quotes srd
3029 \end_inset
3030
3031  to
3032 \begin_inset Quotes sld
3033 \end_inset
3034
3035 unix
3036 \begin_inset Quotes srd
3037 \end_inset
3038
3039  and download/install at least the following packages.
3040  Some packages are selected by default, others will be automatically selected
3041  because of dependencies with the manually selected packages.
3042  Never deselect these packages!
3043 \layout Itemize
3044
3045 flex
3046 \layout Itemize
3047
3048 bison
3049 \layout Itemize
3050
3051 gcc ; version 3.x is fine, no need to use the old 2.9x
3052 \layout Itemize
3053
3054 binutils ; selected with gcc
3055 \layout Itemize
3056
3057 make
3058 \layout Itemize
3059
3060 rxvt ; a nice console, which makes life much easier under windoze (see below)
3061 \layout Itemize
3062
3063 man ; not really needed for building SDCC, but you'll miss it sooner or
3064  later
3065 \layout Itemize
3066
3067 less ; not really needed for building SDCC, but you'll miss it sooner or
3068  later
3069 \layout Itemize
3070
3071 cvs ; only if you use CVS access
3072 \layout Standard
3073
3074 If you want to develop something you'll need:
3075 \layout Itemize
3076
3077 python ; for the regression tests
3078 \layout Itemize
3079
3080 gdb ; the gnu debugger, together with the nice GUI
3081 \begin_inset Quotes sld
3082 \end_inset
3083
3084 insight
3085 \begin_inset Quotes srd
3086 \end_inset
3087
3088
3089 \layout Itemize
3090
3091 openssh ; to access the CF or commit changes
3092 \layout Itemize
3093
3094 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3095  use autoconf-stable!
3096 \layout Standard
3097
3098 rxvt is a nice console with history.
3099  Replace in your cygwin.bat the line
3100 \layout LyX-Code
3101
3102 bash -
3103 \begin_inset ERT
3104 status Collapsed
3105
3106 \layout Standard
3107
3108 \backslash
3109 /
3110 \end_inset
3111
3112 -login -i
3113 \layout Standard
3114
3115 with (one line):
3116 \layout LyX-Code
3117
3118 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3119 \layout LyX-Code
3120
3121      -bg black -fg white -geometry 100x65 -e bash -
3122 \begin_inset ERT
3123 status Collapsed
3124
3125 \layout Standard
3126
3127 \backslash
3128 /
3129 \end_inset
3130
3131 -login
3132 \layout Standard
3133
3134 Text selected with the mouse is automatically copied to the clipboard, pasting
3135  works with shift-insert.
3136 \newline
3137
3138 \newline
3139 The other good tip is to make sure you have no //c/-style paths anywhere,
3140  use /cygdrive/c/ instead.
3141  Using // invokes a network lookup which is very slow.
3142  If you think
3143 \begin_inset Quotes sld
3144 \end_inset
3145
3146 cygdrive
3147 \begin_inset Quotes srd
3148 \end_inset
3149
3150  is too long, you can change it with e.g.
3151 \layout LyX-Code
3152
3153 mount -s -u -c /mnt
3154 \layout Standard
3155
3156 SDCC sources use the unix line ending LF.
3157  Life is much easier, if you store the source tree on a drive which is mounted
3158  in binary mode.
3159  And use an editor which can handle LF-only line endings.
3160  Make sure not to commit files with windows line endings.
3161  The tabulator spacing
3162 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3163
3164 \end_inset
3165
3166  used in the project is 8.
3167  Although a tabulator spacing of 8 is a sensible choice for programmers
3168  (it's a power of 2 and allows to display 8/16 bit signed variables without
3169  loosing columns) the plan is to move towards using only spaces in the source.
3170 \layout Subsection
3171
3172 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3173 \layout Standard
3174
3175
3176 \series medium
3177 Download the source package
3178 \series default
3179  either from the SDCC CVS repository or from the
3180 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3181
3182 \end_inset
3183
3184
3185 \series medium
3186 , it will be named something like sdcc
3187 \series default
3188 .src
3189 \series medium
3190 .tgz.
3191
3192 \series default
3193  SDCC is distributed with all the projects, workspaces, and files you need
3194  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3195  doesn't build under MSVC).
3196  The workspace name is 'sdcc.dsw'.
3197  Please note that as it is now, all the executables are created in a folder
3198  called sdcc
3199 \backslash
3200 bin_vc.
3201  Once built you need to copy the executables from sdcc
3202 \backslash
3203 bin_vc to sdcc
3204 \backslash
3205 bin before running SDCC.
3206
3207 \newline
3208
3209 \newline
3210 WARNING: Visual studio is very picky with line terminations; it expects
3211  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3212  If you are getting a message such as "This makefile was not generated by
3213  Developer Studio etc.
3214  etc.
3215 \begin_inset Quotes srd
3216 \end_inset
3217
3218  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3219  need to convert the Unix style line endings to DOS style line endings.
3220  To do so you can use the
3221 \begin_inset Quotes sld
3222 \end_inset
3223
3224 unix2dos
3225 \begin_inset Quotes srd
3226 \end_inset
3227
3228  utility freely available on the internet.
3229  Doug Hawkins reported in the sdcc-user list that this works:
3230 \newline
3231
3232 \newline
3233 C:
3234 \backslash
3235 Programming
3236 \backslash
3237 SDCC> unix2dos sdcc.dsw
3238 \newline
3239 C:
3240 \backslash
3241 Programming
3242 \backslash
3243 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3244 \newline
3245
3246 \newline
3247 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3248  flex.exe, and gawk.exe.
3249  One good place to get them is
3250 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3251
3252 \end_inset
3253
3254
3255 \newline
3256
3257 \newline
3258 Download the file UnxUtils
3259 \begin_inset LatexCommand \index{UnxUtils}
3260
3261 \end_inset
3262
3263 .zip.
3264  Now you have to install the utilities and setup MSVC so it can locate the
3265  required programs.
3266  Here there are two alternatives (choose one!):
3267 \layout Enumerate
3268
3269 The easy way:
3270 \newline
3271
3272 \newline
3273 a) Extract UnxUtils.zip to your C:
3274 \backslash
3275  hard disk PRESERVING the original paths, otherwise bison won't work.
3276  (If you are using WinZip make certain that 'Use folder names' is selected)
3277 \newline
3278
3279 \newline
3280 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3281  in 'Show directories for:' select 'Executable files', and in the directories
3282  window add a new path: 'C:
3283 \backslash
3284 user
3285 \backslash
3286 local
3287 \backslash
3288 wbin', click ok.
3289 \newline
3290
3291 \newline
3292 (As a side effect, you get a bunch of Unix utilities that could be useful,
3293  such as diff and patch.)
3294 \layout Enumerate
3295
3296 A more compact way:
3297 \newline
3298
3299 \newline
3300 This one avoids extracting a bunch of files you may not use, but requires
3301  some extra work:
3302 \newline
3303
3304 \newline
3305 a) Create a directory were to put the tools needed, or use a directory already
3306  present.
3307  Say for example 'C:
3308 \backslash
3309 util'.
3310 \newline
3311
3312 \newline
3313 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3314  to such directory WITHOUT preserving the original paths.
3315  (If you are using WinZip make certain that 'Use folder names' is not selected)
3316 \newline
3317
3318 \newline
3319 c) Rename bison.exe to '_bison.exe'.
3320 \newline
3321
3322 \newline
3323 d) Create a batch file 'bison.bat' in 'C:
3324 \backslash
3325 util
3326 \backslash
3327 ' and add these lines:
3328 \newline
3329 \SpecialChar ~
3330 \SpecialChar ~
3331 set BISON_SIMPLE=C:
3332 \backslash
3333 util
3334 \backslash
3335 bison.simple
3336 \newline
3337 \SpecialChar ~
3338 \SpecialChar ~
3339 set BISON_HAIRY=C:
3340 \backslash
3341 util
3342 \backslash
3343 bison.hairy
3344 \newline
3345 \SpecialChar ~
3346 \SpecialChar ~
3347 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3348 \newline
3349
3350 \newline
3351 Steps 'c' and 'd' are needed because bison requires by default that the
3352  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3353  '/usr/local/share/' I think.
3354  So it is necessary to tell bison where those files are located if they
3355  are not in such directory.
3356  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3357 \newline
3358
3359 \newline
3360 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3361  in 'Show directories for:' select 'Executable files', and in the directories
3362  window add a new path: 'c:
3363 \backslash
3364 util', click ok.
3365  Note that you can use any other path instead of 'c:
3366 \backslash
3367 util', even the path where the Visual C++ tools are, probably: 'C:
3368 \backslash
3369 Program Files
3370 \backslash
3371 Microsoft Visual Studio
3372 \backslash
3373 Common
3374 \backslash
3375 Tools'.
3376  So you don't have to execute step 'e' :)
3377 \layout Standard
3378
3379 That is it.
3380  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3381  the executables from sdcc
3382 \backslash
3383 bin_vc to sdcc
3384 \backslash
3385 bin, and you can compile using SDCC.
3386 \layout Subsection
3387
3388 Building SDCC Using Borland
3389 \layout Enumerate
3390
3391 From the sdcc directory, run the command "make -f Makefile.bcc".
3392  This should regenerate all the .exe files in the bin directory except for
3393  sdcdb.exe (which currently doesn't build under Borland C++).
3394 \layout Enumerate
3395
3396 If you modify any source files and need to rebuild, be aware that the dependenci
3397 es may not be correctly calculated.
3398  The safest option is to delete all .obj files and run the build again.
3399  From a Cygwin BASH prompt, this can easily be done with the command (be
3400  sure you are in the sdcc directory):
3401 \newline
3402
3403 \newline
3404
3405 \family sans
3406 \series bold
3407 find .
3408
3409 \backslash
3410 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3411 \backslash
3412 ) -print -exec rm {}
3413 \backslash
3414 ;
3415 \family default
3416 \series default
3417
3418 \newline
3419
3420 \newline
3421 or on Windows NT/2000/XP from the command prompt with the command:
3422 \newline
3423
3424 \family sans
3425 \series bold
3426
3427 \newline
3428 del /s *.obj *.lib *.rul
3429 \family default
3430 \series default
3431  from the sdcc directory.
3432 \layout Subsection
3433
3434 Windows Install Using a Binary Package
3435 \begin_inset LatexCommand \label{sub:Windows-Install}
3436
3437 \end_inset
3438
3439
3440 \layout Enumerate
3441
3442 Download the binary package from
3443 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3444
3445 \end_inset
3446
3447  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3448  This should unpack to a group of sub-directories.
3449  An example directory structure after unpacking the mingw32 package is:
3450  c:
3451 \backslash
3452 sdcc
3453 \backslash
3454 bin for the executables, c:
3455 \backslash
3456 sdcc
3457 \backslash
3458 include and c:
3459 \backslash
3460 sdcc
3461 \backslash
3462 lib for the include and libraries.
3463 \layout Enumerate
3464
3465 Adjust your environment variable PATH to include the location of the bin
3466  directory or start sdcc using the full path.
3467 \layout Section
3468
3469 Building the Documentation
3470 \layout Standard
3471
3472 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3473  as changing into the doc directory and typing
3474 \family sans
3475 \series bold
3476
3477 \begin_inset Quotes srd
3478 \end_inset
3479
3480 make
3481 \begin_inset Quotes srd
3482 \end_inset
3483
3484
3485 \family default
3486 \series default
3487  there.
3488  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3489 x).
3490  Using LyX
3491 \begin_inset LatexCommand \url{www.lyx.org}
3492
3493 \end_inset
3494
3495  as editor this is straightforward.
3496  Prebuilt documentation in html and pdf format is available from
3497 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3498
3499 \end_inset
3500
3501 .
3502 \layout Section
3503
3504 Reading the Documentation
3505 \layout Standard
3506
3507 Currently reading the document in pdf format is recommended, as for unknown
3508  reason the hyperlinks are working there whereas in the html version they
3509  are not
3510 \begin_inset Foot
3511 collapsed false
3512
3513 \layout Standard
3514
3515 If you should know why please drop us a note
3516 \end_inset
3517
3518 .
3519  You'll find the pdf version at
3520 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
3521
3522 \end_inset
3523
3524 .
3525 \newline
3526 This documentation is in some aspects different from a commercial documentation:
3527
3528 \layout Itemize
3529
3530 It tries to document SDCC for several processor architectures in one document
3531  (commercially these probably would be separate documents/products).
3532  This document
3533 \begin_inset LatexCommand \index{Status of documentation}
3534
3535 \end_inset
3536
3537  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3538 on about f.e.
3539  Z80, PIC14, PIC16 and HC08.
3540 \layout Itemize
3541
3542 There are many references pointing away from this documentation.
3543  Don't let this distract you.
3544  If there f.e.
3545  was a reference like
3546 \begin_inset LatexCommand \url{www.opencores.org}
3547
3548 \end_inset
3549
3550  together with a statement
3551 \begin_inset Quotes sld
3552 \end_inset
3553
3554 some processors which are targetted by SDCC can be implemented in a
3555 \emph on
3556 f
3557 \emph default
3558 ield
3559 \emph on
3560 p
3561 \emph default
3562 rogrammable
3563 \emph on
3564 g
3565 \emph default
3566 ate
3567 \emph on
3568 a
3569 \emph default
3570 rray
3571 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3572
3573 \end_inset
3574
3575
3576 \begin_inset Quotes srd
3577 \end_inset
3578
3579  we expect you to have a quick look there and come back.
3580  If you read this you are on the right track.
3581 \layout Itemize
3582
3583 Some sections attribute more space to problems, restrictions and warnings
3584  than to the solution.
3585 \layout Itemize
3586
3587 The installation section and the section about the debugger is intimidating.
3588 \layout Itemize
3589
3590 There are still lots of typos and there are more different writing styles
3591  than pictures.
3592 \layout Section
3593
3594 Testing the SDCC Compiler
3595 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3596
3597 \end_inset
3598
3599
3600 \layout Standard
3601
3602 The first thing you should do after installing your SDCC compiler is to
3603  see if it runs.
3604  Type
3605 \family sans
3606 \series bold
3607 "sdcc -
3608 \begin_inset ERT
3609 status Collapsed
3610
3611 \layout Standard
3612
3613 \backslash
3614 /
3615 \end_inset
3616
3617 -version"
3618 \begin_inset LatexCommand \index{version}
3619
3620 \end_inset
3621
3622
3623 \family default
3624 \series default
3625  at the prompt, and the program should run and tell you the version.
3626  If it doesn't run, or gives a message about not finding sdcc program, then
3627  you need to check over your installation.
3628  Make sure that the sdcc bin directory is in your executable search path
3629  defined by the PATH environment setting (
3630 \series medium
3631 see
3632 \series default
3633 section
3634 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3635
3636 \end_inset
3637
3638 \SpecialChar ~
3639
3640 \series medium
3641 Install trouble-shooting for suggestions
3642 \series default
3643 ).
3644  Make sure that the sdcc program is in the bin folder, if not perhaps something
3645  did not install correctly.
3646 \newline
3647
3648 \newline
3649
3650 \series medium
3651 SDCC
3652 \series default
3653 is commonly installed as described in section
3654 \begin_inset Quotes sld
3655 \end_inset
3656
3657 Install and search paths
3658 \begin_inset Quotes srd
3659 \end_inset
3660
3661 .
3662 \newline
3663
3664 \newline
3665
3666 \series medium
3667 Make sure the compiler works on a very simple example.
3668  Type in the following test.c program using your favorite
3669 \series default
3670 ASCII
3671 \series medium
3672 editor:
3673 \layout Verse
3674
3675
3676 \family typewriter
3677 char test;
3678 \newline
3679
3680 \newline
3681 void main(void) {
3682 \newline
3683 \SpecialChar ~
3684 \SpecialChar ~
3685 \SpecialChar ~
3686 \SpecialChar ~
3687 test=0;
3688 \newline
3689 }
3690 \layout Standard
3691
3692
3693 \series medium
3694 Compile this using the following command:
3695 \family sans
3696 \series bold
3697 "sdcc -c test.c".
3698
3699 \family default
3700 \series default
3701
3702 \series medium
3703 If all goes well, the compiler will generate a test.asm and test.rel file.
3704  Congratulations, you've just compiled your first program with SDCC.
3705  We used the -c option to tell SDCC not to link the generated code, just
3706  to keep things simple for this step.
3707 \series default
3708
3709 \newline
3710
3711 \newline
3712
3713 \series medium
3714 The next step is to try it with the linker.
3715  Type in
3716 \family sans
3717 \series bold
3718 "sdcc test.c
3719 \family default
3720 \series default
3721 "
3722 \series medium
3723 .
3724  If all goes well the compiler will link with the libraries and produce
3725  a test.ihx output file.
3726  If this step fails
3727 \series default
3728
3729 \series medium
3730 (no test.ihx, and the linker generates warnings), then the problem is most
3731  likely that
3732 \series default
3733 SDCC
3734 \series medium
3735  cannot find the
3736 \series default
3737 /
3738 \series medium
3739 usr/local/share/sdcc/lib directory
3740 \series default
3741
3742 \series medium
3743 (see
3744 \series default
3745 section
3746 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3747
3748 \end_inset
3749
3750 \SpecialChar ~
3751
3752 \series medium
3753 Install trouble-shooting for suggestions).
3754 \series default
3755
3756 \newline
3757
3758 \newline
3759
3760 \series medium
3761 The final test is to ensure
3762 \series default
3763 SDCC
3764 \series medium
3765  can use the
3766 \series default
3767 standard
3768 \series medium
3769  header files and libraries.
3770  Edit test.c and change it to the following:
3771 \layout Verse
3772
3773
3774 \family typewriter
3775 #include <string.h>
3776 \newline
3777
3778 \newline
3779 char str1[10];
3780 \newline
3781
3782 \newline
3783 void main(void) {
3784 \newline
3785 \SpecialChar ~
3786 \SpecialChar ~
3787 strcpy(str1, "testing");
3788 \newline
3789 }
3790 \layout Standard
3791
3792
3793 \series medium
3794 Compile this by typing
3795 \family sans
3796 \series bold
3797 "sdcc test.c"
3798 \family default
3799 \series medium
3800 .
3801  This should generate a test.ihx output file, and it should give no warnings
3802  such as not finding the string.h file.
3803  If it cannot find the string.h file, then the problem is that
3804 \series default
3805 SDCC
3806 \series medium
3807  cannot find the /usr/local/share/sdcc/include directory
3808 \series default
3809
3810 \series medium
3811 (see the
3812 \series default
3813 section
3814 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3815
3816 \end_inset
3817
3818 \SpecialChar ~
3819
3820 \series medium
3821 Install trouble-shooting section for suggestions).
3822
3823 \series default
3824  Use option
3825 \series bold
3826 -
3827 \begin_inset ERT
3828 status Collapsed
3829
3830 \layout Standard
3831
3832 \backslash
3833 /
3834 \end_inset
3835
3836 -print-search-dirs
3837 \series default
3838
3839 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3840
3841 \end_inset
3842
3843  to find exactly where SDCC is looking for the include and lib files.
3844 \layout Section
3845
3846 Install Trouble-shooting
3847 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3848
3849 \end_inset
3850
3851
3852 \begin_inset LatexCommand \index{Install trouble-shooting}
3853
3854 \end_inset
3855
3856
3857 \layout Subsection
3858
3859 If SDCC does not build correctly
3860 \layout Standard
3861
3862 A thing to try is starting from scratch by unpacking the .tgz source package
3863  again in an empty directory.
3864  Configure it like:
3865 \newline
3866
3867 \newline
3868
3869 \family sans
3870 \series bold
3871 ./configure 2>&1 | tee configure.log
3872 \family default
3873 \series default
3874
3875 \newline
3876
3877 \newline
3878 and build it like:
3879 \newline
3880
3881 \newline
3882
3883 \family sans
3884 \series bold
3885 make 2>&1 | tee make.log
3886 \family default
3887 \series default
3888
3889 \newline
3890
3891 \newline
3892 If anything goes wrong, you can review the log files to locate the problem.
3893  Or a relevant part of this can be attached to an email that could be helpful
3894  when requesting help from the mailing list.
3895 \layout Subsection
3896
3897 What the
3898 \begin_inset Quotes sld
3899 \end_inset
3900
3901 ./configure
3902 \begin_inset Quotes srd
3903 \end_inset
3904
3905  does
3906 \layout Standard
3907
3908 The
3909 \begin_inset Quotes sld
3910 \end_inset
3911
3912 ./configure
3913 \begin_inset Quotes srd
3914 \end_inset
3915
3916  command is a script that analyzes your system and performs some configuration
3917  to ensure the source package compiles on your system.
3918  It will take a few minutes to run, and will compile a few tests to determine
3919  what compiler features are installed.
3920 \layout Subsection
3921
3922 What the
3923 \begin_inset Quotes sld
3924 \end_inset
3925
3926 make
3927 \begin_inset Quotes srd
3928 \end_inset
3929
3930  does
3931 \layout Standard
3932
3933 This runs the GNU make tool, which automatically compiles all the source
3934  packages into the final installed binary executables.
3935 \layout Subsection
3936
3937 What the
3938 \begin_inset Quotes sld
3939 \end_inset
3940
3941 make install
3942 \begin_inset Quotes erd
3943 \end_inset
3944
3945  command does.
3946 \layout Standard
3947
3948 This will install the compiler, other executables libraries and include
3949  files into the appropriate directories.
3950  See sections
3951 \begin_inset LatexCommand \ref{sub:Install-paths}
3952
3953 \end_inset
3954
3955 ,\SpecialChar ~
3956
3957 \begin_inset LatexCommand \ref{sub:Search-Paths}
3958
3959 \end_inset
3960
3961 \SpecialChar ~
3962 about install and search paths.
3963 \newline
3964 On most systems you will need super-user privileges to do this.
3965 \layout Section
3966
3967 Components of SDCC
3968 \layout Standard
3969
3970 SDCC is not just a compiler, but a collection of tools by various developers.
3971  These include linkers, assemblers, simulators and other components.
3972  Here is a summary of some of the components.
3973  Note that the included simulator and assembler have separate documentation
3974  which you can find in the source package in their respective directories.
3975  As SDCC grows to include support for other processors, other packages from
3976  various developers are included and may have their own sets of documentation.
3977 \newline
3978
3979 \newline
3980 You might want to look at the files which are installed in <installdir>.
3981  At the time of this writing, we find the following programs for gcc-builds:
3982 \newline
3983
3984 \newline
3985 In <installdir>/bin:
3986 \layout Itemize
3987
3988 sdcc - The compiler.
3989 \layout Itemize
3990
3991 sdcpp - The C preprocessor.
3992 \layout Itemize
3993
3994 asx8051 - The assembler for 8051 type processors.
3995 \layout Itemize
3996
3997 as-z80
3998 \series bold
3999 ,
4000 \series default
4001 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4002 \layout Itemize
4003
4004 aslink -The linker for 8051 type processors.
4005 \layout Itemize
4006
4007 link-z80
4008 \series bold
4009 ,
4010 \series default
4011 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4012 \layout Itemize
4013
4014 s51 - The ucSim 8051 simulator.
4015 \layout Itemize
4016
4017 sdcdb - The source debugger.
4018 \layout Itemize
4019
4020 packihx - A tool to pack (compress) Intel hex files.
4021 \layout Standard
4022
4023 In <installdir>/share/sdcc/include
4024 \layout Itemize
4025
4026 the include files
4027 \layout Standard
4028
4029 In <installdir>/share/sdcc/lib
4030 \layout Itemize
4031
4032 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4033  relocatables.
4034 \layout Standard
4035
4036 In <installdir>/share/sdcc/doc
4037 \layout Itemize
4038
4039 the documentation
4040 \layout Standard
4041
4042 As development for other processors proceeds, this list will expand to include
4043  executables to support processors like AVR, PIC, etc.
4044 \layout Subsection
4045
4046 sdcc - The Compiler
4047 \layout Standard
4048
4049 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4050  the assembler and linkage editor.
4051 \layout Subsection
4052
4053 sdcpp - The C-Preprocessor
4054 \layout Standard
4055
4056 The preprocessor
4057 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4058
4059 \end_inset
4060
4061  is a modified version of the GNU preprocessor.
4062  The C preprocessor is used to pull in #include sources, process #ifdef
4063  statements, #defines and so on.
4064 \layout Subsection
4065
4066 as
4067 \emph on
4068 xxxx
4069 \emph default
4070 , aslink, link-
4071 \emph on
4072 xxx
4073 \emph default
4074  - The Assemblers and Linkage Editors
4075 \layout Standard
4076
4077 This is retargettable assembler & linkage editor, it was developed by Alan
4078  Baldwin.
4079  John Hartman created the version for 8051, and I (Sandeep) have made some
4080  enhancements and bug fixes for it to work properly with SDCC.
4081 \layout Subsection
4082
4083 s51 - The Simulator
4084 \layout Standard
4085
4086 S51
4087 \begin_inset LatexCommand \index{s51}
4088
4089 \end_inset
4090
4091  is a freeware, opensource simulator developed by Daniel Drotos (
4092 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
4093
4094 \end_inset
4095
4096 ).
4097  The simulator is built as part of the build process.
4098  For more information visit Daniel's web site at:
4099 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4100
4101 \end_inset
4102
4103 .
4104  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4105  XA51 family.
4106 \layout Subsection
4107
4108 sdcdb - Source Level Debugger
4109 \layout Standard
4110
4111 Sdcdb
4112 \begin_inset LatexCommand \index{sdcdb (debugger)}
4113
4114 \end_inset
4115
4116  is the companion source level debugger.
4117  More about sdcdb in section
4118 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4119
4120 \end_inset
4121
4122 .
4123  The current version of the debugger uses Daniel's Simulator S51
4124 \begin_inset LatexCommand \index{s51}
4125
4126 \end_inset
4127
4128 , but can be easily changed to use other simulators.
4129
4130 \layout Chapter
4131
4132 Using SDCC
4133 \layout Section
4134
4135 Compiling
4136 \layout Subsection
4137
4138 Single Source File Projects
4139 \layout Standard
4140
4141 For single source file 8051 projects the process is very simple.
4142  Compile your programs with the following command
4143 \family sans
4144 \series bold
4145 "sdcc sourcefile.c".
4146
4147 \family default
4148 \series default
4149  This will compile, assemble and link your source file.
4150  Output files are as follows:
4151 \layout Itemize
4152
4153 sourcefile.asm
4154 \begin_inset LatexCommand \index{<file>.asm}
4155
4156 \end_inset
4157
4158  - Assembler source
4159 \begin_inset LatexCommand \index{Assembler source}
4160
4161 \end_inset
4162
4163  file created by the compiler
4164 \layout Itemize
4165
4166 sourcefile.lst
4167 \begin_inset LatexCommand \index{<file>.lst}
4168
4169 \end_inset
4170
4171  - Assembler listing
4172 \begin_inset LatexCommand \index{Assembler listing}
4173
4174 \end_inset
4175
4176  file created by the Assembler
4177 \layout Itemize
4178
4179 sourcefile.rst
4180 \begin_inset LatexCommand \index{<file>.rst}
4181
4182 \end_inset
4183
4184  - Assembler listing
4185 \begin_inset LatexCommand \index{Assembler listing}
4186
4187 \end_inset
4188
4189  file updated with linkedit information, created by linkage editor
4190 \layout Itemize
4191
4192 sourcefile.sym
4193 \begin_inset LatexCommand \index{<file>.sym}
4194
4195 \end_inset
4196
4197  - symbol listing
4198 \begin_inset LatexCommand \index{Symbol listing}
4199
4200 \end_inset
4201
4202  for the sourcefile, created by the assembler
4203 \layout Itemize
4204
4205 sourcefile.rel
4206 \begin_inset LatexCommand \index{<file>.rel}
4207
4208 \end_inset
4209
4210  or sourcefile.o
4211 \begin_inset LatexCommand \index{<file>.o}
4212
4213 \end_inset
4214
4215  - Object file
4216 \begin_inset LatexCommand \index{Object file}
4217
4218 \end_inset
4219
4220  created by the assembler, input to Linkage editor
4221 \layout Itemize
4222
4223 sourcefile.map
4224 \begin_inset LatexCommand \index{<file>.map}
4225
4226 \end_inset
4227
4228  - The memory map
4229 \begin_inset LatexCommand \index{Memory map}
4230
4231 \end_inset
4232
4233  for the load module, created by the Linker
4234 \layout Itemize
4235
4236 sourcefile.mem
4237 \begin_inset LatexCommand \index{<file>.mem}
4238
4239 \end_inset
4240
4241  - A file with a summary of the memory usage
4242 \layout Itemize
4243
4244 sourcefile.ihx
4245 \begin_inset LatexCommand \index{<file>.ihx}
4246
4247 \end_inset
4248
4249  - The load module in Intel hex format
4250 \begin_inset LatexCommand \index{Intel hex format}
4251
4252 \end_inset
4253
4254  (you can select the Motorola S19 format
4255 \begin_inset LatexCommand \index{Motorola S19 format}
4256
4257 \end_inset
4258
4259  with -
4260 \begin_inset ERT
4261 status Collapsed
4262
4263 \layout Standard
4264
4265 \backslash
4266 /
4267 \end_inset
4268
4269 -out-fmt-s19
4270 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4271
4272 \end_inset
4273
4274 .
4275  If you need another format you might want to use
4276 \family sans
4277 \shape italic
4278 objdump
4279 \family default
4280 \shape default
4281
4282 \begin_inset LatexCommand \index{objdump (tool)}
4283
4284 \end_inset
4285
4286  or
4287 \family sans
4288 \shape italic
4289  srecord
4290 \family default
4291 \shape default
4292
4293 \begin_inset LatexCommand \index{srecord (tool)}
4294
4295 \end_inset
4296
4297 ).
4298  Both formats are documented in the documentation of srecord
4299 \begin_inset LatexCommand \index{srecord (tool)}
4300
4301 \end_inset
4302
4303
4304 \layout Itemize
4305
4306 sourcefile.adb
4307 \begin_inset LatexCommand \index{<file>.adb}
4308
4309 \end_inset
4310
4311  - An intermediate file containing debug information needed to create the
4312  .cdb file (with -
4313 \begin_inset ERT
4314 status Open
4315
4316 \layout Standard
4317
4318 \backslash
4319 /
4320 \end_inset
4321
4322 -debug
4323 \begin_inset LatexCommand \index{-\/-debug}
4324
4325 \end_inset
4326
4327 )
4328 \layout Itemize
4329
4330 sourcefile.cdb
4331 \begin_inset LatexCommand \index{<file>.cdb}
4332
4333 \end_inset
4334
4335  - An optional file (with -
4336 \begin_inset ERT
4337 status Collapsed
4338
4339 \layout Standard
4340
4341 \backslash
4342 /
4343 \end_inset
4344
4345 -debug) containing debug information.
4346  The format is documented in cdbfileformat.pdf.
4347 \layout Itemize
4348
4349 sourcefile.
4350  - (no extension)
4351 \begin_inset LatexCommand \index{<file> (no extension)}
4352
4353 \end_inset
4354
4355  An optional AOMF or AOMF51
4356 \begin_inset LatexCommand \index{AOMF, AOMF51}
4357
4358 \end_inset
4359
4360  file containing debug information (generated with option -
4361 \begin_inset ERT
4362 status Collapsed
4363
4364 \layout Standard
4365
4366 \backslash
4367 /
4368 \end_inset
4369
4370 -debug).
4371  The (Intel)
4372 \emph on
4373  a
4374 \emph default
4375 bsolute
4376 \emph on
4377 o
4378 \emph default
4379 bject
4380 \emph on
4381 m
4382 \emph default
4383 odule
4384 \emph on
4385 f
4386 \emph default
4387 ormat is commonly used by third party tools (debuggers
4388 \begin_inset LatexCommand \index{Debugger}
4389
4390 \end_inset
4391
4392 , simulators, emulators)
4393 \layout Itemize
4394
4395 sourcefile.dump*
4396 \begin_inset LatexCommand \index{<file>.dump*}
4397
4398 \end_inset
4399
4400  - Dump file to debug the compiler it self (generated with option -
4401 \begin_inset ERT
4402 status Collapsed
4403
4404 \layout Standard
4405
4406 \backslash
4407 /
4408 \end_inset
4409
4410 -dumpall) (see section
4411 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4412
4413 \end_inset
4414
4415 \SpecialChar ~
4416  and section
4417 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4418
4419 \end_inset
4420
4421 \SpecialChar ~
4422
4423 \begin_inset Quotes sld
4424 \end_inset
4425
4426 Anatomy of the compiler
4427 \begin_inset Quotes srd
4428 \end_inset
4429
4430 ).
4431 \layout Subsection
4432
4433 Projects with Multiple Source Files
4434 \layout Standard
4435
4436 SDCC can compile only ONE file at a time.
4437  Let us for example assume that you have a project containing the following
4438  files:
4439 \newline
4440
4441 \newline
4442 foo1.c (contains some functions)
4443 \newline
4444 foo2.c (contains some more functions)
4445 \newline
4446 foomain.c (contains more functions and the function main)
4447 \newline
4448
4449 \size footnotesize
4450
4451 \newline
4452
4453 \size default
4454 The first two files will need to be compiled separately with the commands:
4455 \size footnotesize
4456
4457 \size default
4458
4459 \newline
4460
4461 \newline
4462
4463 \family sans
4464 \series bold
4465 sdcc\SpecialChar ~
4466 -c\SpecialChar ~
4467 foo1.c
4468 \family default
4469 \series default
4470 \size footnotesize
4471
4472 \newline
4473
4474 \family sans
4475 \series bold
4476 \size default
4477 sdcc\SpecialChar ~
4478 -c\SpecialChar ~
4479 foo2.c
4480 \family default
4481 \series default
4482
4483 \newline
4484
4485 \newline
4486 Then compile the source file containing the
4487 \emph on
4488 main()
4489 \emph default
4490  function and link
4491 \begin_inset LatexCommand \index{Linker}
4492
4493 \end_inset
4494
4495  the files together with the following command:
4496 \newline
4497
4498 \newline
4499
4500 \family sans
4501 \series bold
4502 sdcc\SpecialChar ~
4503 foomain.c\SpecialChar ~
4504 foo1.rel\SpecialChar ~
4505 foo2.rel
4506 \family default
4507 \series default
4508
4509 \begin_inset LatexCommand \index{<file>.rel}
4510
4511 \end_inset
4512
4513
4514 \newline
4515
4516 \newline
4517 Alternatively,
4518 \emph on
4519 foomain.c
4520 \emph default
4521 can be separately compiled as well:
4522 \family sans
4523 \series bold
4524
4525 \newline
4526
4527 \newline
4528 sdcc\SpecialChar ~
4529 -c\SpecialChar ~
4530 foomain.c
4531 \newline
4532 sdcc foomain.rel foo1.rel foo2.rel
4533 \newline
4534
4535 \newline
4536
4537 \family default
4538 \series default
4539 The file containing the
4540 \emph on
4541 main()
4542 \emph default
4543  function
4544 \emph on
4545
4546 \emph default
4547 \noun on
4548 must
4549 \noun default
4550  be the
4551 \noun on
4552 first
4553 \noun default
4554  file specified in the command line, since the linkage editor processes
4555  file in the order they are presented to it.
4556  The linker is invoked from SDCC using a script file with extension .lnk
4557 \begin_inset LatexCommand \index{<file>.lnk}
4558
4559 \end_inset
4560
4561 .
4562  You can view this file to troubleshoot linking problems such as those arising
4563  from missing libraries.
4564 \layout Subsection
4565
4566 Projects with Additional Libraries
4567 \begin_inset LatexCommand \index{Libraries}
4568
4569 \end_inset
4570
4571
4572 \layout Standard
4573
4574 Some reusable routines may be compiled into a library, see the documentation
4575  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4576  for how to create a
4577 \emph on
4578 .lib
4579 \begin_inset LatexCommand \index{<file>.lib}
4580
4581 \end_inset
4582
4583
4584 \emph default
4585  library file.
4586  Libraries created in this manner can be included in the command line.
4587  Make sure you include the -L <library-path> option to tell the linker where
4588  to look for these files if they are not in the current directory.
4589  Here is an example, assuming you have the source file
4590 \emph on
4591 foomain.c
4592 \emph default
4593  and a library
4594 \emph on
4595  foolib.lib
4596 \emph default
4597  in the directory
4598 \emph on
4599 mylib
4600 \emph default
4601  (if that is not the same as your current project):
4602 \newline
4603
4604 \newline
4605
4606 \family sans
4607 \series bold
4608 sdcc foomain.c foolib.lib -L mylib
4609 \newline
4610
4611 \newline
4612
4613 \family default
4614 \series default
4615 Note here that
4616 \emph on
4617  mylib
4618 \emph default
4619  must be an absolute path name.
4620 \newline
4621
4622 \newline
4623 The most efficient way to use libraries is to keep separate modules in separate
4624  source files.
4625  The lib file now should name all the modules.rel
4626 \begin_inset LatexCommand \index{<file>.rel}
4627
4628 \end_inset
4629
4630  files.
4631  For an example see the standard library file
4632 \emph on
4633 libsdcc.lib
4634 \emph default
4635  in the directory <installdir>/share/lib/small.
4636 \layout Subsection
4637
4638 Using sdcclib to Create and Manage Libraries
4639 \begin_inset LatexCommand \index{sdcclib}
4640
4641 \end_inset
4642
4643
4644 \layout Standard
4645
4646 Alternatively, instead of having a .rel file for each entry on the library
4647  file as described in the preceding section, sdcclib can be used to embed
4648  all the modules belonging to such library in the library file itself.
4649  This results in a larger library file, but it greatly reduces the number
4650  of disk files accessed by the linker.
4651   Additionally, the packed library file contains an index of all include
4652  modules and symbols that significantly speeds up the linking process.
4653  To display a list of options supported by sdcclib type:
4654 \newline
4655
4656 \layout Standard
4657
4658
4659 \family sans
4660 \series bold
4661 sdcclib -?
4662 \begin_inset LatexCommand \index{sdcclib}
4663
4664 \end_inset
4665
4666
4667 \newline
4668
4669 \newline
4670
4671 \family default
4672 \series default
4673 To create a new library file, start by compiling all the required modules.
4674  For example:
4675 \newline
4676
4677 \layout Standard
4678
4679
4680 \family sans
4681 \series bold
4682 sdcc -c _divsint.c
4683 \layout Standard
4684
4685
4686 \family sans
4687 \series bold
4688 sdcc -c _divuint.c
4689 \layout Standard
4690
4691
4692 \family sans
4693 \series bold
4694 sdcc -c _modsint.c
4695 \layout Standard
4696
4697
4698 \family sans
4699 \series bold
4700 sdcc -c _moduint.c
4701 \layout Standard
4702
4703
4704 \family sans
4705 \series bold
4706 sdcc -c _mulint.c
4707 \newline
4708
4709 \layout Standard
4710
4711 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4712  and _mulint.rel.
4713  The next step is to add the .rel files to the library file:
4714 \newline
4715
4716 \layout Standard
4717
4718
4719 \family sans
4720 \series bold
4721 sdcclib libint.lib _divsint.rel
4722 \family default
4723
4724 \begin_inset LatexCommand \index{sdcclib}
4725
4726 \end_inset
4727
4728
4729 \layout Standard
4730
4731
4732 \family sans
4733 \series bold
4734 sdcclib libint.lib _divuint.rel
4735 \layout Standard
4736
4737
4738 \family sans
4739 \series bold
4740 sdcclib libint.lib _modsint.rel
4741 \layout Standard
4742
4743
4744 \family sans
4745 \series bold
4746 sdcclib libint.lib _moduint.rel
4747 \layout Standard
4748
4749
4750 \family sans
4751 \series bold
4752 sdcclib libint.lib _mulint.rel
4753 \series default
4754
4755 \newline
4756
4757 \layout Standard
4758
4759 If the file already exists in the library, it will be replaced.
4760  To see what modules and symbols are included in the library, options -s
4761  and -m are available.
4762  For example:
4763 \newline
4764
4765 \newline
4766
4767 \family sans
4768 \series bold
4769 sdcclib -s libint.lib
4770 \family default
4771
4772 \begin_inset LatexCommand \index{sdcclib}
4773
4774 \end_inset
4775
4776
4777 \newline
4778
4779 \family typewriter
4780 \series default
4781 _divsint.rel:
4782 \layout Standard
4783
4784
4785 \family typewriter
4786 __divsint_a_1_1
4787 \layout Standard
4788
4789
4790 \family typewriter
4791 __divsint_PARM_2
4792 \layout Standard
4793
4794
4795 \family typewriter
4796 __divsint
4797 \newline
4798 _divuint.rel:
4799 \layout Standard
4800
4801
4802 \family typewriter
4803 __divuint_a_1_1
4804 \layout Standard
4805
4806
4807 \family typewriter
4808 __divuint_PARM_2
4809 \layout Standard
4810
4811
4812 \family typewriter
4813 __divuint_reste_1_1
4814 \layout Standard
4815
4816
4817 \family typewriter
4818 __divuint_count_1_1
4819 \layout Standard
4820
4821
4822 \family typewriter
4823 __divuint
4824 \newline
4825 _modsint.rel:
4826 \layout Standard
4827
4828
4829 \family typewriter
4830 __modsint_a_1_1
4831 \layout Standard
4832
4833
4834 \family typewriter
4835 __modsint_PARM_2
4836 \layout Standard
4837
4838
4839 \family typewriter
4840 __modsint
4841 \newline
4842 _moduint.rel:
4843 \layout Standard
4844
4845
4846 \family typewriter
4847 __moduint_a_1_1
4848 \layout Standard
4849
4850
4851 \family typewriter
4852 __moduint_PARM_2
4853 \layout Standard
4854
4855
4856 \family typewriter
4857 __moduint_count_1_1
4858 \layout Standard
4859
4860
4861 \family typewriter
4862 __moduint
4863 \newline
4864 _mulint.rel:
4865 \layout Standard
4866
4867
4868 \family typewriter
4869 __mulint_PARM_2
4870 \layout Standard
4871
4872
4873 \family typewriter
4874 __mulint
4875 \family default
4876 \series bold
4877
4878 \newline
4879
4880 \layout Standard
4881
4882 If the source files are compiled using -
4883 \begin_inset ERT
4884 status Open
4885
4886 \layout Standard
4887
4888 \backslash
4889 /
4890 \end_inset
4891
4892 -debug
4893 \begin_inset LatexCommand \index{-\/-debug}
4894
4895 \end_inset
4896
4897 , the corresponding debug information file .adb will be include in the library
4898  file as well.
4899  The library files created with sdcclib are plain text files, so they can
4900  be viewed with a text editor.
4901  It is not recomended to modify a library file created with sdcclib using
4902  a text editor, as there are file indexes numbers located accross the file
4903  used by the linker to quickly locate the required module to link.
4904  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
4905  it can be safely deleted, since all the information required for linking
4906  is embedded in the library file itself.
4907  Library files created using sdcclib are used as described in the preceding
4908  sections.
4909 \layout Section
4910
4911 Command Line Options
4912 \begin_inset LatexCommand \index{Command Line Options}
4913
4914 \end_inset
4915
4916
4917 \layout Subsection
4918
4919 Processor Selection Options
4920 \begin_inset LatexCommand \index{Options processor selection}
4921
4922 \end_inset
4923
4924
4925 \begin_inset LatexCommand \index{Processor selection options}
4926
4927 \end_inset
4928
4929
4930 \layout List
4931 \labelwidthstring 00.00.0000
4932
4933
4934 \series bold
4935 -mmcs51
4936 \begin_inset LatexCommand \index{-mmcs51}
4937
4938 \end_inset
4939
4940
4941 \series default
4942  Generate code for the Intel MCS51
4943 \begin_inset LatexCommand \index{MCS51}
4944
4945 \end_inset
4946
4947  family of processors.
4948  This is the default processor target.
4949 \layout List
4950 \labelwidthstring 00.00.0000
4951
4952
4953 \series bold
4954 -mds390
4955 \begin_inset LatexCommand \index{-mds390}
4956
4957 \end_inset
4958
4959
4960 \series default
4961  Generate code for the Dallas DS80C390
4962 \begin_inset LatexCommand \index{DS80C390}
4963
4964 \end_inset
4965
4966  processor.
4967 \layout List
4968 \labelwidthstring 00.00.0000
4969
4970
4971 \series bold
4972 -mds400
4973 \begin_inset LatexCommand \index{-mds400}
4974
4975 \end_inset
4976
4977
4978 \series default
4979  Generate code for the Dallas DS80C400
4980 \begin_inset LatexCommand \index{DS80C400}
4981
4982 \end_inset
4983
4984  processor.
4985 \layout List
4986 \labelwidthstring 00.00.0000
4987
4988
4989 \series bold
4990 -mhc08
4991 \begin_inset LatexCommand \index{-mhc08}
4992
4993 \end_inset
4994
4995
4996 \series default
4997  Generate code for the Motorola HC08
4998 \begin_inset LatexCommand \index{HC08}
4999
5000 \end_inset
5001
5002  family of processors (added Oct 2003).
5003 \layout List
5004 \labelwidthstring 00.00.0000
5005
5006
5007 \series bold
5008 -mz80
5009 \begin_inset LatexCommand \index{-mz80}
5010
5011 \end_inset
5012
5013
5014 \series default
5015  Generate code for the Zilog Z80
5016 \begin_inset LatexCommand \index{Z80}
5017
5018 \end_inset
5019
5020  family of processors.
5021 \layout List
5022 \labelwidthstring 00.00.0000
5023
5024
5025 \series bold
5026 -mgbz80
5027 \begin_inset LatexCommand \index{-mgbz80}
5028
5029 \end_inset
5030
5031
5032 \series default
5033  Generate code for the GameBoy Z80
5034 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5035
5036 \end_inset
5037
5038  processor (Not actively maintained).
5039 \layout List
5040 \labelwidthstring 00.00.0000
5041
5042
5043 \series bold
5044 -mavr
5045 \begin_inset LatexCommand \index{-mavr}
5046
5047 \end_inset
5048
5049
5050 \series default
5051  Generate code for the Atmel AVR
5052 \begin_inset LatexCommand \index{AVR}
5053
5054 \end_inset
5055
5056  processor (In development, not complete).
5057  AVR users should probably have a look at avr-gcc
5058 \begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
5059
5060 \end_inset
5061
5062  or winavr
5063 \begin_inset LatexCommand \url{http://winavr.sourceforge.net}
5064
5065 \end_inset
5066
5067 .
5068 \layout Comment
5069
5070 I think it is fair to direct users there for now.
5071  Open source is also about avoiding unnecessary work .
5072  But I didn't find the 'official' link.
5073 \layout List
5074 \labelwidthstring 00.00.0000
5075
5076
5077 \series bold
5078 -mpic14
5079 \begin_inset LatexCommand \index{-mpic14}
5080
5081 \end_inset
5082
5083
5084 \series default
5085  Generate code for the Microchip PIC 14
5086 \begin_inset LatexCommand \index{PIC14}
5087
5088 \end_inset
5089
5090 -bit processors (p16f84 and variants.
5091  In development, not complete).
5092 \layout Comment
5093
5094 p16f627 p16f628 p16f84 p16f873 p16f877?
5095 \layout List
5096 \labelwidthstring 00.00.0000
5097
5098
5099 \series bold
5100 -mpic16
5101 \begin_inset LatexCommand \index{-mpic16}
5102
5103 \end_inset
5104
5105
5106 \series default
5107  Generate code for the Microchip PIC 16
5108 \begin_inset LatexCommand \index{PIC16}
5109
5110 \end_inset
5111
5112 -bit processors (p18f452 and variants.
5113  In development, not complete).
5114 \layout List
5115 \labelwidthstring 00.00.0000
5116
5117
5118 \series bold
5119 -mtlcs900h
5120 \series default
5121  Generate code for the Toshiba TLCS-900H
5122 \begin_inset LatexCommand \index{TLCS-900H}
5123
5124 \end_inset
5125
5126  processor (Not maintained, not complete).
5127 \layout List
5128 \labelwidthstring 00.00.0000
5129
5130
5131 \series bold
5132 -mxa51
5133 \begin_inset LatexCommand \index{-mxa51}
5134
5135 \end_inset
5136
5137
5138 \series default
5139  Generate code for the Phillips XA51
5140 \begin_inset LatexCommand \index{XA51}
5141
5142 \end_inset
5143
5144  processor (Not maintained, not complete).
5145 \layout Subsection
5146
5147 Preprocessor Options
5148 \begin_inset LatexCommand \index{Options preprocessor}
5149
5150 \end_inset
5151
5152
5153 \begin_inset LatexCommand \index{Preprocessor options}
5154
5155 \end_inset
5156
5157
5158 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5159
5160 \end_inset
5161
5162
5163 \layout List
5164 \labelwidthstring 00.00.0000
5165
5166
5167 \series bold
5168 -I<path>
5169 \begin_inset LatexCommand \index{-I<path>}
5170
5171 \end_inset
5172
5173
5174 \series default
5175  The additional location where the pre processor will look for <..h> or
5176 \begin_inset Quotes eld
5177 \end_inset
5178
5179 ..h
5180 \begin_inset Quotes erd
5181 \end_inset
5182
5183  files.
5184 \layout List
5185 \labelwidthstring 00.00.0000
5186
5187
5188 \series bold
5189 -D<macro[=value]>
5190 \begin_inset LatexCommand \index{-D<macro[=value]>}
5191
5192 \end_inset
5193
5194
5195 \series default
5196  Command line definition of macros.
5197  Passed to the preprocessor.
5198 \layout List
5199 \labelwidthstring 00.00.0000
5200
5201
5202 \series bold
5203 -M
5204 \begin_inset LatexCommand \index{-M}
5205
5206 \end_inset
5207
5208
5209 \series default
5210  Tell the preprocessor to output a rule suitable for make describing the
5211  dependencies of each object file.
5212  For each source file, the preprocessor outputs one make-rule whose target
5213  is the object file name for that source file and whose dependencies are
5214  all the files `#include'd in it.
5215  This rule may be a single line or may be continued with `
5216 \backslash
5217 '-newline if it is long.
5218  The list of rules is printed on standard output instead of the preprocessed
5219  C program.
5220  `-M' implies `-E
5221 \begin_inset LatexCommand \index{-E}
5222
5223 \end_inset
5224
5225 '.
5226 \layout List
5227 \labelwidthstring 00.00.0000
5228
5229
5230 \series bold
5231 -C
5232 \begin_inset LatexCommand \index{-C}
5233
5234 \end_inset
5235
5236
5237 \series default
5238  Tell the preprocessor not to discard comments.
5239  Used with the `-E' option.
5240 \layout List
5241 \labelwidthstring 00.00.0000
5242
5243
5244 \series bold
5245 -MM
5246 \begin_inset LatexCommand \index{-MM}
5247
5248 \end_inset
5249
5250
5251 \size large
5252 \bar under
5253
5254 \series default
5255 \size default
5256 \bar default
5257 Like `-M' but the output mentions only the user header files included with
5258  `#include
5259 \begin_inset Quotes eld
5260 \end_inset
5261
5262 file"'.
5263  System header files included with `#include <file>' are omitted.
5264 \layout List
5265 \labelwidthstring 00.00.0000
5266
5267
5268 \series bold
5269 -Aquestion(answer)
5270 \begin_inset LatexCommand \index{-Aquestion(answer)}
5271
5272 \end_inset
5273
5274
5275 \series default
5276  Assert the answer answer for question, in case it is tested with a preprocessor
5277  conditional such as `#if #question(answer)'.
5278  `-A-' disables the standard assertions that normally describe the target
5279  machine.
5280 \layout List
5281 \labelwidthstring 00.00.0000
5282
5283
5284 \series bold
5285 -Umacro
5286 \begin_inset LatexCommand \index{-Umacro}
5287
5288 \end_inset
5289
5290
5291 \series default
5292  Undefine macro macro.
5293  `-U' options are evaluated after all `-D' options, but before any `-include'
5294  and `-imacros' options.
5295 \layout List
5296 \labelwidthstring 00.00.0000
5297
5298
5299 \series bold
5300 -dM
5301 \begin_inset LatexCommand \index{-dM}
5302
5303 \end_inset
5304
5305
5306 \series default
5307  Tell the preprocessor to output only a list of the macro definitions that
5308  are in effect at the end of preprocessing.
5309  Used with the `-E' option.
5310 \layout List
5311 \labelwidthstring 00.00.0000
5312
5313
5314 \series bold
5315 -dD
5316 \begin_inset LatexCommand \index{-dD}
5317
5318 \end_inset
5319
5320
5321 \series default
5322  Tell the preprocessor to pass all macro definitions into the output, in
5323  their proper sequence in the rest of the output.
5324 \layout List
5325 \labelwidthstring 00.00.0000
5326
5327
5328 \series bold
5329 -dN
5330 \begin_inset LatexCommand \index{-dN}
5331
5332 \end_inset
5333
5334
5335 \size large
5336 \bar under
5337
5338 \series default
5339 \size default
5340 \bar default
5341 Like `-dD' except that the macro arguments and contents are omitted.
5342  Only `#define name' is included in the output.
5343 \layout List
5344 \labelwidthstring 00.00.0000
5345
5346
5347 \series bold
5348 -Wp\SpecialChar ~
5349 preprocessorOption[,preprocessorOption]
5350 \series default
5351
5352 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5353
5354 \end_inset
5355
5356 ...
5357  Pass the preprocessorOption to the preprocessor
5358 \family typewriter
5359 sdcpp
5360 \family default
5361
5362 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5363
5364 \end_inset
5365
5366 .
5367  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5368  Collection (gcc), if you need more dedicated options please refer to the
5369  documentation at
5370 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5371
5372 \end_inset
5373
5374 .
5375 \layout Subsection
5376
5377 Linker Options
5378 \begin_inset LatexCommand \index{Options linker}
5379
5380 \end_inset
5381
5382
5383 \begin_inset LatexCommand \index{Linker options}
5384
5385 \end_inset
5386
5387
5388 \layout List
5389 \labelwidthstring 00.00.0000
5390
5391
5392 \series bold
5393 -L\SpecialChar ~
5394 -
5395 \series default
5396
5397 \begin_inset ERT
5398 status Collapsed
5399
5400 \layout Standard
5401
5402 \backslash
5403 /
5404 \end_inset
5405
5406
5407 \series bold
5408 -lib-path
5409 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5410
5411 \end_inset
5412
5413
5414 \begin_inset LatexCommand \index{-L -\/-lib-path}
5415
5416 \end_inset
5417
5418
5419 \series default
5420 \SpecialChar ~
5421 <absolute path to additional libraries> This option is passed to the linkage
5422  editor's additional libraries
5423 \begin_inset LatexCommand \index{Libraries}
5424
5425 \end_inset
5426
5427  search path.
5428  The path name must be absolute.
5429  Additional library files may be specified in the command line.
5430  See section Compiling programs for more details.
5431 \layout List
5432 \labelwidthstring 00.00.0000
5433
5434
5435 \series bold
5436 -
5437 \begin_inset ERT
5438 status Collapsed
5439
5440 \layout Standard
5441
5442 \backslash
5443 /
5444 \end_inset
5445
5446 -xram-loc
5447 \series default
5448
5449 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5450
5451 \end_inset
5452
5453 \SpecialChar ~
5454 <Value> The start location of the external ram
5455 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5456
5457 \end_inset
5458
5459 , default value is 0.
5460  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5461 \begin_inset ERT
5462 status Collapsed
5463
5464 \layout Standard
5465
5466 \backslash
5467 /
5468 \end_inset
5469
5470 -xram-loc 0x8000 or -
5471 \begin_inset ERT
5472 status Collapsed
5473
5474 \layout Standard
5475
5476 \backslash
5477 /
5478 \end_inset
5479
5480 -xram-loc 32768.
5481 \layout List
5482 \labelwidthstring 00.00.0000
5483
5484
5485 \series bold
5486 -
5487 \begin_inset ERT
5488 status Collapsed
5489
5490 \layout Standard
5491
5492 \backslash
5493 /
5494 \end_inset
5495
5496 -code-loc
5497 \series default
5498
5499 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5500
5501 \end_inset
5502
5503 \SpecialChar ~
5504 <Value> The start location of the code
5505 \begin_inset LatexCommand \index{code}
5506
5507 \end_inset
5508
5509  segment, default value 0.
5510  Note when this option is used the interrupt vector table is also relocated
5511  to the given address.
5512  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5513 \begin_inset ERT
5514 status Collapsed
5515
5516 \layout Standard
5517
5518 \backslash
5519 /
5520 \end_inset
5521
5522 -code-loc 0x8000 or -
5523 \begin_inset ERT
5524 status Collapsed
5525
5526 \layout Standard
5527
5528 \backslash
5529 /
5530 \end_inset
5531
5532 -code-loc 32768.
5533 \layout List
5534 \labelwidthstring 00.00.0000
5535
5536
5537 \series bold
5538 -
5539 \begin_inset ERT
5540 status Collapsed
5541
5542 \layout Standard
5543
5544 \backslash
5545 /
5546 \end_inset
5547
5548 -stack-loc
5549 \series default
5550
5551 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5552
5553 \end_inset
5554
5555 \SpecialChar ~
5556 <Value> By default the stack
5557 \begin_inset LatexCommand \index{stack}
5558
5559 \end_inset
5560
5561  is placed after the data segment.
5562  Using this option the stack can be placed anywhere in the internal memory
5563  space of the 8051.
5564  The value entered can be in Hexadecimal or Decimal format, e.g.
5565  -
5566 \begin_inset ERT
5567 status Collapsed
5568
5569 \layout Standard
5570
5571 \backslash
5572 /
5573 \end_inset
5574
5575 -stack-loc 0x20 or -
5576 \begin_inset ERT
5577 status Collapsed
5578
5579 \layout Standard
5580
5581 \backslash
5582 /
5583 \end_inset
5584
5585 -stack-loc 32.
5586  Since the sp register is incremented before a push or call, the initial
5587  sp will be set to one byte prior the provided value.
5588  The provided value should not overlap any other memory areas such as used
5589  register banks or the data segment and with enough space for the current
5590  application.
5591 \layout List
5592 \labelwidthstring 00.00.0000
5593
5594
5595 \series bold
5596 -
5597 \begin_inset ERT
5598 status Collapsed
5599
5600 \layout Standard
5601
5602 \backslash
5603 /
5604 \end_inset
5605
5606 -data-loc
5607 \series default
5608
5609 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5610
5611 \end_inset
5612
5613 \SpecialChar ~
5614 <Value> The start location of the internal ram data
5615 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5616
5617 \end_inset
5618
5619  segment.
5620  The value entered can be in Hexadecimal or Decimal format, eg.
5621  -
5622 \begin_inset ERT
5623 status Collapsed
5624
5625 \layout Standard
5626
5627 \backslash
5628 /
5629 \end_inset
5630
5631 -data-loc 0x20 or -
5632 \begin_inset ERT
5633 status Collapsed
5634
5635 \layout Standard
5636
5637 \backslash
5638 /
5639 \end_inset
5640
5641 -data-loc 32.
5642  (By default, the start location of the internal ram data segment  is set
5643  as low as possible in memory, taking into account the used register banks
5644  and the bit segment at address 0x20.
5645  For example if register banks 0 and 1 are used without bit variables, the
5646  data segment will be set, if -
5647 \begin_inset ERT
5648 status Collapsed
5649
5650 \layout Standard
5651
5652 \backslash
5653 /
5654 \end_inset
5655
5656 -data-loc is not used, to location 0x10.)
5657 \layout List
5658 \labelwidthstring 00.00.0000
5659
5660
5661 \series bold
5662 -
5663 \begin_inset ERT
5664 status Collapsed
5665
5666 \layout Standard
5667
5668 \backslash
5669 /
5670 \end_inset
5671
5672 -idata-loc
5673 \series default
5674
5675 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5676
5677 \end_inset
5678
5679 \SpecialChar ~
5680 <Value> The start location of the indirectly addressable internal ram
5681 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5682
5683 \end_inset
5684
5685  of the 8051, default value is 0x80.
5686  The value entered can be in Hexadecimal or Decimal format, eg.
5687  -
5688 \begin_inset ERT
5689 status Collapsed
5690
5691 \layout Standard
5692
5693 \backslash
5694 /
5695 \end_inset
5696
5697 -idata-loc 0x88 or -
5698 \begin_inset ERT
5699 status Collapsed
5700
5701 \layout Standard
5702
5703 \backslash
5704 /
5705 \end_inset
5706
5707 -idata-loc 136.
5708 \layout List
5709 \labelwidthstring 00.00.0000
5710
5711
5712 \series bold
5713 -
5714 \begin_inset ERT
5715 status Collapsed
5716
5717 \layout Standard
5718
5719 \backslash
5720 /
5721 \end_inset
5722
5723 -bit-loc
5724 \series default
5725 \SpecialChar ~
5726 <Value> The start location of the bit
5727 \begin_inset LatexCommand \index{bit}
5728
5729 \end_inset
5730
5731  addressable internal ram of the 8051.
5732  This is
5733 \emph on
5734 not
5735 \emph default
5736  implemented yet.
5737  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5738 -bBSEG=<Value>.
5739 \layout List
5740 \labelwidthstring 00.00.0000
5741
5742
5743 \series bold
5744 -
5745 \begin_inset ERT
5746 status Collapsed
5747
5748 \layout Standard
5749
5750 \backslash
5751 /
5752 \end_inset
5753
5754 -out-fmt-ihx
5755 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5756
5757 \end_inset
5758
5759
5760 \bar under
5761
5762 \series default
5763 \bar default
5764 The linker output (final object code) is in Intel Hex format.
5765 \begin_inset LatexCommand \index{Intel hex format}
5766
5767 \end_inset
5768
5769  This is the default option.
5770  The format itself is documented in the documentation of srecord
5771 \begin_inset LatexCommand \index{srecord (tool)}
5772
5773 \end_inset
5774
5775 .
5776 \layout List
5777 \labelwidthstring 00.00.0000
5778
5779
5780 \series bold
5781 -
5782 \begin_inset ERT
5783 status Collapsed
5784
5785 \layout Standard
5786
5787 \backslash
5788 /
5789 \end_inset
5790
5791 -out-fmt-s19
5792 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5793
5794 \end_inset
5795
5796
5797 \bar under
5798
5799 \series default
5800 \bar default
5801 The linker output (final object code) is in Motorola S19 format
5802 \begin_inset LatexCommand \index{Motorola S19 format}
5803
5804 \end_inset
5805
5806 .
5807  The format itself is documented in the documentation of srecord.
5808 \layout List
5809 \labelwidthstring 00.00.0000
5810
5811
5812 \series bold
5813 -Wl\SpecialChar ~
5814 linkOption[,linkOption]
5815 \series default
5816
5817 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5818
5819 \end_inset
5820
5821 ...
5822  Pass the linkOption to the linker.
5823  See file sdcc/as/doc/asxhtm.html for more on linker options.
5824 \layout Subsection
5825
5826 MCS51 Options
5827 \begin_inset LatexCommand \index{Options MCS51}
5828
5829 \end_inset
5830
5831
5832 \begin_inset LatexCommand \index{MCS51 options}
5833
5834 \end_inset
5835
5836
5837 \layout List
5838 \labelwidthstring 00.00.0000
5839
5840
5841 \series bold
5842 -
5843 \begin_inset ERT
5844 status Collapsed
5845
5846 \layout Standard
5847
5848 \backslash
5849 /
5850 \end_inset
5851
5852 -model-small
5853 \begin_inset LatexCommand \index{-\/-model-small}
5854
5855 \end_inset
5856
5857
5858 \series default
5859 \size large
5860 \emph on
5861
5862 \size default
5863 \emph default
5864 Generate code for Small Model programs, see section Memory Models for more
5865  details.
5866  This is the default model.
5867 \layout List
5868 \labelwidthstring 00.00.0000
5869
5870
5871 \series bold
5872 -
5873 \begin_inset ERT
5874 status Collapsed
5875
5876 \layout Standard
5877
5878 \backslash
5879 /
5880 \end_inset
5881
5882 -model-large
5883 \begin_inset LatexCommand \index{-\/-model-large}
5884
5885 \end_inset
5886
5887
5888 \series default
5889  Generate code for Large model programs, see section Memory Models for more
5890  details.
5891  If this option is used all source files in the project have to be compiled
5892  with this option.
5893 \layout List
5894 \labelwidthstring 00.00.0000
5895
5896
5897 \series bold
5898 -
5899 \begin_inset ERT
5900 status Collapsed
5901
5902 \layout Standard
5903
5904 \backslash
5905 /
5906 \end_inset
5907
5908 -xstack
5909 \begin_inset LatexCommand \index{-\/-xstack}
5910
5911 \end_inset
5912
5913
5914 \series default
5915  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
5916  variables and passing parameters.
5917  See section
5918 \begin_inset LatexCommand \ref{sub:External-Stack}
5919
5920 \end_inset
5921
5922 \SpecialChar ~
5923  External Stack for more details.
5924 \layout List
5925 \labelwidthstring 00.00.0000
5926
5927
5928 \series bold
5929 -
5930 \begin_inset ERT
5931 status Collapsed
5932
5933 \layout Standard
5934
5935 \backslash
5936 /
5937 \end_inset
5938
5939 -iram-size
5940 \series default
5941 \SpecialChar ~
5942 <Value>
5943 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
5944
5945 \end_inset
5946
5947  Causes the linker to check if the internal ram usage is within limits of
5948  the given value.
5949 \layout List
5950 \labelwidthstring 00.00.0000
5951
5952
5953 \series bold
5954 -
5955 \begin_inset ERT
5956 status Collapsed
5957
5958 \layout Standard
5959
5960 \backslash
5961 /
5962 \end_inset
5963
5964 -xram-size
5965 \series default
5966 \SpecialChar ~
5967 <Value>
5968 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
5969
5970 \end_inset
5971
5972  Causes the linker to check if the external ram usage is within limits of
5973  the given value.
5974 \layout List
5975 \labelwidthstring 00.00.0000
5976
5977
5978 \series bold
5979 -
5980 \begin_inset ERT
5981 status Collapsed
5982
5983 \layout Standard
5984
5985 \backslash
5986 /
5987 \end_inset
5988
5989 -code-size
5990 \series default
5991 \SpecialChar ~
5992 <Value>
5993 \begin_inset LatexCommand \index{-\/-code-size <Value>}
5994
5995 \end_inset
5996
5997  Causes the linker to check if the code memory usage is within limits of
5998  the given value.
5999 \layout List
6000 \labelwidthstring 00.00.0000
6001
6002
6003 \series bold
6004 -
6005 \begin_inset ERT
6006 status Collapsed
6007
6008 \layout Standard
6009
6010 \backslash
6011 /
6012 \end_inset
6013
6014 -stack-size
6015 \series default
6016 \SpecialChar ~
6017 <Value>
6018 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6019
6020 \end_inset
6021
6022  Causes the linker to check if there is at minimum <Value> bytes for stack.
6023 \layout List
6024 \labelwidthstring 00.00.0000
6025
6026
6027 \series bold
6028 -
6029 \begin_inset ERT
6030 status Collapsed
6031
6032 \layout Standard
6033
6034 \backslash
6035 /
6036 \end_inset
6037
6038 -pack-iram
6039 \series default
6040 \SpecialChar ~
6041
6042 \begin_inset LatexCommand \index{-\/-pack-iram}
6043
6044 \end_inset
6045
6046  Causes the linker use unused register banks for data variables or stack.
6047 \layout Subsection
6048
6049 DS390 / DS400 Options
6050 \begin_inset LatexCommand \index{Options DS390}
6051
6052 \end_inset
6053
6054
6055 \begin_inset LatexCommand \index{DS390 options}
6056
6057 \end_inset
6058
6059
6060 \layout List
6061 \labelwidthstring 00.00.0000
6062
6063
6064 \series bold
6065 -
6066 \begin_inset ERT
6067 status Collapsed
6068
6069 \layout Standard
6070
6071 \backslash
6072 /
6073 \end_inset
6074
6075 -model-flat24
6076 \series default
6077
6078 \begin_inset LatexCommand \index{-\/-model-flat24}
6079
6080 \end_inset
6081
6082
6083 \size large
6084 \emph on
6085
6086 \size default
6087 \emph default
6088 Generate 24-bit flat mode code.
6089  This is the one and only that the ds390 code generator supports right now
6090  and is default when using
6091 \emph on
6092 -mds390
6093 \emph default
6094 .
6095  See section Memory Models for more details.
6096 \layout List
6097 \labelwidthstring 00.00.0000
6098
6099
6100 \series bold
6101 -
6102 \begin_inset ERT
6103 status Collapsed
6104
6105 \layout Standard
6106
6107 \backslash
6108 /
6109 \end_inset
6110
6111 -protect-sp-update
6112 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6113
6114 \end_inset
6115
6116
6117 \series default
6118  disable interrupts during ESP:SP updates.
6119 \layout List
6120 \labelwidthstring 00.00.0000
6121
6122
6123 \series bold
6124 -
6125 \begin_inset ERT
6126 status Collapsed
6127
6128 \layout Standard
6129
6130 \backslash
6131 /
6132 \end_inset
6133
6134 -stack-10bit
6135 \series default
6136
6137 \begin_inset LatexCommand \index{-\/-stack-10bit}
6138
6139 \end_inset
6140
6141  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6142  This is the one and only that the ds390 code generator supports right now
6143  and is default when using
6144 \emph on
6145 -mds390
6146 \emph default
6147 .
6148  In this mode, the stack is located in the lower 1K of the internal RAM,
6149  which is mapped to 0x400000.
6150  Note that the support is incomplete, since it still uses a single byte
6151  as the stack pointer.
6152  This means that only the lower 256 bytes of the potential 1K stack space
6153  will actually be used.
6154  However, this does allow you to reclaim the precious 256 bytes of low RAM
6155  for use for the DATA and IDATA segments.
6156  The compiler will not generate any code to put the processor into 10 bit
6157  stack mode.
6158  It is important to ensure that the processor is in this mode before calling
6159  any re-entrant functions compiled with this option.
6160  In principle, this should work with the
6161 \emph on
6162 -
6163 \begin_inset ERT
6164 status Collapsed
6165
6166 \layout Standard
6167
6168 \backslash
6169 /
6170 \end_inset
6171
6172 -stack-auto
6173 \begin_inset LatexCommand \index{-\/-stack-auto}
6174
6175 \end_inset
6176
6177
6178 \emph default
6179  option, but that has not been tested.
6180  It is incompatible with the
6181 \emph on
6182 -
6183 \begin_inset ERT
6184 status Collapsed
6185
6186 \layout Standard
6187
6188 \backslash
6189 /
6190 \end_inset
6191
6192 -xstack
6193 \begin_inset LatexCommand \index{-\/-xstack}
6194
6195 \end_inset
6196
6197
6198 \emph default
6199  option.
6200  It also only makes sense if the processor is in 24 bit contiguous addressing
6201  mode (see the
6202 \emph on
6203 -
6204 \begin_inset ERT
6205 status Collapsed
6206
6207 \layout Standard
6208
6209 \backslash
6210 /
6211 \end_inset
6212
6213 -model-flat24 option
6214 \emph default
6215 ).
6216 \layout List
6217 \labelwidthstring 00.00.0000
6218
6219
6220 \series bold
6221 -
6222 \begin_inset ERT
6223 status Collapsed
6224
6225 \layout Standard
6226
6227 \backslash
6228 /
6229 \end_inset
6230
6231 -stack-probe
6232 \begin_inset LatexCommand \index{-\/-stack-probe}
6233
6234 \end_inset
6235
6236
6237 \series default
6238  insert call to function __stack_probe at each function prologue.
6239 \layout List
6240 \labelwidthstring 00.00.0000
6241
6242
6243 \series bold
6244 -
6245 \begin_inset ERT
6246 status Collapsed
6247
6248 \layout Standard
6249
6250 \backslash
6251 /
6252 \end_inset
6253
6254 -tini-libid
6255 \begin_inset LatexCommand \index{-\/-tini-libid}
6256
6257 \end_inset
6258
6259
6260 \series default
6261  <nnnn> LibraryID used in -mTININative.
6262
6263 \layout List
6264 \labelwidthstring 00.00.0000
6265
6266
6267 \series bold
6268 -
6269 \begin_inset ERT
6270 status Collapsed
6271
6272 \layout Standard
6273
6274 \backslash
6275 /
6276 \end_inset
6277
6278 -use-accelerator
6279 \begin_inset LatexCommand \index{-\/-use-accelerator}
6280
6281 \end_inset
6282
6283
6284 \series default
6285  generate code for DS390 Arithmetic Accelerator.
6286
6287 \layout Subsection
6288
6289 Z80 Options
6290 \begin_inset LatexCommand \index{Options Z80}
6291
6292 \end_inset
6293
6294
6295 \begin_inset LatexCommand \index{Z80 options}
6296
6297 \end_inset
6298
6299
6300 \layout List
6301 \labelwidthstring 00.00.0000
6302
6303
6304 \series bold
6305 -
6306 \begin_inset ERT
6307 status Collapsed
6308
6309 \layout Standard
6310
6311 \backslash
6312 /
6313 \end_inset
6314
6315 -callee-saves-bc
6316 \series default
6317
6318 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6319
6320 \end_inset
6321
6322
6323 \size large
6324 \emph on
6325
6326 \size default
6327 \emph default
6328 Force a called function to always save BC.
6329 \layout List
6330 \labelwidthstring 00.00.0000
6331
6332
6333 \series bold
6334 -
6335 \begin_inset ERT
6336 status Collapsed
6337
6338 \layout Standard
6339
6340 \backslash
6341 /
6342 \end_inset
6343
6344 -no-std-crt0
6345 \series default
6346
6347 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6348
6349 \end_inset
6350
6351  When linking, skip the standard crt0.o object file.
6352  You must provide your own crt0.o for your system when linking.
6353
6354 \layout Subsection
6355
6356 Optimization Options
6357 \begin_inset LatexCommand \index{Options optimization}
6358
6359 \end_inset
6360
6361
6362 \begin_inset LatexCommand \index{Optimization options}
6363
6364 \end_inset
6365
6366
6367 \layout List
6368 \labelwidthstring 00.00.0000
6369
6370
6371 \series bold
6372 -
6373 \begin_inset ERT
6374 status Collapsed
6375
6376 \layout Standard
6377
6378 \backslash
6379 /
6380 \end_inset
6381
6382 -nogcse
6383 \begin_inset LatexCommand \index{-\/-nogcse}
6384
6385 \end_inset
6386
6387
6388 \series default
6389  Will not do global subexpression elimination, this option may be used when
6390  the compiler creates undesirably large stack/data spaces to store compiler
6391  temporaries.
6392  A warning message will be generated when this happens and the compiler
6393  will indicate the number of extra bytes it allocated.
6394  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6395 nogcse
6396 \begin_inset LatexCommand \index{\#pragma nogcse}
6397
6398 \end_inset
6399
6400  can be used to turn off global subexpression elimination
6401 \begin_inset LatexCommand \index{Subexpression elimination}
6402
6403 \end_inset
6404
6405  for a given function only.
6406 \layout List
6407 \labelwidthstring 00.00.0000
6408
6409
6410 \series bold
6411 -
6412 \begin_inset ERT
6413 status Collapsed
6414
6415 \layout Standard
6416
6417 \backslash
6418 /
6419 \end_inset
6420
6421 -noinvariant
6422 \begin_inset LatexCommand \index{-\/-noinvariant}
6423
6424 \end_inset
6425
6426
6427 \series default
6428  Will not do loop invariant optimizations, this may be turned off for reasons
6429  explained for the previous option.
6430  For more details of loop optimizations performed see Loop Invariants in
6431  section
6432 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6433
6434 \end_inset
6435
6436 .
6437  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6438 noinvariant
6439 \begin_inset LatexCommand \index{\#pragma noinvariant}
6440
6441 \end_inset
6442
6443  can be used to turn off invariant optimizations for a given function only.
6444 \layout List
6445 \labelwidthstring 00.00.0000
6446
6447
6448 \series bold
6449 -
6450 \begin_inset ERT
6451 status Collapsed
6452
6453 \layout Standard
6454
6455 \backslash
6456 /
6457 \end_inset
6458
6459 -noinduction
6460 \begin_inset LatexCommand \index{-\/-noinduction}
6461
6462 \end_inset
6463
6464
6465 \series default
6466  Will not do loop induction optimizations, see section strength reduction
6467  for more details.
6468  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6469 noinduction
6470 \begin_inset LatexCommand \index{\#pragma noinduction}
6471
6472 \end_inset
6473
6474  can be used to turn off induction optimizations for a given function only.
6475 \layout List
6476 \labelwidthstring 00.00.0000
6477
6478
6479 \series bold
6480 -
6481 \begin_inset ERT
6482 status Collapsed
6483
6484 \layout Standard
6485
6486 \backslash
6487 /
6488 \end_inset
6489
6490 -nojtbound
6491 \begin_inset LatexCommand \index{-\/-nojtbound}
6492
6493 \end_inset
6494
6495
6496 \size large
6497 \bar under
6498
6499 \series default
6500 \size default
6501 \bar default
6502  Will not generate boundary condition check when switch statements
6503 \begin_inset LatexCommand \index{switch statement}
6504
6505 \end_inset
6506
6507  are implemented using jump-tables.
6508  See section
6509 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6510
6511 \end_inset
6512
6513 \SpecialChar ~
6514 Switch Statements for more details.
6515  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6516 nojtbound
6517 \begin_inset LatexCommand \index{\#pragma nojtbound}
6518
6519 \end_inset
6520
6521  can be used to turn off boundary checking for jump tables for a given function
6522  only.
6523 \layout List
6524 \labelwidthstring 00.00.0000
6525
6526
6527 \series bold
6528 -
6529 \begin_inset ERT
6530 status Collapsed
6531
6532 \layout Standard
6533
6534 \backslash
6535 /
6536 \end_inset
6537
6538 -noloopreverse
6539 \begin_inset LatexCommand \index{-\/-noloopreverse}
6540
6541 \end_inset
6542
6543
6544 \series default
6545 \size large
6546
6547 \size default
6548 Will not do loop reversal
6549 \begin_inset LatexCommand \index{Loop reversing}
6550
6551 \end_inset
6552
6553 optimization.
6554 \layout List
6555 \labelwidthstring 00.00.0000
6556
6557 -
6558 \begin_inset ERT
6559 status Collapsed
6560
6561 \layout Standard
6562
6563 \backslash
6564 /
6565 \end_inset
6566
6567 -
6568 \series bold
6569 nolabelopt
6570 \series default
6571
6572 \begin_inset LatexCommand \index{-\/-nolabelopt }
6573
6574 \end_inset
6575
6576 Will not optimize labels (makes the dumpfiles more readable).
6577 \layout List
6578 \labelwidthstring 00.00.0000
6579
6580
6581 \series bold
6582 -
6583 \begin_inset ERT
6584 status Collapsed
6585
6586 \layout Standard
6587
6588 \backslash
6589 /
6590 \end_inset
6591
6592 -no-xinit-opt
6593 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6594
6595 \end_inset
6596
6597
6598 \series default
6599  Will not memcpy initialized data from code space into xdata space.
6600  This saves a few bytes in code space if you don't have initialized data.
6601 \layout List
6602 \labelwidthstring 00.00.0000
6603
6604
6605 \series bold
6606 -
6607 \begin_inset ERT
6608 status Collapsed
6609
6610 \layout Standard
6611
6612 \backslash
6613 /
6614 \end_inset
6615
6616 -nooverlay
6617 \begin_inset LatexCommand \index{-\/-nooverlay}
6618
6619 \end_inset
6620
6621
6622 \series default
6623   The compiler will not overlay parameters and local variables of any function,
6624  see section Parameters and local variables for more details.
6625 \layout List
6626 \labelwidthstring 00.00.0000
6627
6628
6629 \series bold
6630 -
6631 \begin_inset ERT
6632 status Collapsed
6633
6634 \layout Standard
6635
6636 \backslash
6637 /
6638 \end_inset
6639
6640 -no-peep
6641 \begin_inset LatexCommand \index{-\/-no-peep}
6642
6643 \end_inset
6644
6645
6646 \series default
6647  Disable peep-hole optimization.
6648 \layout List
6649 \labelwidthstring 00.00.0000
6650
6651
6652 \series bold
6653 -
6654 \begin_inset ERT
6655 status Collapsed
6656
6657 \layout Standard
6658
6659 \backslash
6660 /
6661 \end_inset
6662
6663 -peep-file
6664 \series default
6665
6666 \begin_inset LatexCommand \index{-\/-peep-file}
6667
6668 \end_inset
6669
6670 \SpecialChar ~
6671 <filename> This option can be used to use additional rules to be used by
6672  the peep hole optimizer.
6673  See section
6674 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6675
6676 \end_inset
6677
6678 \SpecialChar ~
6679 Peep Hole optimizations for details on how to write these rules.
6680 \layout List
6681 \labelwidthstring 00.00.0000
6682
6683
6684 \series bold
6685 -
6686 \begin_inset ERT
6687 status Collapsed
6688
6689 \layout Standard
6690
6691 \backslash
6692 /
6693 \end_inset
6694
6695 -peep-asm
6696 \begin_inset LatexCommand \index{-\/-peep-asm}
6697
6698 \end_inset
6699
6700
6701 \series default
6702  Pass the inline assembler code through the peep hole optimizer.
6703  This can cause unexpected changes to inline assembler code, please go through
6704  the peephole optimizer
6705 \begin_inset LatexCommand \index{Peephole optimizer}
6706
6707 \end_inset
6708
6709  rules defined in the source file tree '<target>/peeph.def' before using
6710  this option.
6711 \layout List
6712 \labelwidthstring 00.00.0000
6713
6714
6715 \series bold
6716 -
6717 \begin_inset ERT
6718 status Collapsed
6719
6720 \layout Standard
6721
6722 \backslash
6723 /
6724 \end_inset
6725
6726 -opt-code-speed
6727 \begin_inset LatexCommand \index{-\/-opt-code-speed}
6728
6729 \end_inset
6730
6731
6732 \series default
6733  The compiler will optimize code generation towards fast code, possibly
6734  at the expense of code size.
6735 \layout List
6736 \labelwidthstring 00.00.0000
6737
6738
6739 \series bold
6740 -
6741 \begin_inset ERT
6742 status Collapsed
6743
6744 \layout Standard
6745
6746 \backslash
6747 /
6748 \end_inset
6749
6750 -opt-code-size
6751 \begin_inset LatexCommand \index{-\/-opt-code-size}
6752
6753 \end_inset
6754
6755
6756 \series default
6757  The compiler will optimize code generation towards compact code, possibly
6758  at the expense of code speed.
6759 \layout Subsection
6760
6761 Other Options
6762 \begin_inset LatexCommand \index{Options other}
6763
6764 \end_inset
6765
6766
6767 \layout List
6768 \labelwidthstring 00.00.0000
6769
6770
6771 \series bold
6772 -c\SpecialChar ~
6773 -
6774 \begin_inset ERT
6775 status Collapsed
6776
6777 \layout Standard
6778
6779 \backslash
6780 /
6781 \end_inset
6782
6783 -compile-only
6784 \begin_inset LatexCommand \index{-\/-compile-only}
6785
6786 \end_inset
6787
6788
6789 \begin_inset LatexCommand \index{-c -\/-compile-only}
6790
6791 \end_inset
6792
6793
6794 \series default
6795  will compile and assemble the source, but will not call the linkage editor.
6796 \layout List
6797 \labelwidthstring 00.00.0000
6798
6799
6800 \series bold
6801 -
6802 \series default
6803
6804 \begin_inset ERT
6805 status Collapsed
6806
6807 \layout Standard
6808
6809 \backslash
6810 /
6811 \end_inset
6812
6813
6814 \series bold
6815 -c1mode
6816 \begin_inset LatexCommand \index{-\/-c1mode}
6817
6818 \end_inset
6819
6820
6821 \series default
6822  reads the preprocessed source from standard input and compiles it.
6823  The file name for the assembler output must be specified using the -o option.
6824 \layout List
6825 \labelwidthstring 00.00.0000
6826
6827
6828 \series bold
6829 -E
6830 \begin_inset LatexCommand \index{-E}
6831
6832 \end_inset
6833
6834
6835 \series default
6836  Run only the C preprocessor.
6837  Preprocess all the C source files specified and output the results to standard
6838  output.
6839 \layout List
6840 \labelwidthstring 00.00.0000
6841
6842
6843 \series bold
6844 -o\SpecialChar ~
6845 <path/file>
6846 \begin_inset LatexCommand \index{-o <path/file>}
6847
6848 \end_inset
6849
6850
6851 \series default
6852 The output path resp.
6853  file where everything will be placed.
6854  If the parameter is a path, it must have a trailing slash (or backslash
6855  for the Windows binaries) to be recognized as a path.
6856
6857 \layout List
6858 \labelwidthstring 00.00.0000
6859
6860
6861 \series bold
6862 -
6863 \begin_inset ERT
6864 status Collapsed
6865
6866 \layout Standard
6867
6868 \backslash
6869 /
6870 \end_inset
6871
6872 -stack-auto
6873 \begin_inset LatexCommand \index{-\/-stack-auto}
6874
6875 \end_inset
6876
6877
6878 \series default
6879 \size large
6880 \emph on
6881
6882 \size default
6883 \emph default
6884 All functions in the source file will be compiled as
6885 \emph on
6886 reentrant
6887 \emph default
6888
6889 \begin_inset LatexCommand \index{reentrant}
6890
6891 \end_inset
6892
6893 , i.e.
6894  the parameters and local variables will be allocated on the stack
6895 \begin_inset LatexCommand \index{stack}
6896
6897 \end_inset
6898
6899 .
6900  See section
6901 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
6902
6903 \end_inset
6904
6905  Parameters and Local Variables for more details.
6906  If this option is used all source files in the project should be compiled
6907  with this option.
6908
6909 \layout List
6910 \labelwidthstring 00.00.0000
6911
6912
6913 \series bold
6914 -
6915 \begin_inset ERT
6916 status Collapsed
6917
6918 \layout Standard
6919
6920 \backslash
6921 /
6922 \end_inset
6923
6924 -callee-saves
6925 \begin_inset LatexCommand \index{-\/-callee-saves}
6926
6927 \end_inset
6928
6929  function1[,function2][,function3]....
6930
6931 \series default
6932  The compiler by default uses a caller saves convention for register saving
6933  across function calls, however this can cause unnecessary register pushing
6934  & popping when calling small functions from larger functions.
6935  This option can be used to switch the register saving convention for the
6936  function names specified.
6937  The compiler will not save registers when calling these functions, no extra
6938  code will be generated at the entry & exit (function prologue
6939 \series bold
6940
6941 \begin_inset LatexCommand \index{function prologue}
6942
6943 \end_inset
6944
6945
6946 \series default
6947  & epilogue
6948 \series bold
6949
6950 \begin_inset LatexCommand \index{function epilogue}
6951
6952 \end_inset
6953
6954
6955 \series default
6956 ) for these functions to save & restore the registers used by these functions,
6957  this can SUBSTANTIALLY reduce code & improve run time performance of the
6958  generated code.
6959  In the future the compiler (with inter procedural analysis) will be able
6960  to determine the appropriate scheme to use for each function call.
6961  DO NOT use this option for built-in functions such as _mulint..., if this
6962  option is used for a library function the appropriate library function
6963  needs to be recompiled with the same option.
6964  If the project consists of multiple source files then all the source file
6965  should be compiled with the same -
6966 \begin_inset ERT
6967 status Collapsed
6968
6969 \layout Standard
6970
6971 \backslash
6972 /
6973 \end_inset
6974
6975 -callee-saves option string.
6976  Also see #pragma\SpecialChar ~
6977 callee_saves
6978 \begin_inset LatexCommand \index{\#pragma callee\_saves}
6979
6980 \end_inset
6981
6982 .
6983 \layout List
6984 \labelwidthstring 00.00.0000
6985
6986
6987 \series bold
6988 -
6989 \begin_inset ERT
6990 status Collapsed
6991
6992 \layout Standard
6993
6994 \backslash
6995 /
6996 \end_inset
6997
6998 -debug
6999 \begin_inset LatexCommand \index{-\/-debug}
7000
7001 \end_inset
7002
7003
7004 \bar under
7005
7006 \series default
7007 \bar default
7008 When this option is used the compiler will generate debug information.
7009  The debug information collected in a file with .cdb extension can be used
7010  with the SDCDB.
7011  For more information see documentation for SDCDB.
7012  Another file with no extension contains debug information in AOMF or AOMF51
7013 \begin_inset LatexCommand \index{AOMF, AOMF51}
7014
7015 \end_inset
7016
7017  format which is commonly used by third party tools.
7018 \layout List
7019 \labelwidthstring 00.00.0000
7020
7021
7022 \series bold
7023 -S
7024 \begin_inset LatexCommand \index{-S}
7025
7026 \end_inset
7027
7028
7029 \size large
7030 \bar under
7031
7032 \series default
7033 \size default
7034 \bar default
7035 Stop after the stage of compilation proper; do not assemble.
7036  The output is an assembler code file for the input file specified.
7037 \layout List
7038 \labelwidthstring 00.00.0000
7039
7040
7041 \series bold
7042 -
7043 \begin_inset ERT
7044 status Collapsed
7045
7046 \layout Standard
7047
7048 \backslash
7049 /
7050 \end_inset
7051
7052 -int-long-reent
7053 \begin_inset LatexCommand \index{-\/-int-long-reent}
7054
7055 \end_inset
7056
7057
7058 \series default
7059  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7060  Note by default these libraries are compiled as non-reentrant.
7061  See section Installation for more details.
7062 \layout List
7063 \labelwidthstring 00.00.0000
7064
7065
7066 \series bold
7067 -
7068 \begin_inset ERT
7069 status Collapsed
7070
7071 \layout Standard
7072
7073 \backslash
7074 /
7075 \end_inset
7076
7077 -cyclomatic
7078 \begin_inset LatexCommand \index{-\/-cyclomatic}
7079
7080 \end_inset
7081
7082
7083 \bar under
7084
7085 \series default
7086 \bar default
7087 This option will cause the compiler to generate an information message for
7088  each function in the source file.
7089  The message contains some
7090 \emph on
7091 important
7092 \emph default
7093  information about the function.
7094  The number of edges and nodes the compiler detected in the control flow
7095  graph of the function, and most importantly the
7096 \emph on
7097 cyclomatic complexity
7098 \begin_inset LatexCommand \index{Cyclomatic complexity}
7099
7100 \end_inset
7101
7102
7103 \emph default
7104  see section on Cyclomatic Complexity for more details.
7105 \layout List
7106 \labelwidthstring 00.00.0000
7107
7108
7109 \series bold
7110 -
7111 \begin_inset ERT
7112 status Collapsed
7113
7114 \layout Standard
7115
7116 \backslash
7117 /
7118 \end_inset
7119
7120 -float-reent
7121 \begin_inset LatexCommand \index{-\/-float-reent}
7122
7123 \end_inset
7124
7125
7126 \series default
7127  Floating point library is compiled as reentrant
7128 \begin_inset LatexCommand \index{reentrant}
7129
7130 \end_inset
7131
7132 .
7133  See section Installation for more details.
7134 \layout List
7135 \labelwidthstring 00.00.0000
7136
7137
7138 \series bold
7139 -
7140 \begin_inset ERT
7141 status Collapsed
7142
7143 \layout Standard
7144
7145 \backslash
7146 /
7147 \end_inset
7148
7149 -main-return
7150 \begin_inset LatexCommand \index{-\/-main-return}
7151
7152 \end_inset
7153
7154
7155 \series default
7156  This option can be used if the code generated is called by a monitor program
7157  or if the main routine includes an endless loop.
7158  This option might result in slightly smaller code and save two bytes of
7159  stack space.
7160  The return from the 'main'
7161 \begin_inset LatexCommand \index{main return}
7162
7163 \end_inset
7164
7165  function will return to the function calling main.
7166  The default setting is to lock up i.e.
7167  generate a '
7168 \family typewriter
7169 sjmp .
7170 \family default
7171 '.
7172 \layout List
7173 \labelwidthstring 00.00.0000
7174
7175
7176 \series bold
7177 -
7178 \begin_inset ERT
7179 status Collapsed
7180
7181 \layout Standard
7182
7183 \backslash
7184 /
7185 \end_inset
7186
7187 -nostdincl
7188 \begin_inset LatexCommand \index{-\/-nostdincl}
7189
7190 \end_inset
7191
7192
7193 \series default
7194  This will prevent the compiler from passing on the default include path
7195  to the preprocessor.
7196 \layout List
7197 \labelwidthstring 00.00.0000
7198
7199
7200 \series bold
7201 -
7202 \begin_inset ERT
7203 status Collapsed
7204
7205 \layout Standard
7206
7207 \backslash
7208 /
7209 \end_inset
7210
7211 -nostdlib
7212 \begin_inset LatexCommand \index{-\/-nostdlib}
7213
7214 \end_inset
7215
7216
7217 \series default
7218  This will prevent the compiler from passing on the default library
7219 \begin_inset LatexCommand \index{Libraries}
7220
7221 \end_inset
7222
7223  path to the linker.
7224 \layout List
7225 \labelwidthstring 00.00.0000
7226
7227
7228 \series bold
7229 -
7230 \begin_inset ERT
7231 status Collapsed
7232
7233 \layout Standard
7234
7235 \backslash
7236 /
7237 \end_inset
7238
7239 -verbose
7240 \begin_inset LatexCommand \index{-\/-verbose}
7241
7242 \end_inset
7243
7244
7245 \series default
7246  Shows the various actions the compiler is performing.
7247 \layout List
7248 \labelwidthstring 00.00.0000
7249
7250
7251 \series bold
7252 -V
7253 \begin_inset LatexCommand \index{-V}
7254
7255 \end_inset
7256
7257
7258 \series default
7259  Shows the actual commands the compiler is executing.
7260 \layout List
7261 \labelwidthstring 00.00.0000
7262
7263
7264 \series bold
7265 -
7266 \begin_inset ERT
7267 status Collapsed
7268
7269 \layout Standard
7270
7271 \backslash
7272 /
7273 \end_inset
7274
7275 -no-c-code-in-asm
7276 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7277
7278 \end_inset
7279
7280
7281 \series default
7282  Hides your ugly and inefficient c-code from the asm file, so you can always
7283  blame the compiler :)
7284 \layout List
7285 \labelwidthstring 00.00.0000
7286
7287
7288 \series bold
7289 -
7290 \begin_inset ERT
7291 status Collapsed
7292
7293 \layout Standard
7294
7295 \backslash
7296 /
7297 \end_inset
7298
7299 -no-peep-comments
7300 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7301
7302 \end_inset
7303
7304
7305 \series default
7306  Will not include peep-hole comments in the generated files.
7307 \layout List
7308 \labelwidthstring 00.00.0000
7309
7310
7311 \series bold
7312 -
7313 \begin_inset ERT
7314 status Collapsed
7315
7316 \layout Standard
7317
7318 \backslash
7319 /
7320 \end_inset
7321
7322 -i-code-in-asm
7323 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7324
7325 \end_inset
7326
7327
7328 \series default
7329  Include i-codes in the asm file.
7330  Sounds like noise but is most helpful for debugging the compiler itself.
7331 \layout List
7332 \labelwidthstring 00.00.0000
7333
7334
7335 \series bold
7336 -
7337 \begin_inset ERT
7338 status Collapsed
7339
7340 \layout Standard
7341
7342 \backslash
7343 /
7344 \end_inset
7345
7346 -less-pedantic
7347 \begin_inset LatexCommand \index{-\/-less-pedantic}
7348
7349 \end_inset
7350
7351
7352 \series default
7353  Disable some of the more pedantic warnings
7354 \begin_inset LatexCommand \index{Warnings}
7355
7356 \end_inset
7357
7358  (jwk burps: please be more specific here, please!).
7359  If you want rather more than less warnings you should consider using a
7360  separate tool dedicated to syntax checking like splint
7361 \begin_inset LatexCommand \url{www.splint.org}
7362
7363 \end_inset
7364
7365 .
7366 \layout List
7367 \labelwidthstring 00.00.0000
7368
7369
7370 \series bold
7371 -
7372 \begin_inset ERT
7373 status Collapsed
7374
7375 \layout Standard
7376
7377 \backslash
7378 /
7379 \end_inset
7380
7381 -disable-warning\SpecialChar ~
7382 <nnnn>
7383 \begin_inset LatexCommand \index{-\/-disable-warning}
7384
7385 \end_inset
7386
7387
7388 \series default
7389  Disable specific warning with number <nnnn>.
7390 \layout List
7391 \labelwidthstring 00.00.0000
7392
7393
7394 \series bold
7395 -
7396 \begin_inset ERT
7397 status Collapsed
7398
7399 \layout Standard
7400
7401 \backslash
7402 /
7403 \end_inset
7404
7405 -print-search-dirs
7406 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7407
7408 \end_inset
7409
7410
7411 \series default
7412  Display the directories in the compiler's search path
7413 \layout List
7414 \labelwidthstring 00.00.0000
7415
7416
7417 \series bold
7418 -
7419 \begin_inset ERT
7420 status Collapsed
7421
7422 \layout Standard
7423
7424 \backslash
7425 /
7426 \end_inset
7427
7428 -vc
7429 \begin_inset LatexCommand \index{-\/-vc}
7430
7431 \end_inset
7432
7433
7434 \series default
7435  Display errors and warnings using MSVC style, so you can use SDCC with
7436  visual studio.
7437 \layout List
7438 \labelwidthstring 00.00.0000
7439
7440
7441 \series bold
7442 -
7443 \begin_inset ERT
7444 status Collapsed
7445
7446 \layout Standard
7447
7448 \backslash
7449 /
7450 \end_inset
7451
7452 -use-stdout
7453 \begin_inset LatexCommand \index{-\/-use-stdout}
7454
7455 \end_inset
7456
7457
7458 \series default
7459  Send errors and warnings to stdout instead of stderr.
7460 \layout List
7461 \labelwidthstring 00.00.0000
7462
7463
7464 \series bold
7465 -Wa\SpecialChar ~
7466 asmOption[,asmOption]
7467 \series default
7468
7469 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7470
7471 \end_inset
7472
7473 ...
7474  Pass the asmOption to the assembler
7475 \begin_inset LatexCommand \index{Options assembler}
7476
7477 \end_inset
7478
7479
7480 \begin_inset LatexCommand \index{Assembler options}
7481
7482 \end_inset
7483
7484 .
7485  See file sdcc/as/doc/asxhtm.html for assembler options.
7486 \layout Subsection
7487
7488 Intermediate Dump Options
7489 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7490
7491 \end_inset
7492
7493
7494 \begin_inset LatexCommand \index{Options intermediate dump}
7495
7496 \end_inset
7497
7498
7499 \begin_inset LatexCommand \index{Intermediate dump options}
7500
7501 \end_inset
7502
7503
7504 \layout Standard
7505
7506 The following options are provided for the purpose of retargetting and debugging
7507  the compiler.
7508  These provided a means to dump the intermediate code (iCode
7509 \begin_inset LatexCommand \index{iCode}
7510
7511 \end_inset
7512
7513 ) generated by the compiler in human readable form at various stages of
7514  the compilation process.
7515  More on iCodes see chapter
7516 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7517
7518 \end_inset
7519
7520
7521 \begin_inset Quotes srd
7522 \end_inset
7523
7524 The anatomy of the compiler
7525 \begin_inset Quotes srd
7526 \end_inset
7527
7528 .
7529 \layout List
7530 \labelwidthstring 00.00.0000
7531
7532
7533 \series bold
7534 -
7535 \begin_inset ERT
7536 status Collapsed
7537
7538 \layout Standard
7539
7540 \backslash
7541 /
7542 \end_inset
7543
7544 -dumpraw
7545 \begin_inset LatexCommand \index{-\/-dumpraw}
7546
7547 \end_inset
7548
7549
7550 \series default
7551  This option will cause the compiler to dump the intermediate code into
7552  a file of named
7553 \emph on
7554 <source filename>.dumpraw
7555 \emph default
7556  just after the intermediate code has been generated for a function, i.e.
7557  before any optimizations are done.
7558  The basic blocks
7559 \begin_inset LatexCommand \index{Basic blocks}
7560
7561 \end_inset
7562
7563  at this stage ordered in the depth first number, so they may not be in
7564  sequence of execution.
7565 \layout List
7566 \labelwidthstring 00.00.0000
7567
7568
7569 \series bold
7570 -
7571 \begin_inset ERT
7572 status Collapsed
7573
7574 \layout Standard
7575
7576 \backslash
7577 /
7578 \end_inset
7579
7580 -dumpgcse
7581 \begin_inset LatexCommand \index{-\/-dumpgcse}
7582
7583 \end_inset
7584
7585
7586 \series default
7587  Will create a dump of iCode's, after global subexpression elimination
7588 \begin_inset LatexCommand \index{Global subexpression elimination}
7589
7590 \end_inset
7591
7592 , into a file named
7593 \emph on
7594 <source filename>.dumpgcse.
7595 \layout List
7596 \labelwidthstring 00.00.0000
7597
7598
7599 \series bold
7600 -
7601 \begin_inset ERT
7602 status Collapsed
7603
7604 \layout Standard
7605
7606 \backslash
7607 /
7608 \end_inset
7609
7610 -dumpdeadcode
7611 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
7612
7613 \end_inset
7614
7615
7616 \series default
7617  Will create a dump of iCode's, after deadcode elimination
7618 \begin_inset LatexCommand \index{Dead-code elimination}
7619
7620 \end_inset
7621
7622 , into a file named
7623 \emph on
7624 <source filename>.dumpdeadcode.
7625 \layout List
7626 \labelwidthstring 00.00.0000
7627
7628
7629 \series bold
7630 -
7631 \begin_inset ERT
7632 status Collapsed
7633
7634 \layout Standard
7635
7636 \backslash
7637 /
7638 \end_inset
7639
7640 -dumploop
7641 \begin_inset LatexCommand \index{-\/-dumploop}
7642
7643 \end_inset
7644
7645
7646 \series default
7647 \size large
7648
7649 \size default
7650 Will create a dump of iCode's, after loop optimizations
7651 \begin_inset LatexCommand \index{Loop optimization}
7652
7653 \end_inset
7654
7655 , into a file named
7656 \emph on
7657 <source filename>.dumploop.
7658 \layout List
7659 \labelwidthstring 00.00.0000
7660
7661
7662 \series bold
7663 -
7664 \begin_inset ERT
7665 status Collapsed
7666
7667 \layout Standard
7668
7669 \backslash
7670 /
7671 \end_inset
7672
7673 -dumprange
7674 \begin_inset LatexCommand \index{-\/-dumprange}
7675
7676 \end_inset
7677
7678
7679 \series default
7680 \size large
7681
7682 \size default
7683 Will create a dump of iCode's, after live range analysis
7684 \begin_inset LatexCommand \index{Live range analysis}
7685
7686 \end_inset
7687
7688 , into a file named
7689 \emph on
7690 <source filename>.dumprange.
7691 \layout List
7692 \labelwidthstring 00.00.0000
7693
7694
7695 \series bold
7696 -
7697 \begin_inset ERT
7698 status Collapsed
7699
7700 \layout Standard
7701
7702 \backslash
7703 /
7704 \end_inset
7705
7706 -dumlrange
7707 \begin_inset LatexCommand \index{-\/-dumlrange}
7708
7709 \end_inset
7710
7711
7712 \series default
7713  Will dump the life ranges
7714 \begin_inset LatexCommand \index{Live range analysis}
7715
7716 \end_inset
7717
7718  for all symbols.
7719 \layout List
7720 \labelwidthstring 00.00.0000
7721
7722
7723 \series bold
7724 -
7725 \begin_inset ERT
7726 status Collapsed
7727
7728 \layout Standard
7729
7730 \backslash
7731 /
7732 \end_inset
7733
7734 -dumpregassign
7735 \begin_inset LatexCommand \index{-\/-dumpregassign}
7736
7737 \end_inset
7738
7739
7740 \bar under
7741
7742 \series default
7743 \bar default
7744 Will create a dump of iCode's, after register assignment
7745 \begin_inset LatexCommand \index{Register assignment}
7746
7747 \end_inset
7748
7749 , into a file named
7750 \emph on
7751 <source filename>.dumprassgn.
7752 \layout List
7753 \labelwidthstring 00.00.0000
7754
7755
7756 \series bold
7757 -
7758 \begin_inset ERT
7759 status Collapsed
7760
7761 \layout Standard
7762
7763 \backslash
7764 /
7765 \end_inset
7766
7767 -dumplrange
7768 \begin_inset LatexCommand \index{-\/-dumplrange}
7769
7770 \end_inset
7771
7772
7773 \series default
7774  Will create a dump of the live ranges of iTemp's
7775 \layout List
7776 \labelwidthstring 00.00.0000
7777
7778
7779 \series bold
7780 -
7781 \begin_inset ERT
7782 status Collapsed
7783
7784 \layout Standard
7785
7786 \backslash
7787 /
7788 \end_inset
7789
7790 -dumpall
7791 \begin_inset LatexCommand \index{-\/-dumpall}
7792
7793 \end_inset
7794
7795
7796 \size large
7797 \bar under
7798
7799 \series default
7800 \size default
7801 \bar default
7802 Will cause all the above mentioned dumps to be created.
7803 \layout Subsection
7804
7805 Redirecting output on Windows Shells
7806 \layout Standard
7807
7808 By default SDCC writes it's error messages to
7809 \begin_inset Quotes sld
7810 \end_inset
7811
7812 standard error
7813 \begin_inset Quotes srd
7814 \end_inset
7815
7816 .
7817  To force all messages to
7818 \begin_inset Quotes sld
7819 \end_inset
7820
7821 standard output
7822 \begin_inset Quotes srd
7823 \end_inset
7824
7825  use
7826 \series bold
7827 -
7828 \series default
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 \series bold
7842 \emph default
7843 -
7844 \series default
7845 use-stdout
7846 \begin_inset LatexCommand \index{-\/-use-stdout}
7847
7848 \end_inset
7849
7850 .
7851  Additionally, if you happen to have visual studio installed in your windows
7852  machine, you can use it to compile your sources using a custom build and
7853  the SDCC -
7854 \emph on
7855
7856 \begin_inset ERT
7857 status Collapsed
7858
7859 \layout Standard
7860
7861 \backslash
7862 /
7863 \end_inset
7864
7865
7866 \emph default
7867 -vc
7868 \begin_inset LatexCommand \index{-\/-vc}
7869
7870 \end_inset
7871
7872  option.
7873  Something like this should work:
7874 \newline
7875
7876 \newline
7877
7878 \series bold
7879 c:
7880 \backslash
7881 sdcc
7882 \backslash
7883 bin
7884 \backslash
7885 sdcc.exe -
7886 \series default
7887 \emph on
7888
7889 \begin_inset ERT
7890 status Collapsed
7891
7892 \layout Standard
7893
7894 \backslash
7895 /
7896 \end_inset
7897
7898
7899 \series bold
7900 \emph default
7901 -vc -
7902 \series default
7903 \emph on
7904
7905 \begin_inset ERT
7906 status Collapsed
7907
7908 \layout Standard
7909
7910 \backslash
7911 /
7912 \end_inset
7913
7914
7915 \series bold
7916 \emph default
7917 -model-large -c $(InputPath)
7918 \layout Section
7919
7920 Environment variables
7921 \begin_inset LatexCommand \index{Environment variables}
7922
7923 \end_inset
7924
7925
7926 \layout Standard
7927
7928 SDCC recognizes the following environment variables:
7929 \layout List
7930 \labelwidthstring 00.00.0000
7931
7932
7933 \series bold
7934 SDCC_LEAVE_SIGNALS
7935 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
7936
7937 \end_inset
7938
7939
7940 \series default
7941  SDCC installs a signal handler
7942 \begin_inset LatexCommand \index{signal handler}
7943
7944 \end_inset
7945
7946  to be able to delete temporary files after an user break (^C) or an exception.
7947  If this environment variable is set, SDCC won't install the signal handler
7948  in order to be able to debug SDCC.
7949 \layout List
7950 \labelwidthstring 00.00.0000
7951
7952
7953 \series bold
7954 TMP,\SpecialChar ~
7955 TEMP,\SpecialChar ~
7956 TMPDIR
7957 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
7958
7959 \end_inset
7960
7961
7962 \series default
7963  Path, where temporary files will be created.
7964  The order of the variables is the search order.
7965  In a standard *nix environment these variables are not set, and there's
7966  no need to set them.
7967  On Windows it's recommended to set one of them.
7968 \layout List
7969 \labelwidthstring 00.00.0000
7970
7971
7972 \series bold
7973 SDCC_HOME
7974 \begin_inset LatexCommand \index{SDCC\_HOME}
7975
7976 \end_inset
7977
7978
7979 \series default
7980  Path, see section
7981 \begin_inset LatexCommand \ref{sub:Install-paths}
7982
7983 \end_inset
7984
7985 \SpecialChar ~
7986
7987 \begin_inset Quotes sld
7988 \end_inset
7989
7990  Install Paths
7991 \begin_inset Quotes srd
7992 \end_inset
7993
7994 .
7995 \layout List
7996 \labelwidthstring 00.00.0000
7997
7998
7999 \series bold
8000 SDCC_INCLUDE
8001 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8002
8003 \end_inset
8004
8005
8006 \series default
8007  Path, see section
8008 \begin_inset LatexCommand \ref{sub:Search-Paths}
8009
8010 \end_inset
8011
8012 \SpecialChar ~
8013
8014 \begin_inset Quotes sld
8015 \end_inset
8016
8017 Search Paths
8018 \begin_inset Quotes srd
8019 \end_inset
8020
8021 .
8022 \layout List
8023 \labelwidthstring 00.00.0000
8024
8025
8026 \series bold
8027 SDCC_LIB
8028 \begin_inset LatexCommand \index{SDCC\_LIB}
8029
8030 \end_inset
8031
8032
8033 \series default
8034  Path, see section
8035 \begin_inset LatexCommand \ref{sub:Search-Paths}
8036
8037 \end_inset
8038
8039 \SpecialChar ~
8040
8041 \begin_inset Quotes sld
8042 \end_inset
8043
8044 Search Paths
8045 \begin_inset Quotes srd
8046 \end_inset
8047
8048 ..
8049 \layout Standard
8050
8051 There are some more environment variables recognized by SDCC, but these
8052  are solely used for debugging purposes.
8053  They can change or disappear very quickly, and will never be documented.
8054 \layout Section
8055
8056 Storage Class Language Extensions
8057 \layout Subsection
8058
8059 MCS51/DS390 Storage Class
8060 \begin_inset LatexCommand \index{Storage class}
8061
8062 \end_inset
8063
8064  Language Extensions
8065 \layout Standard
8066
8067 In addition to the ANSI storage classes SDCC allows the following MCS51
8068  specific storage classes:
8069 \layout Subsubsection
8070
8071 data
8072 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8073
8074 \end_inset
8075
8076  / near
8077 \begin_inset LatexCommand \index{near (storage class)}
8078
8079 \end_inset
8080
8081
8082 \layout Standard
8083
8084 This is the
8085 \series bold
8086 default
8087 \series default
8088  storage class for the Small Memory model (
8089 \emph on
8090 data
8091 \emph default
8092  and
8093 \emph on
8094 near
8095 \emph default
8096  can be used synonymously).
8097  Variables declared with this storage class will be allocated in the directly
8098  addressable portion of the internal RAM of a 8051, e.g.:
8099 \layout Verse
8100
8101
8102 \family typewriter
8103 data unsigned char test_data;
8104 \layout Standard
8105
8106 Writing 0x01 to this variable generates the assembly code:
8107 \layout Verse
8108
8109
8110 \family typewriter
8111 75*00 01\SpecialChar ~
8112 \SpecialChar ~
8113 \SpecialChar ~
8114 mov\SpecialChar ~
8115 \SpecialChar ~
8116 _test_data,#0x01
8117 \layout Subsubsection
8118
8119 xdata
8120 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8121
8122 \end_inset
8123
8124  / far
8125 \begin_inset LatexCommand \index{far (storage class)}
8126
8127 \end_inset
8128
8129
8130 \layout Standard
8131
8132 Variables declared with this storage class will be placed in the external
8133  RAM.
8134  This is the
8135 \series bold
8136 default
8137 \series default
8138  storage class for the Large Memory model, e.g.:
8139 \layout Verse
8140
8141
8142 \family typewriter
8143 xdata unsigned char test_xdata;
8144 \layout Standard
8145
8146 Writing 0x01 to this variable generates the assembly code:
8147 \layout Verse
8148
8149
8150 \family typewriter
8151 90s00r00\SpecialChar ~
8152 \SpecialChar ~
8153 \SpecialChar ~
8154 mov\SpecialChar ~
8155 \SpecialChar ~
8156 dptr,#_test_xdata
8157 \newline
8158 74\SpecialChar ~
8159 01\SpecialChar ~
8160 \SpecialChar ~
8161 \SpecialChar ~
8162 \SpecialChar ~
8163 \SpecialChar ~
8164 \SpecialChar ~
8165 mov\SpecialChar ~
8166 \SpecialChar ~
8167 a,#0x01
8168 \newline
8169 F0\SpecialChar ~
8170 \SpecialChar ~
8171 \SpecialChar ~
8172 \SpecialChar ~
8173 \SpecialChar ~
8174 \SpecialChar ~
8175 \SpecialChar ~
8176 \SpecialChar ~
8177 \SpecialChar ~
8178 movx\SpecialChar ~
8179 @dptr,a
8180 \layout Subsubsection
8181
8182 idata
8183 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8184
8185 \end_inset
8186
8187
8188 \layout Standard
8189
8190 Variables declared with this storage class will be allocated into the indirectly
8191  addressable portion of the internal ram of a 8051, e.g.:
8192 \layout Verse
8193
8194
8195 \family typewriter
8196 idata unsigned char test_idata;
8197 \layout Standard
8198
8199 Writing 0x01 to this variable generates the assembly code:
8200 \layout Verse
8201
8202
8203 \family typewriter
8204 78r00\SpecialChar ~
8205 \SpecialChar ~
8206 \SpecialChar ~
8207 \SpecialChar ~
8208 \SpecialChar ~
8209 \SpecialChar ~
8210 \SpecialChar ~
8211 mov\SpecialChar ~
8212 \SpecialChar ~
8213 r0,#_test_idata
8214 \newline
8215 76\SpecialChar ~
8216 01\SpecialChar ~
8217 \SpecialChar ~
8218 \SpecialChar ~
8219 \SpecialChar ~
8220 \SpecialChar ~
8221 \SpecialChar ~
8222 \SpecialChar ~
8223 mov\SpecialChar ~
8224 \SpecialChar ~
8225 @r0,#0x01
8226 \layout Standard
8227
8228 Please note, the first 128 byte of idata physically access the same RAM
8229  as the data memory.
8230  The original 8051 had 128 byte idata memory, nowadays most devices have
8231  256 byte idata memory.
8232  The stack
8233 \begin_inset LatexCommand \index{stack}
8234
8235 \end_inset
8236
8237  is located in idata memory.
8238 \layout Subsubsection
8239
8240 pdata
8241 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8242
8243 \end_inset
8244
8245
8246 \layout Standard
8247
8248 Paged xdata access is currently not as straightforward as using the other
8249  addressing modes of a 8051.
8250  The following example writes 0x01 to the address pointed to.
8251  Please note, pdata access physically accesses xdata memory.
8252  The high byte of the address is determined by port P2
8253 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8254
8255 \end_inset
8256
8257 (or in case of some 8051 variants by a separate Special Function Register,
8258  see section
8259 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8260
8261 \end_inset
8262
8263 ).
8264 \layout Verse
8265
8266
8267 \family typewriter
8268 pdata unsigned char *test_pdata_ptr;
8269 \newline
8270
8271 \newline
8272 void main()
8273 \newline
8274 {
8275 \newline
8276 \SpecialChar ~
8277 \SpecialChar ~
8278 \SpecialChar ~
8279 \SpecialChar ~
8280 test_pdata_ptr = (pdata *)0xfe;
8281 \newline
8282 \SpecialChar ~
8283 \SpecialChar ~
8284 \SpecialChar ~
8285 \SpecialChar ~
8286 *test_pdata_ptr = 1;
8287 \newline
8288 }
8289 \layout Standard
8290
8291 Generates the assembly code:
8292 \layout Verse
8293
8294
8295 \family typewriter
8296 75*01 FE\SpecialChar ~
8297 \SpecialChar ~
8298 \SpecialChar ~
8299 mov\SpecialChar ~
8300  _test_pdata_ptr,#0xFE
8301 \newline
8302 78 FE\SpecialChar ~
8303 \SpecialChar ~
8304 \SpecialChar ~
8305 \SpecialChar ~
8306 \SpecialChar ~
8307 \SpecialChar ~
8308 mov\SpecialChar ~
8309  r0,#0xFE
8310 \newline
8311 74 01\SpecialChar ~
8312 \SpecialChar ~
8313 \SpecialChar ~
8314 \SpecialChar ~
8315 \SpecialChar ~
8316 \SpecialChar ~
8317 mov\SpecialChar ~
8318  a,#0x01
8319 \newline
8320 F2\SpecialChar ~
8321 \SpecialChar ~
8322 \SpecialChar ~
8323 \SpecialChar ~
8324 \SpecialChar ~
8325 \SpecialChar ~
8326 \SpecialChar ~
8327 \SpecialChar ~
8328 \SpecialChar ~
8329 movx @r0,a
8330 \layout Standard
8331
8332 Be extremely carefull if you use pdata together with the -
8333 \begin_inset ERT
8334 status Collapsed
8335
8336 \layout Standard
8337
8338 \backslash
8339 /
8340 \end_inset
8341
8342 -xstack
8343 \begin_inset LatexCommand \index{-\/-xstack}
8344
8345 \end_inset
8346
8347  option.
8348 \layout Subsubsection
8349
8350 code
8351 \begin_inset LatexCommand \index{code}
8352
8353 \end_inset
8354
8355
8356 \layout Standard
8357
8358 'Variables' declared with this storage class will be placed in the code
8359  memory:
8360 \layout Verse
8361
8362
8363 \family typewriter
8364 code unsigned char test_code;
8365 \layout Standard
8366
8367 Read access to this variable generates the assembly code:
8368 \layout Verse
8369
8370
8371 \family typewriter
8372 90s00r6F\SpecialChar ~
8373 \SpecialChar ~
8374 \SpecialChar ~
8375 mov dptr,#_test_code
8376 \newline
8377 E4\SpecialChar ~
8378 \SpecialChar ~
8379 \SpecialChar ~
8380 \SpecialChar ~
8381 \SpecialChar ~
8382 \SpecialChar ~
8383 \SpecialChar ~
8384 \SpecialChar ~
8385 \SpecialChar ~
8386 clr a
8387 \newline
8388 93\SpecialChar ~
8389 \SpecialChar ~
8390 \SpecialChar ~
8391 \SpecialChar ~
8392 \SpecialChar ~
8393 \SpecialChar ~
8394 \SpecialChar ~
8395 \SpecialChar ~
8396 \SpecialChar ~
8397 movc a,@a+dptr
8398 \layout Standard
8399
8400
8401 \family typewriter
8402 char
8403 \family default
8404  indexed arrays of characters in code memory can be accessed efficiently:
8405 \layout Verse
8406
8407
8408 \family typewriter
8409 code char test_array[] = {'c','h','e','a','p'};
8410 \layout Standard
8411
8412 Read access to this array using an 8-bit unsigned index generates the assembly
8413  code:
8414 \layout Verse
8415
8416
8417 \family typewriter
8418 E5*00\SpecialChar ~
8419 \SpecialChar ~
8420 \SpecialChar ~
8421 \SpecialChar ~
8422 \SpecialChar ~
8423 \SpecialChar ~
8424 mov a,_index
8425 \layout Verse
8426
8427
8428 \family typewriter
8429 90s00r41\SpecialChar ~
8430 \SpecialChar ~
8431 \SpecialChar ~
8432 mov dptr,#_test_array
8433 \layout Verse
8434
8435
8436 \family typewriter
8437 93\SpecialChar ~
8438 \SpecialChar ~
8439 \SpecialChar ~
8440 \SpecialChar ~
8441 \SpecialChar ~
8442 \SpecialChar ~
8443 \SpecialChar ~
8444 \SpecialChar ~
8445 \SpecialChar ~
8446 movc a,@a+dptr
8447 \layout Subsubsection
8448
8449 bit
8450 \begin_inset LatexCommand \index{bit}
8451
8452 \end_inset
8453
8454
8455 \layout Standard
8456
8457 This is a data-type and a storage class specifier.
8458  When a variable is declared as a bit, it is allocated into the bit addressable
8459  memory of 8051, e.g.:
8460 \layout Verse
8461
8462
8463 \family typewriter
8464 bit test_bit;
8465 \layout Standard
8466
8467 Writing 1 to this variable generates the assembly code:
8468 \layout Verse
8469
8470
8471 \family typewriter
8472 D2*00\SpecialChar ~
8473 \SpecialChar ~
8474 \SpecialChar ~
8475 \SpecialChar ~
8476 \SpecialChar ~
8477 \SpecialChar ~
8478 \SpecialChar ~
8479 setb\SpecialChar ~
8480 _test_bit
8481 \layout Standard
8482
8483 The bit addressable memory consists of 128 bits which are located from 0x20
8484  to 0x2f in data memory.
8485
8486 \newline
8487 Apart from this 8051 specific storage class most architectures support ANSI-C
8488  bitfields
8489 \begin_inset LatexCommand \index{bitfields}
8490
8491 \end_inset
8492
8493
8494 \begin_inset Foot
8495 collapsed false
8496
8497 \layout Standard
8498
8499 Not really meant as examples, but nevertheless showing what bitfields are
8500  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8501 \end_inset
8502
8503 .
8504  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
8505  signed modifier are implemented as unsigned.
8506 \layout Subsubsection
8507
8508 sfr
8509 \begin_inset LatexCommand \index{sfr}
8510
8511 \end_inset
8512
8513  / sbit
8514 \begin_inset LatexCommand \index{sbit}
8515
8516 \end_inset
8517
8518
8519 \layout Standard
8520
8521 Like the bit keyword,
8522 \emph on
8523 sfr / sbit
8524 \emph default
8525 signifies both a data-type and storage class, they are used to describe
8526  the
8527 \emph on
8528 s
8529 \emph default
8530 pecial
8531 \emph on
8532 f
8533 \emph default
8534 unction
8535 \emph on
8536 r
8537 \emph default
8538 egisters and
8539 \emph on
8540 s
8541 \emph default
8542 pecial
8543 \emph on
8544 bit
8545 \emph default
8546  variables of a 8051, eg:
8547 \layout Verse
8548
8549
8550 \family typewriter
8551 sfr at
8552 \begin_inset LatexCommand \index{at}
8553
8554 \end_inset
8555
8556  0x80 P0;\SpecialChar ~
8557  /* special function register P0 at location 0x80 */
8558 \newline
8559 sbit at 0xd7 CY; /* CY (Carry Flag
8560 \begin_inset LatexCommand \index{Flags}
8561
8562 \end_inset
8563
8564
8565 \begin_inset LatexCommand \index{Carry flag}
8566
8567 \end_inset
8568
8569 ) */
8570 \layout Standard
8571
8572 Special function registers which are located on an address dividable by
8573  8 are bit-addressable, an
8574 \emph on
8575  sbit
8576 \emph default
8577  addresses a specific bit within these sfr.
8578 \layout Subsubsection
8579
8580 Pointers
8581 \begin_inset LatexCommand \index{Pointer}
8582
8583 \end_inset
8584
8585  to MCS51/DS390 specific memory spaces
8586 \layout Standard
8587
8588 SDCC allows (via language extensions) pointers to explicitly point to any
8589  of the memory spaces
8590 \begin_inset LatexCommand \index{Memory model}
8591
8592 \end_inset
8593
8594  of the 8051.
8595  In addition to the explicit pointers, the compiler uses (by default) generic
8596  pointers which can be used to point to any of the memory spaces.
8597 \newline
8598
8599 \newline
8600 Pointer declaration examples:
8601 \layout Verse
8602
8603
8604 \family typewriter
8605 /* pointer physically in internal ram pointing to object in external ram
8606  */
8607 \newline
8608 xdata unsigned char * data p;
8609 \newline
8610
8611 \newline
8612 /* pointer physically in external ram pointing to object in internal ram
8613  */
8614 \newline
8615 data unsigned char * xdata p;
8616 \newline
8617
8618 \newline
8619 /* pointer physically in code rom pointing to data in xdata space */
8620 \newline
8621 xdata unsigned char * code p;
8622 \newline
8623
8624 \newline
8625 /* pointer physically in code space pointing to data in code space */
8626 \newline
8627 code unsigned char * code p;
8628 \newline
8629
8630 \newline
8631 /* the following is a generic pointer physically located in xdata space
8632  */
8633 \newline
8634 char * xdata p;
8635 \layout Standard
8636
8637 Well you get the idea.
8638
8639 \newline
8640
8641 \newline
8642 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
8643 \emph on
8644 generic
8645 \emph default
8646  pointers.
8647
8648 \size small
8649
8650 \newline
8651
8652 \newline
8653
8654 \size default
8655 The highest order byte of the
8656 \emph on
8657 generic
8658 \emph default
8659  pointers contains the data space information.
8660  Assembler support routines are called whenever data is stored or retrieved
8661  using
8662 \emph on
8663 generic
8664 \emph default
8665  pointers.
8666  These are useful for developing reusable library
8667 \begin_inset LatexCommand \index{Libraries}
8668
8669 \end_inset
8670
8671  routines.
8672  Explicitly specifying the pointer type will generate the most efficient
8673  code.
8674 \layout Subsubsection
8675
8676 Notes on MCS51 memory
8677 \begin_inset LatexCommand \index{MCS51 memory}
8678
8679 \end_inset
8680
8681  layout
8682 \layout Standard
8683
8684 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
8685  RAM memory which is structured as follows:
8686 \newline
8687
8688 \newline
8689 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
8690
8691 \newline
8692 - Bytes 20-2F - 16 bytes to hold 128 bit
8693 \begin_inset LatexCommand \index{bit}
8694
8695 \end_inset
8696
8697  variables and,
8698 \newline
8699 - Bytes 30-7F - 80 bytes for general purpose use.
8700 \newline
8701
8702 \layout Standard
8703
8704 Additionally some members of the MCS51 family may have up to 128 bytes of
8705  additional, indirectly addressable, internal RAM memory (
8706 \emph on
8707 idata
8708 \emph default
8709
8710 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8711
8712 \end_inset
8713
8714 ).
8715  Furthermore, some chips may have some built in external memory (
8716 \emph on
8717 xdata
8718 \emph default
8719
8720 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8721
8722 \end_inset
8723
8724 ) which should not be confused with the internal, directly addressable RAM
8725  memory (
8726 \emph on
8727 data
8728 \emph default
8729
8730 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8731
8732 \end_inset
8733
8734 ).
8735  Sometimes this built in
8736 \emph on
8737 xdata
8738 \emph default
8739  memory has to be activated before using it (you can probably find this
8740  information on the datasheet of the microcontroller your are using, see
8741  also section
8742 \begin_inset LatexCommand \ref{sub:Startup-Code}
8743
8744 \end_inset
8745
8746 \SpecialChar ~
8747 Startup-Code).
8748 \layout Standard
8749
8750 Normally SDCC will only use the first bank
8751 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
8752
8753 \end_inset
8754
8755  of registers (register bank 0), but it is possible to specify that other
8756  banks of registers should be used in interrupt
8757 \begin_inset LatexCommand \index{interrupt}
8758
8759 \end_inset
8760
8761  routines.
8762  By default, the compiler will place the stack after the last byte of allocated
8763  memory for variables.
8764  For example, if the first 2 banks of registers are used, and only four
8765  bytes are used for
8766 \emph on
8767 data
8768 \emph default
8769  variables, it will position the base of the internal stack at address 20
8770  (0x14).
8771  This implies that as the stack
8772 \begin_inset LatexCommand \index{stack}
8773
8774 \end_inset
8775
8776  grows, it will use up the remaining register banks, and the 16 bytes used
8777  by the 128 bit variables, and 80 bytes for general purpose use.
8778  If any bit variables are used, the data variables will be placed after
8779  the byte holding the last bit variable.
8780  For example, if register banks 0 and 1 are used, and there are 9 bit variables
8781  (two bytes used),
8782 \emph on
8783 data
8784 \emph default
8785  variables will be placed starting at address 0x22.
8786  You can also use -
8787 \begin_inset ERT
8788 status Collapsed
8789
8790 \layout Standard
8791
8792 \backslash
8793 /
8794 \end_inset
8795
8796 -data-loc
8797 \begin_inset LatexCommand \index{-\/-data-loc<Value>}
8798
8799 \end_inset
8800
8801  to specify the start address of the
8802 \emph on
8803 data
8804 \emph default
8805  and -
8806 \begin_inset ERT
8807 status Collapsed
8808
8809 \layout Standard
8810
8811 \backslash
8812 /
8813 \end_inset
8814
8815 -iram-size to specify the size of the total internal RAM (
8816 \emph on
8817 data
8818 \emph default
8819 +
8820 \emph on
8821 idata
8822 \emph default
8823 ).
8824
8825 \layout Standard
8826
8827 By default the 8051 linker will place the stack after the last byte of data
8828  variables.
8829  Option -
8830 \begin_inset ERT
8831 status Collapsed
8832
8833 \layout Standard
8834
8835 \backslash
8836 /
8837 \end_inset
8838
8839 -stack-loc
8840 \begin_inset LatexCommand \index{-\/-stack-loc<Value>}
8841
8842 \end_inset
8843
8844  allows you to specify the start of the stack, i.e.
8845  you could start it after any data in the general purpose area.
8846  If your microcontroller has additional indirectly addressable internal
8847  RAM (
8848 \emph on
8849 idata
8850 \emph default
8851 ) you can place the stack on it.
8852  You may also need to use -
8853 \begin_inset ERT
8854 status Collapsed
8855
8856 \layout Standard
8857
8858 \backslash
8859 /
8860 \end_inset
8861
8862 -xdata-loc
8863 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
8864
8865 \end_inset
8866
8867  to set the start address of the external RAM (
8868 \emph on
8869 xdata
8870 \emph default
8871 ) and -
8872 \begin_inset ERT
8873 status Collapsed
8874
8875 \layout Standard
8876
8877 \backslash
8878 /
8879 \end_inset
8880
8881 -xram-size
8882 \begin_inset LatexCommand \index{-\/-data-loc}
8883
8884 \end_inset
8885
8886  to specify its size.
8887  Same goes for the code memory, using -
8888 \begin_inset ERT
8889 status Collapsed
8890
8891 \layout Standard
8892
8893 \backslash
8894 /
8895 \end_inset
8896
8897 -code-loc
8898 \begin_inset LatexCommand \index{-\/-data-loc}
8899
8900 \end_inset
8901
8902  and -
8903 \begin_inset ERT
8904 status Collapsed
8905
8906 \layout Standard
8907
8908 \backslash
8909 /
8910 \end_inset
8911
8912 -code-size
8913 \begin_inset LatexCommand \index{-\/-data-loc}
8914
8915 \end_inset
8916
8917 .
8918  If in doubt, don't specify any options and see if the resulting memory
8919  layout is appropriate, then you can adjust it.
8920 \layout Standard
8921
8922 The linker generates two files with memory allocation information.
8923  The first, with extension .map
8924 \begin_inset LatexCommand \index{<file>.map}
8925
8926 \end_inset
8927
8928  shows all the variables and segments.
8929  The second with extension .mem
8930 \begin_inset LatexCommand \index{<file>.mem}
8931
8932 \end_inset
8933
8934  shows the final memory layout.
8935  The linker will complain either if memory segments overlap, there is not
8936  enough memory, or there is not enough space for stack.
8937  If you get any linking warnings and/or errors related to stack or segments
8938  allocation, take a look at either the .map or .mem files to find out what
8939  the problem is.
8940  The .mem file may even suggest a solution to the problem.
8941 \layout Subsection
8942
8943 Z80/Z180 Storage Class
8944 \begin_inset LatexCommand \index{Storage class}
8945
8946 \end_inset
8947
8948  Language Extensions
8949 \layout Subsubsection
8950
8951 sfr
8952 \begin_inset LatexCommand \index{sfr}
8953
8954 \end_inset
8955
8956  (in/out to 8-bit addresses)
8957 \layout Standard
8958
8959 The Z80
8960 \begin_inset LatexCommand \index{Z80}
8961
8962 \end_inset
8963
8964  family has separate address spaces for memory and
8965 \emph on
8966 i
8967 \emph default
8968 nput/
8969 \emph on
8970 o
8971 \emph default
8972 utput memory.
8973  I/O memory
8974 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
8975
8976 \end_inset
8977
8978  is accessed with special instructions, e.g.:
8979 \layout Verse
8980
8981
8982 \family typewriter
8983 sfr at 0x78 IoPort;\SpecialChar ~
8984 \SpecialChar ~
8985 /* define a var in I/O space at 78h called IoPort */
8986
8987 \layout Standard
8988
8989 Writing 0x01 to this variable generates the assembly code:
8990 \layout Verse
8991
8992
8993 \family typewriter
8994 3E 01\SpecialChar ~
8995 \SpecialChar ~
8996 \SpecialChar ~
8997 \SpecialChar ~
8998 \SpecialChar ~
8999 \SpecialChar ~
9000 ld a,#0x01
9001 \newline
9002 D3 78\SpecialChar ~
9003 \SpecialChar ~
9004 \SpecialChar ~
9005 \SpecialChar ~
9006 \SpecialChar ~
9007 \SpecialChar ~
9008 out (_IoPort),a
9009 \layout Subsubsection
9010
9011 banked sfr
9012 \begin_inset LatexCommand \index{sfr}
9013
9014 \end_inset
9015
9016  (in/out to 16-bit addresses)
9017 \layout Standard
9018
9019 The keyword
9020 \emph on
9021 banked
9022 \emph default
9023  is used to support 16 bit addresses in I/O memory e.g.:
9024 \layout Verse
9025
9026
9027 \family typewriter
9028 sfr banked at
9029 \begin_inset LatexCommand \index{at}
9030
9031 \end_inset
9032
9033  0x123 IoPort;
9034 \layout Standard
9035
9036 Writing 0x01 to this variable generates the assembly code:
9037 \layout Verse
9038
9039
9040 \family typewriter
9041 01 23 01\SpecialChar ~
9042 \SpecialChar ~
9043 \SpecialChar ~
9044 ld bc,#_IoPort
9045 \newline
9046 3E 01\SpecialChar ~
9047 \SpecialChar ~
9048 \SpecialChar ~
9049 \SpecialChar ~
9050 \SpecialChar ~
9051 \SpecialChar ~
9052 ld a,#0x01
9053 \newline
9054 ED 79\SpecialChar ~
9055 \SpecialChar ~
9056 \SpecialChar ~
9057 \SpecialChar ~
9058 \SpecialChar ~
9059 \SpecialChar ~
9060 out (c),a
9061 \layout Subsubsection
9062
9063 sfr
9064 \begin_inset LatexCommand \index{sfr}
9065
9066 \end_inset
9067
9068  (in0/out0 to 8 bit addresses on Z180
9069 \begin_inset LatexCommand \index{Z180}
9070
9071 \end_inset
9072
9073 /HD64180
9074 \begin_inset LatexCommand \index{HD64180}
9075
9076 \end_inset
9077
9078 )
9079 \layout Standard
9080
9081 The compiler option -
9082 \begin_inset ERT
9083 status Collapsed
9084
9085 \layout Standard
9086
9087 \backslash
9088 /
9089 \end_inset
9090
9091 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9092 portmode
9093 \begin_inset LatexCommand \index{\#pragma portmode}
9094
9095 \end_inset
9096
9097 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9098 ns
9099 \family typewriter
9100 in0/out0
9101 \family default
9102  instead of
9103 \family typewriter
9104 in/out
9105 \family default
9106 .
9107  If you include the file z180.h this will be set automatically.
9108 \layout Subsection
9109
9110 HC08 Storage Class
9111 \begin_inset LatexCommand \index{Storage class}
9112
9113 \end_inset
9114
9115  Language Extensions
9116 \layout Subsubsection
9117
9118 data
9119 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9120
9121 \end_inset
9122
9123
9124 \layout Standard
9125
9126 The data storage class declares a variable that resides in the first 256
9127  bytes of memory (the direct page).
9128  The HC08 is most efficient at accessing variables (especially pointers)
9129  stored here.
9130 \layout Subsubsection
9131
9132 xdata
9133 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9134
9135 \end_inset
9136
9137
9138 \layout Standard
9139
9140 The xdata storage class declares a variable that can reside anywhere in
9141  memory.
9142  This is the default if no storage class is specified.
9143
9144 \layout Section
9145
9146 Absolute Addressing
9147 \begin_inset LatexCommand \index{Absolute addressing}
9148
9149 \end_inset
9150
9151
9152 \layout Standard
9153
9154 Data items can be assigned an absolute address with the
9155 \emph on
9156 at
9157 \begin_inset LatexCommand \index{at}
9158
9159 \end_inset
9160
9161  <address>
9162 \emph default
9163  keyword, in addition to a storage class, e.g.:
9164 \layout Verse
9165
9166
9167 \family typewriter
9168 xdata
9169 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9170
9171 \end_inset
9172
9173  at
9174 \begin_inset LatexCommand \index{at}
9175
9176 \end_inset
9177
9178  0x7ffe unsigned int chksum;
9179 \layout Standard
9180
9181 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9182  of the external ram.
9183  The compiler does
9184 \emph on
9185 not
9186 \emph default
9187  reserve any space for variables declared in this way (they are implemented
9188  with an equate in the assembler).
9189  Thus it is left to the programmer to make sure there are no overlaps with
9190  other variables that are declared without the absolute address.
9191  The assembler listing file (.lst
9192 \begin_inset LatexCommand \index{<file>.lst}
9193
9194 \end_inset
9195
9196 ) and the linker output files (.rst
9197 \begin_inset LatexCommand \index{<file>.rst}
9198
9199 \end_inset
9200
9201 ) and (.map
9202 \begin_inset LatexCommand \index{<file>.map}
9203
9204 \end_inset
9205
9206 ) are good places to look for such overlaps.
9207  Variables with an absolute address are
9208 \emph on
9209 not
9210 \emph default
9211  initialized
9212 \begin_inset LatexCommand \index{Variable initialization}
9213
9214 \end_inset
9215
9216 .
9217 \layout Standard
9218
9219 In case of memory mapped I/O devices the keyword
9220 \emph on
9221 volatile
9222 \emph default
9223  has to be used to tell the compiler that accesses might not be removed:
9224 \layout Verse
9225
9226
9227 \family typewriter
9228 volatile
9229 \begin_inset LatexCommand \index{volatile}
9230
9231 \end_inset
9232
9233  xdata
9234 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9235
9236 \end_inset
9237
9238  at
9239 \begin_inset LatexCommand \index{at}
9240
9241 \end_inset
9242
9243  0x8000 unsigned char PORTA_8255;
9244 \layout Standard
9245
9246 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9247 r) array
9248 \family typewriter
9249 \size footnotesize
9250
9251 \begin_inset LatexCommand \index{Aligned array}
9252
9253 \end_inset
9254
9255
9256 \family default
9257 \size default
9258  starts at a block (256 byte) boundary
9259 \begin_inset LatexCommand \index{block boundary}
9260
9261 \end_inset
9262
9263  (section
9264 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9265
9266 \end_inset
9267
9268  has an example).
9269 \newline
9270 Absolute addresses can be specified for variables in all storage classes,
9271  e.g.:
9272 \layout Verse
9273
9274
9275 \family typewriter
9276 bit
9277 \begin_inset LatexCommand \index{bit}
9278
9279 \end_inset
9280
9281  at
9282 \begin_inset LatexCommand \index{at}
9283
9284 \end_inset
9285
9286  0x02 bvar;
9287 \layout Standard
9288
9289 The above example will allocate the variable at offset 0x02 in the bit-addressab
9290 le space.
9291  There is no real advantage to assigning absolute addresses to variables
9292  in this manner, unless you want strict control over all the variables allocated.
9293  One possible use would be to write hardware portable code.
9294  For example, if you have a routine that uses one or more of the microcontroller
9295  I/O pins, and such pins are different for two different hardwares, you
9296  can declare the I/O pins in your routine using:
9297 \layout Verse
9298
9299
9300 \family typewriter
9301 extern volatile bit MOSI;\SpecialChar ~
9302 \SpecialChar ~
9303 \SpecialChar ~
9304 \SpecialChar ~
9305 /* master out, slave in */
9306 \newline
9307 extern volatile bit MISO;\SpecialChar ~
9308 \SpecialChar ~
9309 \SpecialChar ~
9310 \SpecialChar ~
9311 /* master in, slave out */
9312 \newline
9313 extern volatile bit MCLK;\SpecialChar ~
9314 \SpecialChar ~
9315 \SpecialChar ~
9316 \SpecialChar ~
9317 /* master clock */
9318 \newline
9319
9320 \newline
9321 /* Input and Output of a byte on a 3-wire serial bus.
9322 \newline
9323 \SpecialChar ~
9324 \SpecialChar ~
9325 \SpecialChar ~
9326 If needed adapt polarity of clock, polarity of data and bit order
9327 \newline
9328 \SpecialChar ~
9329 */
9330 \newline
9331 unsigned char spi_io(unsigned char out_byte)
9332 \newline
9333 {
9334 \newline
9335 \SpecialChar ~
9336 \SpecialChar ~
9337 \SpecialChar ~
9338 \SpecialChar ~
9339 unsigned char i=8;
9340 \newline
9341 \SpecialChar ~
9342 \SpecialChar ~
9343 \SpecialChar ~
9344 \SpecialChar ~
9345 do {
9346 \newline
9347 \SpecialChar ~
9348 \SpecialChar ~
9349 \SpecialChar ~
9350 \SpecialChar ~
9351 \SpecialChar ~
9352 \SpecialChar ~
9353 \SpecialChar ~
9354 \SpecialChar ~
9355 MOSI = out_byte & 0x80;
9356 \newline
9357 \SpecialChar ~
9358 \SpecialChar ~
9359 \SpecialChar ~
9360 \SpecialChar ~
9361 \SpecialChar ~
9362 \SpecialChar ~
9363 \SpecialChar ~
9364 \SpecialChar ~
9365 out_byte <<= 1;
9366 \newline
9367 \SpecialChar ~
9368 \SpecialChar ~
9369 \SpecialChar ~
9370 \SpecialChar ~
9371 \SpecialChar ~
9372 \SpecialChar ~
9373 \SpecialChar ~
9374 \SpecialChar ~
9375 MCLK = 1;
9376 \newline
9377 \SpecialChar ~
9378 \SpecialChar ~
9379 \SpecialChar ~
9380 \SpecialChar ~
9381 \SpecialChar ~
9382 \SpecialChar ~
9383 \SpecialChar ~
9384 \SpecialChar ~
9385 /* _asm nop _endasm; */\SpecialChar ~
9386 \SpecialChar ~
9387 \SpecialChar ~
9388 \SpecialChar ~
9389 \SpecialChar ~
9390 \SpecialChar ~
9391 \SpecialChar ~
9392 \SpecialChar ~
9393 /* for slow peripherals */
9394 \newline
9395 \SpecialChar ~
9396 \SpecialChar ~
9397 \SpecialChar ~
9398 \SpecialChar ~
9399 \SpecialChar ~
9400 \SpecialChar ~
9401 \SpecialChar ~
9402 \SpecialChar ~
9403 if(MISO)
9404 \newline
9405 \SpecialChar ~
9406 \SpecialChar ~
9407 \SpecialChar ~
9408 \SpecialChar ~
9409 \SpecialChar ~
9410 \SpecialChar ~
9411 \SpecialChar ~
9412 \SpecialChar ~
9413 \SpecialChar ~
9414 \SpecialChar ~
9415 \SpecialChar ~
9416 \SpecialChar ~
9417 out_byte += 1;
9418 \newline
9419 \SpecialChar ~
9420 \SpecialChar ~
9421 \SpecialChar ~
9422 \SpecialChar ~
9423 \SpecialChar ~
9424 \SpecialChar ~
9425 \SpecialChar ~
9426 \SpecialChar ~
9427 MCLK = 0;
9428 \newline
9429 \SpecialChar ~
9430 \SpecialChar ~
9431 \SpecialChar ~
9432 \SpecialChar ~
9433 } while(--i);
9434 \newline
9435 \SpecialChar ~
9436 \SpecialChar ~
9437 \SpecialChar ~
9438 \SpecialChar ~
9439 return out_byte;
9440 \newline
9441 }
9442 \layout Standard
9443
9444 Then, someplace in the code for the first hardware you would use
9445 \layout Verse
9446
9447
9448 \family typewriter
9449 bit at 0x80 MOSI;\SpecialChar ~
9450 \SpecialChar ~
9451 \SpecialChar ~
9452 \SpecialChar ~
9453 /* I/O port 0, bit 0 */
9454 \newline
9455 bit at 0x81 MISO;\SpecialChar ~
9456 \SpecialChar ~
9457 \SpecialChar ~
9458 \SpecialChar ~
9459 /* I/O port 0, bit 1 */
9460 \newline
9461 bit at 0x82 MCLK;\SpecialChar ~
9462 \SpecialChar ~
9463 \SpecialChar ~
9464 \SpecialChar ~
9465 /* I/O port 0, bit 2 */
9466 \layout Standard
9467
9468 Similarly, for the second hardware you would use
9469 \layout Verse
9470
9471
9472 \family typewriter
9473 bit at 0x83 MOSI;\SpecialChar ~
9474 \SpecialChar ~
9475 \SpecialChar ~
9476 \SpecialChar ~
9477 /* I/O port 0, bit 3 */
9478 \newline
9479 bit at 0x91 MISO;\SpecialChar ~
9480 \SpecialChar ~
9481 \SpecialChar ~
9482 \SpecialChar ~
9483 /* I/O port 1, bit 1 */
9484 \newline
9485 bit
9486 \begin_inset LatexCommand \index{bit}
9487
9488 \end_inset
9489
9490  at 0x92 MCLK;\SpecialChar ~
9491 \SpecialChar ~
9492 \SpecialChar ~
9493 \SpecialChar ~
9494 /* I/O port 1, bit 2 */
9495 \layout Standard
9496
9497 and you can use the same hardware dependent routine without changes, as
9498  for example in a library.
9499  This is somehow similar to sbit, but only one absolute address has to be
9500  specified in the whole project.
9501 \layout Section
9502
9503 Parameters
9504 \begin_inset LatexCommand \index{Parameters}
9505
9506 \end_inset
9507
9508
9509 \begin_inset LatexCommand \index{function parameter}
9510
9511 \end_inset
9512
9513  & Local Variables
9514 \begin_inset LatexCommand \index{local variables}
9515
9516 \end_inset
9517
9518
9519 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
9520
9521 \end_inset
9522
9523
9524 \layout Standard
9525
9526 Automatic (local) variables and parameters to functions can either be placed
9527  on the stack or in data-space.
9528  The default action of the compiler is to place these variables in the internal
9529  RAM (for small model) or external RAM (for large model).
9530  This in fact makes them similar to
9531 \emph on
9532 static
9533 \begin_inset LatexCommand \index{static}
9534
9535 \end_inset
9536
9537
9538 \emph default
9539  so by default functions are non-reentrant
9540 \begin_inset LatexCommand \index{reentrant}
9541
9542 \end_inset
9543
9544 .
9545
9546 \newline
9547
9548 \newline
9549 They can be placed on the stack
9550 \begin_inset LatexCommand \index{stack}
9551
9552 \end_inset
9553
9554  by using the
9555 \emph on
9556  -
9557 \begin_inset ERT
9558 status Collapsed
9559
9560 \layout Standard
9561
9562 \backslash
9563 /
9564 \end_inset
9565
9566 -stack-auto
9567 \begin_inset LatexCommand \index{-\/-stack-auto}
9568
9569 \end_inset
9570
9571
9572 \emph default
9573  option, by using
9574 \emph on
9575 #pragma\SpecialChar ~
9576 stackauto
9577 \emph default
9578
9579 \begin_inset LatexCommand \index{\#pragma stackauto}
9580
9581 \end_inset
9582
9583  or by using the
9584 \emph on
9585 reentrant
9586 \begin_inset LatexCommand \index{reentrant}
9587
9588 \end_inset
9589
9590
9591 \emph default
9592  keyword in the function declaration, e.g.:
9593 \layout Verse
9594
9595
9596 \family typewriter
9597 unsigned char foo(char i) reentrant
9598 \newline
9599 {
9600 \newline
9601 \SpecialChar ~
9602 \SpecialChar ~
9603 \SpecialChar ~
9604 \SpecialChar ~
9605 ...
9606
9607 \newline
9608 }
9609 \layout Standard
9610
9611 Since stack space on 8051 is limited, the
9612 \emph on
9613 reentrant
9614 \emph default
9615 keyword or the
9616 \emph on
9617  -
9618 \begin_inset ERT
9619 status Collapsed
9620
9621 \layout Standard
9622
9623 \backslash
9624 /
9625 \end_inset
9626
9627 -stack-auto
9628 \emph default
9629  option should be used sparingly.
9630  Note that the reentrant keyword just means that the parameters & local
9631  variables will be allocated to the stack, it
9632 \emph on
9633 does not
9634 \emph default
9635  mean that the function is register bank
9636 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9637
9638 \end_inset
9639
9640  independent.
9641 \newline
9642
9643 \newline
9644 Local variables
9645 \begin_inset LatexCommand \index{local variables}
9646
9647 \end_inset
9648
9649  can be assigned storage classes and absolute
9650 \begin_inset LatexCommand \index{Absolute addressing}
9651
9652 \end_inset
9653
9654  addresses, e.g.:
9655 \layout Verse
9656
9657
9658 \family typewriter
9659 unsigned char foo()
9660 \newline
9661 {
9662 \newline
9663 \SpecialChar ~
9664 \SpecialChar ~
9665 \SpecialChar ~
9666 \SpecialChar ~
9667 xdata unsigned char i;
9668 \newline
9669 \SpecialChar ~
9670 \SpecialChar ~
9671 \SpecialChar ~
9672 \SpecialChar ~
9673 bit bvar;
9674 \newline
9675 \SpecialChar ~
9676 \SpecialChar ~
9677 \SpecialChar ~
9678 \SpecialChar ~
9679 data at
9680 \begin_inset LatexCommand \index{at}
9681
9682 \end_inset
9683
9684  0x31 unsigned char j;
9685 \newline
9686 \SpecialChar ~
9687 \SpecialChar ~
9688 \SpecialChar ~
9689 \SpecialChar ~
9690 ...
9691
9692 \newline
9693 }
9694 \layout Standard
9695
9696 In the above example the variable
9697 \emph on
9698 i
9699 \emph default
9700  will be allocated in the external ram,
9701 \emph on
9702 bvar
9703 \emph default
9704  in bit addressable space and
9705 \emph on
9706  j
9707 \emph default
9708  in internal ram.
9709  When compiled with
9710 \emph on
9711 -
9712 \begin_inset ERT
9713 status Collapsed
9714
9715 \layout Standard
9716
9717 \backslash
9718 /
9719 \end_inset
9720
9721 -stack-auto
9722 \emph default
9723  or when a function is declared as
9724 \emph on
9725 reentrant
9726 \emph default
9727  this should only be done for static variables.
9728 \layout Standard
9729
9730 Parameters
9731 \begin_inset LatexCommand \index{function parameter}
9732
9733 \end_inset
9734
9735  however are not allowed any storage class
9736 \begin_inset LatexCommand \index{Storage class}
9737
9738 \end_inset
9739
9740 , (storage classes for parameters will be ignored), their allocation is
9741  governed by the memory model in use, and the reentrancy options.
9742 \layout Section
9743
9744 Overlaying
9745 \begin_inset LatexCommand \label{sub:Overlaying}
9746
9747 \end_inset
9748
9749
9750 \begin_inset LatexCommand \index{Overlaying}
9751
9752 \end_inset
9753
9754
9755 \layout Standard
9756
9757 For non-reentrant
9758 \begin_inset LatexCommand \index{reentrant}
9759
9760 \end_inset
9761
9762  functions SDCC will try to reduce internal ram space usage by overlaying
9763  parameters and local variables of a function (if possible).
9764  Parameters and local variables
9765 \begin_inset LatexCommand \index{local variables}
9766
9767 \end_inset
9768
9769  of a function will be allocated to an overlayable segment if the function
9770  has
9771 \emph on
9772 no other function calls and the function is non-reentrant and the memory
9773  model
9774 \begin_inset LatexCommand \index{Memory model}
9775
9776 \end_inset
9777
9778  is small.
9779
9780 \emph default
9781  If an explicit storage class
9782 \begin_inset LatexCommand \index{Storage class}
9783
9784 \end_inset
9785
9786  is specified for a local variable, it will NOT be overlayed.
9787 \layout Standard
9788
9789 Note that the compiler (not the linkage editor) makes the decision for overlayin
9790 g the data items.
9791  Functions that are called from an interrupt service routine should be preceded
9792  by a #pragma\SpecialChar ~
9793 nooverlay
9794 \begin_inset LatexCommand \index{\#pragma nooverlay}
9795
9796 \end_inset
9797
9798  if they are not reentrant.
9799 \layout Standard
9800
9801 Also note that the compiler does not do any processing of inline assembler
9802  code, so the compiler might incorrectly assign local variables and parameters
9803  of a function into the overlay segment if the inline assembler code calls
9804  other c-functions that might use the overlay.
9805  In that case the #pragma\SpecialChar ~
9806 nooverlay should be used.
9807 \layout Standard
9808
9809 Parameters and local variables of functions that contain 16 or 32 bit multiplica
9810 tion
9811 \begin_inset LatexCommand \index{Multiplication}
9812
9813 \end_inset
9814
9815  or division
9816 \begin_inset LatexCommand \index{Division}
9817
9818 \end_inset
9819
9820  will NOT be overlayed since these are implemented using external functions,
9821  e.g.:
9822 \layout Verse
9823
9824
9825 \family typewriter
9826 #pragma save
9827 \newline
9828 #pragma nooverlay
9829 \begin_inset LatexCommand \index{\#pragma nooverlay}
9830
9831 \end_inset
9832
9833
9834 \newline
9835 void set_error(unsigned char errcd)
9836 \newline
9837 {
9838 \newline
9839 \SpecialChar ~
9840 \SpecialChar ~
9841 \SpecialChar ~
9842 \SpecialChar ~
9843 P3 = errcd;
9844 \newline
9845 }
9846 \newline
9847 #pragma restore
9848 \newline
9849
9850 \newline
9851 void some_isr () interrupt
9852 \begin_inset LatexCommand \index{interrupt}
9853
9854 \end_inset
9855
9856  2
9857 \newline
9858 {
9859 \newline
9860 \SpecialChar ~
9861 \SpecialChar ~
9862 \SpecialChar ~
9863 \SpecialChar ~
9864 ...
9865 \newline
9866 \SpecialChar ~
9867 \SpecialChar ~
9868 \SpecialChar ~
9869 \SpecialChar ~
9870 set_error(10);
9871 \newline
9872 \SpecialChar ~
9873 \SpecialChar ~
9874 \SpecialChar ~
9875 \SpecialChar ~
9876 ...
9877
9878 \newline
9879 }
9880 \layout Standard
9881
9882 In the above example the parameter
9883 \emph on
9884 errcd
9885 \emph default
9886  for the function
9887 \emph on
9888 set_error
9889 \emph default
9890  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
9891 nooverlay was
9892  not present, this could cause unpredictable runtime behavior when called
9893  from an interrupt service routine.
9894  The #pragma\SpecialChar ~
9895 nooverlay ensures that the parameters and local variables for
9896  the function are NOT overlayed.
9897 \layout Section
9898
9899 Interrupt Service Routines
9900 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
9901
9902 \end_inset
9903
9904
9905 \layout Subsection
9906
9907 General Information
9908 \layout Standard
9909
9910 SDCC allows
9911 \emph on
9912 i
9913 \emph default
9914 nterrupt
9915 \emph on
9916 s
9917 \emph default
9918 ervice
9919 \emph on
9920 r
9921 \emph default
9922 outines to be coded in C, with some extended keywords.
9923 \layout Verse
9924
9925
9926 \family typewriter
9927 void timer_isr (void) interrupt 1 using 1
9928 \newline
9929 {
9930 \newline
9931 \SpecialChar ~
9932 \SpecialChar ~
9933 \SpecialChar ~
9934 \SpecialChar ~
9935 ...
9936
9937 \newline
9938 }
9939 \layout Standard
9940
9941 The optional number following the
9942 \emph on
9943 interrupt
9944 \begin_inset LatexCommand \index{interrupt}
9945
9946 \end_inset
9947
9948
9949 \emph default
9950  keyword is the interrupt number this routine will service.
9951  When present, the compiler will insert a call to this routine in the interrupt
9952  vector table for the interrupt number specified.
9953  If you have multiple source files in your project, interrupt service routines
9954  can be present in any of them, but a prototype of the isr MUST be present
9955  or included in the file that contains the function
9956 \emph on
9957 main
9958 \emph default
9959 .
9960  The
9961 \emph on
9962 using
9963 \emph default
9964  keyword can be used to tell the compiler to use the specified register
9965  bank (8051 specific) when generating code for this function.
9966
9967 \newline
9968
9969 \layout Standard
9970
9971 Interrupt service routines open the door for some very interesting bugs:
9972 \newline
9973 If an interrupt service routine changes variables which are accessed by
9974  other functions these variables have to be declared
9975 \emph on
9976 volatile
9977 \emph default
9978
9979 \begin_inset LatexCommand \index{volatile}
9980
9981 \end_inset
9982
9983 .
9984
9985 \layout Standard
9986
9987 If the access to these variables is not
9988 \emph on
9989 atomic
9990 \begin_inset LatexCommand \index{atomic}
9991
9992 \end_inset
9993
9994
9995 \emph default
9996  (i.e.
9997  the processor needs more than one instruction for the access and could
9998  be interrupted while accessing the variable) the interrupt must be disabled
9999  during the access to avoid inconsistent data.
10000  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10001  and should be protected by disabling interrupts.
10002  You're not automatically on the safe side if you use 8 bit variables though.
10003  We need an example here: f.e.
10004  on the 8051 the harmless looking
10005 \begin_inset Quotes srd
10006 \end_inset
10007
10008
10009 \family typewriter
10010 flags\SpecialChar ~
10011 |=\SpecialChar ~
10012 0x80;
10013 \family default
10014
10015 \begin_inset Quotes sld
10016 \end_inset
10017
10018  is not atomic if
10019 \family typewriter
10020 flags
10021 \family default
10022  resides in xdata.
10023  Setting
10024 \begin_inset Quotes srd
10025 \end_inset
10026
10027
10028 \family typewriter
10029 flags\SpecialChar ~
10030 |=\SpecialChar ~
10031 0x40;
10032 \family default
10033
10034 \begin_inset Quotes sld
10035 \end_inset
10036
10037  from within an interrupt routine might get lost if the interrupt occurs
10038  at the wrong time.
10039
10040 \begin_inset Quotes sld
10041 \end_inset
10042
10043
10044 \family typewriter
10045 counter\SpecialChar ~
10046 +=\SpecialChar ~
10047 8;
10048 \family default
10049
10050 \begin_inset Quotes srd
10051 \end_inset
10052
10053  is not atomic on the 8051 even if
10054 \family typewriter
10055 counter
10056 \family default
10057  is located in data memory.
10058  Bugs like these are hard to reproduce and can cause a lot of trouble.
10059
10060 \layout Standard
10061
10062 The return address and the registers used in the interrupt service routine
10063  are saved on the stack
10064 \begin_inset LatexCommand \index{stack}
10065
10066 \end_inset
10067
10068  so there must be sufficient stack space.
10069  If there isn't variables or registers (or even the return address itself)
10070  will be corrupted.
10071  This
10072 \emph on
10073 stack overflow
10074 \emph default
10075
10076 \begin_inset LatexCommand \index{stack overflow}
10077
10078 \end_inset
10079
10080  is most likely to happen if the interrupt occurs during the
10081 \begin_inset Quotes sld
10082 \end_inset
10083
10084 deepest
10085 \begin_inset Quotes srd
10086 \end_inset
10087
10088  subroutine when the stack is already in use for f.e.
10089  many return addresses.
10090 \layout Standard
10091
10092 A special note here, int (16 bit) and long (32 bit) integer division
10093 \begin_inset LatexCommand \index{Division}
10094
10095 \end_inset
10096
10097 , multiplication
10098 \begin_inset LatexCommand \index{Multiplication}
10099
10100 \end_inset
10101
10102  & modulus
10103 \begin_inset LatexCommand \index{Modulus}
10104
10105 \end_inset
10106
10107  and floating-point
10108 \begin_inset LatexCommand \index{Floating point support}
10109
10110 \end_inset
10111
10112  operations are implemented using external support routines developed in
10113  ANSI-C.
10114  If an interrupt service routine needs to do any of these operations then
10115  the support routines (as mentioned in a following section) will have to
10116  be recompiled using the
10117 \emph on
10118  -
10119 \begin_inset ERT
10120 status Collapsed
10121
10122 \layout Standard
10123
10124 \backslash
10125 /
10126 \end_inset
10127
10128 -stack-auto
10129 \begin_inset LatexCommand \index{-\/-stack-auto}
10130
10131 \end_inset
10132
10133
10134 \emph default
10135  option and the source file will need to be compiled using the
10136 \emph on
10137 -
10138 \begin_inset ERT
10139 status Collapsed
10140
10141 \layout Standard
10142
10143 \backslash
10144 /
10145 \end_inset
10146
10147 -int-long-reent
10148 \emph default
10149
10150 \begin_inset LatexCommand \index{-\/-int-long-reent}
10151
10152 \end_inset
10153
10154  compiler option.
10155 \layout Standard
10156
10157 Calling other functions from an interrupt service routine is not recommended,
10158  avoid it if possible.
10159  Note that when some function is called from an interrupt service routine
10160  it should be preceded by a #pragma\SpecialChar ~
10161 nooverlay
10162 \begin_inset LatexCommand \index{\#pragma nooverlay}
10163
10164 \end_inset
10165
10166  if it is not reentrant.
10167  Furthermore nonreentrant functions should not be called from the main program
10168  while the interrupt service routine might be active.
10169
10170 \newline
10171
10172 \newline
10173 Also see section
10174 \begin_inset LatexCommand \ref{sub:Overlaying}
10175
10176 \end_inset
10177
10178 \SpecialChar ~
10179 about Overlaying and section
10180 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10181
10182 \end_inset
10183
10184 \SpecialChar ~
10185 about Functions using private register banks.
10186 \layout Subsection
10187
10188 MCS51/DS390 Interrupt Service Routines
10189 \layout Standard
10190
10191 Interrupt numbers and the corresponding address & descriptions for the Standard
10192  8051/8052 are listed below.
10193  SDCC will automatically adjust the interrupt vector table to the maximum
10194  interrupt number specified.
10195 \newline
10196
10197 \layout Standard
10198 \align center
10199
10200 \begin_inset  Tabular
10201 <lyxtabular version="3" rows="7" columns="3">
10202 <features>
10203 <column alignment="center" valignment="top" leftline="true" width="0in">
10204 <column alignment="center" valignment="top" leftline="true" width="0in">
10205 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10206 <row topline="true" bottomline="true">
10207 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10208 \begin_inset Text
10209
10210 \layout Standard
10211
10212 Interrupt #
10213 \end_inset
10214 </cell>
10215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10216 \begin_inset Text
10217
10218 \layout Standard
10219
10220 Description
10221 \end_inset
10222 </cell>
10223 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10224 \begin_inset Text
10225
10226 \layout Standard
10227
10228 Vector Address
10229 \end_inset
10230 </cell>
10231 </row>
10232 <row topline="true">
10233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10234 \begin_inset Text
10235
10236 \layout Standard
10237
10238 0
10239 \end_inset
10240 </cell>
10241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10242 \begin_inset Text
10243
10244 \layout Standard
10245
10246 External 0
10247 \end_inset
10248 </cell>
10249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10250 \begin_inset Text
10251
10252 \layout Standard
10253
10254 0x0003
10255 \end_inset
10256 </cell>
10257 </row>
10258 <row topline="true">
10259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10260 \begin_inset Text
10261
10262 \layout Standard
10263
10264 1
10265 \end_inset
10266 </cell>
10267 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10268 \begin_inset Text
10269
10270 \layout Standard
10271
10272 Timer 0
10273 \end_inset
10274 </cell>
10275 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10276 \begin_inset Text
10277
10278 \layout Standard
10279
10280 0x000B
10281 \end_inset
10282 </cell>
10283 </row>
10284 <row topline="true">
10285 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10286 \begin_inset Text
10287
10288 \layout Standard
10289
10290 2
10291 \end_inset
10292 </cell>
10293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10294 \begin_inset Text
10295
10296 \layout Standard
10297
10298 External 1
10299 \end_inset
10300 </cell>
10301 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10302 \begin_inset Text
10303
10304 \layout Standard
10305
10306 0x0013
10307 \end_inset
10308 </cell>
10309 </row>
10310 <row topline="true">
10311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10312 \begin_inset Text
10313
10314 \layout Standard
10315
10316 3
10317 \end_inset
10318 </cell>
10319 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10320 \begin_inset Text
10321
10322 \layout Standard
10323
10324 Timer 1
10325 \end_inset
10326 </cell>
10327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10328 \begin_inset Text
10329
10330 \layout Standard
10331
10332 0x001B
10333 \end_inset
10334 </cell>
10335 </row>
10336 <row topline="true">
10337 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10338 \begin_inset Text
10339
10340 \layout Standard
10341
10342 4
10343 \end_inset
10344 </cell>
10345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10346 \begin_inset Text
10347
10348 \layout Standard
10349
10350 Serial
10351 \end_inset
10352 </cell>
10353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10354 \begin_inset Text
10355
10356 \layout Standard
10357
10358 0x0023
10359 \end_inset
10360 </cell>
10361 </row>
10362 <row topline="true" bottomline="true">
10363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10364 \begin_inset Text
10365
10366 \layout Standard
10367
10368 5
10369 \end_inset
10370 </cell>
10371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10372 \begin_inset Text
10373
10374 \layout Standard
10375
10376 Timer 2 (8052)
10377 \end_inset
10378 </cell>
10379 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10380 \begin_inset Text
10381
10382 \layout Standard
10383
10384 0x002B
10385 \end_inset
10386 </cell>
10387 </row>
10388 </lyxtabular>
10389
10390 \end_inset
10391
10392
10393 \newline
10394
10395 \layout Standard
10396
10397 If the interrupt service routine is defined without
10398 \emph on
10399 using
10400 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10401
10402 \end_inset
10403
10404
10405 \emph default
10406  a register bank or with register bank 0 (
10407 \emph on
10408 using
10409 \emph default
10410  0), the compiler will save the registers used by itself on the stack upon
10411  entry and restore them at exit, however if such an interrupt service routine
10412  calls another function then the entire register bank will be saved on the
10413  stack.
10414  This scheme may be advantageous for small interrupt service routines which
10415  have low register usage.
10416 \layout Standard
10417
10418 If the interrupt service routine is defined to be using a specific register
10419  bank then only
10420 \emph on
10421 a, b, dptr
10422 \emph default
10423  & psw are saved and restored, if such an interrupt service routine calls
10424  another function (using another register bank) then the entire register
10425  bank of the called function will be saved on the stack.
10426  This scheme is recommended for larger interrupt service routines.
10427 \layout Subsection
10428
10429 HC08 Interrupt Service Routines
10430 \layout Standard
10431
10432 Since the number of interrupts available is chip specific and the interrupt
10433  vector table always ends at the last byte of memory, the interrupt numbers
10434  corresponds to the interrupt vectors in reverse order of address.
10435  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
10436  2 will use the interrupt vector at 0xfffa, and so on.
10437  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
10438  this way; instead see section
10439 \begin_inset LatexCommand \ref{sub:Startup-Code}
10440
10441 \end_inset
10442
10443  for details on customizing startup.
10444 \layout Subsection
10445
10446 Z80 Interrupt Service Routines
10447 \layout Standard
10448
10449 The Z80 uses several different methods for determining the correct interrupt
10450  vector depending on the hardware implementation.
10451  Therefore, SDCC ignores the optional interrupt number and does not attempt
10452  to generate an interrupt vector table.
10453 \layout Standard
10454
10455 By default, SDCC generates code for a maskable interrupt, which uses an
10456  RETI instruction to return from the interrupt.
10457  To write an interrupt handler for the non-maskable interrupt, which needs
10458  an RETN instruction instead, add the
10459 \emph on
10460 critical
10461 \emph default
10462  keyword:
10463 \layout Verse
10464
10465
10466 \family typewriter
10467 void nmi_isr (void) critical interrupt
10468 \newline
10469 {
10470 \newline
10471 \SpecialChar ~
10472 \SpecialChar ~
10473 \SpecialChar ~
10474 \SpecialChar ~
10475 ...
10476
10477 \newline
10478 }
10479 \layout Section
10480
10481 Enabling and Disabling Interrupts
10482 \layout Subsection
10483
10484 Critical Functions and Critical Statements
10485 \layout Standard
10486
10487 A special keyword may be associated with a block or a function declaring
10488  it as
10489 \emph on
10490 critical
10491 \emph default
10492 .
10493  SDCC will generate code to disable all interrupts
10494 \begin_inset LatexCommand \index{interrupt}
10495
10496 \end_inset
10497
10498  upon entry to a critical function and restore the interrupt enable to the
10499  previous state before returning.
10500  Nesting critical functions will need one additional byte on the stack
10501 \begin_inset LatexCommand \index{stack}
10502
10503 \end_inset
10504
10505  for each call.
10506 \layout Verse
10507
10508
10509 \family typewriter
10510 int foo () critical
10511 \begin_inset LatexCommand \index{critical}
10512
10513 \end_inset
10514
10515
10516 \newline
10517 {
10518 \newline
10519 \SpecialChar ~
10520 \SpecialChar ~
10521 \SpecialChar ~
10522 \SpecialChar ~
10523 ...
10524
10525 \newline
10526 \SpecialChar ~
10527 \SpecialChar ~
10528 \SpecialChar ~
10529 \SpecialChar ~
10530 ...
10531
10532 \newline
10533 }
10534 \layout Standard
10535
10536 The critical attribute maybe used with other attributes like
10537 \emph on
10538 reentrant.
10539 \emph default
10540
10541 \newline
10542 The keyword
10543 \emph on
10544 critical
10545 \emph default
10546  may also be used to disable interrupts more locally:
10547 \layout Verse
10548
10549
10550 \family typewriter
10551 critical{ i++; }
10552 \layout Standard
10553
10554 More than one statement could have been included in the block.
10555 \layout Subsection
10556
10557 Enabling and Disabling Interrupts directly
10558 \layout Standard
10559
10560 Interrupts
10561 \begin_inset LatexCommand \index{interrupt}
10562
10563 \end_inset
10564
10565  can also be disabled and enabled directly (8051):
10566 \layout Verse
10567
10568
10569 \family typewriter
10570 EA = 0;\SpecialChar ~
10571 \SpecialChar ~
10572 \SpecialChar ~
10573 \SpecialChar ~
10574 \SpecialChar ~
10575 \SpecialChar ~
10576 \SpecialChar ~
10577 \SpecialChar ~
10578 \SpecialChar ~
10579 \SpecialChar ~
10580 \SpecialChar ~
10581 \SpecialChar ~
10582 or:\SpecialChar ~
10583 \SpecialChar ~
10584 \SpecialChar ~
10585 \SpecialChar ~
10586 \SpecialChar ~
10587 \SpecialChar ~
10588 \SpecialChar ~
10589 \SpecialChar ~
10590 \SpecialChar ~
10591 \SpecialChar ~
10592 \SpecialChar ~
10593 EA_SAVE = EA;
10594 \layout Verse
10595
10596
10597 \family typewriter
10598 ...\SpecialChar ~
10599 \SpecialChar ~
10600 \SpecialChar ~
10601 \SpecialChar ~
10602 \SpecialChar ~
10603 \SpecialChar ~
10604 \SpecialChar ~
10605 \SpecialChar ~
10606 \SpecialChar ~
10607 \SpecialChar ~
10608 \SpecialChar ~
10609 \SpecialChar ~
10610 \SpecialChar ~
10611 \SpecialChar ~
10612 \SpecialChar ~
10613 \SpecialChar ~
10614 \SpecialChar ~
10615 \SpecialChar ~
10616 \SpecialChar ~
10617 \SpecialChar ~
10618 \SpecialChar ~
10619 \SpecialChar ~
10620 \SpecialChar ~
10621 \SpecialChar ~
10622 \SpecialChar ~
10623 \SpecialChar ~
10624 \SpecialChar ~
10625 \SpecialChar ~
10626 \SpecialChar ~
10627 \SpecialChar ~
10628 EA = 0;
10629 \layout Verse
10630
10631
10632 \family typewriter
10633 EA = 1;\SpecialChar ~
10634 \SpecialChar ~
10635 \SpecialChar ~
10636 \SpecialChar ~
10637 \SpecialChar ~
10638 \SpecialChar ~
10639 \SpecialChar ~
10640 \SpecialChar ~
10641 \SpecialChar ~
10642 \SpecialChar ~
10643 \SpecialChar ~
10644 \SpecialChar ~
10645 \SpecialChar ~
10646 \SpecialChar ~
10647 \SpecialChar ~
10648 \SpecialChar ~
10649 \SpecialChar ~
10650 \SpecialChar ~
10651 \SpecialChar ~
10652 \SpecialChar ~
10653 \SpecialChar ~
10654 \SpecialChar ~
10655 \SpecialChar ~
10656 \SpecialChar ~
10657 \SpecialChar ~
10658 \SpecialChar ~
10659 ...
10660 \layout Verse
10661
10662
10663 \family typewriter
10664 \SpecialChar ~
10665 \SpecialChar ~
10666 \SpecialChar ~
10667 \SpecialChar ~
10668 \SpecialChar ~
10669 \SpecialChar ~
10670 \SpecialChar ~
10671 \SpecialChar ~
10672 \SpecialChar ~
10673 \SpecialChar ~
10674 \SpecialChar ~
10675 \SpecialChar ~
10676 \SpecialChar ~
10677 \SpecialChar ~
10678 \SpecialChar ~
10679 \SpecialChar ~
10680 \SpecialChar ~
10681 \SpecialChar ~
10682 \SpecialChar ~
10683 \SpecialChar ~
10684 \SpecialChar ~
10685 \SpecialChar ~
10686 \SpecialChar ~
10687 \SpecialChar ~
10688 \SpecialChar ~
10689 \SpecialChar ~
10690 \SpecialChar ~
10691 \SpecialChar ~
10692 \SpecialChar ~
10693 \SpecialChar ~
10694 \SpecialChar ~
10695 \SpecialChar ~
10696 \SpecialChar ~
10697 EA = EA_SAVE;
10698 \layout Standard
10699
10700 On other architectures which have seperate opcodes for enabling and disabling
10701  interrupts you might want to make use of defines with inline assembly
10702 \begin_inset LatexCommand \index{Assembler routines}
10703
10704 \end_inset
10705
10706  (HC08):
10707 \layout Verse
10708
10709
10710 \family typewriter
10711 #define CLI _asm
10712 \begin_inset LatexCommand \index{\_asm}
10713
10714 \end_inset
10715
10716 \SpecialChar ~
10717 \SpecialChar ~
10718 cli\SpecialChar ~
10719 \SpecialChar ~
10720 _endasm
10721 \begin_inset LatexCommand \index{\_endasm}
10722
10723 \end_inset
10724
10725 ;
10726 \layout Verse
10727
10728
10729 \family typewriter
10730 #define SEI _asm\SpecialChar ~
10731 \SpecialChar ~
10732 sei\SpecialChar ~
10733 \SpecialChar ~
10734 _endasm;
10735 \layout Verse
10736
10737
10738 \family typewriter
10739 ...
10740 \layout Standard
10741
10742 Note: it is sometimes sufficient to disable only a specific interrupt source
10743  like f.e.
10744  a timer or serial interrupt by manipulating an
10745 \emph on
10746 interrupt mask
10747 \begin_inset LatexCommand \index{interrupt mask}
10748
10749 \end_inset
10750
10751
10752 \emph default
10753  register.
10754
10755 \layout Standard
10756
10757 Usually the time during which interrupts are disabled should be kept as
10758  short as possible.
10759  This minimizes both
10760 \emph on
10761 interrupt latency
10762 \emph default
10763
10764 \begin_inset LatexCommand \index{interrupt latency}
10765
10766 \end_inset
10767
10768  (the time between the occurrence of the interrupt and the execution of
10769  the first code in the interrupt routine) and
10770 \emph on
10771 interrupt jitter
10772 \emph default
10773
10774 \begin_inset LatexCommand \index{interrupt jitter}
10775
10776 \end_inset
10777
10778  (the difference between the shortest and the longest interrupt latency).
10779  These really are something different, f.e.
10780  a serial interrupt has to be served before its buffer overruns so it cares
10781  for the maximum interrupt latency, whereas it does not care about jitter.
10782  On a loudspeaker driven via a digital to analog converter which is fed
10783  by an interrupt a latency of a few milliseconds might be tolerable, whereas
10784  a much smaller jitter will be very audible.
10785 \layout Standard
10786
10787 You can reenable interrupts within an interrupt routine and on some architecture
10788 s you can make use of two (or more) levels of
10789 \emph on
10790 interrupt priorities
10791 \emph default
10792
10793 \begin_inset LatexCommand \index{interrupt priority}
10794
10795 \end_inset
10796
10797 .
10798  On some architectures which don't support interrupt priorities these can
10799  be implemented by manipulating the interrupt mask and reenabling interrupts
10800  within the interrupt routine.
10801  Check there is sufficient space on the stack
10802 \begin_inset LatexCommand \index{stack}
10803
10804 \end_inset
10805
10806  and don't add complexity unless you have to.
10807
10808 \layout Subsection
10809
10810 Semaphore
10811 \begin_inset LatexCommand \index{semaphore}
10812
10813 \end_inset
10814
10815  locking (mcs51/ds390)
10816 \layout Standard
10817
10818 Some architectures (mcs51/ds390) have an atomic
10819 \begin_inset LatexCommand \index{atomic}
10820
10821 \end_inset
10822
10823  bit test and
10824 \emph on
10825
10826 \emph default
10827 clear
10828 \emph on
10829
10830 \emph default
10831 instruction.
10832  These type of instructions are typically used in preemptive multitasking
10833  systems, where a routine f.e.
10834  claims the use of a data structure ('acquires a lock
10835 \begin_inset LatexCommand \index{lock}
10836
10837 \end_inset
10838
10839  on it'), makes some modifications and then releases the lock when the data
10840  structure is consistent again.
10841  The instruction may also be used if interrupt and non-interrupt code have
10842  to compete for a resource.
10843  With the atomic bit test and clear instruction interrupts
10844 \begin_inset LatexCommand \index{interrupt}
10845
10846 \end_inset
10847
10848  don't have to be disabled for the locking operation.
10849
10850 \layout Standard
10851
10852 SDCC generates this instruction if the source follows this pattern:
10853 \layout Verse
10854
10855
10856 \family typewriter
10857 volatile bit resource_is_free;
10858 \newline
10859
10860 \newline
10861 if (resource_is_free)
10862 \newline
10863 \SpecialChar ~
10864 \SpecialChar ~
10865 {
10866 \newline
10867 \SpecialChar ~
10868 \SpecialChar ~
10869 \SpecialChar ~
10870 \SpecialChar ~
10871 resource_is_free=0;
10872 \newline
10873 \SpecialChar ~
10874 \SpecialChar ~
10875 \SpecialChar ~
10876 \SpecialChar ~
10877 ...
10878
10879 \newline
10880 \SpecialChar ~
10881 \SpecialChar ~
10882 \SpecialChar ~
10883 \SpecialChar ~
10884 resource_is_free=1;
10885 \newline
10886 \SpecialChar ~
10887 \SpecialChar ~
10888 }
10889 \layout Standard
10890
10891 Note, mcs51 and ds390 support only an atomic
10892 \begin_inset LatexCommand \index{atomic}
10893
10894 \end_inset
10895
10896  bit test and
10897 \emph on
10898 clear
10899 \emph default
10900  instruction (as opposed to atomic bit test and
10901 \emph on
10902 set).
10903 \layout Section
10904
10905 Functions using private register banks
10906 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
10907
10908 \end_inset
10909
10910  (mcs51/ds390)
10911 \layout Standard
10912
10913 Some architectures have support for quickly changing register sets.
10914  SDCC supports this feature with the
10915 \emph on
10916 using
10917 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10918
10919 \end_inset
10920
10921
10922 \emph default
10923  attribute (which tells the compiler to use a register bank
10924 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10925
10926 \end_inset
10927
10928  other than the default bank zero).
10929  It should only be applied to
10930 \emph on
10931 interrupt
10932 \begin_inset LatexCommand \index{interrupt}
10933
10934 \end_inset
10935
10936
10937 \emph default
10938  functions (see footnote below).
10939  This will in most circumstances make the generated ISR code more efficient
10940  since it will not have to save registers on the stack.
10941 \layout Standard
10942
10943 The
10944 \emph on
10945 using
10946 \emph default
10947  attribute will have no effect on the generated code for a
10948 \emph on
10949 non-interrupt
10950 \emph default
10951  function (but may occasionally be useful anyway
10952 \begin_inset Foot
10953 collapsed false
10954
10955 \layout Standard
10956
10957 possible exception: if a function is called ONLY from 'interrupt' functions
10958  using a particular bank, it can be declared with the same 'using' attribute
10959  as the calling 'interrupt' functions.
10960  For instance, if you have several ISRs using bank one, and all of them
10961  call memcpy(), it might make sense to create a specialized version of memcpy()
10962  'using 1', since this would prevent the ISR from having to save bank zero
10963  to the stack on entry and switch to bank zero before calling the function
10964 \end_inset
10965
10966 ).
10967 \newline
10968
10969 \emph on
10970 (pending: I don't think this has been done yet)
10971 \layout Standard
10972
10973 An
10974 \emph on
10975 interrupt
10976 \emph default
10977  function using a non-zero bank will assume that it can trash that register
10978  bank, and will not save it.
10979  Since high-priority interrupts
10980 \begin_inset LatexCommand \index{interrupt priority}
10981
10982 \end_inset
10983
10984  can interrupt low-priority ones on the 8051 and friends, this means that
10985  if a high-priority ISR
10986 \emph on
10987 using
10988 \emph default
10989  a particular bank occurs while processing a low-priority ISR
10990 \emph on
10991 using
10992 \emph default
10993  the same bank, terrible and bad things can happen.
10994  To prevent this, no single register bank should be
10995 \emph on
10996 used
10997 \emph default
10998  by both a high priority and a low priority ISR.
10999  This is probably most easily done by having all high priority ISRs use
11000  one bank and all low priority ISRs use another.
11001  If you have an ISR which can change priority at runtime, you're on your
11002  own: I suggest using the default bank zero and taking the small performance
11003  hit.
11004 \layout Standard
11005
11006 It is most efficient if your ISR calls no other functions.
11007  If your ISR must call other functions, it is most efficient if those functions
11008  use the same bank as the ISR (see note 1 below); the next best is if the
11009  called functions use bank zero.
11010  It is very inefficient to call a function using a different, non-zero bank
11011  from an ISR.
11012
11013 \layout Section
11014
11015 Startup Code
11016 \begin_inset LatexCommand \label{sub:Startup-Code}
11017
11018 \end_inset
11019
11020
11021 \begin_inset LatexCommand \index{Startup code}
11022
11023 \end_inset
11024
11025
11026 \layout Subsection
11027
11028 MCS51/DS390 Startup Code
11029 \layout Standard
11030
11031 The compiler inserts a call to the C routine
11032 \emph on
11033 _sdcc_external_startup()
11034 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11035
11036 \end_inset
11037
11038
11039 \series bold
11040 \emph default
11041
11042 \series default
11043 at the start of the CODE area.
11044  This routine is in the runtime library
11045 \begin_inset LatexCommand \index{Runtime library}
11046
11047 \end_inset
11048
11049 .
11050  By default this routine returns 0, if this routine returns a non-zero value,
11051  the static & global variable initialization will be skipped and the function
11052  main will be invoked.
11053  Otherwise static & global variables will be initialized before the function
11054  main is invoked.
11055  You could add a
11056 \emph on
11057 _sdcc_external_startup()
11058 \emph default
11059  routine to your program to override the default if you need to setup hardware
11060  or perform some other critical operation prior to static & global variable
11061  initialization.
11062  On some mcs51 variants xdata has to be explicitly enabled before it can
11063  be accessed, this is the place to do it.
11064  The startup code clears the complete 256 byte of idata memory, this might
11065  cause problems for 128 byte devices (endless loop reported for Chipcon
11066  CC1010).
11067 \layout Standard
11068
11069 See also the compiler option
11070 \emph on
11071 -
11072 \begin_inset ERT
11073 status Collapsed
11074
11075 \layout Standard
11076
11077 \backslash
11078 /
11079 \end_inset
11080
11081 -no-xinit
11082 \emph default
11083 -
11084 \emph on
11085 opt
11086 \emph default
11087
11088 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11089
11090 \end_inset
11091
11092  and section
11093 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11094
11095 \end_inset
11096
11097 \SpecialChar ~
11098 about MCS51-variants.
11099 \layout Subsection
11100
11101 HC08 Startup Code
11102 \layout Standard
11103
11104 The HC08 startup code follows the same scheme as the MCS51 startup code.
11105 \layout Subsection
11106
11107 Z80 Startup Code
11108 \layout Standard
11109
11110 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11111  from sdcc/device/lib/z80/crt0.s.
11112  If you need a different startup code you can use the compiler option
11113 \emph on
11114 -
11115 \series bold
11116 \emph default
11117
11118 \begin_inset ERT
11119 status Collapsed
11120
11121 \layout Standard
11122
11123 \backslash
11124 /
11125 \end_inset
11126
11127
11128 \series default
11129 \emph on
11130 -no-std-crt0
11131 \emph default
11132
11133 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11134
11135 \end_inset
11136
11137  and provide your own crt0.o.
11138
11139 \layout Section
11140
11141 Inline Assembler Code
11142 \begin_inset LatexCommand \index{Assembler routines}
11143
11144 \end_inset
11145
11146
11147 \layout Subsection
11148
11149 A Step by Step Introduction
11150 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11151
11152 \end_inset
11153
11154
11155 \layout Standard
11156
11157 Starting from a small snippet of c-code this example shows for the MCS51
11158  how to use inline assembly, access variables, a function parameter and
11159  an array in xdata memory.
11160  The example uses an MCS51 here but is easily adapted for other architectures.
11161  This is a buffer routine which should be optimized:
11162 \layout Verse
11163
11164
11165 \family typewriter
11166 \size footnotesize
11167 unsigned char far
11168 \begin_inset LatexCommand \index{far (storage class)}
11169
11170 \end_inset
11171
11172  at
11173 \begin_inset LatexCommand \index{at}
11174
11175 \end_inset
11176
11177  0x7f00 buf[0x100];
11178 \begin_inset LatexCommand \index{Aligned array}
11179
11180 \end_inset
11181
11182
11183 \newline
11184 unsigned char head,tail;
11185 \newline
11186
11187 \newline
11188 void to_buffer( unsigned char c )
11189 \newline
11190 {
11191 \newline
11192 \SpecialChar ~
11193 \SpecialChar ~
11194 \SpecialChar ~
11195 \SpecialChar ~
11196 if( head != tail-1 )
11197 \newline
11198 \SpecialChar ~
11199 \SpecialChar ~
11200 \SpecialChar ~
11201 \SpecialChar ~
11202 \SpecialChar ~
11203 \SpecialChar ~
11204 \SpecialChar ~
11205 \SpecialChar ~
11206 buf[ head++ ] = c;\SpecialChar ~
11207 \SpecialChar ~
11208 \SpecialChar ~
11209 \SpecialChar ~
11210 /* access to a 256 byte aligned array */
11211 \newline
11212 }
11213 \layout Standard
11214
11215 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
11216  then a corresponding buffer.asm file is generated.
11217  We define a new function
11218 \family typewriter
11219 to_buffer_asm()
11220 \family default
11221  in file buffer.c in which we cut and paste the generated code, removing
11222  unwanted comments and some ':'.
11223  Then add
11224 \begin_inset Quotes sld
11225 \end_inset
11226
11227 _asm
11228 \begin_inset Quotes srd
11229 \end_inset
11230
11231  and
11232 \begin_inset Quotes sld
11233 \end_inset
11234
11235 _endasm;
11236 \begin_inset Quotes srd
11237 \end_inset
11238
11239  to the beginning and the end of the function body:
11240 \layout Verse
11241
11242
11243 \family typewriter
11244 \size footnotesize
11245 /* With a cut and paste from the .asm file, we have something to start with.
11246 \newline
11247 \SpecialChar ~
11248 \SpecialChar ~
11249 \SpecialChar ~
11250 The function is not yet OK! (registers aren't saved) */
11251 \newline
11252 void to_buffer_asm( unsigned char c )
11253 \newline
11254 {
11255 \newline
11256 \SpecialChar ~
11257 \SpecialChar ~
11258 \SpecialChar ~
11259 \SpecialChar ~
11260 _asm
11261 \begin_inset LatexCommand \index{\_asm}
11262
11263 \end_inset
11264
11265
11266 \newline
11267 \SpecialChar ~
11268 \SpecialChar ~
11269 \SpecialChar ~
11270 \SpecialChar ~
11271 mov\SpecialChar ~
11272 \SpecialChar ~
11273 r2,dpl
11274 \newline
11275 ;buffer.c if( head != tail-1 )
11276 \newline
11277 \SpecialChar ~
11278 \SpecialChar ~
11279 \SpecialChar ~
11280 \SpecialChar ~
11281 mov\SpecialChar ~
11282 \SpecialChar ~
11283 a,_tail
11284 \newline
11285 \SpecialChar ~
11286 \SpecialChar ~
11287 \SpecialChar ~
11288 \SpecialChar ~
11289 dec\SpecialChar ~
11290 \SpecialChar ~
11291 a
11292 \newline
11293 \SpecialChar ~
11294 \SpecialChar ~
11295 \SpecialChar ~
11296 \SpecialChar ~
11297 mov\SpecialChar ~
11298 \SpecialChar ~
11299 r3,a
11300 \newline
11301 \SpecialChar ~
11302 \SpecialChar ~
11303 \SpecialChar ~
11304 \SpecialChar ~
11305 mov\SpecialChar ~
11306 \SpecialChar ~
11307 a,_head
11308 \newline
11309 \SpecialChar ~
11310 \SpecialChar ~
11311 \SpecialChar ~
11312 \SpecialChar ~
11313 cjne a,ar3,00106$
11314 \newline
11315 \SpecialChar ~
11316 \SpecialChar ~
11317 \SpecialChar ~
11318 \SpecialChar ~
11319 ret
11320 \newline
11321 00106$:
11322 \newline
11323 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
11324 \begin_inset LatexCommand \index{Aligned array}
11325
11326 \end_inset
11327
11328
11329 \newline
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 \SpecialChar ~
11334 mov\SpecialChar ~
11335 \SpecialChar ~
11336 r3,_head
11337 \newline
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 \SpecialChar ~
11341 \SpecialChar ~
11342 inc\SpecialChar ~
11343 \SpecialChar ~
11344 _head
11345 \newline
11346 \SpecialChar ~
11347 \SpecialChar ~
11348 \SpecialChar ~
11349 \SpecialChar ~
11350 mov\SpecialChar ~
11351 \SpecialChar ~
11352 dpl,r3
11353 \newline
11354 \SpecialChar ~
11355 \SpecialChar ~
11356 \SpecialChar ~
11357 \SpecialChar ~
11358 mov\SpecialChar ~
11359 \SpecialChar ~
11360 dph,#(_buf >> 8)
11361 \newline
11362 \SpecialChar ~
11363 \SpecialChar ~
11364 \SpecialChar ~
11365 \SpecialChar ~
11366 mov\SpecialChar ~
11367 \SpecialChar ~
11368 a,r2
11369 \newline
11370 \SpecialChar ~
11371 \SpecialChar ~
11372 \SpecialChar ~
11373 \SpecialChar ~
11374 movx @dptr,a
11375 \newline
11376 00103$:
11377 \newline
11378 \SpecialChar ~
11379 \SpecialChar ~
11380 \SpecialChar ~
11381 \SpecialChar ~
11382 ret
11383 \newline
11384 \SpecialChar ~
11385 \SpecialChar ~
11386 \SpecialChar ~
11387 \SpecialChar ~
11388 _endasm;
11389 \newline
11390 }
11391 \layout Standard
11392
11393 The new file buffer.c should compile with only one warning about the unreferenced
11394  function argument 'c'.
11395  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
11396  (1) and finally have:
11397 \layout Verse
11398
11399
11400 \family typewriter
11401 \size footnotesize
11402 unsigned char far at 0x7f00 buf[0x100];
11403 \newline
11404 unsigned char head,tail;
11405 \newline
11406 #define USE_ASSEMBLY (1)
11407 \newline
11408
11409 \newline
11410 #if !USE_ASSEMBLY
11411 \newline
11412
11413 \newline
11414 void to_buffer( unsigned char c )
11415 \newline
11416 {
11417 \newline
11418 \SpecialChar ~
11419 \SpecialChar ~
11420 \SpecialChar ~
11421 \SpecialChar ~
11422 if( head != tail-1 )
11423 \newline
11424 \SpecialChar ~
11425 \SpecialChar ~
11426 \SpecialChar ~
11427 \SpecialChar ~
11428 \SpecialChar ~
11429 \SpecialChar ~
11430 \SpecialChar ~
11431 \SpecialChar ~
11432 buf[ head++ ] = c;
11433 \newline
11434 }
11435 \newline
11436
11437 \newline
11438 #else
11439 \newline
11440
11441 \newline
11442 void to_buffer( unsigned char c )
11443 \newline
11444 {
11445 \newline
11446 \SpecialChar ~
11447 \SpecialChar ~
11448 \SpecialChar ~
11449 \SpecialChar ~
11450 c; // to avoid warning: unreferenced function argument
11451 \newline
11452 \SpecialChar ~
11453 \SpecialChar ~
11454 \SpecialChar ~
11455 \SpecialChar ~
11456 _asm
11457 \begin_inset LatexCommand \index{\_asm}
11458
11459 \end_inset
11460
11461
11462 \newline
11463 \SpecialChar ~
11464 \SpecialChar ~
11465 \SpecialChar ~
11466 \SpecialChar ~
11467 \SpecialChar ~
11468 \SpecialChar ~
11469 \SpecialChar ~
11470 \SpecialChar ~
11471 ; save used registers here.
11472
11473 \newline
11474 \SpecialChar ~
11475 \SpecialChar ~
11476 \SpecialChar ~
11477 \SpecialChar ~
11478 \SpecialChar ~
11479 \SpecialChar ~
11480 \SpecialChar ~
11481 \SpecialChar ~
11482 ; If we were still using r2,r3 we would have to push them here.
11483
11484 \newline
11485 ; if( head != tail-1 )
11486 \newline
11487 \SpecialChar ~
11488 \SpecialChar ~
11489 \SpecialChar ~
11490 \SpecialChar ~
11491 \SpecialChar ~
11492 \SpecialChar ~
11493 \SpecialChar ~
11494 \SpecialChar ~
11495 mov\SpecialChar ~
11496  a,_tail
11497 \newline
11498 \SpecialChar ~
11499 \SpecialChar ~
11500 \SpecialChar ~
11501 \SpecialChar ~
11502 \SpecialChar ~
11503 \SpecialChar ~
11504 \SpecialChar ~
11505 \SpecialChar ~
11506 dec\SpecialChar ~
11507  a
11508 \newline
11509 \SpecialChar ~
11510 \SpecialChar ~
11511 \SpecialChar ~
11512 \SpecialChar ~
11513 \SpecialChar ~
11514 \SpecialChar ~
11515 \SpecialChar ~
11516 \SpecialChar ~
11517 xrl\SpecialChar ~
11518  a,_head
11519 \newline
11520 \SpecialChar ~
11521 \SpecialChar ~
11522 \SpecialChar ~
11523 \SpecialChar ~
11524 \SpecialChar ~
11525 \SpecialChar ~
11526 \SpecialChar ~
11527 \SpecialChar ~
11528 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
11529 \newline
11530 \SpecialChar ~
11531 \SpecialChar ~
11532 \SpecialChar ~
11533 \SpecialChar ~
11534 \SpecialChar ~
11535 \SpecialChar ~
11536 \SpecialChar ~
11537 \SpecialChar ~
11538 jz\SpecialChar ~
11539 \SpecialChar ~
11540  t_b_end$
11541 \newline
11542 \SpecialChar ~
11543 \SpecialChar ~
11544 \SpecialChar ~
11545 \SpecialChar ~
11546 \SpecialChar ~
11547 \SpecialChar ~
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 ;
11551 \newline
11552 ; buf[ head++ ] = c;
11553 \newline
11554 \SpecialChar ~
11555 \SpecialChar ~
11556 \SpecialChar ~
11557 \SpecialChar ~
11558 \SpecialChar ~
11559 \SpecialChar ~
11560 \SpecialChar ~
11561 \SpecialChar ~
11562 mov\SpecialChar ~
11563  a,dpl \SpecialChar ~
11564 \SpecialChar ~
11565 \SpecialChar ~
11566 \SpecialChar ~
11567 \SpecialChar ~
11568 \SpecialChar ~
11569 \SpecialChar ~
11570 ; dpl holds lower byte of function argument
11571 \newline
11572 \SpecialChar ~
11573 \SpecialChar ~
11574 \SpecialChar ~
11575 \SpecialChar ~
11576 \SpecialChar ~
11577 \SpecialChar ~
11578 \SpecialChar ~
11579 \SpecialChar ~
11580 mov\SpecialChar ~
11581  dpl,_head \SpecialChar ~
11582 \SpecialChar ~
11583 \SpecialChar ~
11584 ; buf is 0x100 byte aligned so head can be used directly
11585 \newline
11586 \SpecialChar ~
11587 \SpecialChar ~
11588 \SpecialChar ~
11589 \SpecialChar ~
11590 \SpecialChar ~
11591 \SpecialChar ~
11592 \SpecialChar ~
11593 \SpecialChar ~
11594 mov\SpecialChar ~
11595  dph,#(_buf>>8)
11596 \newline
11597 \SpecialChar ~
11598 \SpecialChar ~
11599 \SpecialChar ~
11600 \SpecialChar ~
11601 \SpecialChar ~
11602 \SpecialChar ~
11603 \SpecialChar ~
11604 \SpecialChar ~
11605 movx @dptr,a
11606 \newline
11607 \SpecialChar ~
11608 \SpecialChar ~
11609 \SpecialChar ~
11610 \SpecialChar ~
11611 \SpecialChar ~
11612 \SpecialChar ~
11613 \SpecialChar ~
11614 \SpecialChar ~
11615 inc \SpecialChar ~
11616 _head
11617 \newline
11618 \SpecialChar ~
11619 \SpecialChar ~
11620 \SpecialChar ~
11621 \SpecialChar ~
11622 \SpecialChar ~
11623 \SpecialChar ~
11624 \SpecialChar ~
11625 \SpecialChar ~
11626 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
11627 \newline
11628 t_b_end$:
11629 \newline
11630 \SpecialChar ~
11631 \SpecialChar ~
11632 \SpecialChar ~
11633 \SpecialChar ~
11634 \SpecialChar ~
11635 \SpecialChar ~
11636 \SpecialChar ~
11637 \SpecialChar ~
11638 ; restore used registers here
11639 \newline
11640 \SpecialChar ~
11641 \SpecialChar ~
11642 \SpecialChar ~
11643 \SpecialChar ~
11644 _endasm;
11645 \newline
11646 }
11647 \newline
11648 #endif
11649 \layout Standard
11650
11651 The inline assembler code can contain any valid code understood by the assembler
11652 , this includes any assembler directives and comment lines
11653 \begin_inset Foot
11654 collapsed false
11655
11656 \layout Standard
11657
11658 The assembler does not like some characters like ':' or ''' in comments.
11659  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
11660 \end_inset
11661
11662 .
11663  The compiler does not do any validation of the code within the
11664 \family typewriter
11665 _asm
11666 \begin_inset LatexCommand \index{\_asm}
11667
11668 \end_inset
11669
11670  ...
11671  _endasm;
11672 \family default
11673  keyword pair.
11674  Specifically it will not know which registers are used and thus register
11675  pushing/popping
11676 \begin_inset LatexCommand \index{push/pop}
11677
11678 \end_inset
11679
11680  has to be done manually.
11681
11682 \layout Standard
11683
11684 It is recommended that each assembly instruction (including labels) be placed
11685  in a separate line (as the example shows).
11686  When the -
11687 \begin_inset ERT
11688 status Collapsed
11689
11690 \layout Standard
11691
11692 \backslash
11693 /
11694 \end_inset
11695
11696 -
11697 \emph on
11698 peep-asm
11699 \begin_inset LatexCommand \index{-\/-peep-asm}
11700
11701 \end_inset
11702
11703
11704 \emph default
11705  command line option is used, the inline assembler code will be passed through
11706  the peephole optimizer
11707 \begin_inset LatexCommand \index{Peephole optimizer}
11708
11709 \end_inset
11710
11711 .
11712  There are only a few (if any) cases where this option makes sense, it might
11713  cause some unexpected changes in the inline assembler code.
11714  Please go through the peephole optimizer rules defined in file
11715 \emph on
11716 SDCCpeeph.def
11717 \emph default
11718  before using this option.
11719 \layout Subsection
11720
11721 Naked Functions
11722 \begin_inset LatexCommand \label{sub:Naked-Functions}
11723
11724 \end_inset
11725
11726
11727 \begin_inset LatexCommand \index{Naked functions}
11728
11729 \end_inset
11730
11731
11732 \layout Standard
11733
11734 A special keyword may be associated with a function declaring it as
11735 \emph on
11736 _naked
11737 \begin_inset LatexCommand \index{\_naked}
11738
11739 \end_inset
11740
11741 .
11742
11743 \emph default
11744 The
11745 \emph on
11746 _naked
11747 \emph default
11748  function modifier attribute prevents the compiler from generating prologue
11749 \begin_inset LatexCommand \index{function prologue}
11750
11751 \end_inset
11752
11753  and epilogue
11754 \begin_inset LatexCommand \index{function epilogue}
11755
11756 \end_inset
11757
11758  code for that function.
11759  This means that the user is entirely responsible for such things as saving
11760  any registers that may need to be preserved, selecting the proper register
11761  bank, generating the
11762 \emph on
11763 return
11764 \emph default
11765  instruction at the end, etc.
11766  Practically, this means that the contents of the function must be written
11767  in inline assembler.
11768  This is particularly useful for interrupt functions, which can have a large
11769  (and often unnecessary) prologue/epilogue.
11770  For example, compare the code generated by these two functions:
11771 \layout Verse
11772
11773
11774 \family typewriter
11775 volatile
11776 \begin_inset LatexCommand \index{volatile}
11777
11778 \end_inset
11779
11780  data unsigned char counter;
11781 \newline
11782
11783 \newline
11784 void simpleInterrupt(void) interrupt
11785 \begin_inset LatexCommand \index{interrupt}
11786
11787 \end_inset
11788
11789  1
11790 \newline
11791 {
11792 \newline
11793 \SpecialChar ~
11794 \SpecialChar ~
11795 \SpecialChar ~
11796 \SpecialChar ~
11797 counter++;
11798 \newline
11799 }
11800 \newline
11801
11802 \newline
11803 void nakedInterrupt(void) interrupt 2 _naked
11804 \newline
11805 {
11806 \newline
11807 \SpecialChar ~
11808 \SpecialChar ~
11809 \SpecialChar ~
11810 \SpecialChar ~
11811 _asm
11812 \begin_inset LatexCommand \index{\_asm}
11813
11814 \end_inset
11815
11816
11817 \newline
11818 \SpecialChar ~
11819 \SpecialChar ~
11820 \SpecialChar ~
11821 \SpecialChar ~
11822 \SpecialChar ~
11823 \SpecialChar ~
11824 inc\SpecialChar ~
11825 \SpecialChar ~
11826 \SpecialChar ~
11827 \SpecialChar ~
11828 \SpecialChar ~
11829 _counter ; does not change flags, no need to save psw
11830 \newline
11831 \SpecialChar ~
11832 \SpecialChar ~
11833 \SpecialChar ~
11834 \SpecialChar ~
11835 \SpecialChar ~
11836 \SpecialChar ~
11837 reti\SpecialChar ~
11838 \SpecialChar ~
11839 \SpecialChar ~
11840 \SpecialChar ~
11841 ; MUST explicitly include ret or reti in _naked function.
11842 \newline
11843 \SpecialChar ~
11844 \SpecialChar ~
11845 \SpecialChar ~
11846 \SpecialChar ~
11847 _endasm
11848 \begin_inset LatexCommand \index{\_endasm}
11849
11850 \end_inset
11851
11852 ;
11853 \newline
11854 }
11855 \layout Standard
11856
11857 For an 8051 target, the generated simpleInterrupt looks like:
11858 \layout Verse
11859
11860
11861 \family typewriter
11862 _simpleInterrupt:
11863 \newline
11864 \SpecialChar ~
11865 \SpecialChar ~
11866 \SpecialChar ~
11867 \SpecialChar ~
11868 push\SpecialChar ~
11869 \SpecialChar ~
11870 \SpecialChar ~
11871 \SpecialChar ~
11872 acc
11873 \newline
11874 \SpecialChar ~
11875 \SpecialChar ~
11876 \SpecialChar ~
11877 \SpecialChar ~
11878 push\SpecialChar ~
11879 \SpecialChar ~
11880 \SpecialChar ~
11881 \SpecialChar ~
11882 b
11883 \newline
11884 \SpecialChar ~
11885 \SpecialChar ~
11886 \SpecialChar ~
11887 \SpecialChar ~
11888 push\SpecialChar ~
11889 \SpecialChar ~
11890 \SpecialChar ~
11891 \SpecialChar ~
11892 dpl
11893 \newline
11894 \SpecialChar ~
11895 \SpecialChar ~
11896 \SpecialChar ~
11897 \SpecialChar ~
11898 push\SpecialChar ~
11899 \SpecialChar ~
11900 \SpecialChar ~
11901 \SpecialChar ~
11902 dph
11903 \newline
11904 \SpecialChar ~
11905 \SpecialChar ~
11906 \SpecialChar ~
11907 \SpecialChar ~
11908 push\SpecialChar ~
11909 \SpecialChar ~
11910 \SpecialChar ~
11911 \SpecialChar ~
11912 psw
11913 \newline
11914 \SpecialChar ~
11915 \SpecialChar ~
11916 \SpecialChar ~
11917 \SpecialChar ~
11918 mov\SpecialChar ~
11919 \SpecialChar ~
11920 \SpecialChar ~
11921 \SpecialChar ~
11922 \SpecialChar ~
11923 psw,#0x00
11924 \newline
11925 \SpecialChar ~
11926 \SpecialChar ~
11927 \SpecialChar ~
11928 \SpecialChar ~
11929 inc\SpecialChar ~
11930 \SpecialChar ~
11931 \SpecialChar ~
11932 \SpecialChar ~
11933 \SpecialChar ~
11934 _counter
11935 \newline
11936 \SpecialChar ~
11937 \SpecialChar ~
11938 \SpecialChar ~
11939 \SpecialChar ~
11940 pop\SpecialChar ~
11941 \SpecialChar ~
11942 \SpecialChar ~
11943 \SpecialChar ~
11944 \SpecialChar ~
11945 psw
11946 \newline
11947 \SpecialChar ~
11948 \SpecialChar ~
11949 \SpecialChar ~
11950 \SpecialChar ~
11951 pop\SpecialChar ~
11952 \SpecialChar ~
11953 \SpecialChar ~
11954 \SpecialChar ~
11955 \SpecialChar ~
11956 dph
11957 \newline
11958 \SpecialChar ~
11959 \SpecialChar ~
11960 \SpecialChar ~
11961 \SpecialChar ~
11962 pop\SpecialChar ~
11963 \SpecialChar ~
11964 \SpecialChar ~
11965 \SpecialChar ~
11966 \SpecialChar ~
11967 dpl
11968 \newline
11969 \SpecialChar ~
11970 \SpecialChar ~
11971 \SpecialChar ~
11972 \SpecialChar ~
11973 pop\SpecialChar ~
11974 \SpecialChar ~
11975 \SpecialChar ~
11976 \SpecialChar ~
11977 \SpecialChar ~
11978 b
11979 \newline
11980 \SpecialChar ~
11981 \SpecialChar ~
11982 \SpecialChar ~
11983 \SpecialChar ~
11984 pop\SpecialChar ~
11985 \SpecialChar ~
11986 \SpecialChar ~
11987 \SpecialChar ~
11988 \SpecialChar ~
11989 acc
11990 \newline
11991 \SpecialChar ~
11992 \SpecialChar ~
11993 \SpecialChar ~
11994 \SpecialChar ~
11995 reti
11996 \layout Standard
11997
11998 whereas nakedInterrupt looks like:
11999 \layout Verse
12000
12001
12002 \family typewriter
12003 _nakedInterrupt:
12004 \newline
12005 \SpecialChar ~
12006 \SpecialChar ~
12007 \SpecialChar ~
12008 \SpecialChar ~
12009 inc\SpecialChar ~
12010 \SpecialChar ~
12011 \SpecialChar ~
12012 \SpecialChar ~
12013 _counter ; does not change flags, no need to save psw
12014 \newline
12015 \SpecialChar ~
12016 \SpecialChar ~
12017 \SpecialChar ~
12018 \SpecialChar ~
12019 reti\SpecialChar ~
12020 \SpecialChar ~
12021 \SpecialChar ~
12022 \SpecialChar ~
12023 \SpecialChar ~
12024 \SpecialChar ~
12025 \SpecialChar ~
12026 \SpecialChar ~
12027 \SpecialChar ~
12028 \SpecialChar ~
12029 \SpecialChar ~
12030 \SpecialChar ~
12031 ; MUST explicitly include ret or reti in _naked function
12032 \layout Standard
12033
12034 The related directive #pragma exclude
12035 \begin_inset LatexCommand \index{\#pragma exclude}
12036
12037 \end_inset
12038
12039  allows a more fine grained control over pushing & popping
12040 \begin_inset LatexCommand \index{push/pop}
12041
12042 \end_inset
12043
12044  the registers.
12045 \layout Standard
12046
12047 While there is nothing preventing you from writing C code inside a
12048 \family typewriter
12049 _naked
12050 \family default
12051  function, there are many ways to shoot yourself in the foot doing this,
12052  and it is recommended that you stick to inline assembler.
12053 \layout Subsection
12054
12055 Use of Labels within Inline Assembler
12056 \layout Standard
12057
12058 SDCC allows the use of in-line assembler with a few restrictions regarding
12059  labels.
12060  In older versions of the compiler all labels defined within inline assembler
12061  code
12062 \emph on
12063 had to be
12064 \emph default
12065  of the form
12066 \emph on
12067 nnnnn$
12068 \emph default
12069  where nnnn is a number less than 100 (which implies a limit of utmost 100
12070  inline assembler labels
12071 \emph on
12072 per function
12073 \emph default
12074 \noun on
12075 )
12076 \noun default
12077 .
12078
12079 \layout Verse
12080
12081
12082 \family typewriter
12083 _asm
12084 \begin_inset LatexCommand \index{\_asm}
12085
12086 \end_inset
12087
12088
12089 \newline
12090 \SpecialChar ~
12091 \SpecialChar ~
12092 \SpecialChar ~
12093 \SpecialChar ~
12094 mov\SpecialChar ~
12095 \SpecialChar ~
12096 \SpecialChar ~
12097 \SpecialChar ~
12098 \SpecialChar ~
12099 b,#10
12100 \newline
12101 00001$:
12102 \newline
12103 \SpecialChar ~
12104 \SpecialChar ~
12105 \SpecialChar ~
12106 \SpecialChar ~
12107 djnz\SpecialChar ~
12108 \SpecialChar ~
12109 \SpecialChar ~
12110 \SpecialChar ~
12111 b,00001$
12112 \newline
12113 _endasm
12114 \begin_inset LatexCommand \index{\_endasm}
12115
12116 \end_inset
12117
12118  ;
12119 \layout Standard
12120
12121 Inline assembler code cannot reference any C-Labels, however it can reference
12122  labels
12123 \begin_inset LatexCommand \index{Labels}
12124
12125 \end_inset
12126
12127  defined by the inline assembler, e.g.:
12128 \layout Verse
12129
12130
12131 \family typewriter
12132 foo() {
12133 \newline
12134 \SpecialChar ~
12135 \SpecialChar ~
12136 \SpecialChar ~
12137 \SpecialChar ~
12138 /* some c code */
12139 \newline
12140 \SpecialChar ~
12141 \SpecialChar ~
12142 \SpecialChar ~
12143 \SpecialChar ~
12144 _asm
12145 \newline
12146 \SpecialChar ~
12147 \SpecialChar ~
12148 \SpecialChar ~
12149 \SpecialChar ~
12150 \SpecialChar ~
12151 \SpecialChar ~
12152 ; some assembler code
12153 \newline
12154 \SpecialChar ~
12155 \SpecialChar ~
12156 \SpecialChar ~
12157 \SpecialChar ~
12158 \SpecialChar ~
12159 \SpecialChar ~
12160 ljmp $0003
12161 \newline
12162 \SpecialChar ~
12163 \SpecialChar ~
12164 \SpecialChar ~
12165 \SpecialChar ~
12166 _endasm;
12167 \newline
12168 \SpecialChar ~
12169 \SpecialChar ~
12170 \SpecialChar ~
12171 \SpecialChar ~
12172 /* some more c code */
12173 \newline
12174 clabel:\SpecialChar ~
12175 \SpecialChar ~
12176 /* inline assembler cannot reference this label */
12177 \newline
12178 \SpecialChar ~
12179 \SpecialChar ~
12180 \SpecialChar ~
12181 \SpecialChar ~
12182 _asm
12183 \newline
12184 \SpecialChar ~
12185 \SpecialChar ~
12186 \SpecialChar ~
12187 \SpecialChar ~
12188 $0003: ;label (can be referenced by inline assembler only)
12189 \newline
12190 \SpecialChar ~
12191 \SpecialChar ~
12192 \SpecialChar ~
12193 \SpecialChar ~
12194 _endasm ;
12195 \newline
12196 \SpecialChar ~
12197 \SpecialChar ~
12198 \SpecialChar ~
12199 \SpecialChar ~
12200 /* some more c code */
12201 \newline
12202 }
12203 \layout Standard
12204
12205 In other words inline assembly code can access labels defined in inline
12206  assembly within the scope of the function.
12207  The same goes the other way, i.e.
12208  labels defines in inline assembly can not be accessed by C statements.
12209 \layout Section
12210
12211 Interfacing with Assembler Code
12212 \begin_inset LatexCommand \index{Assembler routines}
12213
12214 \end_inset
12215
12216
12217 \layout Subsection
12218
12219 Global Registers used for Parameter Passing
12220 \begin_inset LatexCommand \index{Parameter passing}
12221
12222 \end_inset
12223
12224
12225 \layout Standard
12226
12227 The compiler always uses the global registers
12228 \emph on
12229 DPL, DPH
12230 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12231
12232 \end_inset
12233
12234
12235 \begin_inset LatexCommand \index{DPTR}
12236
12237 \end_inset
12238
12239 , B
12240 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
12241
12242 \end_inset
12243
12244
12245 \emph default
12246 and
12247 \emph on
12248  ACC
12249 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
12250
12251 \end_inset
12252
12253
12254 \emph default
12255  to pass the first parameter to a routine.
12256  The second parameter onwards is either allocated on the stack (for reentrant
12257  routines or if -
12258 \begin_inset ERT
12259 status Collapsed
12260
12261 \layout Standard
12262
12263 \backslash
12264 /
12265 \end_inset
12266
12267 -stack-auto is used) or in data / xdata memory (depending on the memory
12268  model).
12269
12270 \layout Subsection
12271
12272 Assembler Routine (non-reentrant)
12273 \layout Standard
12274
12275 In the following example
12276 \begin_inset LatexCommand \index{reentrant}
12277
12278 \end_inset
12279
12280
12281 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
12282
12283 \end_inset
12284
12285  the function c_func calls an assembler routine asm_func, which takes two
12286  parameters
12287 \begin_inset LatexCommand \index{function parameter}
12288
12289 \end_inset
12290
12291 .
12292 \layout Verse
12293
12294
12295 \family typewriter
12296 extern int asm_func(unsigned char, unsigned char);
12297 \newline
12298
12299 \newline
12300 int c_func (unsigned char i, unsigned char j)
12301 \newline
12302 {
12303 \newline
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 \SpecialChar ~
12308 return asm_func(i,j);
12309 \newline
12310 }
12311 \newline
12312
12313 \newline
12314 int main()
12315 \newline
12316 {
12317 \newline
12318 \SpecialChar ~
12319 \SpecialChar ~
12320 \SpecialChar ~
12321 \SpecialChar ~
12322 return c_func(10,9);
12323 \newline
12324 }
12325 \layout Standard
12326
12327 The corresponding assembler function is:
12328 \layout Verse
12329
12330
12331 \family typewriter
12332 .globl _asm_func_PARM_2
12333 \newline
12334 \SpecialChar ~
12335 \SpecialChar ~
12336 \SpecialChar ~
12337 \SpecialChar ~
12338 \SpecialChar ~
12339 \SpecialChar ~
12340 \SpecialChar ~
12341 \SpecialChar ~
12342 .globl _asm_func
12343 \newline
12344 \SpecialChar ~
12345 \SpecialChar ~
12346 \SpecialChar ~
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 \SpecialChar ~
12350 \SpecialChar ~
12351 \SpecialChar ~
12352 .area OSEG
12353 \newline
12354 _asm_func_PARM_2:
12355 \newline
12356 \SpecialChar ~
12357 \SpecialChar ~
12358 \SpecialChar ~
12359 \SpecialChar ~
12360 \SpecialChar ~
12361 \SpecialChar ~
12362 \SpecialChar ~
12363 \SpecialChar ~
12364 .ds    1
12365 \newline
12366 \SpecialChar ~
12367 \SpecialChar ~
12368 \SpecialChar ~
12369 \SpecialChar ~
12370 \SpecialChar ~
12371 \SpecialChar ~
12372 \SpecialChar ~
12373 \SpecialChar ~
12374 .area CSEG
12375 \newline
12376 _asm_func:
12377 \newline
12378 \SpecialChar ~
12379 \SpecialChar ~
12380 \SpecialChar ~
12381 \SpecialChar ~
12382 \SpecialChar ~
12383 \SpecialChar ~
12384 \SpecialChar ~
12385 \SpecialChar ~
12386 mov\SpecialChar ~
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 a,dpl
12391 \newline
12392 \SpecialChar ~
12393 \SpecialChar ~
12394 \SpecialChar ~
12395 \SpecialChar ~
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 \SpecialChar ~
12399 \SpecialChar ~
12400 add\SpecialChar ~
12401 \SpecialChar ~
12402 \SpecialChar ~
12403 \SpecialChar ~
12404 a,_asm_func_PARM_2
12405 \newline
12406 \SpecialChar ~
12407 \SpecialChar ~
12408 \SpecialChar ~
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 \SpecialChar ~
12414 mov\SpecialChar ~
12415 \SpecialChar ~
12416 \SpecialChar ~
12417 \SpecialChar ~
12418 dpl,a
12419 \newline
12420 \SpecialChar ~
12421 \SpecialChar ~
12422 \SpecialChar ~
12423 \SpecialChar ~
12424 \SpecialChar ~
12425 \SpecialChar ~
12426 \SpecialChar ~
12427 \SpecialChar ~
12428 mov\SpecialChar ~
12429 \SpecialChar ~
12430 \SpecialChar ~
12431 \SpecialChar ~
12432 dph
12433 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12434
12435 \end_inset
12436
12437 ,#0x00
12438 \newline
12439 \SpecialChar ~
12440 \SpecialChar ~
12441 \SpecialChar ~
12442 \SpecialChar ~
12443 \SpecialChar ~
12444 \SpecialChar ~
12445 \SpecialChar ~
12446 \SpecialChar ~
12447 ret
12448 \layout Standard
12449
12450 Note here that the return values
12451 \begin_inset LatexCommand \index{return value}
12452
12453 \end_inset
12454
12455  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
12456  two byte values.
12457  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
12458 b' & 'acc' for four byte values.
12459 \layout Standard
12460
12461 The parameter naming convention is _<function_name>_PARM_<n>, where n is
12462  the parameter number starting from 1, and counting from the left.
12463  The first parameter is passed in
12464 \begin_inset Quotes eld
12465 \end_inset
12466
12467 dpl
12468 \begin_inset Quotes erd
12469 \end_inset
12470
12471  for a one byte parameter,
12472 \begin_inset Quotes eld
12473 \end_inset
12474
12475 dptr
12476 \begin_inset Quotes erd
12477 \end_inset
12478
12479  for two bytes,
12480 \begin_inset Quotes eld
12481 \end_inset
12482
12483 b,dptr
12484 \begin_inset Quotes erd
12485 \end_inset
12486
12487  for three bytes and
12488 \begin_inset Quotes eld
12489 \end_inset
12490
12491 acc,b,dptr
12492 \begin_inset Quotes erd
12493 \end_inset
12494
12495  for a four bytes parameter.
12496  The variable name for the second parameter will be _<function_name>_PARM_2.
12497 \newline
12498
12499 \newline
12500 Assemble the assembler routine with the following command:
12501 \newline
12502
12503 \newline
12504
12505 \family sans
12506 \series bold
12507 asx8051 -losg asmfunc.asm
12508 \newline
12509
12510 \newline
12511
12512 \family default
12513 \series default
12514 Then compile and link the assembler routine to the C source file with the
12515  following command:
12516 \newline
12517
12518 \newline
12519
12520 \family sans
12521 \series bold
12522 sdcc cfunc.c asmfunc.rel
12523 \layout Subsection
12524
12525 Assembler Routine (reentrant)
12526 \layout Standard
12527
12528 In this case
12529 \begin_inset LatexCommand \index{reentrant}
12530
12531 \end_inset
12532
12533
12534 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
12535
12536 \end_inset
12537
12538  the second parameter
12539 \begin_inset LatexCommand \index{function parameter}
12540
12541 \end_inset
12542
12543  onwards will be passed on the stack, the parameters are pushed from right
12544  to left i.e.
12545  after the call the leftmost parameter will be on the top of the stack.
12546  Here is an example:
12547 \layout Verse
12548
12549
12550 \family typewriter
12551 extern int asm_func(unsigned char, unsigned char);
12552 \newline
12553
12554 \newline
12555 int c_func (unsigned char i, unsigned char j) reentrant
12556 \newline
12557 {
12558 \newline
12559 \SpecialChar ~
12560 \SpecialChar ~
12561 \SpecialChar ~
12562 \SpecialChar ~
12563 return asm_func(i,j);
12564 \newline
12565 }
12566 \newline
12567
12568 \newline
12569 int main()
12570 \newline
12571 {
12572 \newline
12573 \SpecialChar ~
12574 \SpecialChar ~
12575 \SpecialChar ~
12576 \SpecialChar ~
12577 return c_func(10,9);
12578 \newline
12579 }
12580 \layout Standard
12581
12582 The corresponding assembler routine is:
12583 \layout Verse
12584
12585
12586 \family typewriter
12587 .globl _asm_func
12588 \newline
12589 _asm_func:
12590 \newline
12591 \SpecialChar ~
12592 \SpecialChar ~
12593 \SpecialChar ~
12594 \SpecialChar ~
12595 push  _bp
12596 \newline
12597 \SpecialChar ~
12598 \SpecialChar ~
12599 \SpecialChar ~
12600 \SpecialChar ~
12601 mov _bp,sp
12602 \newline
12603 \SpecialChar ~
12604 \SpecialChar ~
12605 \SpecialChar ~
12606 \SpecialChar ~
12607 mov r2,dpl
12608 \newline
12609 \SpecialChar ~
12610 \SpecialChar ~
12611 \SpecialChar ~
12612 \SpecialChar ~
12613 mov a,_bp
12614 \newline
12615 \SpecialChar ~
12616 \SpecialChar ~
12617 \SpecialChar ~
12618 \SpecialChar ~
12619 add a,#0xfd
12620 \newline
12621 \SpecialChar ~
12622 \SpecialChar ~
12623 \SpecialChar ~
12624 \SpecialChar ~
12625 mov r0,a
12626 \newline
12627 \SpecialChar ~
12628 \SpecialChar ~
12629 \SpecialChar ~
12630 \SpecialChar ~
12631 add  a,#0xfc ;?
12632 \newline
12633 \SpecialChar ~
12634 \SpecialChar ~
12635 \SpecialChar ~
12636 \SpecialChar ~
12637 mov  r1,a
12638 \newline
12639 \SpecialChar ~
12640 \SpecialChar ~
12641 \SpecialChar ~
12642 \SpecialChar ~
12643 mov  a,@r0
12644 \newline
12645 \SpecialChar ~
12646 \SpecialChar ~
12647 \SpecialChar ~
12648 \SpecialChar ~
12649 add  a,r2 ;?
12650 \newline
12651 \SpecialChar ~
12652 \SpecialChar ~
12653 \SpecialChar ~
12654 \SpecialChar ~
12655 mov  dpl,a
12656 \newline
12657 \SpecialChar ~
12658 \SpecialChar ~
12659 \SpecialChar ~
12660 \SpecialChar ~
12661 mov  dph,#0x00
12662 \newline
12663 \SpecialChar ~
12664 \SpecialChar ~
12665 \SpecialChar ~
12666 \SpecialChar ~
12667 mov  sp,_bp
12668 \newline
12669 \SpecialChar ~
12670 \SpecialChar ~
12671 \SpecialChar ~
12672 \SpecialChar ~
12673 pop  _bp
12674 \newline
12675 \SpecialChar ~
12676 \SpecialChar ~
12677 \SpecialChar ~
12678 \SpecialChar ~
12679 ret
12680 \layout Standard
12681
12682 The compiling and linking procedure remains the same, however note the extra
12683  entry & exit linkage required for the assembler code, _bp is the stack
12684  frame pointer and is used to compute the offset into the stack for parameters
12685  and local variables.
12686 \layout Section
12687
12688 int (16 bit)
12689 \begin_inset LatexCommand \index{int (16 bit)}
12690
12691 \end_inset
12692
12693  and long (32 bit)
12694 \begin_inset LatexCommand \index{long (32 bit)}
12695
12696 \end_inset
12697
12698  Support
12699 \layout Standard
12700
12701 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
12702  multiplication and modulus operations are implemented by support routines.
12703  These support routines are all developed in ANSI-C to facilitate porting
12704  to other MCUs, although some model specific assembler optimizations are
12705  used.
12706  The following files contain the described routines, all of them can be
12707  found in <installdir>/share/sdcc/lib.
12708 \newline
12709
12710 \layout Standard
12711 \align center
12712
12713 \begin_inset  Tabular
12714 <lyxtabular version="3" rows="11" columns="2">
12715 <features>
12716 <column alignment="center" valignment="top" leftline="true" width="0">
12717 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12718 <row topline="true" bottomline="true">
12719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12720 \begin_inset Text
12721
12722 \layout Standard
12723
12724
12725 \series bold
12726 Function
12727 \end_inset
12728 </cell>
12729 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12730 \begin_inset Text
12731
12732 \layout Standard
12733
12734
12735 \series bold
12736 Description
12737 \end_inset
12738 </cell>
12739 </row>
12740 <row topline="true">
12741 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12742 \begin_inset Text
12743
12744 \layout Standard
12745
12746 _mulint.c
12747 \end_inset
12748 </cell>
12749 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12750 \begin_inset Text
12751
12752 \layout Standard
12753
12754 16 bit multiplication
12755 \end_inset
12756 </cell>
12757 </row>
12758 <row topline="true">
12759 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12760 \begin_inset Text
12761
12762 \layout Standard
12763
12764 _divsint.c
12765 \end_inset
12766 </cell>
12767 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12768 \begin_inset Text
12769
12770 \layout Standard
12771
12772  signed 16 bit division (calls _divuint)
12773 \end_inset
12774 </cell>
12775 </row>
12776 <row topline="true">
12777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12778 \begin_inset Text
12779
12780 \layout Standard
12781
12782 _divuint.c
12783 \end_inset
12784 </cell>
12785 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12786 \begin_inset Text
12787
12788 \layout Standard
12789
12790  unsigned 16 bit division
12791 \end_inset
12792 </cell>
12793 </row>
12794 <row topline="true">
12795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12796 \begin_inset Text
12797
12798 \layout Standard
12799
12800 _modsint.c
12801 \end_inset
12802 </cell>
12803 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12804 \begin_inset Text
12805
12806 \layout Standard
12807
12808 signed 16 bit modulus (calls _moduint)
12809 \end_inset
12810 </cell>
12811 </row>
12812 <row topline="true">
12813 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12814 \begin_inset Text
12815
12816 \layout Standard
12817
12818 _moduint.c
12819 \end_inset
12820 </cell>
12821 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12822 \begin_inset Text
12823
12824 \layout Standard
12825
12826 unsigned 16 bit modulus
12827 \end_inset
12828 </cell>
12829 </row>
12830 <row topline="true">
12831 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12832 \begin_inset Text
12833
12834 \layout Standard
12835
12836 _mullong.c
12837 \end_inset
12838 </cell>
12839 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12840 \begin_inset Text
12841
12842 \layout Standard
12843
12844 32 bit multiplication
12845 \end_inset
12846 </cell>
12847 </row>
12848 <row topline="true">
12849 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12850 \begin_inset Text
12851
12852 \layout Standard
12853
12854 _divslong.c
12855 \end_inset
12856 </cell>
12857 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12858 \begin_inset Text
12859
12860 \layout Standard
12861
12862  signed 32 division (calls _divulong)
12863 \end_inset
12864 </cell>
12865 </row>
12866 <row topline="true">
12867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12868 \begin_inset Text
12869
12870 \layout Standard
12871
12872 _divulong.c
12873 \end_inset
12874 </cell>
12875 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12876 \begin_inset Text
12877
12878 \layout Standard
12879
12880 unsigned 32 division
12881 \end_inset
12882 </cell>
12883 </row>
12884 <row topline="true">
12885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12886 \begin_inset Text
12887
12888 \layout Standard
12889
12890 _modslong.c
12891 \end_inset
12892 </cell>
12893 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12894 \begin_inset Text
12895
12896 \layout Standard
12897
12898  signed 32 bit modulus (calls _modulong)
12899 \end_inset
12900 </cell>
12901 </row>
12902 <row topline="true" bottomline="true">
12903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12904 \begin_inset Text
12905
12906 \layout Standard
12907
12908 _modulong.c
12909 \end_inset
12910 </cell>
12911 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12912 \begin_inset Text
12913
12914 \layout Standard
12915
12916 unsigned 32 bit modulus
12917 \end_inset
12918 </cell>
12919 </row>
12920 </lyxtabular>
12921
12922 \end_inset
12923
12924
12925 \newline
12926
12927 \layout Standard
12928
12929 Since they are compiled as
12930 \emph on
12931 non-reentrant
12932 \emph default
12933
12934 \begin_inset LatexCommand \index{reentrant}
12935
12936 \end_inset
12937
12938 , interrupt
12939 \begin_inset LatexCommand \index{interrupt}
12940
12941 \end_inset
12942
12943  service routines should not do any of the above operations.
12944  If this is unavoidable then the above routines will need to be compiled
12945  with the
12946 \emph on
12947 -
12948 \begin_inset ERT
12949 status Collapsed
12950
12951 \layout Standard
12952
12953 \backslash
12954 /
12955 \end_inset
12956
12957 -stack-auto
12958 \begin_inset LatexCommand \index{-\/-stack-auto}
12959
12960 \end_inset
12961
12962
12963 \emph default
12964  option, after which the source program will have to be compiled with
12965 \emph on
12966 -
12967 \begin_inset ERT
12968 status Collapsed
12969
12970 \layout Standard
12971
12972 \backslash
12973 /
12974 \end_inset
12975
12976 -int-long-reent
12977 \begin_inset LatexCommand \index{-\/-int-long-reent}
12978
12979 \end_inset
12980
12981
12982 \emph default
12983  option.
12984  Notice that you don't have to call these routines directly.
12985  The compiler will use them automatically every time an integer operation
12986  is required.
12987 \layout Section
12988
12989 Floating Point Support
12990 \begin_inset LatexCommand \index{Floating point support}
12991
12992 \end_inset
12993
12994
12995 \layout Standard
12996
12997 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
12998  floating point support routines are derived from gcc's floatlib.c and consist
12999  of the following routines:
13000 \newline
13001
13002 \layout Standard
13003 \align center
13004
13005 \size footnotesize
13006
13007 \begin_inset  Tabular
13008 <lyxtabular version="3" rows="17" columns="2">
13009 <features>
13010 <column alignment="center" valignment="top" leftline="true" width="0">
13011 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13012 <row topline="true" bottomline="true">
13013 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13014 \begin_inset Text
13015
13016 \layout Standard
13017
13018
13019 \family roman
13020 \series medium
13021 \shape up
13022 \size normal
13023 \emph off
13024 \bar no
13025 \noun off
13026 \color none
13027 Function
13028 \end_inset
13029 </cell>
13030 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13031 \begin_inset Text
13032
13033 \layout Standard
13034
13035 Description
13036 \end_inset
13037 </cell>
13038 </row>
13039 <row topline="true">
13040 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13041 \begin_inset Text
13042
13043 \layout Standard
13044
13045
13046 \family roman
13047 \series medium
13048 \shape up
13049 \size normal
13050 \emph off
13051 \bar no
13052 \noun off
13053 \color none
13054 _fsadd.c
13055 \end_inset
13056 </cell>
13057 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13058 \begin_inset Text
13059
13060 \layout Standard
13061
13062
13063 \family roman
13064 \series medium
13065 \shape up
13066 \size normal
13067 \emph off
13068 \bar no
13069 \noun off
13070 \color none
13071 add floating point numbers
13072 \end_inset
13073 </cell>
13074 </row>
13075 <row topline="true">
13076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13077 \begin_inset Text
13078
13079 \layout Standard
13080
13081
13082 \family roman
13083 \series medium
13084 \shape up
13085 \size normal
13086 \emph off
13087 \bar no
13088 \noun off
13089 \color none
13090 _fssub.c
13091 \end_inset
13092 </cell>
13093 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13094 \begin_inset Text
13095
13096 \layout Standard
13097
13098
13099 \family roman
13100 \series medium
13101 \shape up
13102 \size normal
13103 \emph off
13104 \bar no
13105 \noun off
13106 \color none
13107 subtract floating point numbers
13108 \end_inset
13109 </cell>
13110 </row>
13111 <row topline="true">
13112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13113 \begin_inset Text
13114
13115 \layout Standard
13116
13117
13118 \family roman
13119 \series medium
13120 \shape up
13121 \size normal
13122 \emph off
13123 \bar no
13124 \noun off
13125 \color none
13126 _fsdiv.c
13127 \end_inset
13128 </cell>
13129 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13130 \begin_inset Text
13131
13132 \layout Standard
13133
13134
13135 \family roman
13136 \series medium
13137 \shape up
13138 \size normal
13139 \emph off
13140 \bar no
13141 \noun off
13142 \color none
13143 divide floating point numbers
13144 \end_inset
13145 </cell>
13146 </row>
13147 <row topline="true">
13148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13149 \begin_inset Text
13150
13151 \layout Standard
13152
13153
13154 \family roman
13155 \series medium
13156 \shape up
13157 \size normal
13158 \emph off
13159 \bar no
13160 \noun off
13161 \color none
13162 _fsmul.c
13163 \end_inset
13164 </cell>
13165 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13166 \begin_inset Text
13167
13168 \layout Standard
13169
13170
13171 \family roman
13172 \series medium
13173 \shape up
13174 \size normal
13175 \emph off
13176 \bar no
13177 \noun off
13178 \color none
13179 multiply floating point numbers
13180 \end_inset
13181 </cell>
13182 </row>
13183 <row topline="true">
13184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13185 \begin_inset Text
13186
13187 \layout Standard
13188
13189
13190 \family roman
13191 \series medium
13192 \shape up
13193 \size normal
13194 \emph off
13195 \bar no
13196 \noun off
13197 \color none
13198 _fs2uchar.c
13199 \end_inset
13200 </cell>
13201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13202 \begin_inset Text
13203
13204 \layout Standard
13205
13206
13207 \family roman
13208 \series medium
13209 \shape up
13210 \size normal
13211 \emph off
13212 \bar no
13213 \noun off
13214 \color none
13215 convert floating point to unsigned char
13216 \end_inset
13217 </cell>
13218 </row>
13219 <row topline="true">
13220 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13221 \begin_inset Text
13222
13223 \layout Standard
13224
13225
13226 \family roman
13227 \series medium
13228 \shape up
13229 \size normal
13230 \emph off
13231 \bar no
13232 \noun off
13233 \color none
13234 _fs2char.c
13235 \end_inset
13236 </cell>
13237 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13238 \begin_inset Text
13239
13240 \layout Standard
13241
13242
13243 \family roman
13244 \series medium
13245 \shape up
13246 \size normal
13247 \emph off
13248 \bar no
13249 \noun off
13250 \color none
13251 convert floating point to signed char
13252 \end_inset
13253 </cell>
13254 </row>
13255 <row topline="true">
13256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13257 \begin_inset Text
13258
13259 \layout Standard
13260
13261
13262 \family roman
13263 \series medium
13264 \shape up
13265 \size normal
13266 \emph off
13267 \bar no
13268 \noun off
13269 \color none
13270 _fs2uint.c
13271 \end_inset
13272 </cell>
13273 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13274 \begin_inset Text
13275
13276 \layout Standard
13277
13278
13279 \family roman
13280 \series medium
13281 \shape up
13282 \size normal
13283 \emph off
13284 \bar no
13285 \noun off
13286 \color none
13287 convert floating point to unsigned int
13288 \end_inset
13289 </cell>
13290 </row>
13291 <row topline="true">
13292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13293 \begin_inset Text
13294
13295 \layout Standard
13296
13297
13298 \family roman
13299 \series medium
13300 \shape up
13301 \size normal
13302 \emph off
13303 \bar no
13304 \noun off
13305 \color none
13306 _fs2int.c
13307 \end_inset
13308 </cell>
13309 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13310 \begin_inset Text
13311
13312 \layout Standard
13313
13314
13315 \family roman
13316 \series medium
13317 \shape up
13318 \size normal
13319 \emph off
13320 \bar no
13321 \noun off
13322 \color none
13323 convert floating point to signed int
13324 \end_inset
13325 </cell>
13326 </row>
13327 <row topline="true">
13328 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13329 \begin_inset Text
13330
13331 \layout Standard
13332
13333
13334 \family roman
13335 \series medium
13336 \shape up
13337 \size normal
13338 \emph off
13339 \bar no
13340 \noun off
13341 \color none
13342 _fs2ulong.
13343 \family default
13344 \series default
13345 \shape default
13346 \size default
13347 \emph default
13348 \bar default
13349 \noun default
13350 \color default
13351 c
13352 \end_inset
13353 </cell>
13354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13355 \begin_inset Text
13356
13357 \layout Standard
13358
13359
13360 \family roman
13361 \series medium
13362 \shape up
13363 \size normal
13364 \emph off
13365 \bar no
13366 \noun off
13367 \color none
13368 convert floating point to unsigned long
13369 \end_inset
13370 </cell>
13371 </row>
13372 <row topline="true">
13373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13374 \begin_inset Text
13375
13376 \layout Standard
13377
13378
13379 \family roman
13380 \series medium
13381 \shape up
13382 \size normal
13383 \emph off
13384 \bar no
13385 \noun off
13386 \color none
13387 _fs2long.c
13388 \end_inset
13389 </cell>
13390 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13391 \begin_inset Text
13392
13393 \layout Standard
13394
13395
13396 \family roman
13397 \series medium
13398 \shape up
13399 \size normal
13400 \emph off
13401 \bar no
13402 \noun off
13403 \color none
13404 convert floating point to signed long
13405 \end_inset
13406 </cell>
13407 </row>
13408 <row topline="true">
13409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13410 \begin_inset Text
13411
13412 \layout Standard
13413
13414
13415 \family roman
13416 \series medium
13417 \shape up
13418 \size normal
13419 \emph off
13420 \bar no
13421 \noun off
13422 \color none
13423 _uchar2fs.c
13424 \end_inset
13425 </cell>
13426 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13427 \begin_inset Text
13428
13429 \layout Standard
13430
13431
13432 \family roman
13433 \series medium
13434 \shape up
13435 \size normal
13436 \emph off
13437 \bar no
13438 \noun off
13439 \color none
13440 convert unsigned char to floating point
13441 \end_inset
13442 </cell>
13443 </row>
13444 <row topline="true">
13445 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13446 \begin_inset Text
13447
13448 \layout Standard
13449
13450
13451 \family roman
13452 \series medium
13453 \shape up
13454 \size normal
13455 \emph off
13456 \bar no
13457 \noun off
13458 \color none
13459 _char2fs.c
13460 \end_inset
13461 </cell>
13462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13463 \begin_inset Text
13464
13465 \layout Standard
13466
13467
13468 \family roman
13469 \series medium
13470 \shape up
13471 \size normal
13472 \emph off
13473 \bar no
13474 \noun off
13475 \color none
13476 convert char to floating point number
13477 \end_inset
13478 </cell>
13479 </row>
13480 <row topline="true">
13481 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13482 \begin_inset Text
13483
13484 \layout Standard
13485
13486
13487 \family roman
13488 \series medium
13489 \shape up
13490 \size normal
13491 \emph off
13492 \bar no
13493 \noun off
13494 \color none
13495 _uint2fs.c
13496 \end_inset
13497 </cell>
13498 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13499 \begin_inset Text
13500
13501 \layout Standard
13502
13503
13504 \family roman
13505 \series medium
13506 \shape up
13507 \size normal
13508 \emph off
13509 \bar no
13510 \noun off
13511 \color none
13512 convert unsigned int to floating point
13513 \end_inset
13514 </cell>
13515 </row>
13516 <row topline="true">
13517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13518 \begin_inset Text
13519
13520 \layout Standard
13521
13522
13523 \family roman
13524 \series medium
13525 \shape up
13526 \size normal
13527 \emph off
13528 \bar no
13529 \noun off
13530 \color none
13531 _int2fs.c
13532 \end_inset
13533 </cell>
13534 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13535 \begin_inset Text
13536
13537 \layout Standard
13538
13539
13540 \family roman
13541 \series medium
13542 \shape up
13543 \size normal
13544 \emph off
13545 \bar no
13546 \noun off
13547 \color none
13548 convert int to floating point numbers
13549 \end_inset
13550 </cell>
13551 </row>
13552 <row topline="true">
13553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13554 \begin_inset Text
13555
13556 \layout Standard
13557
13558
13559 \family roman
13560 \series medium
13561 \shape up
13562 \size normal
13563 \emph off
13564 \bar no
13565 \noun off
13566 \color none
13567 _ulong2fs.c
13568 \end_inset
13569 </cell>
13570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13571 \begin_inset Text
13572
13573 \layout Standard
13574
13575
13576 \family roman
13577 \series medium
13578 \shape up
13579 \size normal
13580 \emph off
13581 \bar no
13582 \noun off
13583 \color none
13584 convert unsigned long to floating point number
13585 \end_inset
13586 </cell>
13587 </row>
13588 <row topline="true" bottomline="true">
13589 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13590 \begin_inset Text
13591
13592 \layout Standard
13593
13594
13595 \family roman
13596 \series medium
13597 \shape up
13598 \size normal
13599 \emph off
13600 \bar no
13601 \noun off
13602 \color none
13603 _long2fs.c
13604 \end_inset
13605 </cell>
13606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13607 \begin_inset Text
13608
13609 \layout Standard
13610
13611
13612 \family roman
13613 \series medium
13614 \shape up
13615 \size normal
13616 \emph off
13617 \bar no
13618 \noun off
13619 \color none
13620 convert long to floating point number
13621 \end_inset
13622 </cell>
13623 </row>
13624 </lyxtabular>
13625
13626 \end_inset
13627
13628
13629 \newline
13630
13631 \layout Standard
13632
13633 These support routines are developed in ANSI-C so there is room for space
13634  and speed improvement.
13635  Note if all these routines are used simultaneously the data space might
13636  overflow.
13637  For serious floating point usage it is recommended that the large model
13638  be used.
13639  Also notice that you don't have to call this routines directly.
13640  The compiler will use them automatically every time a floating point operation
13641  is required.
13642 \layout Section
13643
13644 Library Routines
13645 \begin_inset LatexCommand \index{Libraries}
13646
13647 \end_inset
13648
13649
13650 \layout Standard
13651
13652
13653 \emph on
13654 <pending: this is messy and incomplete - a little more information is in
13655  sdcc/doc/libdoc.txt
13656 \emph default
13657  >
13658 \layout Subsection
13659
13660 Compiler support routines (_gptrget, _mulint etc.)
13661 \layout Subsection
13662
13663 Stdclib functions (puts, printf, strcat etc.)
13664 \layout Subsubsection
13665
13666 <stdio.h>
13667 \layout Standard
13668
13669
13670 \begin_inset LatexCommand \index{<stdio.h>}
13671
13672 \end_inset
13673
13674 As usual on embedded systems you have to provide your own
13675 \family typewriter
13676 getchar()
13677 \begin_inset LatexCommand \index{getchar()}
13678
13679 \end_inset
13680
13681
13682 \family default
13683 and
13684 \family typewriter
13685 putchar()
13686 \begin_inset LatexCommand \index{putchar()}
13687
13688 \end_inset
13689
13690
13691 \family default
13692  routines.
13693  SDCC does not know whether the system connects to a serial line with or
13694  without handshake, LCD, keyboard or other device.
13695  You'll find examples for serial routines f.e.
13696  in sdcc/device/lib.
13697 \layout Standard
13698
13699 The default
13700 \family typewriter
13701  printf()
13702 \begin_inset LatexCommand \index{printf()}
13703
13704 \end_inset
13705
13706
13707 \family default
13708 implementation in
13709 \family typewriter
13710  printf_large.c
13711 \family default
13712  does not support float (except on ds390).
13713  To enable this recompile it with the option
13714 \emph on
13715 -
13716 \begin_inset ERT
13717 status Collapsed
13718
13719 \layout Standard
13720
13721 \backslash
13722 /
13723 \end_inset
13724
13725 DUSE_FLOATS=1
13726 \begin_inset LatexCommand \index{USE\_FLOATS}
13727
13728 \end_inset
13729
13730
13731 \emph default
13732  on the command line.
13733  Use
13734 \emph on
13735 -
13736 \begin_inset ERT
13737 status Collapsed
13738
13739 \layout Standard
13740
13741 \backslash
13742 /
13743 \end_inset
13744
13745 -model-large
13746 \begin_inset LatexCommand \index{-\/-model-large}
13747
13748 \end_inset
13749
13750
13751 \emph default
13752  for the mcs51 port, since this uses a lot of memory.
13753 \layout Standard
13754
13755 If you're short on memory you might want to use
13756 \family typewriter
13757 printf_small()
13758 \family default
13759
13760 \emph on
13761 instead
13762 \emph default
13763  of
13764 \family typewriter
13765  printf().
13766
13767 \family default
13768  For the mcs51 there is an assembly version
13769 \family typewriter
13770 printf_fast()
13771 \family default
13772  which should fit the requirements of many embedded systems (by unsetting
13773  #defines it can be customized to
13774 \emph on
13775 not
13776 \emph default
13777  support long variables and field widths).
13778 \layout Subsection
13779
13780 Math functions (sin, pow, sqrt etc.)
13781 \layout Subsection
13782
13783 Other libraries
13784 \layout Standard
13785
13786 Libraries
13787 \begin_inset LatexCommand \index{Libraries}
13788
13789 \end_inset
13790
13791  included in SDCC should have a license at least as liberal as the GNU Lesser
13792  General Public License
13793 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
13794
13795 \end_inset
13796
13797
13798 \emph on
13799 LGPL
13800 \emph default
13801 .
13802 \layout Comment
13803
13804 license statements for the libraries are missing.
13805  sdcc/device/lib/ser_ir.c
13806 \layout Comment
13807
13808 or _decdptr f.e.
13809  come with a GPL (as opposed to LGPL) License - this will not be liberal
13810  enough for many embedded programmers.
13811 \layout Standard
13812
13813 If you have ported some library or want to share experience about some code
13814  which f.e.
13815  falls into any of these categories Busses (I
13816 \begin_inset Formula $^{\textrm{2}}$
13817 \end_inset
13818
13819 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
13820  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
13821  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
13822 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
13823
13824 \end_inset
13825
13826 \SpecialChar ~
13827 would certainly like to hear about it.
13828  Programmers coding for embedded systems are not especially famous for being
13829  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
13830 e these references are very valuable.
13831  Let's help to create a climate where information is shared.
13832 \layout Section
13833
13834 Memory Models
13835 \layout Subsection
13836
13837 MCS51 Memory Models
13838 \begin_inset LatexCommand \index{Memory model}
13839
13840 \end_inset
13841
13842
13843 \begin_inset LatexCommand \index{MCS51 memory model}
13844
13845 \end_inset
13846
13847
13848 \layout Subsubsection
13849
13850 Small and Large
13851 \layout Standard
13852
13853 SDCC allows two memory models for MCS51 code,
13854 \shape slanted
13855 small
13856 \shape default
13857  and
13858 \shape slanted
13859 large
13860 \shape default
13861 .
13862  Modules compiled with different memory models should
13863 \emph on
13864 never
13865 \emph default
13866  be combined together or the results would be unpredictable.
13867  The library routines supplied with the compiler are compiled as both small
13868  and large.
13869  The compiled library modules are contained in separate directories as small
13870  and large so that you can link to either set.
13871
13872 \layout Standard
13873
13874 When the large model is used all variables declared without a storage class
13875  will be allocated into the external ram, this includes all parameters and
13876  local variables (for non-reentrant
13877 \begin_inset LatexCommand \index{reentrant}
13878
13879 \end_inset
13880
13881  functions).
13882  When the small model is used variables without storage class are allocated
13883  in the internal ram.
13884 \layout Standard
13885
13886 Judicious usage of the processor specific storage classes
13887 \begin_inset LatexCommand \index{Storage class}
13888
13889 \end_inset
13890
13891  and the 'reentrant' function type will yield much more efficient code,
13892  than using the large model.
13893  Several optimizations are disabled when the program is compiled using the
13894  large model, it is therefore recommended that the small model be used unless
13895  absolutely required.
13896 \layout Subsubsection
13897
13898 External Stack
13899 \begin_inset LatexCommand \label{sub:External-Stack}
13900
13901 \end_inset
13902
13903
13904 \begin_inset LatexCommand \index{stack}
13905
13906 \end_inset
13907
13908
13909 \begin_inset LatexCommand \index{External stack (mcs51)}
13910
13911 \end_inset
13912
13913
13914 \layout Standard
13915
13916
13917 \series bold
13918 Attention
13919 \series default
13920 : this option wasn't maintained for a long time and is quite buggy.
13921  Small programs might work.
13922  You've been warned!
13923 \layout Standard
13924
13925 The external stack (-
13926 \begin_inset ERT
13927 status Collapsed
13928
13929 \layout Standard
13930
13931 \backslash
13932 /
13933 \end_inset
13934
13935 -xstack option
13936 \begin_inset LatexCommand \index{-\/-xstack}
13937
13938 \end_inset
13939
13940 ) is located in pdata
13941 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
13942
13943 \end_inset
13944
13945  memory (usually at the start of the external ram segment) and is 256 bytes
13946  in size.
13947  When -
13948 \begin_inset ERT
13949 status Collapsed
13950
13951 \layout Standard
13952
13953 \backslash
13954 /
13955 \end_inset
13956
13957 -xstack option is used to compile the program, the parameters and local
13958  variables
13959 \begin_inset LatexCommand \index{local variables}
13960
13961 \end_inset
13962
13963  of all reentrant functions are allocated in this area.
13964  This option is provided for programs with large stack space requirements.
13965  When used with the -
13966 \begin_inset ERT
13967 status Collapsed
13968
13969 \layout Standard
13970
13971 \backslash
13972 /
13973 \end_inset
13974
13975 -stack-auto
13976 \begin_inset LatexCommand \index{-\/-stack-auto}
13977
13978 \end_inset
13979
13980  option, all parameters and local variables are allocated on the external
13981  stack (note: support libraries will need to be recompiled with the same
13982  options).
13983 \layout Standard
13984
13985 The compiler outputs the higher order address byte of the external ram segment
13986  into port P2
13987 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
13988
13989 \end_inset
13990
13991  (see also section
13992 \begin_inset LatexCommand \ref{sub:MCS51-variants}
13993
13994 \end_inset
13995
13996 ), therefore when using the External Stack option, this port
13997 \emph on
13998 may not
13999 \emph default
14000  be used by the application program.
14001 \layout Subsection
14002
14003 DS390 Memory Model
14004 \begin_inset LatexCommand \index{Memory model}
14005
14006 \end_inset
14007
14008
14009 \begin_inset LatexCommand \index{DS390 memory model}
14010
14011 \end_inset
14012
14013
14014 \layout Standard
14015
14016 The only model supported is Flat 24
14017 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
14018
14019 \end_inset
14020
14021 .
14022  This generates code for the 24 bit contiguous addressing mode of the Dallas
14023  DS80C390 part.
14024  In this mode, up to four meg of external RAM or code space can be directly
14025  addressed.
14026  See the data sheets at www.dalsemi.com for further information on this part.
14027 \newline
14028
14029 \newline
14030 Note that the compiler does not generate any code to place the processor
14031  into 24 bitmode (although
14032 \emph on
14033 tinibios
14034 \emph default
14035  in the ds390 libraries will do that for you).
14036  If you don't use
14037 \emph on
14038 tinibios
14039 \emph default
14040
14041 \begin_inset LatexCommand \index{Tinibios (DS390)}
14042
14043 \end_inset
14044
14045 , the boot loader or similar code must ensure that the processor is in 24
14046  bit contiguous addressing mode before calling the SDCC startup code.
14047 \newline
14048
14049 \newline
14050 Like the
14051 \emph on
14052 -
14053 \begin_inset ERT
14054 status Collapsed
14055
14056 \layout Standard
14057
14058 \backslash
14059 /
14060 \end_inset
14061
14062 -model-large
14063 \emph default
14064  option, variables will by default be placed into the XDATA segment.
14065
14066 \newline
14067
14068 \newline
14069 Segments may be placed anywhere in the 4 meg address space using the usual
14070  -
14071 \begin_inset ERT
14072 status Collapsed
14073
14074 \layout Standard
14075
14076 \backslash
14077 /
14078 \end_inset
14079
14080 -*-loc options.
14081  Note that if any segments are located above 64K, the -r flag must be passed
14082  to the linker to generate the proper segment relocations, and the Intel
14083  HEX output format must be used.
14084  The -r flag can be passed to the linker by using the option
14085 \emph on
14086 -Wl-r
14087 \emph default
14088  on the SDCC command line.
14089  However, currently the linker can not handle code segments > 64k.
14090 \layout Section
14091
14092 Pragmas
14093 \begin_inset LatexCommand \index{Pragmas}
14094
14095 \end_inset
14096
14097
14098 \layout Standard
14099
14100 SDCC supports the following #pragma directives:
14101 \layout Itemize
14102
14103 save
14104 \begin_inset LatexCommand \index{\#pragma save}
14105
14106 \end_inset
14107
14108  - this will save all current options to the save/restore stack.
14109  See #pragma\SpecialChar ~
14110 restore.
14111 \layout Itemize
14112
14113 restore
14114 \begin_inset LatexCommand \index{\#pragma restore}
14115
14116 \end_inset
14117
14118  - will restore saved options from the last save.
14119  saves & restores can be nested.
14120  SDCC uses a save/restore stack: save pushes current options to the stack,
14121  restore pulls current options from the stack.
14122  See #pragma\SpecialChar ~
14123 save.
14124 \newline
14125
14126 \layout Itemize
14127
14128 callee_saves
14129 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14130
14131 \end_inset
14132
14133
14134 \begin_inset LatexCommand \index{function prologue}
14135
14136 \end_inset
14137
14138  function1[,function2[,function3...]] - The compiler by default uses a caller
14139  saves convention for register saving across function calls, however this
14140  can cause unnecessary register pushing & popping
14141 \begin_inset LatexCommand \index{push/pop}
14142
14143 \end_inset
14144
14145  when calling small functions from larger functions.
14146  This option can be used to switch off the register saving convention for
14147  the function names specified.
14148  The compiler will not save registers when calling these functions, extra
14149  code need to be manually inserted at the entry & exit for these functions
14150  to save & restore the registers used by these functions, this can SUBSTANTIALLY
14151  reduce code & improve run time performance of the generated code.
14152  In the future the compiler (with inter procedural analysis) may be able
14153  to determine the appropriate scheme to use for each function call.
14154  If -
14155 \begin_inset ERT
14156 status Collapsed
14157
14158 \layout Standard
14159
14160 \backslash
14161 /
14162 \end_inset
14163
14164 -callee-saves command line option is used, the function names specified
14165  in #pragma\SpecialChar ~
14166 callee_saves
14167 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14168
14169 \end_inset
14170
14171  is appended to the list of functions specified in the command line.
14172 \layout Itemize
14173
14174 exclude
14175 \begin_inset LatexCommand \index{\#pragma exclude}
14176
14177 \end_inset
14178
14179  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
14180  of pairs of push/pop
14181 \begin_inset LatexCommand \index{push/pop}
14182
14183 \end_inset
14184
14185  instructions in
14186 \emph on
14187 I
14188 \emph default
14189 nterrupt
14190 \begin_inset LatexCommand \index{interrupt}
14191
14192 \end_inset
14193
14194
14195 \emph on
14196 S
14197 \emph default
14198 ervice
14199 \emph on
14200 R
14201 \emph default
14202 outines.
14203  The directive should be placed immediately before the ISR function definition
14204  and it affects ALL ISR functions following it.
14205  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
14206 exclude\SpecialChar ~
14207 none
14208 \begin_inset LatexCommand \index{\#pragma exclude}
14209
14210 \end_inset
14211
14212 .
14213  See also the related keyword _naked
14214 \begin_inset LatexCommand \index{\_naked}
14215
14216 \end_inset
14217
14218 .
14219 \layout Itemize
14220
14221 less_pedantic
14222 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
14223
14224 \end_inset
14225
14226  - the compiler will not warn you anymore for obvious mistakes, you'r on
14227  your own now ;-(
14228 \layout Itemize
14229
14230 disable_warning <nnnn>
14231 \begin_inset LatexCommand \index{\#pragma disable\_warning}
14232
14233 \end_inset
14234
14235  - the compiler will not warn you anymore about warning number <nnnn>.
14236 \layout Itemize
14237
14238 nogcse
14239 \begin_inset LatexCommand \index{\#pragma nogcse}
14240
14241 \end_inset
14242
14243  - will stop global common subexpression elimination.
14244 \layout Itemize
14245
14246 noinduction
14247 \begin_inset LatexCommand \index{\#pragma noinduction}
14248
14249 \end_inset
14250
14251  - will stop loop induction optimizations.
14252 \layout Itemize
14253
14254 noinvariant
14255 \begin_inset LatexCommand \index{\#pragma noinvariant}
14256
14257 \end_inset
14258
14259  - will not do loop invariant optimizations.
14260  For more details see Loop Invariants in section
14261 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
14262
14263 \end_inset
14264
14265 .
14266 \layout Itemize
14267
14268 noiv
14269 \begin_inset LatexCommand \index{\#pragma noiv}
14270
14271 \end_inset
14272
14273  - Do not generate interrupt
14274 \begin_inset LatexCommand \index{interrupt}
14275
14276 \end_inset
14277
14278  vector table entries for all ISR functions defined after the pragma.
14279  This is useful in cases where the interrupt vector table must be defined
14280  manually, or when there is a secondary, manually defined interrupt vector
14281  table (e.g.
14282  for the autovector feature of the Cypress EZ-USB FX2).
14283  More elegantly this can be achieved by obmitting the optional interrupt
14284  number after the interrupt keyword, see section
14285 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
14286
14287 \end_inset
14288
14289 \SpecialChar ~
14290 about interrupts.
14291 \layout Itemize
14292
14293 nojtbound
14294 \begin_inset LatexCommand \index{\#pragma nojtbound}
14295
14296 \end_inset
14297
14298  - will not generate code for boundary value checking, when switch statements
14299  are turned into jump-tables (dangerous).
14300  For more details see section
14301 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
14302
14303 \end_inset
14304
14305 .
14306 \layout Itemize
14307
14308 noloopreverse
14309 \begin_inset LatexCommand \index{\#pragma noloopreverse}
14310
14311 \end_inset
14312
14313  - Will not do loop reversal optimization
14314 \layout Itemize
14315
14316 nooverlay
14317 \begin_inset LatexCommand \index{\#pragma nooverlay}
14318
14319 \end_inset
14320
14321  - the compiler will not overlay the parameters and local variables of a
14322  function.
14323 \layout Itemize
14324
14325 stackauto
14326 \begin_inset LatexCommand \index{\#pragma stackauto}
14327
14328 \end_inset
14329
14330 - See option -
14331 \begin_inset ERT
14332 status Collapsed
14333
14334 \layout Standard
14335
14336 \backslash
14337 /
14338 \end_inset
14339
14340 -stack-auto
14341 \begin_inset LatexCommand \index{-\/-stack-auto}
14342
14343 \end_inset
14344
14345  and section
14346 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
14347
14348 \end_inset
14349
14350  Parameters and Local Variables.
14351 \layout Itemize
14352
14353 opt_code_speed
14354 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
14355
14356 \end_inset
14357
14358 - The compiler will optimize code generation towards fast code, possibly
14359  at the expense of code size.
14360 \layout Itemize
14361
14362 opt_code_size
14363 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
14364
14365 \end_inset
14366
14367 - The compiler will optimize code generation towards compact code, possibly
14368  at the expense of code speed.
14369 \layout Itemize
14370
14371 opt_code_balanced
14372 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
14373
14374 \end_inset
14375
14376 - The compiler will attempt to generate code that is both compact and fast,
14377  as long as meeting one goal is not a detriment to the other (this is the
14378  default).
14379
14380 \layout Standard
14381
14382 SDCPP supports the following #pragma directives:
14383 \layout Itemize
14384
14385 preproc_asm
14386 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
14387
14388 \end_inset
14389
14390  (+ | -) - switch _asm _endasm block preprocessing on / off.
14391  Default is on.
14392 \layout Standard
14393
14394 The pragma's are intended to be used to turn-on or off certain optimizations
14395  which might cause the compiler to generate extra stack / data space to
14396  store compiler generated temporary variables.
14397  This usually happens in large functions.
14398  Pragma directives should be used as shown in the following example, they
14399  are used to control options & optimizations for a given function; pragmas
14400  should be placed before and/or after a function, placing pragma's inside
14401  a function body could have unpredictable results.
14402 \layout Verse
14403
14404
14405 \family typewriter
14406 #pragma save
14407 \begin_inset LatexCommand \index{\#pragma save}
14408
14409 \end_inset
14410
14411  \SpecialChar ~
14412 \SpecialChar ~
14413 \SpecialChar ~
14414 \SpecialChar ~
14415 \SpecialChar ~
14416 \SpecialChar ~
14417 \SpecialChar ~
14418 /* save the current settings */
14419 \newline
14420 #pragma nogcse
14421 \begin_inset LatexCommand \index{\#pragma nogcse}
14422
14423 \end_inset
14424
14425  \SpecialChar ~
14426 \SpecialChar ~
14427 \SpecialChar ~
14428 \SpecialChar ~
14429 \SpecialChar ~
14430 /* turnoff global subexpression elimination */
14431 \newline
14432 #pragma noinduction
14433 \begin_inset LatexCommand \index{\#pragma noinduction}
14434
14435 \end_inset
14436
14437  /* turn off induction optimizations */
14438 \newline
14439 int foo ()
14440 \newline
14441 {
14442 \newline
14443 \SpecialChar ~
14444  \SpecialChar ~
14445  ...
14446
14447 \newline
14448 \SpecialChar ~
14449  \SpecialChar ~
14450  /* large code */
14451 \newline
14452 \SpecialChar ~
14453  \SpecialChar ~
14454  ...
14455
14456 \newline
14457 }
14458 \newline
14459 #pragma restore
14460 \begin_inset LatexCommand \index{\#pragma restore}
14461
14462 \end_inset
14463
14464  /* turn the optimizations back on */
14465 \layout Standard
14466
14467 The compiler will generate a warning message when extra space is allocated.
14468  It is strongly recommended that the save and restore pragma's be used when
14469  changing options for a function.
14470 \layout Section
14471
14472 Defines Created by the Compiler
14473 \layout Standard
14474
14475 The compiler creates the following #defines
14476 \begin_inset LatexCommand \index{\#defines}
14477
14478 \end_inset
14479
14480
14481 \begin_inset LatexCommand \index{Defines created by the compiler}
14482
14483 \end_inset
14484
14485 :
14486 \newline
14487
14488 \layout Standard
14489
14490
14491 \begin_inset  Tabular
14492 <lyxtabular version="3" rows="10" columns="2">
14493 <features>
14494 <column alignment="center" valignment="top" leftline="true" width="0">
14495 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
14496 <row topline="true" bottomline="true">
14497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14498 \begin_inset Text
14499
14500 \layout Standard
14501
14502
14503 \series bold
14504 #define
14505 \end_inset
14506 </cell>
14507 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14508 \begin_inset Text
14509
14510 \layout Standard
14511
14512
14513 \series bold
14514 Description
14515 \end_inset
14516 </cell>
14517 </row>
14518 <row topline="true">
14519 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14520 \begin_inset Text
14521
14522 \layout Standard
14523
14524 SDCC
14525 \begin_inset LatexCommand \index{SDCC}
14526
14527 \end_inset
14528
14529
14530 \end_inset
14531 </cell>
14532 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14533 \begin_inset Text
14534
14535 \layout Standard
14536
14537 this Symbol is always defined
14538 \end_inset
14539 </cell>
14540 </row>
14541 <row topline="true">
14542 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14543 \begin_inset Text
14544
14545 \layout Standard
14546
14547 SDCC_mcs51
14548 \begin_inset LatexCommand \index{SDCC\_mcs51}
14549
14550 \end_inset
14551
14552  or SDCC_ds390
14553 \begin_inset LatexCommand \index{SDCC\_ds390}
14554
14555 \end_inset
14556
14557  or SDCC_z80
14558 \begin_inset LatexCommand \index{SDCC\_z80}
14559
14560 \end_inset
14561
14562 , etc
14563 \end_inset
14564 </cell>
14565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14566 \begin_inset Text
14567
14568 \layout Standard
14569
14570 depending on the model used (e.g.: -mds390
14571 \end_inset
14572 </cell>
14573 </row>
14574 <row topline="true">
14575 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14576 \begin_inset Text
14577
14578 \layout Standard
14579
14580 __mcs51
14581 \begin_inset LatexCommand \index{\_\_mcs51}
14582
14583 \end_inset
14584
14585 , __ds390
14586 \begin_inset LatexCommand \index{\_\_ds390}
14587
14588 \end_inset
14589
14590 , __hc08
14591 \begin_inset LatexCommand \index{\_\_hc08}
14592
14593 \end_inset
14594
14595 , __z80
14596 \begin_inset LatexCommand \index{\_\_z80}
14597
14598 \end_inset
14599
14600 , etc
14601 \end_inset
14602 </cell>
14603 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14604 \begin_inset Text
14605
14606 \layout Standard
14607
14608 depending on the model used (e.g.
14609  -mz80)
14610 \end_inset
14611 </cell>
14612 </row>
14613 <row topline="true">
14614 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14615 \begin_inset Text
14616
14617 \layout Standard
14618
14619 SDCC_STACK_AUTO
14620 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
14621
14622 \end_inset
14623
14624
14625 \end_inset
14626 </cell>
14627 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14628 \begin_inset Text
14629
14630 \layout Standard
14631
14632 when
14633 \emph on
14634 -
14635 \begin_inset ERT
14636 status Collapsed
14637
14638 \layout Standard
14639
14640 \backslash
14641 /
14642 \end_inset
14643
14644 -stack-auto
14645 \emph default
14646  option is used
14647 \end_inset
14648 </cell>
14649 </row>
14650 <row topline="true">
14651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14652 \begin_inset Text
14653
14654 \layout Standard
14655
14656 SDCC_MODEL_SMALL
14657 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
14658
14659 \end_inset
14660
14661
14662 \end_inset
14663 </cell>
14664 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14665 \begin_inset Text
14666
14667 \layout Standard
14668
14669 when
14670 \emph on
14671 -
14672 \begin_inset ERT
14673 status Collapsed
14674
14675 \layout Standard
14676
14677 \backslash
14678 /
14679 \end_inset
14680
14681 -model-small
14682 \emph default
14683  is used
14684 \end_inset
14685 </cell>
14686 </row>
14687 <row topline="true">
14688 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14689 \begin_inset Text
14690
14691 \layout Standard
14692
14693 SDCC_MODEL_LARGE
14694 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
14695
14696 \end_inset
14697
14698
14699 \end_inset
14700 </cell>
14701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14702 \begin_inset Text
14703
14704 \layout Standard
14705
14706 when
14707 \emph on
14708 -
14709 \begin_inset ERT
14710 status Collapsed
14711
14712 \layout Standard
14713
14714 \backslash
14715 /
14716 \end_inset
14717
14718 -model-large
14719 \emph default
14720  is used
14721 \end_inset
14722 </cell>
14723 </row>
14724 <row topline="true">
14725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14726 \begin_inset Text
14727
14728 \layout Standard
14729
14730 SDCC_USE_XSTACK
14731 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
14732
14733 \end_inset
14734
14735
14736 \end_inset
14737 </cell>
14738 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14739 \begin_inset Text
14740
14741 \layout Standard
14742
14743 when
14744 \emph on
14745 -
14746 \begin_inset ERT
14747 status Collapsed
14748
14749 \layout Standard
14750
14751 \backslash
14752 /
14753 \end_inset
14754
14755 -xstack
14756 \emph default
14757  option is used
14758 \end_inset
14759 </cell>
14760 </row>
14761 <row topline="true">
14762 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14763 \begin_inset Text
14764
14765 \layout Standard
14766
14767 SDCC_STACK_TENBIT
14768 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
14769
14770 \end_inset
14771
14772
14773 \end_inset
14774 </cell>
14775 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14776 \begin_inset Text
14777
14778 \layout Standard
14779
14780 when
14781 \emph on
14782 -mds390
14783 \emph default
14784  is used
14785 \end_inset
14786 </cell>
14787 </row>
14788 <row topline="true" bottomline="true">
14789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14790 \begin_inset Text
14791
14792 \layout Standard
14793
14794 SDCC_MODEL_FLAT24
14795 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
14796
14797 \end_inset
14798
14799
14800 \end_inset
14801 </cell>
14802 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14803 \begin_inset Text
14804
14805 \layout Standard
14806
14807 when
14808 \emph on
14809 -mds390
14810 \emph default
14811  is used
14812 \end_inset
14813 </cell>
14814 </row>
14815 </lyxtabular>
14816
14817 \end_inset
14818
14819
14820 \layout Chapter
14821
14822 Notes on supported Processors
14823 \layout Section
14824
14825 MCS51 variants
14826 \begin_inset LatexCommand \label{sub:MCS51-variants}
14827
14828 \end_inset
14829
14830
14831 \begin_inset LatexCommand \index{MCS51 variants}
14832
14833 \end_inset
14834
14835
14836 \layout Standard
14837
14838 MCS51 processors are available from many vendors and come in many different
14839  flavours.
14840  While they might differ considerably in respect to Special Function Registers
14841  the core MCS51 is usually not modified or is kept compatible.
14842
14843 \layout Subsection
14844
14845 pdata access by SFR
14846 \layout Standard
14847
14848 With the upcome of devices with internal xdata and flash memory devices
14849  using port P2
14850 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14851
14852 \end_inset
14853
14854  as dedicated I/O port is becoming more popular.
14855  Switching the high byte for pdata
14856 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14857
14858 \end_inset
14859
14860  access which was formerly done by port P2 is then achieved by a Special
14861  Function Register
14862 \begin_inset LatexCommand \index{sfr}
14863
14864 \end_inset
14865
14866 .
14867  In well-established MCS51 tradition the address of this
14868 \emph on
14869 sfr
14870 \emph default
14871  is where the chip designers decided to put it.
14872  Needless to say that they didn't agree on a common name either.
14873  So that the startup code can correctly initialize xdata variables, you
14874  should define an sfr with the name _XPAGE
14875 \family typewriter
14876
14877 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
14878
14879 \end_inset
14880
14881
14882 \family default
14883  at the appropriate location if the default, port P2, is not used for this.
14884  Some examples are:
14885 \layout Verse
14886
14887
14888 \family typewriter
14889 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
14890 \layout Verse
14891
14892
14893 \family typewriter
14894 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
14895 \layout Verse
14896
14897
14898 \family typewriter
14899 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
14900 \layout Standard
14901
14902 For more exotic implementations further customizations may be needed.
14903  See section
14904 \begin_inset LatexCommand \ref{sub:Startup-Code}
14905
14906 \end_inset
14907
14908  for other possibilities.
14909 \layout Subsection
14910
14911 Other Features available by SFR
14912 \layout Standard
14913
14914 Some MCS51 variants offer features like Double DPTR
14915 \begin_inset LatexCommand \index{DPTR}
14916
14917 \end_inset
14918
14919 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
14920  These are currently not used for the MCS51 port.
14921  If you absolutely need them you can fall back to inline assembly or submit
14922  a patch to SDCC.
14923 \layout Section
14924
14925 DS400 port
14926 \layout Standard
14927
14928 The DS80C400 microcontroller has a rich set of peripherals.
14929  In its built-in ROM library it includes functions to access some of the
14930  features, among them is a TCP stack with IP4 and IP6 support.
14931  Library headers (currently in beta status) and other files are provided
14932  at
14933 \size footnotesize
14934
14935 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
14936
14937 \end_inset
14938
14939 .
14940
14941 \layout Section
14942
14943 The Z80 and gbz80 port
14944 \layout Standard
14945
14946 SDCC can target both the Zilog
14947 \begin_inset LatexCommand \index{Z80}
14948
14949 \end_inset
14950
14951  and the Nintendo Gameboy's Z80-like gbz80
14952 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
14953
14954 \end_inset
14955
14956 .
14957  The Z80 port is passed through the same
14958 \emph on
14959 regressions tests
14960 \begin_inset LatexCommand \index{Regression test}
14961
14962 \end_inset
14963
14964
14965 \emph default
14966  as the MCS51 and DS390 ports, so floating point support, support for long
14967  variables and bitfield support is fine.
14968  See mailing lists and forums about interrupt routines.
14969 \layout Standard
14970
14971 As always, the code is the authoritative reference - see z80/ralloc.c and
14972  z80/gen.c.
14973  The stack
14974 \begin_inset LatexCommand \index{stack}
14975
14976 \end_inset
14977
14978  frame is similar to that generated by the IAR Z80 compiler.
14979  IX is used as the base pointer, HL and IY are used as a temporary registers,
14980  and BC and DE are available for holding variables.
14981  Return values
14982 \begin_inset LatexCommand \index{return value}
14983
14984 \end_inset
14985
14986  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
14987  bytes).
14988  The gbz80 port use the same set of registers for the return values, but
14989  in a different order of significance: E (one byte), DE (two bytes), or
14990  HLDE (four bytes).
14991 \layout Section
14992
14993 The HC08 port
14994 \layout Standard
14995
14996 The port to the Motorola HC08
14997 \begin_inset LatexCommand \index{HC08}
14998
14999 \end_inset
15000
15001  family has been added in October 2003, and is still undergoing some basic
15002  development.
15003  The code generator is complete, but the register allocation is still quite
15004  unoptimized.
15005  Some of the SDCC's standard C library functions have embedded non-HC08
15006  inline assembly and so are not yet usable.
15007 \newline
15008
15009 \newline
15010
15011 \layout Section
15012
15013 The PIC14 port
15014 \layout Standard
15015
15016 The 14bit PIC
15017 \begin_inset LatexCommand \index{PIC14}
15018
15019 \end_inset
15020
15021  port still requires a major effort from the development community.
15022  However it can work for very simple code.
15023 \layout Subsection
15024
15025 C code and 14bit PIC code page
15026 \begin_inset LatexCommand \index{code page (pic14)}
15027
15028 \end_inset
15029
15030  and RAM banks
15031 \begin_inset LatexCommand \index{RAM bank (pic14)}
15032
15033 \end_inset
15034
15035
15036 \layout Standard
15037
15038 The linker organizes allocation for the code page and RAM banks.
15039  It does not have intimate knowledge of the code flow.
15040  It will put all the code section of a single asm file into a single code
15041  page.
15042  In order to make use of multiple code pages, separate asm files must be
15043  used.
15044  The compiler treats all functions of a single C file as being in the same
15045  code page unless it is non static.
15046  The compiler treats all local variables of a single C file as being in
15047  the same RAM bank unless it is an extern.
15048 \newline
15049
15050 \newline
15051 To get the best follow these guide lines:
15052 \layout Enumerate
15053
15054 make local functions static, as non static functions require code page selection
15055  overhead.
15056 \layout Enumerate
15057
15058 Make local variables static as extern variables require RAM bank selection
15059  overhead.
15060 \layout Enumerate
15061
15062 For devices that have multiple code pages it is more efficient to use the
15063  same number of files as pages, i.e.
15064  for the 16F877 use 4 separate files and i.e.
15065  for the 16F874 use 2 separate files.
15066  This way the linker can put the code for each file into different code
15067  pages and the compiler can allocate reusable variables more efficiently
15068  and there's less page selection overhead.
15069  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
15070  instruction set) use 'unsigned char' whereever possible instead of 'int'.
15071 \layout Subsection
15072
15073 Creating a device include file
15074 \layout Standard
15075
15076 For generating a device include file use the support perl script inc2h.pl
15077  kept in directory support/script.
15078 \layout Subsection
15079
15080 Interrupt code
15081 \layout Standard
15082
15083 For the interrupt function, use the keyword 'interrupt'
15084 \begin_inset LatexCommand \index{interrupt}
15085
15086 \end_inset
15087
15088  with level number of 0 (PIC14 only has 1 interrupt so this number is only
15089  there to avoid a syntax error - it ought to be fixed).
15090  E.g.:
15091 \layout Verse
15092
15093
15094 \family typewriter
15095 void Intr(void) interrupt 0
15096 \newline
15097 {
15098 \newline
15099 \SpecialChar ~
15100 \SpecialChar ~
15101 T0IF = 0; /* Clear timer interrupt */
15102 \newline
15103 }
15104 \layout Subsection
15105
15106 Linking and assembling
15107 \layout Standard
15108
15109 For assembling you can use either GPUTILS'
15110 \begin_inset LatexCommand \index{gputils (pic tools)}
15111
15112 \end_inset
15113
15114  gpasm.exe or MPLAB's mpasmwin.exe.
15115  GPUTILS is available from
15116 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
15117
15118 \end_inset
15119
15120 .
15121  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
15122  If you use MPLAB and an interrupt function then the linker script file
15123  vectors section will need to be enlarged to link with mplink.
15124 \newline
15125
15126 \newline
15127 Here is a
15128 \family typewriter
15129 Makefile
15130 \family default
15131  using GPUTILS:
15132 \layout Verse
15133
15134
15135 \family typewriter
15136 .c.o:
15137 \newline
15138 \SpecialChar ~
15139 \SpecialChar ~
15140 \SpecialChar ~
15141 \SpecialChar ~
15142 \SpecialChar ~
15143 \SpecialChar ~
15144 \SpecialChar ~
15145 \SpecialChar ~
15146 sdcc -S -V -mpic14 -p16F877 $<
15147 \newline
15148 \SpecialChar ~
15149 \SpecialChar ~
15150 \SpecialChar ~
15151 \SpecialChar ~
15152 \SpecialChar ~
15153 \SpecialChar ~
15154 \SpecialChar ~
15155 \SpecialChar ~
15156 gpasm -c $*.asm
15157 \newline
15158
15159 \newline
15160 $(PRJ).hex: $(OBJS)
15161 \newline
15162 \SpecialChar ~
15163 \SpecialChar ~
15164 \SpecialChar ~
15165 \SpecialChar ~
15166 \SpecialChar ~
15167 \SpecialChar ~
15168 \SpecialChar ~
15169 \SpecialChar ~
15170 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
15171 \layout Standard
15172
15173 Here is a
15174 \family typewriter
15175 Makefile
15176 \family default
15177  using MPLAB:
15178 \layout Verse
15179
15180
15181 \family typewriter
15182 .c.o:
15183 \newline
15184 \SpecialChar ~
15185 \SpecialChar ~
15186 \SpecialChar ~
15187 \SpecialChar ~
15188 \SpecialChar ~
15189 \SpecialChar ~
15190 \SpecialChar ~
15191 \SpecialChar ~
15192 sdcc -S -V -mpic14 -p16F877 $<
15193 \newline
15194 \SpecialChar ~
15195 \SpecialChar ~
15196 \SpecialChar ~
15197 \SpecialChar ~
15198 \SpecialChar ~
15199 \SpecialChar ~
15200 \SpecialChar ~
15201 \SpecialChar ~
15202 mpasmwin /q /o $*.asm
15203 \newline
15204
15205 \newline
15206 $(PRJ).hex: $(OBJS)
15207 \newline
15208 \SpecialChar ~
15209 \SpecialChar ~
15210 \SpecialChar ~
15211 \SpecialChar ~
15212 \SpecialChar ~
15213 \SpecialChar ~
15214 \SpecialChar ~
15215 \SpecialChar ~
15216 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
15217 \layout Standard
15218
15219 Please note that indentations within a
15220 \family typewriter
15221  Makefile
15222 \family default
15223  have to be done with a tabulator character.
15224 \layout Section
15225
15226 The PIC16
15227 \begin_inset LatexCommand \index{PIC16}
15228
15229 \end_inset
15230
15231  port
15232 \layout Standard
15233
15234 The PIC16
15235 \begin_inset LatexCommand \index{PIC16}
15236
15237 \end_inset
15238
15239  port is the portion of SDCC that is responsible to produce code for the
15240  Microchip
15241 \begin_inset LatexCommand \index{Microchip}
15242
15243 \end_inset
15244
15245 (TM) microcontrollers with 16 bit core.
15246  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
15247 \layout Subsection
15248
15249 Global Options
15250 \layout Standard
15251
15252 PIC16 port supports the standard command line arguments as supposed, with
15253  the exception of certain cases that will be mentioned in the following
15254  list:
15255 \layout List
15256 \labelwidthstring 00.00.0000
15257
15258 -
15259 \begin_inset ERT
15260 status Collapsed
15261
15262 \layout Standard
15263
15264 \backslash
15265 /
15266 \end_inset
15267
15268 -stack-auto Auto variables that are function parameters, will be saved on
15269  stack by default.
15270
15271 \emph on
15272 There is no need to specify this in the command line.
15273 \layout List
15274 \labelwidthstring 00.00.0000
15275
15276 -
15277 \begin_inset ERT
15278 status Collapsed
15279
15280 \layout Standard
15281
15282 \backslash
15283 /
15284 \end_inset
15285
15286 -float-reent All floating point functions are reentrant by default.
15287
15288 \emph on
15289 There is no need to specifiy this in the command line.
15290 \layout List
15291 \labelwidthstring 00.00.0000
15292
15293 -
15294 \begin_inset ERT
15295 status Collapsed
15296
15297 \layout Standard
15298
15299 \backslash
15300 /
15301 \end_inset
15302
15303 -callee-saves See -
15304 \begin_inset ERT
15305 status Collapsed
15306
15307 \layout Standard
15308
15309 \backslash
15310 /
15311 \end_inset
15312
15313 -all-callee-saves
15314 \layout List
15315 \labelwidthstring 00.00.0000
15316
15317 -
15318 \begin_inset ERT
15319 status Collapsed
15320
15321 \layout Standard
15322
15323 \backslash
15324 /
15325 \end_inset
15326
15327 -all-callee-saves All function arguments are passed on stack by default.
15328
15329 \emph on
15330 There is no need to specify this in the command line.
15331 \layout List
15332 \labelwidthstring 00.00.0000
15333
15334 -
15335 \begin_inset ERT
15336 status Collapsed
15337
15338 \layout Standard
15339
15340 \backslash
15341 /
15342 \end_inset
15343
15344 -fommit-frame-pointer Frame pointer will be omitted when the function uses
15345  no local variables.
15346 \layout Subsection
15347
15348 Port Specific Options
15349 \begin_inset LatexCommand \index{Options PIC16}
15350
15351 \end_inset
15352
15353
15354 \layout Standard
15355
15356 The port specific options appear after the global options in the sdcc --help
15357  output.
15358 \layout Subsubsection
15359
15360 General Options
15361 \layout Standard
15362
15363 General options enable certain port features and optimizations.
15364 \layout List
15365 \labelwidthstring 00.00.0000
15366
15367 -
15368 \begin_inset ERT
15369 status Collapsed
15370
15371 \layout Standard
15372
15373 \backslash
15374 /
15375 \end_inset
15376
15377 -pgen-bank Instructs the port to insert BANKSEL directives before instructions
15378  that use the Bank Select Register (BSR).
15379 \layout List
15380 \labelwidthstring 00.00.0000
15381
15382 -
15383 \begin_inset ERT
15384 status Collapsed
15385
15386 \layout Standard
15387
15388 \backslash
15389 /
15390 \end_inset
15391
15392 -pomit-config-words Instructs the port to omit the generation of the configurati
15393 on words.
15394 \layout List
15395 \labelwidthstring 00.00.0000
15396
15397 -
15398 \begin_inset ERT
15399 status Collapsed
15400
15401 \layout Standard
15402
15403 \backslash
15404 /
15405 \end_inset
15406
15407 -pomit-ivt Instructs the port to omit the generation of the interrupt vectors
15408 \layout List
15409 \labelwidthstring 00.00.0000
15410
15411 -
15412 \begin_inset ERT
15413 status Collapsed
15414
15415 \layout Standard
15416
15417 \backslash
15418 /
15419 \end_inset
15420
15421 -pleave-reset-vector Used in conjuction with the previous command, instructs
15422  the port NOT to omit the reset vector.
15423 \layout List
15424 \labelwidthstring 00.00.0000
15425
15426 -
15427 \begin_inset ERT
15428 status Collapsed
15429
15430 \layout Standard
15431
15432 \backslash
15433 /
15434 \end_inset
15435
15436 -stack-model=[model] Used in conjuction with the command above.
15437  Defines the stack model to be used, valid stack models are :
15438 \begin_deeper
15439 \layout List
15440 \labelwidthstring 00.00.0000
15441
15442
15443 \emph on
15444 small
15445 \emph default
15446  Selects small stack model.
15447  8 bit stack and frame pointers.
15448  Supports 256 bytes stack size.
15449 \layout List
15450 \labelwidthstring 00.00.0000
15451
15452
15453 \emph on
15454 large
15455 \emph default
15456  Selects large stack model.
15457  16 bit stack and frame pointers.
15458  Supports 65536 bytes stack size.
15459 \end_deeper
15460 \layout List
15461 \labelwidthstring 00.00.0000
15462
15463 -
15464 \begin_inset ERT
15465 status Collapsed
15466
15467 \layout Standard
15468
15469 \backslash
15470 /
15471 \end_inset
15472
15473 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
15474  unitialized data variables with [kword].
15475  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
15476 \layout List
15477 \labelwidthstring 00.00.0000
15478
15479 -
15480 \begin_inset ERT
15481 status Collapsed
15482
15483 \layout Standard
15484
15485 \backslash
15486 /
15487 \end_inset
15488
15489 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
15490  Useful for bootloaders.
15491 \layout List
15492 \labelwidthstring 00.00.0000
15493
15494 -
15495 \begin_inset ERT
15496 status Collapsed
15497
15498 \layout Standard
15499
15500 \backslash
15501 /
15502 \end_inset
15503
15504 -asm= sets the full path and name of an external assembler to call.
15505 \layout List
15506 \labelwidthstring 00.00.0000
15507
15508 -
15509 \begin_inset ERT
15510 status Collapsed
15511
15512 \layout Standard
15513
15514 \backslash
15515 /
15516 \end_inset
15517
15518 -link= sets the full path and name of an external linker to call.
15519 \layout Subsubsection
15520
15521 Debugging Options
15522 \layout Standard
15523
15524 Debugging options enable extra debugging information in the output files.
15525 \layout List
15526 \labelwidthstring 00.00.0000
15527
15528 -
15529 \begin_inset ERT
15530 status Collapsed
15531
15532 \layout Standard
15533
15534 \backslash
15535 /
15536 \end_inset
15537
15538 -debug-xtra Similar to -
15539 \begin_inset ERT
15540 status Collapsed
15541
15542 \layout Standard
15543
15544 \backslash
15545 /
15546 \end_inset
15547
15548 -debug
15549 \begin_inset LatexCommand \index{-\/-debug}
15550
15551 \end_inset
15552
15553 , but dumps more information.
15554 \layout List
15555 \labelwidthstring 00.00.0000
15556
15557 -
15558 \begin_inset ERT
15559 status Collapsed
15560
15561 \layout Standard
15562
15563 \backslash
15564 /
15565 \end_inset
15566
15567 -debug-ralloc Force register allocator to dump <source>.d file with debugging
15568  information.
15569  <source> is the name of the file compiled.
15570 \layout List
15571 \labelwidthstring 00.00.0000
15572
15573 -
15574 \begin_inset ERT
15575 status Collapsed
15576
15577 \layout Standard
15578
15579 \backslash
15580 /
15581 \end_inset
15582
15583 -pcode-verbose Enable pcode debugging information in translation.
15584 \layout Subsection
15585
15586 Preprocessor Macros
15587 \layout Standard
15588
15589 PIC16 port defines the following preprocessor macros while translating a
15590  source.
15591 \layout Standard
15592 \align center
15593
15594 \begin_inset  Tabular
15595 <lyxtabular version="3" rows="2" columns="2">
15596 <features>
15597 <column alignment="center" valignment="top" leftline="true" width="0">
15598 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15599 <row topline="true" bottomline="true">
15600 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15601 \begin_inset Text
15602
15603 \layout Standard
15604
15605 Macro
15606 \end_inset
15607 </cell>
15608 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15609 \begin_inset Text
15610
15611 \layout Standard
15612
15613 Description
15614 \end_inset
15615 </cell>
15616 </row>
15617 <row topline="true" bottomline="true">
15618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15619 \begin_inset Text
15620
15621 \layout Standard
15622
15623 pic18fxxxx
15624 \end_inset
15625 </cell>
15626 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15627 \begin_inset Text
15628
15629 \layout Standard
15630
15631 MCU Identification.
15632
15633 \emph on
15634 xxxx
15635 \emph default
15636  is the microcontrol identification number, i.e.
15637  452, 6620, etc
15638 \end_inset
15639 </cell>
15640 </row>
15641 </lyxtabular>
15642
15643 \end_inset
15644
15645
15646 \layout Subsection
15647
15648 Directories
15649 \layout Standard
15650
15651 PIC16
15652 \begin_inset LatexCommand \index{PIC16}
15653
15654 \end_inset
15655
15656  port uses the following directories for searching header files and libraries.
15657 \layout Standard
15658 \align center
15659
15660 \begin_inset  Tabular
15661 <lyxtabular version="3" rows="3" columns="4">
15662 <features>
15663 <column alignment="center" valignment="top" leftline="true" width="0">
15664 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15665 <column alignment="center" valignment="top" width="0">
15666 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15667 <row topline="true" bottomline="true">
15668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15669 \begin_inset Text
15670
15671 \layout Standard
15672
15673 Directory
15674 \end_inset
15675 </cell>
15676 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15677 \begin_inset Text
15678
15679 \layout Standard
15680
15681 Description
15682 \end_inset
15683 </cell>
15684 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15685 \begin_inset Text
15686
15687 \layout Standard
15688
15689 Target
15690 \end_inset
15691 </cell>
15692 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15693 \begin_inset Text
15694
15695 \layout Standard
15696
15697 Command prefix
15698 \end_inset
15699 </cell>
15700 </row>
15701 <row topline="true">
15702 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15703 \begin_inset Text
15704
15705 \layout Standard
15706
15707 PREFIX/sdcc/include/pic16
15708 \end_inset
15709 </cell>
15710 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15711 \begin_inset Text
15712
15713 \layout Standard
15714
15715 PIC16 specific headers
15716 \end_inset
15717 </cell>
15718 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15719 \begin_inset Text
15720
15721 \layout Standard
15722
15723 Compiler
15724 \end_inset
15725 </cell>
15726 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15727 \begin_inset Text
15728
15729 \layout Standard
15730
15731 -I
15732 \end_inset
15733 </cell>
15734 </row>
15735 <row topline="true" bottomline="true">
15736 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15737 \begin_inset Text
15738
15739 \layout Standard
15740
15741 PREFIX/sdcc/lib/pic16
15742 \end_inset
15743 </cell>
15744 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15745 \begin_inset Text
15746
15747 \layout Standard
15748
15749 PIC16 specific libraries
15750 \end_inset
15751 </cell>
15752 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15753 \begin_inset Text
15754
15755 \layout Standard
15756
15757 Linker
15758 \end_inset
15759 </cell>
15760 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15761 \begin_inset Text
15762
15763 \layout Standard
15764
15765 -L
15766 \end_inset
15767 </cell>
15768 </row>
15769 </lyxtabular>
15770
15771 \end_inset
15772
15773
15774 \layout Subsection
15775
15776 Pragmas
15777 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
15778
15779 \end_inset
15780
15781
15782 \layout Standard
15783
15784 PIC16 port currently supports the following pragmas:
15785 \layout List
15786 \labelwidthstring 00.00.0000
15787
15788 stack pragma stack forces the code generator to initialize the stack & frame
15789  pointers at a specific address.
15790  This is an adhoc solution since gplink does not support yet stack.
15791  When the gplink issue is resolved the pragma will be deprecated
15792 \begin_inset Foot
15793 collapsed true
15794
15795 \layout Standard
15796
15797
15798 \emph on
15799 It is important to initialize the stack, otherwise strange things can happen.
15800  Stack is not initialized by default because there are some sources that
15801  do not require it.
15802  (like library sources)
15803 \end_inset
15804
15805 .
15806 \newline
15807 The stack pragma should be used only once in a project.
15808  Multiple pragmas may result in indeterminate behaviour of the program.
15809 \layout LyX-Code
15810
15811 Example:
15812 \layout LyX-Code
15813
15814 \layout LyX-Code
15815
15816 /* initializes stack at RAM address 0x5ff */
15817 \layout LyX-Code
15818
15819 #pragma stack 0x5ff
15820 \layout List
15821 \labelwidthstring 00.00.0000
15822
15823 udata pragma udata instructs the compiler to emit code so that linker will
15824  place a variable at a specific memory bank
15825 \layout LyX-Code
15826
15827 Example:
15828 \layout LyX-Code
15829
15830 \layout LyX-Code
15831
15832 /* places variable foo at bank2 */
15833 \layout LyX-Code
15834
15835 #pragma udata bank2 foo
15836 \layout LyX-Code
15837
15838 char foo;
15839 \layout Standard
15840
15841 In order for this pragma to work there are some changes that must be made
15842  in the .lkr script used in link stage.
15843  In the following example a sample .lkr file is shown:
15844 \layout LyX-Code
15845
15846 \layout LyX-Code
15847
15848 // Sample linker script for the PIC18F452 processor
15849 \layout LyX-Code
15850
15851 LIBPATH .
15852 \layout LyX-Code
15853
15854 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
15855 \layout LyX-Code
15856
15857 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
15858 \layout LyX-Code
15859
15860 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
15861 \layout LyX-Code
15862
15863 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
15864 \layout LyX-Code
15865
15866 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
15867 \layout LyX-Code
15868
15869 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
15870 \layout LyX-Code
15871
15872 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
15873 \layout LyX-Code
15874
15875 \layout LyX-Code
15876
15877 DATABANK   NAME=gpr0       START=0x80           END=0xFF
15878 \layout LyX-Code
15879
15880 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
15881 \layout LyX-Code
15882
15883 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
15884 \layout LyX-Code
15885
15886 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
15887 \layout LyX-Code
15888
15889 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
15890 \layout LyX-Code
15891
15892 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
15893 \layout LyX-Code
15894
15895 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
15896 \layout LyX-Code
15897
15898 \layout LyX-Code
15899
15900 SECTION    NAME=CONFIG     ROM=config
15901 \layout LyX-Code
15902
15903 \layout LyX-Code
15904
15905 SECTION    NAME=bank0      RAM=gpr0
15906 \layout LyX-Code
15907
15908 SECTION    NAME=bank1      RAM=gpr1
15909 \layout LyX-Code
15910
15911 SECTION    NAME=bank2      RAM=gpr2
15912 \layout LyX-Code
15913
15914 SECTION    NAME=bank3      RAM=gpr3
15915 \layout LyX-Code
15916
15917 SECTION    NAME=bank4      RAM=gpr4
15918 \layout LyX-Code
15919
15920 SECTION    NAME=bank5      RAM=gpr5
15921 \layout Standard
15922
15923 The linker will recognise the section name set in the pragma statement and
15924  will position the variable at the memory bank set with the RAM field at
15925  the SECTION line in the linker script file.
15926 \layout Subsection
15927
15928 Header Files
15929 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
15930
15931 \end_inset
15932
15933
15934 \layout Standard
15935
15936 There is one main header file that can be included to the source files using
15937  the pic16 port.
15938  That file is the
15939 \series bold
15940 pic18fregs.h
15941 \series default
15942 .
15943  This header file contains the definitions for the processor special registers,
15944  so it is necessary if the source accesses them.
15945  It can be included by adding the following line in the beginning of the
15946  file:
15947 \layout LyX-Code
15948
15949 #include <pic18fregs.h>
15950 \layout Standard
15951
15952 The specific microcontroller is selected within the pic18fregs.h automatically,
15953  so the same source can be used with a variety of devices.
15954 \layout Subsection
15955
15956 Libraries
15957 \layout Standard
15958
15959 The libraries that PIC16
15960 \begin_inset LatexCommand \index{PIC16}
15961
15962 \end_inset
15963
15964  port depends on are the microcontroller device libraries which contain
15965  the symbol definitions for the microcontroller special function registers.
15966  These libraries have the format pic18fxxxx.lib, where
15967 \emph on
15968 xxxx
15969 \emph default
15970  is the microcontroller identification number.
15971  The specific library is selected automatically by the compiler at link
15972  stage according to the selected device.
15973 \layout Standard
15974
15975 Libraries are created with gplib which is part of the gputils package
15976 \begin_inset LatexCommand \url{http://gputils.sourceforge.net}
15977
15978 \end_inset
15979
15980 .
15981 \layout Subsection
15982
15983 Memory Models
15984 \layout Standard
15985
15986 The following memory models are supported by the PIC16 port:
15987 \layout Itemize
15988
15989 small model
15990 \layout Itemize
15991
15992 large model
15993 \layout Standard
15994
15995 Memory model affects the default size of pointers within the source.
15996  The sizes are shown in the next table:
15997 \layout Standard
15998 \align center
15999
16000 \begin_inset  Tabular
16001 <lyxtabular version="3" rows="3" columns="3">
16002 <features>
16003 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16004 <column alignment="center" valignment="top" leftline="true" width="0">
16005 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16006 <row topline="true" bottomline="true">
16007 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16008 \begin_inset Text
16009
16010 \layout Standard
16011
16012 Pointer sizes according to memory model
16013 \end_inset
16014 </cell>
16015 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16016 \begin_inset Text
16017
16018 \layout Standard
16019
16020 small model
16021 \end_inset
16022 </cell>
16023 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16024 \begin_inset Text
16025
16026 \layout Standard
16027
16028 large model
16029 \end_inset
16030 </cell>
16031 </row>
16032 <row topline="true" bottomline="true">
16033 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16034 \begin_inset Text
16035
16036 \layout Standard
16037
16038 code pointers
16039 \end_inset
16040 </cell>
16041 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16042 \begin_inset Text
16043
16044 \layout Standard
16045
16046 16-bits
16047 \end_inset
16048 </cell>
16049 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16050 \begin_inset Text
16051
16052 \layout Standard
16053
16054 24-bits
16055 \end_inset
16056 </cell>
16057 </row>
16058 <row topline="true" bottomline="true">
16059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16060 \begin_inset Text
16061
16062 \layout Standard
16063
16064 data pointers
16065 \end_inset
16066 </cell>
16067 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
16068 \begin_inset Text
16069
16070 \layout Standard
16071
16072 16-bits
16073 \end_inset
16074 </cell>
16075 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16076 \begin_inset Text
16077
16078 \layout Standard
16079
16080 16-bits
16081 \end_inset
16082 </cell>
16083 </row>
16084 </lyxtabular>
16085
16086 \end_inset
16087
16088
16089 \layout Standard
16090
16091 It is advisable that all sources within a project are compiled with the
16092  same memory model.
16093  If one wants to override the default memory model, this can be done by
16094  declaring a pointer as
16095 \series bold
16096 far
16097 \series default
16098  or
16099 \series bold
16100 near
16101 \series default
16102 .
16103  Far selects large memory model's pointers, while near selects small memory
16104  model's pointers.
16105 \layout Standard
16106
16107 The standard device libraries (see
16108 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
16109
16110 \end_inset
16111
16112 ) contain no reference to pointers, so they can be used with both memory
16113  models.
16114 \layout Subsection
16115
16116 Stack
16117 \layout Standard
16118
16119 The stack implementation for the PIC16 port uses two indirect registers,
16120  FSR1 and FSR2.
16121 \layout List
16122 \labelwidthstring 00.00.0000
16123
16124 FSR1 is assigned as stack pointer
16125 \layout List
16126 \labelwidthstring 00.00.0000
16127
16128 FSR2 is assigned as frame pointer
16129 \layout Standard
16130
16131 The following stack models are supported by the PIC16 port
16132 \layout Itemize
16133
16134 small model
16135 \layout Itemize
16136
16137 large model
16138 \layout Standard
16139
16140
16141 \noun on
16142 Small
16143 \noun default
16144  model means that only the FSRxL byte is used to access stack and frame,
16145  while
16146 \emph on
16147 \noun on
16148 large
16149 \emph default
16150 \noun default
16151  uses both FSRxL and FSRxH registers.
16152  The following table shows the stack/frame pointers sizes according to stack
16153  model and the maximum space they can address:
16154 \layout Standard
16155 \align center
16156
16157 \begin_inset  Tabular
16158 <lyxtabular version="3" rows="3" columns="3">
16159 <features>
16160 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16161 <column alignment="center" valignment="top" leftline="true" width="0">
16162 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16163 <row topline="true" bottomline="true">
16164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16165 \begin_inset Text
16166
16167 \layout Standard
16168
16169 Stack & Frame pointer sizes according to stack model
16170 \end_inset
16171 </cell>
16172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16173 \begin_inset Text
16174
16175 \layout Standard
16176
16177 small
16178 \end_inset
16179 </cell>
16180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16181 \begin_inset Text
16182
16183 \layout Standard
16184
16185 large
16186 \end_inset
16187 </cell>
16188 </row>
16189 <row topline="true">
16190 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16191 \begin_inset Text
16192
16193 \layout Standard
16194
16195 Stack pointer FSR1
16196 \end_inset
16197 </cell>
16198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16199 \begin_inset Text
16200
16201 \layout Standard
16202
16203 8-bits
16204 \end_inset
16205 </cell>
16206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16207 \begin_inset Text
16208
16209 \layout Standard
16210
16211 16-bits
16212 \end_inset
16213 </cell>
16214 </row>
16215 <row topline="true" bottomline="true">
16216 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16217 \begin_inset Text
16218
16219 \layout Standard
16220
16221 Frame pointer FSR2
16222 \end_inset
16223 </cell>
16224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16225 \begin_inset Text
16226
16227 \layout Standard
16228
16229 8-bits
16230 \end_inset
16231 </cell>
16232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16233 \begin_inset Text
16234
16235 \layout Standard
16236
16237 16-bits
16238 \end_inset
16239 </cell>
16240 </row>
16241 </lyxtabular>
16242
16243 \end_inset
16244
16245
16246 \layout Standard
16247
16248
16249 \series bold
16250 Currently stack and frame pointers should be initialized explicit by the
16251  user at the desired Data RAM position (see
16252 \begin_inset LatexCommand \ref{sub:PIC16_Pragmas}
16253
16254 \end_inset
16255
16256  Pragma stack).
16257  Uninitialized stack and frame pointers can result in unexpected behavior
16258  of the resulting binary.
16259 \layout Subsection
16260
16261 Function return values
16262 \layout Standard
16263
16264 Return values from functions are placed to the appropriate registers following
16265  a modified Microchip policy optimized for SDCC.
16266  The following table shows these registers:
16267 \layout Standard
16268 \align center
16269
16270 \begin_inset  Tabular
16271 <lyxtabular version="3" rows="6" columns="2">
16272 <features>
16273 <column alignment="center" valignment="top" leftline="true" width="0">
16274 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16275 <row topline="true" bottomline="true">
16276 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16277 \begin_inset Text
16278
16279 \layout Standard
16280
16281 size
16282 \end_inset
16283 </cell>
16284 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16285 \begin_inset Text
16286
16287 \layout Standard
16288
16289 destination register
16290 \end_inset
16291 </cell>
16292 </row>
16293 <row topline="true">
16294 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16295 \begin_inset Text
16296
16297 \layout Standard
16298
16299 8 bits
16300 \end_inset
16301 </cell>
16302 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16303 \begin_inset Text
16304
16305 \layout Standard
16306
16307 WREG
16308 \end_inset
16309 </cell>
16310 </row>
16311 <row topline="true">
16312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16313 \begin_inset Text
16314
16315 \layout Standard
16316
16317 16 bits
16318 \end_inset
16319 </cell>
16320 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16321 \begin_inset Text
16322
16323 \layout Standard
16324
16325 PRODL:WREG
16326 \end_inset
16327 </cell>
16328 </row>
16329 <row topline="true">
16330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16331 \begin_inset Text
16332
16333 \layout Standard
16334
16335 24 bits
16336 \end_inset
16337 </cell>
16338 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16339 \begin_inset Text
16340
16341 \layout Standard
16342
16343 PRODH:PRODL:WREG
16344 \end_inset
16345 </cell>
16346 </row>
16347 <row topline="true">
16348 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16349 \begin_inset Text
16350
16351 \layout Standard
16352
16353 32 bits
16354 \end_inset
16355 </cell>
16356 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16357 \begin_inset Text
16358
16359 \layout Standard
16360
16361 FSR0L:PRODH:PRODL:WREG
16362 \end_inset
16363 </cell>
16364 </row>
16365 <row topline="true" bottomline="true">
16366 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16367 \begin_inset Text
16368
16369 \layout Standard
16370
16371 >32 bits
16372 \end_inset
16373 </cell>
16374 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16375 \begin_inset Text
16376
16377 \layout Standard
16378
16379 on stack, FSR0 points to the beginning
16380 \end_inset
16381 </cell>
16382 </row>
16383 </lyxtabular>
16384
16385 \end_inset
16386
16387
16388 \layout Subsection
16389
16390 Interrupts
16391 \layout Standard
16392
16393 When entering an interrupt, currently the PIC16
16394 \begin_inset LatexCommand \index{PIC16}
16395
16396 \end_inset
16397
16398  port automatically saves the following registers:
16399 \layout Itemize
16400
16401 WREG
16402 \layout Itemize
16403
16404 STATUS
16405 \layout Itemize
16406
16407 BSR
16408 \layout Itemize
16409
16410 PROD (PRODL and PRODH)
16411 \layout Itemize
16412
16413 FSR0 (FSR0L and FSR0H)
16414 \layout Standard
16415
16416 These registers are restored upon return from the interrupt routine.
16417
16418 \layout Standard
16419
16420 When entering a high priority interrupt WREG, STATUS and BSR are not explicit
16421  saved by software.
16422  The hardware shadow registers for WREG, STATUS and BSR are used in these
16423  cases.
16424 \layout Standard
16425
16426
16427 \begin_inset Foot
16428 collapsed false
16429
16430 \layout Standard
16431
16432 NOTE that when the _naked attribute is specified for an interrupt routine,
16433  then NO registers are stored or restored.
16434 \end_inset
16435
16436 .
16437 \layout Chapter
16438
16439 Debugging with SDCDB
16440 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
16441
16442 \end_inset
16443
16444
16445 \begin_inset LatexCommand \index{sdcdb (debugger)}
16446
16447 \end_inset
16448
16449
16450 \layout Standard
16451
16452 SDCC is distributed with a source level debugger
16453 \begin_inset LatexCommand \index{Debugger}
16454
16455 \end_inset
16456
16457 .
16458  The debugger uses a command line interface, the command repertoire of the
16459  debugger has been kept as close to gdb
16460 \begin_inset LatexCommand \index{gdb}
16461
16462 \end_inset
16463
16464  (the GNU debugger) as possible.
16465  The configuration and build process is part of the standard compiler installati
16466 on, which also builds and installs the debugger in the target directory
16467  specified during configuration.
16468  The debugger allows you debug BOTH at the C source and at the ASM source
16469  level.
16470  Sdcdb is available on Unix platforms only.
16471 \layout Section
16472
16473 Compiling for Debugging
16474 \layout Standard
16475
16476 The -
16477 \begin_inset ERT
16478 status Collapsed
16479
16480 \layout Standard
16481
16482 \backslash
16483 /
16484 \end_inset
16485
16486 -debug
16487 \begin_inset LatexCommand \index{-\/-debug}
16488
16489 \end_inset
16490
16491  option must be specified for all files for which debug information is to
16492  be generated.
16493  The complier generates a .adb file for each of these files.
16494  The linker creates the .cdb
16495 \begin_inset LatexCommand \index{<file>.cdb}
16496
16497 \end_inset
16498
16499  file from the .adb
16500 \begin_inset LatexCommand \index{<file>.adb}
16501
16502 \end_inset
16503
16504  files and the address information.
16505  This .cdb is used by the debugger.
16506 \layout Section
16507
16508 How the Debugger Works
16509 \layout Standard
16510
16511 When the -
16512 \begin_inset ERT
16513 status Collapsed
16514
16515 \layout Standard
16516
16517 \backslash
16518 /
16519 \end_inset
16520
16521 -debug option is specified the compiler generates extra symbol information
16522  some of which are put into the assembler source and some are put into the
16523  .adb file.
16524   Then the linker creates the .cdb file from the individual .adb files with
16525  the address information for the symbols.
16526  The debugger reads the symbolic information generated by the compiler &
16527  the address information generated by the linker.
16528  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
16529  execution is controlled by the debugger.
16530  When a command is issued for the debugger, it translates it into appropriate
16531  commands for the simulator.
16532 \layout Section
16533
16534 Starting the Debugger
16535 \layout Standard
16536
16537 The debugger can be started using the following command line.
16538  (Assume the file you are debugging has the file name foo).
16539 \newline
16540
16541 \newline
16542
16543 \family sans
16544 \series bold
16545 sdcdb foo
16546 \newline
16547
16548 \family default
16549 \series default
16550
16551 \newline
16552 The debugger will look for the following files.
16553 \layout Itemize
16554
16555 foo.c - the source file.
16556 \layout Itemize
16557
16558 foo.cdb - the debugger symbol information file.
16559 \layout Itemize
16560
16561 foo.ihx - the Intel hex format
16562 \begin_inset LatexCommand \index{Intel hex format}
16563
16564 \end_inset
16565
16566  object file.
16567 \layout Section
16568
16569 Command Line Options.
16570 \layout Itemize
16571
16572 -
16573 \begin_inset ERT
16574 status Collapsed
16575
16576 \layout Standard
16577
16578 \backslash
16579 /
16580 \end_inset
16581
16582 -directory=<source file directory> this option can used to specify the directory
16583  search list.
16584  The debugger will look into the directory list specified for source, cdb
16585  & ihx files.
16586  The items in the directory list must be separated by ':', e.g.
16587  if the source files can be in the directories /home/src1 and /home/src2,
16588  the -
16589 \begin_inset ERT
16590 status Collapsed
16591
16592 \layout Standard
16593
16594 \backslash
16595 /
16596 \end_inset
16597
16598 -directory option should be -
16599 \begin_inset ERT
16600 status Collapsed
16601
16602 \layout Standard
16603
16604 \backslash
16605 /
16606 \end_inset
16607
16608 -directory=/home/src1:/home/src2.
16609  Note there can be no spaces in the option.
16610
16611 \layout Itemize
16612
16613 -cd <directory> - change to the <directory>.
16614 \layout Itemize
16615
16616 -fullname - used by GUI front ends.
16617 \layout Itemize
16618
16619 -cpu <cpu-type> - this argument is passed to the simulator please see the
16620  simulator docs for details.
16621 \layout Itemize
16622
16623 -X <Clock frequency > this options is passed to the simulator please see
16624  the simulator docs for details.
16625 \layout Itemize
16626
16627 -s <serial port file> passed to simulator see the simulator docs for details.
16628 \layout Itemize
16629
16630 -S <serial in,out> passed to simulator see the simulator docs for details.
16631 \layout Itemize
16632
16633 -k <port number> passed to simulator see the simulator docs for details.
16634 \layout Section
16635
16636 Debugger Commands.
16637 \layout Standard
16638
16639 As mentioned earlier the command interface for the debugger has been deliberatel
16640 y kept as close the GNU debugger gdb, as possible.
16641  This will help the integration with existing graphical user interfaces
16642  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
16643  If you use a graphical user interface for the debugger you can skip the
16644  next sections.
16645 \layout Subsubsection*
16646
16647 break [line | file:line | function | file:function]
16648 \layout Standard
16649
16650 Set breakpoint at specified line or function:
16651 \newline
16652
16653 \newline
16654
16655 \family sans
16656 \series bold
16657 sdcdb>break 100
16658 \newline
16659 sdcdb>break foo.c:100
16660 \newline
16661 sdcdb>break funcfoo
16662 \newline
16663 sdcdb>break foo.c:funcfoo
16664 \layout Subsubsection*
16665
16666 clear [line | file:line | function | file:function ]
16667 \layout Standard
16668
16669 Clear breakpoint at specified line or function:
16670 \newline
16671
16672 \newline
16673
16674 \family sans
16675 \series bold
16676 sdcdb>clear 100
16677 \newline
16678 sdcdb>clear foo.c:100
16679 \newline
16680 sdcdb>clear funcfoo
16681 \newline
16682 sdcdb>clear foo.c:funcfoo
16683 \layout Subsubsection*
16684
16685 continue
16686 \layout Standard
16687
16688 Continue program being debugged, after breakpoint.
16689 \layout Subsubsection*
16690
16691 finish
16692 \layout Standard
16693
16694 Execute till the end of the current function.
16695 \layout Subsubsection*
16696
16697 delete [n]
16698 \layout Standard
16699
16700 Delete breakpoint number 'n'.
16701  If used without any option clear ALL user defined break points.
16702 \layout Subsubsection*
16703
16704 info [break | stack | frame | registers ]
16705 \layout Itemize
16706
16707 info break - list all breakpoints
16708 \layout Itemize
16709
16710 info stack - show the function call stack.
16711 \layout Itemize
16712
16713 info frame - show information about the current execution frame.
16714 \layout Itemize
16715
16716 info registers - show content of all registers.
16717 \layout Subsubsection*
16718
16719 step
16720 \layout Standard
16721
16722 Step program until it reaches a different source line.
16723  Note: pressing <return> repeats the last command.
16724 \layout Subsubsection*
16725
16726 next
16727 \layout Standard
16728
16729 Step program, proceeding through subroutine calls.
16730 \layout Subsubsection*
16731
16732 run
16733 \layout Standard
16734
16735 Start debugged program.
16736 \layout Subsubsection*
16737
16738 ptype variable
16739 \layout Standard
16740
16741 Print type information of the variable.
16742 \layout Subsubsection*
16743
16744 print variable
16745 \layout Standard
16746
16747 print value of variable.
16748 \layout Subsubsection*
16749
16750 file filename
16751 \layout Standard
16752
16753 load the given file name.
16754  Note this is an alternate method of loading file for debugging.
16755 \layout Subsubsection*
16756
16757 frame
16758 \layout Standard
16759
16760 print information about current frame.
16761 \layout Subsubsection*
16762
16763 set srcmode
16764 \layout Standard
16765
16766 Toggle between C source & assembly source.
16767 \layout Subsubsection*
16768
16769 ! simulator command
16770 \layout Standard
16771
16772 Send the string following '!' to the simulator, the simulator response is
16773  displayed.
16774  Note the debugger does not interpret the command being sent to the simulator,
16775  so if a command like 'go' is sent the debugger can loose its execution
16776  context and may display incorrect values.
16777 \layout Subsubsection*
16778
16779 quit
16780 \layout Standard
16781
16782 "Watch me now.
16783  Iam going Down.
16784  My name is Bobby Brown"
16785 \layout Section
16786
16787 Interfacing with XEmacs
16788 \begin_inset LatexCommand \index{XEmacs}
16789
16790 \end_inset
16791
16792
16793 \begin_inset LatexCommand \index{Emacs}
16794
16795 \end_inset
16796
16797 .
16798 \layout Standard
16799
16800 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
16801  sdcdb.el and sdcdbsrc.el.
16802  These two files can be found in the $(prefix)/bin directory after the installat
16803 ion is complete.
16804  These files need to be loaded into XEmacs for the interface to work.
16805  This can be done at XEmacs startup time by inserting the following into
16806  your '.xemacs' file (which can be found in your HOME directory):
16807 \newline
16808
16809 \newline
16810
16811 \family typewriter
16812 (load-file sdcdbsrc.el)
16813 \family default
16814
16815 \newline
16816
16817 \newline
16818 .xemacs is a lisp file so the () around the command is REQUIRED.
16819  The files can also be loaded dynamically while XEmacs is running, set the
16820  environment variable 'EMACSLOADPATH' to the installation bin directory
16821  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
16822  To start the interface enter the following command:
16823 \newline
16824
16825 \newline
16826
16827 \family sans
16828 \series bold
16829 ESC-x sdcdbsrc
16830 \family default
16831 \series default
16832
16833 \newline
16834
16835 \newline
16836 You will prompted to enter the file name to be debugged.
16837
16838 \newline
16839
16840 \newline
16841 The command line options that are passed to the simulator directly are bound
16842  to default values in the file sdcdbsrc.el.
16843  The variables are listed below, these values maybe changed as required.
16844 \layout Itemize
16845
16846 sdcdbsrc-cpu-type '51
16847 \layout Itemize
16848
16849 sdcdbsrc-frequency '11059200
16850 \layout Itemize
16851
16852 sdcdbsrc-serial nil
16853 \layout Standard
16854
16855 The following is a list of key mapping for the debugger interface.
16856 \layout Standard
16857
16858 \SpecialChar ~
16859
16860 \family typewriter
16861
16862 \newline
16863 ;;\SpecialChar ~
16864 Current Listing ::
16865 \newline
16866 ;;key\SpecialChar ~
16867 \SpecialChar ~
16868 \SpecialChar ~
16869 \SpecialChar ~
16870 \SpecialChar ~
16871 \SpecialChar ~
16872 \SpecialChar ~
16873 \SpecialChar ~
16874 \SpecialChar ~
16875 \SpecialChar ~
16876 \SpecialChar ~
16877 \SpecialChar ~
16878 \SpecialChar ~
16879 \SpecialChar ~
16880 binding\SpecialChar ~
16881 \SpecialChar ~
16882 \SpecialChar ~
16883 \SpecialChar ~
16884 \SpecialChar ~
16885 \SpecialChar ~
16886 \SpecialChar ~
16887 \SpecialChar ~
16888 \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 Comment
16903 \newline
16904 ;;---\SpecialChar ~
16905 \SpecialChar ~
16906 \SpecialChar ~
16907 \SpecialChar ~
16908 \SpecialChar ~
16909 \SpecialChar ~
16910 \SpecialChar ~
16911 \SpecialChar ~
16912 \SpecialChar ~
16913 \SpecialChar ~
16914 \SpecialChar ~
16915 \SpecialChar ~
16916 \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 \SpecialChar ~
16932 \SpecialChar ~
16933 \SpecialChar ~
16934 \SpecialChar ~
16935 \SpecialChar ~
16936 \SpecialChar ~
16937 \SpecialChar ~
16938 \SpecialChar ~
16939 \SpecialChar ~
16940 -------
16941 \newline
16942 ;;
16943 \newline
16944 ;;\SpecialChar ~
16945 n\SpecialChar ~
16946 \SpecialChar ~
16947 \SpecialChar ~
16948 \SpecialChar ~
16949 \SpecialChar ~
16950 \SpecialChar ~
16951 \SpecialChar ~
16952 \SpecialChar ~
16953 \SpecialChar ~
16954 \SpecialChar ~
16955 \SpecialChar ~
16956 \SpecialChar ~
16957 \SpecialChar ~
16958 \SpecialChar ~
16959 \SpecialChar ~
16960 sdcdb-next-from-src\SpecialChar ~
16961 \SpecialChar ~
16962 \SpecialChar ~
16963 \SpecialChar ~
16964 \SpecialChar ~
16965 \SpecialChar ~
16966 \SpecialChar ~
16967 \SpecialChar ~
16968 \SpecialChar ~
16969 \SpecialChar ~
16970 SDCDB next command
16971 \newline
16972 ;;\SpecialChar ~
16973 b\SpecialChar ~
16974 \SpecialChar ~
16975 \SpecialChar ~
16976 \SpecialChar ~
16977 \SpecialChar ~
16978 \SpecialChar ~
16979 \SpecialChar ~
16980 \SpecialChar ~
16981 \SpecialChar ~
16982 \SpecialChar ~
16983 \SpecialChar ~
16984 \SpecialChar ~
16985 \SpecialChar ~
16986 \SpecialChar ~
16987 \SpecialChar ~
16988 sdcdb-back-from-src\SpecialChar ~
16989 \SpecialChar ~
16990 \SpecialChar ~
16991 \SpecialChar ~
16992 \SpecialChar ~
16993 \SpecialChar ~
16994 \SpecialChar ~
16995 \SpecialChar ~
16996 \SpecialChar ~
16997 \SpecialChar ~
16998 SDCDB back command
16999 \newline
17000 ;;\SpecialChar ~
17001 c\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 sdcdb-cont-from-src\SpecialChar ~
17017 \SpecialChar ~
17018 \SpecialChar ~
17019 \SpecialChar ~
17020 \SpecialChar ~
17021 \SpecialChar ~
17022 \SpecialChar ~
17023 \SpecialChar ~
17024 \SpecialChar ~
17025 \SpecialChar ~
17026 SDCDB continue command
17027 \newline
17028 ;;\SpecialChar ~
17029 s\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 sdcdb-step-from-src\SpecialChar ~
17045 \SpecialChar ~
17046 \SpecialChar ~
17047 \SpecialChar ~
17048 \SpecialChar ~
17049 \SpecialChar ~
17050 \SpecialChar ~
17051 \SpecialChar ~
17052 \SpecialChar ~
17053 \SpecialChar ~
17054 SDCDB step command
17055 \newline
17056 ;;\SpecialChar ~
17057 ?\SpecialChar ~
17058 \SpecialChar ~
17059 \SpecialChar ~
17060 \SpecialChar ~
17061 \SpecialChar ~
17062 \SpecialChar ~
17063 \SpecialChar ~
17064 \SpecialChar ~
17065 \SpecialChar ~
17066 \SpecialChar ~
17067 \SpecialChar ~
17068 \SpecialChar ~
17069 \SpecialChar ~
17070 \SpecialChar ~
17071 \SpecialChar ~
17072 sdcdb-whatis-c-sexp\SpecialChar ~
17073 \SpecialChar ~
17074 \SpecialChar ~
17075 \SpecialChar ~
17076 \SpecialChar ~
17077 \SpecialChar ~
17078 \SpecialChar ~
17079 \SpecialChar ~
17080 \SpecialChar ~
17081 \SpecialChar ~
17082 SDCDB ptypecommand for data at
17083 \newline
17084 ;;\SpecialChar ~
17085 \SpecialChar ~
17086 \SpecialChar ~
17087 \SpecialChar ~
17088 \SpecialChar ~
17089 \SpecialChar ~
17090 \SpecialChar ~
17091 \SpecialChar ~
17092 \SpecialChar ~
17093 \SpecialChar ~
17094 \SpecialChar ~
17095 \SpecialChar ~
17096 \SpecialChar ~
17097 \SpecialChar ~
17098 \SpecialChar ~
17099 \SpecialChar ~
17100 \SpecialChar ~
17101 \SpecialChar ~
17102 \SpecialChar ~
17103 \SpecialChar ~
17104 \SpecialChar ~
17105 \SpecialChar ~
17106 \SpecialChar ~
17107 \SpecialChar ~
17108 \SpecialChar ~
17109 \SpecialChar ~
17110 \SpecialChar ~
17111 \SpecialChar ~
17112 \SpecialChar ~
17113 \SpecialChar ~
17114 \SpecialChar ~
17115 \SpecialChar ~
17116 \SpecialChar ~
17117 \SpecialChar ~
17118 \SpecialChar ~
17119 \SpecialChar ~
17120 \SpecialChar ~
17121 \SpecialChar ~
17122 \SpecialChar ~
17123 \SpecialChar ~
17124 \SpecialChar ~
17125 \SpecialChar ~
17126 \SpecialChar ~
17127 \SpecialChar ~
17128 \SpecialChar ~
17129 \SpecialChar ~
17130 \SpecialChar ~
17131 buffer point
17132 \newline
17133 ;;\SpecialChar ~
17134 x\SpecialChar ~
17135 \SpecialChar ~
17136 \SpecialChar ~
17137 \SpecialChar ~
17138 \SpecialChar ~
17139 \SpecialChar ~
17140 \SpecialChar ~
17141 \SpecialChar ~
17142 \SpecialChar ~
17143 \SpecialChar ~
17144 \SpecialChar ~
17145 \SpecialChar ~
17146 \SpecialChar ~
17147 \SpecialChar ~
17148 \SpecialChar ~
17149 sdcdbsrc-delete\SpecialChar ~
17150 \SpecialChar ~
17151 \SpecialChar ~
17152 \SpecialChar ~
17153 \SpecialChar ~
17154 \SpecialChar ~
17155 \SpecialChar ~
17156 \SpecialChar ~
17157 \SpecialChar ~
17158 \SpecialChar ~
17159 \SpecialChar ~
17160 \SpecialChar ~
17161 \SpecialChar ~
17162 \SpecialChar ~
17163 SDCDB Delete all breakpoints if no arg
17164 \newline
17165 ;;\SpecialChar ~
17166 \SpecialChar ~
17167 \SpecialChar ~
17168 \SpecialChar ~
17169 \SpecialChar ~
17170 \SpecialChar ~
17171 \SpecialChar ~
17172 \SpecialChar ~
17173 \SpecialChar ~
17174 \SpecialChar ~
17175 \SpecialChar ~
17176 \SpecialChar ~
17177 \SpecialChar ~
17178 \SpecialChar ~
17179 \SpecialChar ~
17180 \SpecialChar ~
17181 \SpecialChar ~
17182 \SpecialChar ~
17183 \SpecialChar ~
17184 \SpecialChar ~
17185 \SpecialChar ~
17186 \SpecialChar ~
17187 \SpecialChar ~
17188 \SpecialChar ~
17189 \SpecialChar ~
17190 \SpecialChar ~
17191 \SpecialChar ~
17192 \SpecialChar ~
17193 \SpecialChar ~
17194 \SpecialChar ~
17195 \SpecialChar ~
17196 \SpecialChar ~
17197 \SpecialChar ~
17198 \SpecialChar ~
17199 \SpecialChar ~
17200 \SpecialChar ~
17201 \SpecialChar ~
17202 \SpecialChar ~
17203 \SpecialChar ~
17204 \SpecialChar ~
17205 \SpecialChar ~
17206 \SpecialChar ~
17207 \SpecialChar ~
17208 \SpecialChar ~
17209 \SpecialChar ~
17210 \SpecialChar ~
17211 \SpecialChar ~
17212 given or delete arg (C-u arg x)
17213 \newline
17214 ;;\SpecialChar ~
17215 m\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 sdcdbsrc-frame\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 SDCDB Display current frame if no arg,
17246 \newline
17247 ;;\SpecialChar ~
17248 \SpecialChar ~
17249 \SpecialChar ~
17250 \SpecialChar ~
17251 \SpecialChar ~
17252 \SpecialChar ~
17253 \SpecialChar ~
17254 \SpecialChar ~
17255 \SpecialChar ~
17256 \SpecialChar ~
17257 \SpecialChar ~
17258 \SpecialChar ~
17259 \SpecialChar ~
17260 \SpecialChar ~
17261 \SpecialChar ~
17262 \SpecialChar ~
17263 \SpecialChar ~
17264 \SpecialChar ~
17265 \SpecialChar ~
17266 \SpecialChar ~
17267 \SpecialChar ~
17268 \SpecialChar ~
17269 \SpecialChar ~
17270 \SpecialChar ~
17271 \SpecialChar ~
17272 \SpecialChar ~
17273 \SpecialChar ~
17274 \SpecialChar ~
17275 \SpecialChar ~
17276 \SpecialChar ~
17277 \SpecialChar ~
17278 \SpecialChar ~
17279 \SpecialChar ~
17280 \SpecialChar ~
17281 \SpecialChar ~
17282 \SpecialChar ~
17283 \SpecialChar ~
17284 \SpecialChar ~
17285 \SpecialChar ~
17286 \SpecialChar ~
17287 \SpecialChar ~
17288 \SpecialChar ~
17289 \SpecialChar ~
17290 \SpecialChar ~
17291 \SpecialChar ~
17292 \SpecialChar ~
17293 \SpecialChar ~
17294 given or display frame arg
17295 \newline
17296 ;;\SpecialChar ~
17297 \SpecialChar ~
17298 \SpecialChar ~
17299 \SpecialChar ~
17300 \SpecialChar ~
17301 \SpecialChar ~
17302 \SpecialChar ~
17303 \SpecialChar ~
17304 \SpecialChar ~
17305 \SpecialChar ~
17306 \SpecialChar ~
17307 \SpecialChar ~
17308 \SpecialChar ~
17309 \SpecialChar ~
17310 \SpecialChar ~
17311 \SpecialChar ~
17312 \SpecialChar ~
17313 \SpecialChar ~
17314 \SpecialChar ~
17315 \SpecialChar ~
17316 \SpecialChar ~
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 buffer point
17344 \newline
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 sdcdbsrc-goto-sdcdb\SpecialChar ~
17362 \SpecialChar ~
17363 \SpecialChar ~
17364 \SpecialChar ~
17365 \SpecialChar ~
17366 \SpecialChar ~
17367 \SpecialChar ~
17368 \SpecialChar ~
17369 \SpecialChar ~
17370 \SpecialChar ~
17371 Goto the SDCDB output buffer
17372 \newline
17373 ;;\SpecialChar ~
17374 p\SpecialChar ~
17375 \SpecialChar ~
17376 \SpecialChar ~
17377 \SpecialChar ~
17378 \SpecialChar ~
17379 \SpecialChar ~
17380 \SpecialChar ~
17381 \SpecialChar ~
17382 \SpecialChar ~
17383 \SpecialChar ~
17384 \SpecialChar ~
17385 \SpecialChar ~
17386 \SpecialChar ~
17387 \SpecialChar ~
17388 \SpecialChar ~
17389 sdcdb-print-c-sexp\SpecialChar ~
17390 \SpecialChar ~
17391 \SpecialChar ~
17392 \SpecialChar ~
17393 \SpecialChar ~
17394 \SpecialChar ~
17395 \SpecialChar ~
17396 \SpecialChar ~
17397 \SpecialChar ~
17398 \SpecialChar ~
17399 \SpecialChar ~
17400 SDCDB print command for data at
17401 \newline
17402 ;;\SpecialChar ~
17403 \SpecialChar ~
17404 \SpecialChar ~
17405 \SpecialChar ~
17406 \SpecialChar ~
17407 \SpecialChar ~
17408 \SpecialChar ~
17409 \SpecialChar ~
17410 \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 \SpecialChar ~
17427 \SpecialChar ~
17428 \SpecialChar ~
17429 \SpecialChar ~
17430 \SpecialChar ~
17431 \SpecialChar ~
17432 \SpecialChar ~
17433 \SpecialChar ~
17434 \SpecialChar ~
17435 \SpecialChar ~
17436 \SpecialChar ~
17437 \SpecialChar ~
17438 \SpecialChar ~
17439 \SpecialChar ~
17440 \SpecialChar ~
17441 \SpecialChar ~
17442 \SpecialChar ~
17443 \SpecialChar ~
17444 \SpecialChar ~
17445 \SpecialChar ~
17446 \SpecialChar ~
17447 \SpecialChar ~
17448 \SpecialChar ~
17449 buffer point
17450 \newline
17451 ;;\SpecialChar ~
17452 g\SpecialChar ~
17453 \SpecialChar ~
17454 \SpecialChar ~
17455 \SpecialChar ~
17456 \SpecialChar ~
17457 \SpecialChar ~
17458 \SpecialChar ~
17459 \SpecialChar ~
17460 \SpecialChar ~
17461 \SpecialChar ~
17462 \SpecialChar ~
17463 \SpecialChar ~
17464 \SpecialChar ~
17465 \SpecialChar ~
17466 \SpecialChar ~
17467 sdcdbsrc-goto-sdcdb\SpecialChar ~
17468 \SpecialChar ~
17469 \SpecialChar ~
17470 \SpecialChar ~
17471 \SpecialChar ~
17472 \SpecialChar ~
17473 \SpecialChar ~
17474 \SpecialChar ~
17475 \SpecialChar ~
17476 \SpecialChar ~
17477 Goto the SDCDB output buffer
17478 \newline
17479 ;;\SpecialChar ~
17480 t\SpecialChar ~
17481 \SpecialChar ~
17482 \SpecialChar ~
17483 \SpecialChar ~
17484 \SpecialChar ~
17485 \SpecialChar ~
17486 \SpecialChar ~
17487 \SpecialChar ~
17488 \SpecialChar ~
17489 \SpecialChar ~
17490 \SpecialChar ~
17491 \SpecialChar ~
17492 \SpecialChar ~
17493 \SpecialChar ~
17494 \SpecialChar ~
17495 sdcdbsrc-mode\SpecialChar ~
17496 \SpecialChar ~
17497 \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 Toggles Sdcdbsrc mode (turns it off)
17512 \newline
17513 ;;
17514 \newline
17515 ;;\SpecialChar ~
17516 C-c\SpecialChar ~
17517 C-f\SpecialChar ~
17518 \SpecialChar ~
17519 \SpecialChar ~
17520 \SpecialChar ~
17521 \SpecialChar ~
17522 \SpecialChar ~
17523 \SpecialChar ~
17524 \SpecialChar ~
17525 \SpecialChar ~
17526 sdcdb-finish-from-src\SpecialChar ~
17527 \SpecialChar ~
17528 \SpecialChar ~
17529 \SpecialChar ~
17530 \SpecialChar ~
17531 \SpecialChar ~
17532 \SpecialChar ~
17533 \SpecialChar ~
17534 SDCDB finish command
17535 \newline
17536 ;;
17537 \newline
17538 ;;\SpecialChar ~
17539 C-x\SpecialChar ~
17540 SPC\SpecialChar ~
17541 \SpecialChar ~
17542 \SpecialChar ~
17543 \SpecialChar ~
17544 \SpecialChar ~
17545 \SpecialChar ~
17546 \SpecialChar ~
17547 \SpecialChar ~
17548 \SpecialChar ~
17549 sdcdb-break\SpecialChar ~
17550 \SpecialChar ~
17551 \SpecialChar ~
17552 \SpecialChar ~
17553 \SpecialChar ~
17554 \SpecialChar ~
17555 \SpecialChar ~
17556 \SpecialChar ~
17557 \SpecialChar ~
17558 \SpecialChar ~
17559 \SpecialChar ~
17560 \SpecialChar ~
17561 \SpecialChar ~
17562 \SpecialChar ~
17563 \SpecialChar ~
17564 \SpecialChar ~
17565 \SpecialChar ~
17566 \SpecialChar ~
17567 Set break for line with point
17568 \newline
17569 ;;\SpecialChar ~
17570 ESC\SpecialChar ~
17571 t\SpecialChar ~
17572 \SpecialChar ~
17573 \SpecialChar ~
17574 \SpecialChar ~
17575 \SpecialChar ~
17576 \SpecialChar ~
17577 \SpecialChar ~
17578 \SpecialChar ~
17579 \SpecialChar ~
17580 \SpecialChar ~
17581 \SpecialChar ~
17582 sdcdbsrc-mode\SpecialChar ~
17583 \SpecialChar ~
17584 \SpecialChar ~
17585 \SpecialChar ~
17586 \SpecialChar ~
17587 \SpecialChar ~
17588 \SpecialChar ~
17589 \SpecialChar ~
17590 \SpecialChar ~
17591 \SpecialChar ~
17592 \SpecialChar ~
17593 \SpecialChar ~
17594 \SpecialChar ~
17595 \SpecialChar ~
17596 \SpecialChar ~
17597 \SpecialChar ~
17598 Toggle Sdcdbsrc mode
17599 \newline
17600 ;;\SpecialChar ~
17601 ESC\SpecialChar ~
17602 m\SpecialChar ~
17603 \SpecialChar ~
17604 \SpecialChar ~
17605 \SpecialChar ~
17606 \SpecialChar ~
17607 \SpecialChar ~
17608 \SpecialChar ~
17609 \SpecialChar ~
17610 \SpecialChar ~
17611 \SpecialChar ~
17612 \SpecialChar ~
17613 sdcdbsrc-srcmode\SpecialChar ~
17614 \SpecialChar ~
17615 \SpecialChar ~
17616 \SpecialChar ~
17617 \SpecialChar ~
17618 \SpecialChar ~
17619 \SpecialChar ~
17620 \SpecialChar ~
17621 \SpecialChar ~
17622 \SpecialChar ~
17623 \SpecialChar ~
17624 \SpecialChar ~
17625 \SpecialChar ~
17626 Toggle list mode
17627 \newline
17628 ;;
17629 \newline
17630
17631 \layout Chapter
17632 \pagebreak_top
17633 TIPS
17634 \layout Standard
17635
17636 Here are a few guidelines that will help the compiler generate more efficient
17637  code, some of the tips are specific to this compiler others are generally
17638  good programming practice.
17639 \layout Itemize
17640
17641 Use the smallest data type to represent your data-value.
17642  If it is known in advance that the value is going to be less than 256 then
17643  use an 'unsigned char' instead of a 'short' or 'int'.
17644  Please note, that ANSI C requires both signed and unsigned chars to be
17645  promoted to 'signed int' before doing any operation.
17646  This promotion can be omitted, if the result is the same.
17647  The effect of the promotion rules together with the sign-extension is often
17648  surprising:
17649 \begin_deeper
17650 \layout Verse
17651
17652
17653 \family typewriter
17654 unsigned char uc = 0xfe;
17655 \newline
17656 if (uc * uc < 0) /* this is true! */
17657 \newline
17658 {
17659 \newline
17660 \SpecialChar ~
17661 \SpecialChar ~
17662 \SpecialChar ~
17663 \SpecialChar ~
17664 ....
17665 \newline
17666 }
17667 \layout Standard
17668
17669
17670 \family typewriter
17671 uc * uc
17672 \family default
17673  is evaluated as
17674 \family typewriter
17675 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
17676 \family default
17677 .
17678
17679 \newline
17680 Another one:
17681 \layout Verse
17682
17683
17684 \family typewriter
17685 (unsigned char) -12 / (signed char) -3 = ...
17686 \layout Standard
17687
17688 No, the result is not 4:
17689 \layout Verse
17690
17691
17692 \family typewriter
17693 (int) (unsigned char) -12 / (int) (signed char) -3 =
17694 \newline
17695 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
17696 \newline
17697 (int) 0x00f4 / (int) 0xfffd =
17698 \newline
17699 (int) 0x00f4 / (int) 0xfffd =
17700 \newline
17701 (int) 244 / (int) -3 =
17702 \newline
17703 (int) -81 = (int) 0xffaf;
17704 \layout Standard
17705
17706 Don't complain, that gcc gives you a different result.
17707  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
17708  Therefore the results are different.
17709 \newline
17710 From
17711 \begin_inset Quotes sld
17712 \end_inset
17713
17714 comp.lang.c FAQ
17715 \begin_inset Quotes srd
17716 \end_inset
17717
17718 :
17719 \layout Quote
17720
17721 If well-defined overflow characteristics are important and negative values
17722  are not, or if you want to steer clear of sign-extension problems when
17723  manipulating bits or bytes, use one of the corresponding unsigned types.
17724  (Beware when mixing signed and unsigned values in expressions, though.)
17725 \newline
17726 Although character types (especially unsigned char) can be used as "tiny"
17727  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
17728 ble sign extension and increased code size.
17729 \end_deeper
17730 \layout Itemize
17731
17732 Use unsigned when it is known in advance that the value is not going to
17733  be negative.
17734  This helps especially if you are doing division or multiplication, bit-shifting
17735  or are using an array index.
17736 \layout Itemize
17737
17738 NEVER jump into a LOOP.
17739 \layout Itemize
17740
17741 Declare the variables to be local
17742 \begin_inset LatexCommand \index{local variables}
17743
17744 \end_inset
17745
17746  whenever possible, especially loop control variables (induction).
17747 \layout Itemize
17748
17749 Since the compiler does not always do implicit integral promotion, the programme
17750 r should do an explicit cast when integral promotion is required.
17751 \layout Itemize
17752
17753 Reducing the size of division, multiplication & modulus operations can reduce
17754  code size substantially.
17755  Take the following code for example.
17756 \begin_deeper
17757 \layout Verse
17758
17759
17760 \family typewriter
17761 foobar(unsigned int p1, unsigned char ch)
17762 \newline
17763 {
17764 \newline
17765 \SpecialChar ~
17766 \SpecialChar ~
17767 \SpecialChar ~
17768 \SpecialChar ~
17769 unsigned char ch1 = p1 % ch ;
17770 \newline
17771 \SpecialChar ~
17772 \SpecialChar ~
17773 \SpecialChar ~
17774 \SpecialChar ~
17775 ....
17776 \newline
17777 }
17778 \layout Standard
17779
17780 For the modulus operation the variable ch will be promoted to unsigned int
17781  first then the modulus operation will be performed (this will lead to a
17782  call to support routine _moduint()), and the result will be casted to a
17783  char.
17784  If the code is changed to
17785 \layout Verse
17786
17787
17788 \family typewriter
17789 foobar(unsigned int p1, unsigned char ch)
17790 \newline
17791 {
17792 \newline
17793 \SpecialChar ~
17794 \SpecialChar ~
17795 \SpecialChar ~
17796 \SpecialChar ~
17797 unsigned char ch1 = (unsigned char)p1 % ch ;
17798 \newline
17799 \SpecialChar ~
17800 \SpecialChar ~
17801 \SpecialChar ~
17802 \SpecialChar ~
17803 ....
17804 \newline
17805 }
17806 \layout Standard
17807
17808 It would substantially reduce the code generated (future versions of the
17809  compiler will be smart enough to detect such optimization opportunities).
17810 \end_deeper
17811 \layout Itemize
17812
17813 Have a look at the assembly listing to get a
17814 \begin_inset Quotes sld
17815 \end_inset
17816
17817 feeling
17818 \begin_inset Quotes srd
17819 \end_inset
17820
17821  for the code generation.
17822 \layout Section
17823
17824 Tools
17825 \begin_inset LatexCommand \index{Tools}
17826
17827 \end_inset
17828
17829  included in the distribution
17830 \layout Standard
17831 \align center
17832
17833 \begin_inset  Tabular
17834 <lyxtabular version="3" rows="12" columns="3">
17835 <features>
17836 <column alignment="center" valignment="top" leftline="true" width="0pt">
17837 <column alignment="center" valignment="top" leftline="true" width="0pt">
17838 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
17839 <row topline="true" bottomline="true">
17840 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17841 \begin_inset Text
17842
17843 \layout Standard
17844
17845 Name
17846 \end_inset
17847 </cell>
17848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17849 \begin_inset Text
17850
17851 \layout Standard
17852
17853 Purpose
17854 \end_inset
17855 </cell>
17856 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17857 \begin_inset Text
17858
17859 \layout Standard
17860
17861 Directory
17862 \end_inset
17863 </cell>
17864 </row>
17865 <row topline="true">
17866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17867 \begin_inset Text
17868
17869 \layout Standard
17870
17871 uCsim
17872 \end_inset
17873 </cell>
17874 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17875 \begin_inset Text
17876
17877 \layout Standard
17878
17879 Simulator for various architectures
17880 \end_inset
17881 </cell>
17882 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17883 \begin_inset Text
17884
17885 \layout Standard
17886
17887 sdcc/sim/ucsim
17888 \end_inset
17889 </cell>
17890 </row>
17891 <row topline="true">
17892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17893 \begin_inset Text
17894
17895 \layout Standard
17896
17897 keil2sdcc.pl
17898 \end_inset
17899 </cell>
17900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17901 \begin_inset Text
17902
17903 \layout Standard
17904
17905 header file conversion
17906 \end_inset
17907 </cell>
17908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17909 \begin_inset Text
17910
17911 \layout Standard
17912
17913 sdcc/support/scripts
17914 \end_inset
17915 </cell>
17916 </row>
17917 <row topline="true">
17918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17919 \begin_inset Text
17920
17921 \layout Standard
17922
17923 mh2h.c
17924 \end_inset
17925 </cell>
17926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17927 \begin_inset Text
17928
17929 \layout Standard
17930
17931 header file conversion
17932 \end_inset
17933 </cell>
17934 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17935 \begin_inset Text
17936
17937 \layout Standard
17938
17939 sdcc/support/scripts
17940 \end_inset
17941 </cell>
17942 </row>
17943 <row topline="true">
17944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17945 \begin_inset Text
17946
17947 \layout Standard
17948
17949 as-gbz80
17950 \end_inset
17951 </cell>
17952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17953 \begin_inset Text
17954
17955 \layout Standard
17956
17957 Assembler
17958 \end_inset
17959 </cell>
17960 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17961 \begin_inset Text
17962
17963 \layout Standard
17964
17965
17966 \family roman
17967 \series medium
17968 \shape up
17969 \size normal
17970 \emph off
17971 \bar no
17972 \noun off
17973 \color none
17974 sdcc/bin
17975 \end_inset
17976 </cell>
17977 </row>
17978 <row topline="true">
17979 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17980 \begin_inset Text
17981
17982 \layout Standard
17983
17984 as-z80
17985 \end_inset
17986 </cell>
17987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17988 \begin_inset Text
17989
17990 \layout Standard
17991
17992 Assembler
17993 \end_inset
17994 </cell>
17995 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17996 \begin_inset Text
17997
17998 \layout Standard
17999
18000
18001 \family roman
18002 \series medium
18003 \shape up
18004 \size normal
18005 \emph off
18006 \bar no
18007 \noun off
18008 \color none
18009 sdcc/bin
18010 \end_inset
18011 </cell>
18012 </row>
18013 <row topline="true">
18014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18015 \begin_inset Text
18016
18017 \layout Standard
18018
18019 asx8051
18020 \end_inset
18021 </cell>
18022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18023 \begin_inset Text
18024
18025 \layout Standard
18026
18027 Assembler
18028 \end_inset
18029 </cell>
18030 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18031 \begin_inset Text
18032
18033 \layout Standard
18034
18035
18036 \family roman
18037 \series medium
18038 \shape up
18039 \size normal
18040 \emph off
18041 \bar no
18042 \noun off
18043 \color none
18044 sdcc/bin
18045 \end_inset
18046 </cell>
18047 </row>
18048 <row topline="true">
18049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18050 \begin_inset Text
18051
18052 \layout Standard
18053
18054 sdcdb
18055 \end_inset
18056 </cell>
18057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18058 \begin_inset Text
18059
18060 \layout Standard
18061
18062 Simulator
18063 \end_inset
18064 </cell>
18065 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18066 \begin_inset Text
18067
18068 \layout Standard
18069
18070
18071 \family roman
18072 \series medium
18073 \shape up
18074 \size normal
18075 \emph off
18076 \bar no
18077 \noun off
18078 \color none
18079 sdcc/bin
18080 \end_inset
18081 </cell>
18082 </row>
18083 <row topline="true">
18084 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18085 \begin_inset Text
18086
18087 \layout Standard
18088
18089 aslink
18090 \end_inset
18091 </cell>
18092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18093 \begin_inset Text
18094
18095 \layout Standard
18096
18097 Linker
18098 \end_inset
18099 </cell>
18100 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18101 \begin_inset Text
18102
18103 \layout Standard
18104
18105
18106 \family roman
18107 \series medium
18108 \shape up
18109 \size normal
18110 \emph off
18111 \bar no
18112 \noun off
18113 \color none
18114 sdcc/bin
18115 \end_inset
18116 </cell>
18117 </row>
18118 <row topline="true">
18119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18120 \begin_inset Text
18121
18122 \layout Standard
18123
18124 link-z80
18125 \end_inset
18126 </cell>
18127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18128 \begin_inset Text
18129
18130 \layout Standard
18131
18132 Linker
18133 \end_inset
18134 </cell>
18135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18136 \begin_inset Text
18137
18138 \layout Standard
18139
18140
18141 \family roman
18142 \series medium
18143 \shape up
18144 \size normal
18145 \emph off
18146 \bar no
18147 \noun off
18148 \color none
18149 sdcc/bin
18150 \end_inset
18151 </cell>
18152 </row>
18153 <row topline="true">
18154 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18155 \begin_inset Text
18156
18157 \layout Standard
18158
18159 link-gbz80
18160 \end_inset
18161 </cell>
18162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18163 \begin_inset Text
18164
18165 \layout Standard
18166
18167 Linker
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
18176 \family roman
18177 \series medium
18178 \shape up
18179 \size normal
18180 \emph off
18181 \bar no
18182 \noun off
18183 \color none
18184 sdcc/bin
18185 \end_inset
18186 </cell>
18187 </row>
18188 <row topline="true" bottomline="true">
18189 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18190 \begin_inset Text
18191
18192 \layout Standard
18193
18194 packihx
18195 \end_inset
18196 </cell>
18197 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18198 \begin_inset Text
18199
18200 \layout Standard
18201
18202 ihx packer
18203 \end_inset
18204 </cell>
18205 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18206 \begin_inset Text
18207
18208 \layout Standard
18209
18210
18211 \family roman
18212 \series medium
18213 \shape up
18214 \size normal
18215 \emph off
18216 \bar no
18217 \noun off
18218 \color none
18219 sdcc/bin
18220 \end_inset
18221 </cell>
18222 </row>
18223 </lyxtabular>
18224
18225 \end_inset
18226
18227
18228 \newline
18229
18230 \layout Section
18231
18232 Documentation
18233 \begin_inset LatexCommand \index{Documentation}
18234
18235 \end_inset
18236
18237  included in the distribution
18238 \layout Standard
18239 \align center
18240
18241 \begin_inset  Tabular
18242 <lyxtabular version="3" rows="10" columns="2">
18243 <features>
18244 <column alignment="left" valignment="top" leftline="true" width="0">
18245 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
18246 <row topline="true" bottomline="true">
18247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18248 \begin_inset Text
18249
18250 \layout Standard
18251
18252 Subject / Title
18253 \end_inset
18254 </cell>
18255 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18256 \begin_inset Text
18257
18258 \layout Standard
18259
18260 Where to get / filename
18261 \end_inset
18262 </cell>
18263 </row>
18264 <row topline="true">
18265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18266 \begin_inset Text
18267
18268 \layout Standard
18269
18270 SDCC Compiler User Guide
18271 \end_inset
18272 </cell>
18273 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18274 \begin_inset Text
18275
18276 \layout Standard
18277
18278 You're reading it right now
18279 \end_inset
18280 </cell>
18281 </row>
18282 <row topline="true">
18283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18284 \begin_inset Text
18285
18286 \layout Standard
18287
18288 Changelog of SDCC
18289 \end_inset
18290 </cell>
18291 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18292 \begin_inset Text
18293
18294 \layout Standard
18295
18296 sdcc/Changelog
18297 \end_inset
18298 </cell>
18299 </row>
18300 <row topline="true">
18301 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18302 \begin_inset Text
18303
18304 \layout Standard
18305
18306 ASXXXX
18307 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
18308
18309 \end_inset
18310
18311
18312 \begin_inset LatexCommand \index{Assembler documentation}
18313
18314 \end_inset
18315
18316  Assemblers and ASLINK
18317 \begin_inset LatexCommand \index{aslink}
18318
18319 \end_inset
18320
18321
18322 \begin_inset LatexCommand \index{Linker documentation}
18323
18324 \end_inset
18325
18326  Relocating Linker
18327 \end_inset
18328 </cell>
18329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18330 \begin_inset Text
18331
18332 \layout Standard
18333
18334 sdcc/as/doc/asxhtm.html
18335 \end_inset
18336 </cell>
18337 </row>
18338 <row topline="true">
18339 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18340 \begin_inset Text
18341
18342 \layout Standard
18343
18344 SDCC regression test
18345 \begin_inset LatexCommand \index{Regression test}
18346
18347 \end_inset
18348
18349
18350 \end_inset
18351 </cell>
18352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18353 \begin_inset Text
18354
18355 \layout Standard
18356
18357 sdcc/doc/test_suite_spec.pdf
18358 \end_inset
18359 </cell>
18360 </row>
18361 <row topline="true">
18362 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18363 \begin_inset Text
18364
18365 \layout Standard
18366
18367 Various notes
18368 \end_inset
18369 </cell>
18370 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18371 \begin_inset Text
18372
18373 \layout Standard
18374
18375 sdcc/doc/*
18376 \end_inset
18377 </cell>
18378 </row>
18379 <row topline="true">
18380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18381 \begin_inset Text
18382
18383 \layout Standard
18384
18385 Notes on debugging with sdcdb
18386 \begin_inset LatexCommand \index{sdcdb (debugger)}
18387
18388 \end_inset
18389
18390
18391 \end_inset
18392 </cell>
18393 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18394 \begin_inset Text
18395
18396 \layout Standard
18397
18398 sdcc/debugger/README
18399 \end_inset
18400 </cell>
18401 </row>
18402 <row topline="true">
18403 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18404 \begin_inset Text
18405
18406 \layout Standard
18407
18408 Software simulator for microcontrollers
18409 \end_inset
18410 </cell>
18411 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18412 \begin_inset Text
18413
18414 \layout Standard
18415
18416
18417 \family roman
18418 \series medium
18419 \shape up
18420 \size normal
18421 \emph off
18422 \bar no
18423 \noun off
18424 \color none
18425 sdcc/sim/ucsim/doc
18426 \family default
18427 \series default
18428 \shape default
18429 \size default
18430 \emph default
18431 \bar default
18432 \noun default
18433 \color default
18434 /index.html
18435 \end_inset
18436 </cell>
18437 </row>
18438 <row topline="true">
18439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18440 \begin_inset Text
18441
18442 \layout Standard
18443
18444 Temporary notes on the pic16
18445 \begin_inset LatexCommand \index{PIC16}
18446
18447 \end_inset
18448
18449  port
18450 \end_inset
18451 </cell>
18452 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18453 \begin_inset Text
18454
18455 \layout Standard
18456
18457 sdcc/src/pic16/NOTES
18458 \end_inset
18459 </cell>
18460 </row>
18461 <row topline="true" bottomline="true">
18462 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18463 \begin_inset Text
18464
18465 \layout Standard
18466
18467 SDCC internal documentation (debugging file format)
18468 \end_inset
18469 </cell>
18470 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18471 \begin_inset Text
18472
18473 \layout Standard
18474
18475 sdcc/doc/
18476 \family roman
18477 \series medium
18478 \shape up
18479 \size normal
18480 \emph off
18481 \bar no
18482 \noun off
18483 \color none
18484 cdbfileformat.pd
18485 \family default
18486 \series default
18487 \shape default
18488 \size default
18489 \emph default
18490 \bar default
18491 \noun default
18492 \color default
18493 f
18494 \end_inset
18495 </cell>
18496 </row>
18497 </lyxtabular>
18498
18499 \end_inset
18500
18501
18502 \newline
18503
18504 \layout Section
18505
18506 Related open source tools
18507 \begin_inset LatexCommand \index{Related tools}
18508
18509 \end_inset
18510
18511
18512 \layout Standard
18513 \align center
18514
18515 \begin_inset  Tabular
18516 <lyxtabular version="3" rows="11" columns="3">
18517 <features>
18518 <column alignment="center" valignment="top" leftline="true" width="0pt">
18519 <column alignment="block" valignment="top" leftline="true" width="30line%">
18520 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18521 <row topline="true" bottomline="true">
18522 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18523 \begin_inset Text
18524
18525 \layout Standard
18526
18527 Name
18528 \end_inset
18529 </cell>
18530 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18531 \begin_inset Text
18532
18533 \layout Standard
18534
18535 Purpose
18536 \end_inset
18537 </cell>
18538 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18539 \begin_inset Text
18540
18541 \layout Standard
18542
18543 Where to get
18544 \end_inset
18545 </cell>
18546 </row>
18547 <row topline="true">
18548 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18549 \begin_inset Text
18550
18551 \layout Standard
18552
18553 gpsim
18554 \begin_inset LatexCommand \index{gpsim (pic simulator)}
18555
18556 \end_inset
18557
18558
18559 \end_inset
18560 </cell>
18561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18562 \begin_inset Text
18563
18564 \layout Standard
18565
18566 PIC simulator
18567 \end_inset
18568 </cell>
18569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18570 \begin_inset Text
18571
18572 \layout Standard
18573
18574
18575 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
18576
18577 \end_inset
18578
18579
18580 \end_inset
18581 </cell>
18582 </row>
18583 <row topline="true">
18584 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18585 \begin_inset Text
18586
18587 \layout Standard
18588
18589 gputils
18590 \begin_inset LatexCommand \index{gputils (pic tools)}
18591
18592 \end_inset
18593
18594
18595 \end_inset
18596 </cell>
18597 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18598 \begin_inset Text
18599
18600 \layout Standard
18601
18602 GNU PIC utilities
18603 \end_inset
18604 </cell>
18605 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18606 \begin_inset Text
18607
18608 \layout Standard
18609
18610
18611 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
18612
18613 \end_inset
18614
18615
18616 \end_inset
18617 </cell>
18618 </row>
18619 <row topline="true">
18620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18621 \begin_inset Text
18622
18623 \layout Standard
18624
18625 flP5
18626 \end_inset
18627 </cell>
18628 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18629 \begin_inset Text
18630
18631 \layout Standard
18632
18633 PIC programmer
18634 \end_inset
18635 </cell>
18636 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18637 \begin_inset Text
18638
18639 \layout Standard
18640
18641
18642 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
18643
18644 \end_inset
18645
18646
18647 \end_inset
18648 </cell>
18649 </row>
18650 <row topline="true">
18651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18652 \begin_inset Text
18653
18654 \layout Standard
18655
18656 indent
18657 \begin_inset LatexCommand \index{indent (source formatting tool)}
18658
18659 \end_inset
18660
18661
18662 \end_inset
18663 </cell>
18664 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18665 \begin_inset Text
18666
18667 \layout Standard
18668
18669 Formats C source - Master of the white spaces
18670 \end_inset
18671 </cell>
18672 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18673 \begin_inset Text
18674
18675 \layout Standard
18676
18677
18678 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
18679
18680 \end_inset
18681
18682
18683 \end_inset
18684 </cell>
18685 </row>
18686 <row topline="true">
18687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18688 \begin_inset Text
18689
18690 \layout Standard
18691
18692 srecord
18693 \begin_inset LatexCommand \index{srecord (tool)}
18694
18695 \end_inset
18696
18697
18698 \end_inset
18699 </cell>
18700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18701 \begin_inset Text
18702
18703 \layout Standard
18704
18705 Object file conversion, checksumming, ...
18706 \end_inset
18707 </cell>
18708 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18709 \begin_inset Text
18710
18711 \layout Standard
18712
18713
18714 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
18715
18716 \end_inset
18717
18718
18719 \end_inset
18720 </cell>
18721 </row>
18722 <row topline="true">
18723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18724 \begin_inset Text
18725
18726 \layout Standard
18727
18728 objdump
18729 \begin_inset LatexCommand \index{objdump (tool)}
18730
18731 \end_inset
18732
18733
18734 \end_inset
18735 </cell>
18736 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18737 \begin_inset Text
18738
18739 \layout Standard
18740
18741 Object file conversion, ...
18742 \end_inset
18743 </cell>
18744 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18745 \begin_inset Text
18746
18747 \layout Standard
18748
18749 Part of binutils (should be there anyway)
18750 \end_inset
18751 </cell>
18752 </row>
18753 <row topline="true">
18754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18755 \begin_inset Text
18756
18757 \layout Standard
18758
18759 doxygen
18760 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
18761
18762 \end_inset
18763
18764
18765 \end_inset
18766 </cell>
18767 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18768 \begin_inset Text
18769
18770 \layout Standard
18771
18772 Source code documentation system
18773 \end_inset
18774 </cell>
18775 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18776 \begin_inset Text
18777
18778 \layout Standard
18779
18780
18781 \begin_inset LatexCommand \url{http://www.doxygen.org}
18782
18783 \end_inset
18784
18785
18786 \end_inset
18787 </cell>
18788 </row>
18789 <row topline="true">
18790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18791 \begin_inset Text
18792
18793 \layout Standard
18794
18795 kdevelop
18796 \end_inset
18797 </cell>
18798 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18799 \begin_inset Text
18800
18801 \layout Standard
18802
18803 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
18804 \end_inset
18805 </cell>
18806 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18807 \begin_inset Text
18808
18809 \layout Standard
18810
18811
18812 \begin_inset LatexCommand \url{http://www.kdevelop.org}
18813
18814 \end_inset
18815
18816
18817 \end_inset
18818 </cell>
18819 </row>
18820 <row topline="true">
18821 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18822 \begin_inset Text
18823
18824 \layout Standard
18825
18826 splint
18827 \begin_inset LatexCommand \index{splint (syntax checking tool)}
18828
18829 \end_inset
18830
18831
18832 \end_inset
18833 </cell>
18834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18835 \begin_inset Text
18836
18837 \layout Standard
18838
18839 Statically checks c sources (has anyone adapted splint for SDCC?)
18840 \end_inset
18841 </cell>
18842 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18843 \begin_inset Text
18844
18845 \layout Standard
18846
18847
18848 \begin_inset LatexCommand \url{http://www.splint.org}
18849
18850 \end_inset
18851
18852
18853 \end_inset
18854 </cell>
18855 </row>
18856 <row topline="true" bottomline="true">
18857 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18858 \begin_inset Text
18859
18860 \layout Standard
18861
18862 ddd
18863 \begin_inset LatexCommand \index{ddd (debugger)}
18864
18865 \end_inset
18866
18867
18868 \end_inset
18869 </cell>
18870 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18871 \begin_inset Text
18872
18873 \layout Standard
18874
18875 Debugger, serves nicely as GUI to sdcdb
18876 \begin_inset LatexCommand \index{sdcdb (debugger)}
18877
18878 \end_inset
18879
18880  (Unix only)
18881 \end_inset
18882 </cell>
18883 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18884 \begin_inset Text
18885
18886 \layout Standard
18887
18888
18889 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
18890
18891 \end_inset
18892
18893
18894 \end_inset
18895 </cell>
18896 </row>
18897 </lyxtabular>
18898
18899 \end_inset
18900
18901
18902 \newline
18903
18904 \layout Section
18905
18906 Related documentation / recommended reading
18907 \layout Standard
18908 \align center
18909
18910 \begin_inset  Tabular
18911 <lyxtabular version="3" rows="6" columns="3">
18912 <features>
18913 <column alignment="center" valignment="top" leftline="true" width="0pt">
18914 <column alignment="block" valignment="top" leftline="true" width="30line%">
18915 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18916 <row topline="true" bottomline="true">
18917 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18918 \begin_inset Text
18919
18920 \layout Standard
18921
18922 Name
18923 \end_inset
18924 </cell>
18925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18926 \begin_inset Text
18927
18928 \layout Standard
18929
18930 Subject / Title
18931 \end_inset
18932 </cell>
18933 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18934 \begin_inset Text
18935
18936 \layout Standard
18937
18938 Where to get
18939 \end_inset
18940 </cell>
18941 </row>
18942 <row topline="true">
18943 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18944 \begin_inset Text
18945
18946 \layout Standard
18947
18948
18949 \family roman
18950 \series medium
18951 \shape up
18952 \size normal
18953 \emph off
18954 \bar no
18955 \noun off
18956 \color none
18957 c-refcard.pdf
18958 \end_inset
18959 </cell>
18960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18961 \begin_inset Text
18962
18963 \layout Standard
18964
18965 C Reference Card
18966 \begin_inset LatexCommand \index{C Reference card}
18967
18968 \end_inset
18969
18970 , 2 pages
18971 \end_inset
18972 </cell>
18973 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18974 \begin_inset Text
18975
18976 \layout Standard
18977
18978
18979 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
18980
18981 \end_inset
18982
18983
18984 \end_inset
18985 </cell>
18986 </row>
18987 <row topline="true">
18988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18989 \begin_inset Text
18990
18991 \layout Standard
18992
18993 c-faq
18994 \end_inset
18995 </cell>
18996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18997 \begin_inset Text
18998
18999 \layout Standard
19000
19001 C-FAQ-list
19002 \end_inset
19003 </cell>
19004 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19005 \begin_inset Text
19006
19007 \layout Standard
19008
19009
19010 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
19011
19012 \end_inset
19013
19014
19015 \end_inset
19016 </cell>
19017 </row>
19018 <row topline="true">
19019 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19020 \begin_inset Text
19021
19022 \layout Standard
19023
19024 \end_inset
19025 </cell>
19026 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19027 \begin_inset Text
19028
19029 \layout Standard
19030
19031 Latest datasheet of the target CPU
19032 \end_inset
19033 </cell>
19034 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19035 \begin_inset Text
19036
19037 \layout Standard
19038
19039 vendor
19040 \end_inset
19041 </cell>
19042 </row>
19043 <row topline="true">
19044 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19045 \begin_inset Text
19046
19047 \layout Standard
19048
19049 \end_inset
19050 </cell>
19051 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19052 \begin_inset Text
19053
19054 \layout Standard
19055
19056 Revision history of datasheet
19057 \end_inset
19058 </cell>
19059 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19060 \begin_inset Text
19061
19062 \layout Standard
19063
19064 vendor
19065 \end_inset
19066 </cell>
19067 </row>
19068 <row topline="true" bottomline="true">
19069 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19070 \begin_inset Text
19071
19072 \layout Standard
19073
19074 S.
19075  S.
19076  Muchnick
19077 \end_inset
19078 </cell>
19079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19080 \begin_inset Text
19081
19082 \layout Standard
19083
19084 Advanced Compiler Design and Implementation
19085 \end_inset
19086 </cell>
19087 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19088 \begin_inset Text
19089
19090 \layout Standard
19091
19092 bookstore (very dedicated, probably read other books first)
19093 \end_inset
19094 </cell>
19095 </row>
19096 </lyxtabular>
19097
19098 \end_inset
19099
19100
19101 \newline
19102
19103 \layout Section
19104
19105 Some Questions
19106 \layout Standard
19107
19108 Some questions answered, some pointers given - it might be time to in turn
19109  ask
19110 \emph on
19111 you
19112 \emph default
19113  some questions:
19114 \layout Itemize
19115
19116 can you solve your project with the selected microcontroller? Would you
19117  find out early or rather late that your target is too small/slow/whatever?
19118  Can you switch to a slightly better device if it doesn't fit?
19119 \layout Itemize
19120
19121 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
19122  and/or another programming language be more adequate? Would an operating
19123  system on the target device help?
19124 \layout Itemize
19125
19126 if you solved the problem, will the marketing department be happy?
19127 \layout Itemize
19128
19129 if the marketing department is happy, will customers be happy?
19130 \layout Itemize
19131
19132 if you're the project manager, marketing department and maybe even the customer
19133  in one person, have you tried to see the project from the outside?
19134 \layout Itemize
19135
19136 is the project done if you think it is done? Or is just that other interface/pro
19137 tocol/feature/configuration/option missing? How about website, manual(s),
19138  internationali(z|s)ation, packaging, labels, 2nd source for components,
19139  electromagnetic compatability/interference, documentation for production,
19140  production test software, update mechanism, patent issues?
19141 \layout Itemize
19142
19143 is your project adequately positioned in that magic triangle: fame, fortune,
19144  fun?
19145 \layout Standard
19146
19147 Maybe not all answers to these questions are known and some answers may
19148  even be
19149 \emph on
19150 no
19151 \emph default
19152 , nevertheless knowing these questions may help you to avoid burnout
19153 \begin_inset Foot
19154 collapsed false
19155
19156 \layout Standard
19157
19158 burnout is bad for electronic devices, programmers and motorcycle tyres
19159 \end_inset
19160
19161 .
19162  Chances are you didn't want to hear some of them...
19163 \layout Chapter
19164
19165 Support
19166 \begin_inset LatexCommand \index{Support}
19167
19168 \end_inset
19169
19170
19171 \layout Standard
19172
19173 SDCC has grown to be a large project.
19174  The compiler alone (without the preprocessor, assembler and linker) is
19175  well over 100,000 lines of code (blank stripped).
19176  The open source nature of this project is a key to its continued growth
19177  and support.
19178  You gain the benefit and support of many active software developers and
19179  end users.
19180  Is SDCC perfect? No, that's why we need your help.
19181  The developers take pride in fixing reported bugs.
19182  You can help by reporting the bugs and helping other SDCC users.
19183  There are lots of ways to contribute, and we encourage you to take part
19184  in making SDCC a great software package.
19185
19186 \layout Standard
19187
19188 The SDCC project is hosted on the SDCC sourceforge site at
19189 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
19190
19191 \end_inset
19192
19193 .
19194  You'll find the complete set of mailing lists
19195 \begin_inset LatexCommand \index{Mailing list(s)}
19196
19197 \end_inset
19198
19199 , forums, bug reporting system, patch submission
19200 \begin_inset LatexCommand \index{Patch submission}
19201
19202 \end_inset
19203
19204  system, download
19205 \begin_inset LatexCommand \index{download}
19206
19207 \end_inset
19208
19209  area and cvs code repository
19210 \begin_inset LatexCommand \index{cvs code repository}
19211
19212 \end_inset
19213
19214  there.
19215 \layout Section
19216
19217 Reporting Bugs
19218 \begin_inset LatexCommand \index{Bug reporting}
19219
19220 \end_inset
19221
19222
19223 \begin_inset LatexCommand \index{Reporting bugs}
19224
19225 \end_inset
19226
19227
19228 \layout Standard
19229
19230 The recommended way of reporting bugs is using the infrastructure of the
19231  sourceforge site.
19232  You can follow the status of bug reports there and have an overview about
19233  the known bugs.
19234 \layout Standard
19235
19236 Bug reports are automatically forwarded to the developer mailing list and
19237  will be fixed ASAP.
19238  When reporting a bug, it is very useful to include a small test program
19239  (the smaller the better) which reproduces the problem.
19240  If you can isolate the problem by looking at the generated assembly code,
19241  this can be very helpful.
19242  Compiling your program with the -
19243 \begin_inset ERT
19244 status Collapsed
19245
19246 \layout Standard
19247
19248 \backslash
19249 /
19250 \end_inset
19251
19252 -dumpall
19253 \begin_inset LatexCommand \index{-\/-dumpall}
19254
19255 \end_inset
19256
19257  option can sometimes be useful in locating optimization problems.
19258  When reporting a bug please maker sure you:
19259 \layout Enumerate
19260
19261 Attach the code you are compiling with SDCC.
19262
19263 \layout Enumerate
19264
19265 Specify the exact command you use to run SDCC, or attach your Makefile.
19266
19267 \layout Enumerate
19268
19269 Specify the SDCC version (type "
19270 \family sans
19271 \series bold
19272 sdcc -v
19273 \family default
19274 \series default
19275 "), your platform, and operating system.
19276
19277 \layout Enumerate
19278
19279 Provide an exact copy of any error message or incorrect output.
19280
19281 \layout Enumerate
19282
19283 Put something meaningful in the subject of your message.
19284 \layout Standard
19285
19286 Please attempt to include these 5 important parts, as applicable, in all
19287  requests for support or when reporting any problems or bugs with SDCC.
19288  Though this will make your message lengthy, it will greatly improve your
19289  chance that SDCC users and developers will be able to help you.
19290  Some SDCC developers are frustrated by bug reports without code provided
19291  that they can use to reproduce and ultimately fix the problem, so please
19292  be sure to provide sample code if you are reporting a bug!
19293 \layout Standard
19294
19295 Please have a short check that you are using a recent version of SDCC and
19296  the bug is not yet known.
19297  This is the link for reporting bugs:
19298 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
19299
19300 \end_inset
19301
19302 .
19303 \layout Section
19304
19305 Requesting Features
19306 \begin_inset LatexCommand \label{sub:Requesting-Features}
19307
19308 \end_inset
19309
19310
19311 \begin_inset LatexCommand \index{Feature request}
19312
19313 \end_inset
19314
19315
19316 \begin_inset LatexCommand \index{Requesting features}
19317
19318 \end_inset
19319
19320
19321 \layout Standard
19322
19323 Like bug reports feature requests are forwarded to the developer mailing
19324  list.
19325  This is the link for requesting features:
19326 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
19327
19328 \end_inset
19329
19330 .
19331 \layout Section
19332
19333 Submitting patches
19334 \layout Standard
19335
19336 Like bug reports contributed patches are forwarded to the developer mailing
19337  list.
19338  This is the link for submitting patches
19339 \begin_inset LatexCommand \index{Patch submission}
19340
19341 \end_inset
19342
19343 :
19344 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
19345
19346 \end_inset
19347
19348 .
19349 \layout Standard
19350
19351 You need to specify some parameters to the
19352 \family typewriter
19353 diff
19354 \family default
19355  command for the patches to be useful.
19356  If you modified more than one file a patch created f.e.
19357  with
19358 \family sans
19359 \series bold
19360
19361 \begin_inset Quotes sld
19362 \end_inset
19363
19364 diff -Naur unmodified_directory modified_directory >my_changes.patch
19365 \begin_inset Quotes srd
19366 \end_inset
19367
19368
19369 \family default
19370 \series default
19371  will be fine, otherwise
19372 \family sans
19373 \series bold
19374
19375 \begin_inset Quotes sld
19376 \end_inset
19377
19378 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
19379 \begin_inset Quotes srd
19380 \end_inset
19381
19382
19383 \series default
19384
19385 \family default
19386 will do.
19387 \layout Section
19388
19389 Getting Help
19390 \layout Standard
19391
19392 These links should take you directly to the
19393 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
19394
19395 \end_inset
19396
19397
19398 \begin_inset Foot
19399 collapsed false
19400
19401 \layout Standard
19402
19403 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
19404  automated messages (mid 2003)
19405 \end_inset
19406
19407  and the
19408 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
19409
19410 \end_inset
19411
19412 , lists
19413 \begin_inset LatexCommand \index{Mailing list(s)}
19414
19415 \end_inset
19416
19417  and forums are archived and searchable so if you are lucky someone already
19418  had a similar problem.
19419  While mails to the lists themselves are delivered promptly their web front
19420  end on sourceforge sometimes shows a severe time lag (up to several weeks),
19421  if you're seriously using SDCC please consider subscribing to the lists.
19422 \layout Section
19423
19424 ChangeLog
19425 \layout Standard
19426
19427 You can follow the status of the cvs version
19428 \begin_inset LatexCommand \index{version}
19429
19430 \end_inset
19431
19432  of SDCC by watching the Changelog
19433 \begin_inset LatexCommand \index{Changelog}
19434
19435 \end_inset
19436
19437  in the cvs-repository
19438 \newline
19439
19440 \size footnotesize
19441
19442 \begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
19443
19444 \end_inset
19445
19446 .
19447 \layout Section
19448
19449 Release policy
19450 \begin_inset LatexCommand \index{Release policy}
19451
19452 \end_inset
19453
19454
19455 \layout Standard
19456
19457 Historically there often were long delays between official releases and
19458  the sourceforge download area tends to get not updated at all.
19459  Excuses in the past might have referred to problems with live range analysis,
19460  but as this was fixed a while ago, the current problem is that another
19461  excuse has to be found.
19462  Kidding aside, we have to get better there! On the other hand there are
19463  daily snapshots available at
19464 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
19465
19466 \end_inset
19467
19468 , and you can always build the very last version (hopefully with many bugs
19469  fixed, and features added) from the source code available at
19470 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
19471
19472 \end_inset
19473
19474 .
19475 \layout Section
19476
19477 Examples
19478 \begin_inset LatexCommand \index{Examples}
19479
19480 \end_inset
19481
19482
19483 \layout Standard
19484
19485 You'll find some small examples in the directory
19486 \emph on
19487 sdcc/device/examples/.
19488
19489 \emph default
19490 More examples and libraries are available at
19491 \emph on
19492  The SDCC Open Knowledge Resource
19493 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
19494
19495 \end_inset
19496
19497
19498 \emph default
19499 web site or at
19500 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
19501
19502 \end_inset
19503
19504 .
19505 \layout Comment
19506
19507 I did insert a reference to Paul's web site here although it seems rather
19508  dedicated to a specific 8032 board (I think it's okay because it f.e.
19509  shows LCD/Harddisc interface and has a free 8051 monitor.
19510  Independent 8032 board vendors face hard competition of heavily subsidized
19511  development boards anyway).
19512 \layout Comment
19513
19514 Maybe we should include some links to real world applications.
19515  Preferably pointer to pointers (one for each architecture) so this stays
19516  manageable here?
19517 \layout Section
19518
19519 Quality control
19520 \begin_inset LatexCommand \index{Quality control}
19521
19522 \end_inset
19523
19524
19525 \layout Standard
19526
19527 The compiler is passed through nightly compile and build checks.
19528  The so called
19529 \shape italic
19530 regression tests
19531 \shape default
19532
19533 \begin_inset LatexCommand \index{Regression test}
19534
19535 \end_inset
19536
19537  check that SDCC itself compiles flawlessly on several platforms and checks
19538  the quality of the code generated by SDCC by running the code through simulator
19539 s.
19540  There is a separate document
19541 \shape italic
19542 test_suite.pdf
19543 \begin_inset LatexCommand \index{Test suite}
19544
19545 \end_inset
19546
19547
19548 \shape default
19549  about this.
19550 \layout Standard
19551
19552 You'll find the test code in the directory
19553 \shape italic
19554 sdcc/support/regression
19555 \shape default
19556 .
19557  You can run these tests manually by running
19558 \family sans
19559 make
19560 \family default
19561  in this directory (or f.e.
19562
19563 \family sans
19564 \series bold
19565
19566 \begin_inset Quotes sld
19567 \end_inset
19568
19569 make test-mcs51
19570 \begin_inset Quotes srd
19571 \end_inset
19572
19573
19574 \family default
19575 \series default
19576  if you don't want to run the complete tests).
19577  The test code might also be interesting if you want to look for examples
19578 \begin_inset LatexCommand \index{Examples}
19579
19580 \end_inset
19581
19582  checking corner cases of SDCC or if you plan to submit patches
19583 \begin_inset LatexCommand \index{Patch submission}
19584
19585 \end_inset
19586
19587 .
19588 \layout Standard
19589
19590 The pic port uses a different set of regression tests, you'll find them
19591  in the directory
19592 \shape italic
19593 sdcc/src/regression
19594 \shape default
19595 .
19596 \layout Chapter
19597 \pagebreak_top
19598 SDCC Technical Data
19599 \layout Section
19600
19601 Optimizations
19602 \begin_inset LatexCommand \index{Optimizations}
19603
19604 \end_inset
19605
19606
19607 \layout Standard
19608
19609 SDCC performs a host of standard optimizations in addition to some MCU specific
19610  optimizations.
19611
19612 \layout Subsection
19613
19614 Sub-expression Elimination
19615 \begin_inset LatexCommand \index{Subexpression elimination}
19616
19617 \end_inset
19618
19619
19620 \layout Standard
19621
19622 The compiler does local and
19623 \emph on
19624 g
19625 \emph default
19626 lobal
19627 \emph on
19628 c
19629 \emph default
19630 ommon
19631 \emph on
19632 s
19633 \emph default
19634 ubexpression
19635 \emph on
19636 e
19637 \emph default
19638 limination, e.g.:
19639 \layout Verse
19640
19641
19642 \family typewriter
19643 i = x + y + 1;
19644 \newline
19645 j = x + y;
19646 \layout Standard
19647
19648 will be translated to
19649 \layout Verse
19650
19651
19652 \family typewriter
19653 iTemp = x + y;
19654 \newline
19655 i = iTemp + 1;
19656 \newline
19657 j = iTemp;
19658 \layout Standard
19659
19660 Some subexpressions are not as obvious as the above example, e.g.:
19661 \layout Verse
19662
19663
19664 \family typewriter
19665 a->b[i].c = 10;
19666 \newline
19667 a->b[i].d = 11;
19668 \layout Standard
19669
19670 In this case the address arithmetic a->b[i] will be computed only once;
19671  the equivalent code in C would be.
19672 \layout Verse
19673
19674
19675 \family typewriter
19676 iTemp = a->b[i];
19677 \newline
19678 iTemp.c = 10;
19679 \newline
19680 iTemp.d = 11;
19681 \layout Standard
19682
19683 The compiler will try to keep these temporary variables in registers.
19684 \layout Subsection
19685
19686 Dead-Code Elimination
19687 \begin_inset LatexCommand \index{Dead-code elimination}
19688
19689 \end_inset
19690
19691
19692 \layout Verse
19693
19694
19695 \family typewriter
19696 int global;
19697 \newline
19698
19699 \newline
19700 void f () {
19701 \newline
19702 \SpecialChar ~
19703 \SpecialChar ~
19704 int i;
19705 \newline
19706 \SpecialChar ~
19707 \SpecialChar ~
19708 i = 1; \SpecialChar ~
19709 \SpecialChar ~
19710 \SpecialChar ~
19711 \SpecialChar ~
19712 \SpecialChar ~
19713 /* dead store */
19714 \newline
19715 \SpecialChar ~
19716 \SpecialChar ~
19717 global = 1;\SpecialChar ~
19718 /* dead store */
19719 \newline
19720 \SpecialChar ~
19721 \SpecialChar ~
19722 global = 2;
19723 \newline
19724 \SpecialChar ~
19725 \SpecialChar ~
19726 return;
19727 \newline
19728 \SpecialChar ~
19729 \SpecialChar ~
19730 global = 3;\SpecialChar ~
19731 /* unreachable */
19732 \newline
19733 }
19734 \layout Standard
19735
19736 will be changed to
19737 \layout Verse
19738
19739
19740 \family typewriter
19741 int global;
19742 \newline
19743
19744 \newline
19745 void f () {
19746 \newline
19747 \SpecialChar ~
19748 \SpecialChar ~
19749 global = 2;
19750 \newline
19751 }
19752 \layout Subsection
19753
19754 Copy-Propagation
19755 \begin_inset LatexCommand \index{Copy propagation}
19756
19757 \end_inset
19758
19759
19760 \layout Verse
19761
19762
19763 \family typewriter
19764 int f() {
19765 \newline
19766 \SpecialChar ~
19767 \SpecialChar ~
19768 int i, j;
19769 \newline
19770 \SpecialChar ~
19771 \SpecialChar ~
19772 i = 10;
19773 \newline
19774 \SpecialChar ~
19775 \SpecialChar ~
19776 j = i;
19777 \newline
19778 \SpecialChar ~
19779 \SpecialChar ~
19780 return j;
19781 \newline
19782 }
19783 \layout Standard
19784
19785 will be changed to
19786 \layout Verse
19787
19788
19789 \family typewriter
19790 int f() {
19791 \newline
19792 \SpecialChar ~
19793 \SpecialChar ~
19794 int i, j;
19795 \newline
19796 \SpecialChar ~
19797 \SpecialChar ~
19798 i = 10;
19799 \newline
19800 \SpecialChar ~
19801 \SpecialChar ~
19802 j = 10;
19803 \newline
19804 \SpecialChar ~
19805 \SpecialChar ~
19806 return 10;
19807 \newline
19808 }
19809 \layout Standard
19810
19811 Note: the dead stores created by this copy propagation will be eliminated
19812  by dead-code elimination.
19813 \layout Subsection
19814
19815 Loop Optimizations
19816 \begin_inset LatexCommand \index{Loop optimization}
19817
19818 \end_inset
19819
19820
19821 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
19822
19823 \end_inset
19824
19825
19826 \layout Standard
19827
19828 Two types of loop optimizations are done by SDCC
19829 \emph on
19830 loop invariant
19831 \emph default
19832  lifting and
19833 \emph on
19834  strength reduction
19835 \emph default
19836  of loop induction variables.
19837  In addition to the strength reduction the optimizer marks the induction
19838  variables and the register allocator tries to keep the induction variables
19839  in registers for the duration of the loop.
19840  Because of this preference of the register allocator
19841 \begin_inset LatexCommand \index{Register allocation}
19842
19843 \end_inset
19844
19845 , loop induction optimization causes an increase in register pressure, which
19846  may cause unwanted spilling of other temporary variables into the stack
19847 \begin_inset LatexCommand \index{stack}
19848
19849 \end_inset
19850
19851  / data space.
19852  The compiler will generate a warning message when it is forced to allocate
19853  extra space either on the stack or data space.
19854  If this extra space allocation is undesirable then induction optimization
19855  can be eliminated either for the entire source file (with -
19856 \begin_inset ERT
19857 status Collapsed
19858
19859 \layout Standard
19860
19861 \backslash
19862 /
19863 \end_inset
19864
19865 -noinduction option) or for a given function only using #pragma\SpecialChar ~
19866 noinduction
19867 \begin_inset LatexCommand \index{\#pragma noinduction}
19868
19869 \end_inset
19870
19871 .
19872 \newline
19873
19874 \newline
19875 Loop Invariant:
19876 \layout Verse
19877
19878
19879 \family typewriter
19880 for (i = 0 ; i < 100 ; i ++)
19881 \newline
19882 \SpecialChar ~
19883 \SpecialChar ~
19884 \SpecialChar ~
19885 \SpecialChar ~
19886 f += k + l;
19887 \layout Standard
19888
19889 changed to
19890 \layout Verse
19891
19892
19893 \family typewriter
19894 itemp = k + l;
19895 \newline
19896 for (i = 0; i < 100; i++)
19897 \newline
19898 \SpecialChar ~
19899 \SpecialChar ~
19900 \SpecialChar ~
19901 \SpecialChar ~
19902 f += itemp;
19903 \layout Standard
19904
19905 As mentioned previously some loop invariants are not as apparent, all static
19906  address computations are also moved out of the loop.
19907 \newline
19908
19909 \newline
19910 Strength Reduction
19911 \begin_inset LatexCommand \index{Strength reduction}
19912
19913 \end_inset
19914
19915 , this optimization substitutes an expression by a cheaper expression:
19916 \layout Verse
19917
19918
19919 \family typewriter
19920 for (i=0;i < 100; i++)
19921 \newline
19922 \SpecialChar ~
19923 \SpecialChar ~
19924 \SpecialChar ~
19925 \SpecialChar ~
19926 ar[i*5] = i*3;
19927 \layout Standard
19928
19929 changed to
19930 \layout Verse
19931
19932
19933 \family typewriter
19934 itemp1 = 0;
19935 \newline
19936 itemp2 = 0;
19937 \newline
19938 for (i=0;i< 100;i++) {
19939 \newline
19940 \SpecialChar ~
19941 \SpecialChar ~
19942 \SpecialChar ~
19943 \SpecialChar ~
19944 ar[itemp1] = itemp2;
19945 \newline
19946 \SpecialChar ~
19947 \SpecialChar ~
19948 \SpecialChar ~
19949 \SpecialChar ~
19950 itemp1 += 5;
19951 \newline
19952 \SpecialChar ~
19953 \SpecialChar ~
19954 \SpecialChar ~
19955 \SpecialChar ~
19956 itemp2 += 3;
19957 \newline
19958 }
19959 \layout Standard
19960
19961 The more expensive multiplication
19962 \begin_inset LatexCommand \index{Multiplication}
19963
19964 \end_inset
19965
19966  is changed to a less expensive addition.
19967 \layout Subsection
19968
19969 Loop Reversing
19970 \begin_inset LatexCommand \index{Loop reversing}
19971
19972 \end_inset
19973
19974
19975 \layout Standard
19976
19977 This optimization is done to reduce the overhead of checking loop boundaries
19978  for every iteration.
19979  Some simple loops can be reversed and implemented using a
19980 \begin_inset Quotes eld
19981 \end_inset
19982
19983 decrement and jump if not zero
19984 \begin_inset Quotes erd
19985 \end_inset
19986
19987  instruction.
19988  SDCC checks for the following criterion to determine if a loop is reversible
19989  (note: more sophisticated compilers use data-dependency analysis to make
19990  this determination, SDCC uses a more simple minded analysis).
19991 \layout Itemize
19992
19993 The 'for' loop is of the form
19994 \newline
19995
19996 \newline
19997
19998 \family typewriter
19999 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
20000  += 1])
20001 \newline
20002 \SpecialChar ~
20003 \SpecialChar ~
20004 \SpecialChar ~
20005 \SpecialChar ~
20006 <for body>
20007 \layout Itemize
20008
20009 The <for body> does not contain
20010 \begin_inset Quotes eld
20011 \end_inset
20012
20013 continue
20014 \begin_inset Quotes erd
20015 \end_inset
20016
20017  or 'break
20018 \begin_inset Quotes erd
20019 \end_inset
20020
20021 .
20022 \layout Itemize
20023
20024 All goto's are contained within the loop.
20025 \layout Itemize
20026
20027 No function calls within the loop.
20028 \layout Itemize
20029
20030 The loop control variable <sym> is not assigned any value within the loop
20031 \layout Itemize
20032
20033 The loop control variable does NOT participate in any arithmetic operation
20034  within the loop.
20035 \layout Itemize
20036
20037 There are NO switch statements in the loop.
20038 \layout Subsection
20039
20040 Algebraic Simplifications
20041 \layout Standard
20042
20043 SDCC does numerous algebraic simplifications, the following is a small sub-set
20044  of these optimizations.
20045 \layout Verse
20046
20047
20048 \family typewriter
20049 i = j + 0;\SpecialChar ~
20050 \SpecialChar ~
20051 \SpecialChar ~
20052 \SpecialChar ~
20053  /* changed to: */\SpecialChar ~
20054 \SpecialChar ~
20055 \SpecialChar ~
20056 \SpecialChar ~
20057  i = j;
20058 \newline
20059 i /= 2;\SpecialChar ~
20060 \SpecialChar ~
20061 \SpecialChar ~
20062 \SpecialChar ~
20063 \SpecialChar ~
20064 \SpecialChar ~
20065 \SpecialChar ~
20066  /* changed to: */\SpecialChar ~
20067 \SpecialChar ~
20068 \SpecialChar ~
20069 \SpecialChar ~
20070  i >>= 1;
20071 \newline
20072 i = j - j;\SpecialChar ~
20073 \SpecialChar ~
20074 \SpecialChar ~
20075 \SpecialChar ~
20076  /* changed to: */\SpecialChar ~
20077 \SpecialChar ~
20078 \SpecialChar ~
20079 \SpecialChar ~
20080  i = 0;
20081 \newline
20082 i = j / 1;\SpecialChar ~
20083 \SpecialChar ~
20084 \SpecialChar ~
20085 \SpecialChar ~
20086  /* changed to: */\SpecialChar ~
20087 \SpecialChar ~
20088 \SpecialChar ~
20089 \SpecialChar ~
20090  i = j;
20091 \layout Standard
20092
20093 Note the subexpressions
20094 \begin_inset LatexCommand \index{Subexpression}
20095
20096 \end_inset
20097
20098  given above are generally introduced by macro expansions or as a result
20099  of copy/constant propagation.
20100 \layout Subsection
20101
20102 'switch' Statements
20103 \begin_inset LatexCommand \label{sub:'switch'-Statements}
20104
20105 \end_inset
20106
20107
20108 \begin_inset LatexCommand \index{switch statement}
20109
20110 \end_inset
20111
20112
20113 \layout Standard
20114
20115 SDCC can optimize switch statements to jump tables
20116 \begin_inset LatexCommand \index{jump tables}
20117
20118 \end_inset
20119
20120 .
20121  It makes the decision based on an estimate of the generated code size.
20122  SDCC is quite liberal in the requirements for jump table generation:
20123 \layout Itemize
20124
20125 The labels need not be in order, and the starting number need not be one
20126  or zero, the case labels are in numerical sequence or not too many case
20127  labels are missing.
20128 \begin_deeper
20129 \layout Verse
20130
20131
20132 \family typewriter
20133 switch(i) {\SpecialChar ~
20134 \SpecialChar ~
20135 \SpecialChar ~
20136 \SpecialChar ~
20137 \SpecialChar ~
20138 \SpecialChar ~
20139 \SpecialChar ~
20140 \SpecialChar ~
20141 \SpecialChar ~
20142 \SpecialChar ~
20143 \SpecialChar ~
20144 \SpecialChar ~
20145 \SpecialChar ~
20146 \SpecialChar ~
20147 \SpecialChar ~
20148 \SpecialChar ~
20149 \SpecialChar ~
20150 \SpecialChar ~
20151 \SpecialChar ~
20152 \SpecialChar ~
20153 \SpecialChar ~
20154 \SpecialChar ~
20155 \SpecialChar ~
20156 \SpecialChar ~
20157 \SpecialChar ~
20158 \SpecialChar ~
20159 switch (i) {
20160 \newline
20161 \SpecialChar ~
20162 \SpecialChar ~
20163 \SpecialChar ~
20164 case 4: ...\SpecialChar ~
20165 \SpecialChar ~
20166 \SpecialChar ~
20167 \SpecialChar ~
20168 \SpecialChar ~
20169 \SpecialChar ~
20170 \SpecialChar ~
20171 \SpecialChar ~
20172 \SpecialChar ~
20173 \SpecialChar ~
20174 \SpecialChar ~
20175 \SpecialChar ~
20176 \SpecialChar ~
20177 \SpecialChar ~
20178 \SpecialChar ~
20179 \SpecialChar ~
20180 \SpecialChar ~
20181 \SpecialChar ~
20182 \SpecialChar ~
20183 \SpecialChar ~
20184 \SpecialChar ~
20185 \SpecialChar ~
20186 \SpecialChar ~
20187 \SpecialChar ~
20188 \SpecialChar ~
20189 \SpecialChar ~
20190 case 0: ...
20191
20192 \newline
20193 \SpecialChar ~
20194 \SpecialChar ~
20195 \SpecialChar ~
20196 case 5: ...\SpecialChar ~
20197 \SpecialChar ~
20198 \SpecialChar ~
20199 \SpecialChar ~
20200 \SpecialChar ~
20201 \SpecialChar ~
20202 \SpecialChar ~
20203 \SpecialChar ~
20204 \SpecialChar ~
20205 \SpecialChar ~
20206 \SpecialChar ~
20207 \SpecialChar ~
20208 \SpecialChar ~
20209 \SpecialChar ~
20210 \SpecialChar ~
20211 \SpecialChar ~
20212 \SpecialChar ~
20213 \SpecialChar ~
20214 \SpecialChar ~
20215 \SpecialChar ~
20216 \SpecialChar ~
20217 \SpecialChar ~
20218 \SpecialChar ~
20219 \SpecialChar ~
20220 \SpecialChar ~
20221 \SpecialChar ~
20222 case 1: ...
20223
20224 \newline
20225 \SpecialChar ~
20226 \SpecialChar ~
20227 \SpecialChar ~
20228 case 3: ...\SpecialChar ~
20229 \SpecialChar ~
20230 \SpecialChar ~
20231 \SpecialChar ~
20232 \SpecialChar ~
20233 \SpecialChar ~
20234 \SpecialChar ~
20235 \SpecialChar ~
20236 \SpecialChar ~
20237 \SpecialChar ~
20238 \SpecialChar ~
20239 \SpecialChar ~
20240 \SpecialChar ~
20241 \SpecialChar ~
20242 \SpecialChar ~
20243 \SpecialChar ~
20244 \SpecialChar ~
20245 \SpecialChar ~
20246 \SpecialChar ~
20247 \SpecialChar ~
20248 \SpecialChar ~
20249 \SpecialChar ~
20250 \SpecialChar ~
20251 \SpecialChar ~
20252 \SpecialChar ~
20253 \SpecialChar ~
20254
20255 \newline
20256 \SpecialChar ~
20257 \SpecialChar ~
20258 \SpecialChar ~
20259 case 6: ...\SpecialChar ~
20260 \SpecialChar ~
20261 \SpecialChar ~
20262 \SpecialChar ~
20263 \SpecialChar ~
20264 \SpecialChar ~
20265 \SpecialChar ~
20266 \SpecialChar ~
20267 \SpecialChar ~
20268 \SpecialChar ~
20269 \SpecialChar ~
20270 \SpecialChar ~
20271 \SpecialChar ~
20272 \SpecialChar ~
20273 \SpecialChar ~
20274 \SpecialChar ~
20275 \SpecialChar ~
20276 \SpecialChar ~
20277 \SpecialChar ~
20278 \SpecialChar ~
20279 \SpecialChar ~
20280 \SpecialChar ~
20281 \SpecialChar ~
20282 \SpecialChar ~
20283 \SpecialChar ~
20284 \SpecialChar ~
20285 case 3: ...
20286
20287 \newline
20288 \SpecialChar ~
20289 \SpecialChar ~
20290 \SpecialChar ~
20291 case 7: ...\SpecialChar ~
20292 \SpecialChar ~
20293 \SpecialChar ~
20294 \SpecialChar ~
20295 \SpecialChar ~
20296 \SpecialChar ~
20297 \SpecialChar ~
20298 \SpecialChar ~
20299 \SpecialChar ~
20300 \SpecialChar ~
20301 \SpecialChar ~
20302 \SpecialChar ~
20303 \SpecialChar ~
20304 \SpecialChar ~
20305 \SpecialChar ~
20306 \SpecialChar ~
20307 \SpecialChar ~
20308 \SpecialChar ~
20309 \SpecialChar ~
20310 \SpecialChar ~
20311 \SpecialChar ~
20312 \SpecialChar ~
20313 \SpecialChar ~
20314 \SpecialChar ~
20315 \SpecialChar ~
20316 \SpecialChar ~
20317 case 4: ...
20318
20319 \newline
20320 \SpecialChar ~
20321 \SpecialChar ~
20322 \SpecialChar ~
20323 case 8: ...\SpecialChar ~
20324 \SpecialChar ~
20325 \SpecialChar ~
20326 \SpecialChar ~
20327 \SpecialChar ~
20328 \SpecialChar ~
20329 \SpecialChar ~
20330 \SpecialChar ~
20331 \SpecialChar ~
20332 \SpecialChar ~
20333 \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 case 5: ...
20350
20351 \newline
20352 \SpecialChar ~
20353 \SpecialChar ~
20354 \SpecialChar ~
20355 case 9: ...\SpecialChar ~
20356 \SpecialChar ~
20357 \SpecialChar ~
20358 \SpecialChar ~
20359 \SpecialChar ~
20360 \SpecialChar ~
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 case 6: ...
20382
20383 \newline
20384 \SpecialChar ~
20385 \SpecialChar ~
20386 \SpecialChar ~
20387 case 10: ...\SpecialChar ~
20388 \SpecialChar ~
20389 \SpecialChar ~
20390 \SpecialChar ~
20391 \SpecialChar ~
20392 \SpecialChar ~
20393 \SpecialChar ~
20394 \SpecialChar ~
20395 \SpecialChar ~
20396 \SpecialChar ~
20397 \SpecialChar ~
20398 \SpecialChar ~
20399 \SpecialChar ~
20400 \SpecialChar ~
20401 \SpecialChar ~
20402 \SpecialChar ~
20403 \SpecialChar ~
20404 \SpecialChar ~
20405 \SpecialChar ~
20406 \SpecialChar ~
20407 \SpecialChar ~
20408 \SpecialChar ~
20409 \SpecialChar ~
20410 \SpecialChar ~
20411 \SpecialChar ~
20412 case 7: ...
20413
20414 \newline
20415 \SpecialChar ~
20416 \SpecialChar ~
20417 \SpecialChar ~
20418 case 11: ...\SpecialChar ~
20419 \SpecialChar ~
20420 \SpecialChar ~
20421 \SpecialChar ~
20422 \SpecialChar ~
20423 \SpecialChar ~
20424 \SpecialChar ~
20425 \SpecialChar ~
20426 \SpecialChar ~
20427 \SpecialChar ~
20428 \SpecialChar ~
20429 \SpecialChar ~
20430 \SpecialChar ~
20431 \SpecialChar ~
20432 \SpecialChar ~
20433 \SpecialChar ~
20434 \SpecialChar ~
20435 \SpecialChar ~
20436 \SpecialChar ~
20437 \SpecialChar ~
20438 \SpecialChar ~
20439 \SpecialChar ~
20440 \SpecialChar ~
20441 \SpecialChar ~
20442 \SpecialChar ~
20443 case 8: ...
20444
20445 \newline
20446 }\SpecialChar ~
20447 \SpecialChar ~
20448 \SpecialChar ~
20449 \SpecialChar ~
20450 \SpecialChar ~
20451 \SpecialChar ~
20452 \SpecialChar ~
20453 \SpecialChar ~
20454 \SpecialChar ~
20455 \SpecialChar ~
20456 \SpecialChar ~
20457 \SpecialChar ~
20458 \SpecialChar ~
20459 \SpecialChar ~
20460 \SpecialChar ~
20461 \SpecialChar ~
20462 \SpecialChar ~
20463 \SpecialChar ~
20464 \SpecialChar ~
20465 \SpecialChar ~
20466 \SpecialChar ~
20467 \SpecialChar ~
20468 \SpecialChar ~
20469 \SpecialChar ~
20470 \SpecialChar ~
20471 \SpecialChar ~
20472 \SpecialChar ~
20473 \SpecialChar ~
20474 \SpecialChar ~
20475 \SpecialChar ~
20476 \SpecialChar ~
20477 \SpecialChar ~
20478 \SpecialChar ~
20479 \SpecialChar ~
20480 \SpecialChar ~
20481 \SpecialChar ~
20482 }
20483 \layout Standard
20484
20485 Both the above switch statements will be implemented using a jump-table.
20486  The example to the right side is slightly more efficient as the check for
20487  the lower boundary of the jump-table is not needed.
20488 \end_deeper
20489 \layout Itemize
20490
20491 The number of case labels is not larger than supported by the target architectur
20492 e.
20493 \layout Itemize
20494
20495 If the case labels are not in numerical sequence ('gaps' between cases)
20496  SDCC checks whether a jump table with additionally inserted dummy cases
20497  is still attractive.
20498
20499 \layout Itemize
20500
20501 If the starting number is not zero and a check for the lower boundary of
20502  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
20503  ...
20504  .
20505 \layout Standard
20506
20507 Switch statements which have large gaps in the numeric sequence or those
20508  that have too many case labels can be split into more than one switch statement
20509  for efficient code generation, e.g.:
20510 \layout Verse
20511
20512
20513 \family typewriter
20514 switch (i) {
20515 \newline
20516 \SpecialChar ~
20517 \SpecialChar ~
20518 case 1: ...
20519
20520 \newline
20521 \SpecialChar ~
20522 \SpecialChar ~
20523 case 2: ...
20524
20525 \newline
20526 \SpecialChar ~
20527 \SpecialChar ~
20528 case 3: ...
20529
20530 \newline
20531 \SpecialChar ~
20532 \SpecialChar ~
20533 case 4: ...
20534
20535 \newline
20536 \SpecialChar ~
20537 \SpecialChar ~
20538 case 5: ...
20539
20540 \newline
20541 \SpecialChar ~
20542 \SpecialChar ~
20543 case 6: ...
20544
20545 \newline
20546 \SpecialChar ~
20547 \SpecialChar ~
20548 case 7: ...
20549
20550 \newline
20551 \SpecialChar ~
20552 \SpecialChar ~
20553 case 101: ...
20554
20555 \newline
20556 \SpecialChar ~
20557 \SpecialChar ~
20558 case 102: ...
20559
20560 \newline
20561 \SpecialChar ~
20562 \SpecialChar ~
20563 case 103: ...
20564
20565 \newline
20566 \SpecialChar ~
20567 \SpecialChar ~
20568 case 104: ...
20569
20570 \newline
20571 \SpecialChar ~
20572 \SpecialChar ~
20573 case 105: ...
20574
20575 \newline
20576 \SpecialChar ~
20577 \SpecialChar ~
20578 case 106: ...
20579
20580 \newline
20581 \SpecialChar ~
20582 \SpecialChar ~
20583 case 107: ...
20584
20585 \newline
20586 }
20587 \layout Standard
20588
20589 If the above switch statement is broken down into two switch statements
20590 \layout Verse
20591
20592
20593 \family typewriter
20594 switch (i) {
20595 \newline
20596 \SpecialChar ~
20597 \SpecialChar ~
20598 case 1: ...
20599
20600 \newline
20601 \SpecialChar ~
20602 \SpecialChar ~
20603 case 2: ...
20604
20605 \newline
20606 \SpecialChar ~
20607 \SpecialChar ~
20608 case 3: ...
20609
20610 \newline
20611 \SpecialChar ~
20612 \SpecialChar ~
20613 case 4: ...
20614
20615 \newline
20616 \SpecialChar ~
20617 \SpecialChar ~
20618 case 5: ...
20619
20620 \newline
20621 \SpecialChar ~
20622 \SpecialChar ~
20623 case 6: ...
20624
20625 \newline
20626 \SpecialChar ~
20627 \SpecialChar ~
20628 case 7: ...
20629
20630 \newline
20631 }
20632 \layout Standard
20633
20634 and
20635 \layout Verse
20636
20637
20638 \family typewriter
20639 switch (i) {
20640 \newline
20641 \SpecialChar ~
20642 \SpecialChar ~
20643 case 101: ...
20644
20645 \newline
20646 \SpecialChar ~
20647 \SpecialChar ~
20648 case 102: ...
20649
20650 \newline
20651 \SpecialChar ~
20652 \SpecialChar ~
20653 case 103: ...
20654
20655 \newline
20656 \SpecialChar ~
20657 \SpecialChar ~
20658 case 104: ...
20659
20660 \newline
20661 \SpecialChar ~
20662 \SpecialChar ~
20663 case 105: ...
20664
20665 \newline
20666 \SpecialChar ~
20667 \SpecialChar ~
20668 case 106: ...
20669
20670 \newline
20671 \SpecialChar ~
20672 \SpecialChar ~
20673 case 107: ...
20674
20675 \newline
20676 }
20677 \layout Standard
20678
20679 then both the switch statements will be implemented using jump-tables whereas
20680  the unmodified switch statement will not be.
20681 \layout Comment
20682
20683 There might be reasons which SDCC cannot know about to either favour or
20684  not favour jump tables.
20685  If the target system has to be as quick for the last switch case as for
20686  the first (pro jump table), or if the switch argument is known to be zero
20687  in the majority of the cases (contra jump table).
20688 \layout Standard
20689
20690 The pragma nojtbound
20691 \begin_inset LatexCommand \index{\#pragma nojtbound}
20692
20693 \end_inset
20694
20695  can be used to turn off checking the
20696 \emph on
20697 j
20698 \emph default
20699 ump
20700 \emph on
20701 t
20702 \emph default
20703 able
20704 \emph on
20705 bound
20706 \emph default
20707 aries.
20708  It has no effect if a default label is supplied.
20709  Use of this pragma is dangerous: if the switch argument is not matched
20710  by a case statement the processor will happily jump into Nirvana.
20711 \layout Subsection
20712
20713 Bit-shifting Operations
20714 \begin_inset LatexCommand \index{Bit shifting}
20715
20716 \end_inset
20717
20718 .
20719 \layout Standard
20720
20721 Bit shifting is one of the most frequently used operation in embedded programmin
20722 g.
20723  SDCC tries to implement bit-shift operations in the most efficient way
20724  possible, e.g.:
20725 \layout Verse
20726
20727
20728 \family typewriter
20729 unsigned char i;
20730 \newline
20731 ...
20732
20733 \newline
20734 i >>= 4;
20735 \newline
20736 ...
20737 \layout Standard
20738
20739 generates the following code:
20740 \layout Verse
20741
20742
20743 \family typewriter
20744 mov\SpecialChar ~
20745  a,_i
20746 \newline
20747 swap a
20748 \newline
20749 anl\SpecialChar ~
20750  a,#0x0f
20751 \newline
20752 mov\SpecialChar ~
20753  _i,a
20754 \layout Standard
20755
20756 In general SDCC will never setup a loop if the shift count is known.
20757  Another example:
20758 \layout Verse
20759
20760
20761 \family typewriter
20762 unsigned int i;
20763 \newline
20764 ...
20765
20766 \newline
20767 i >>= 9;
20768 \newline
20769 ...
20770 \layout Standard
20771
20772 will generate:
20773 \layout Verse
20774
20775
20776 \family typewriter
20777 mov\SpecialChar ~
20778 \SpecialChar ~
20779 a,(_i + 1)
20780 \newline
20781 mov\SpecialChar ~
20782 \SpecialChar ~
20783 (_i + 1),#0x00
20784 \newline
20785 clr\SpecialChar ~
20786 \SpecialChar ~
20787 c
20788 \newline
20789 rrc\SpecialChar ~
20790 \SpecialChar ~
20791 a
20792 \newline
20793 mov\SpecialChar ~
20794 \SpecialChar ~
20795 _i,a
20796 \layout Subsection
20797
20798 Bit-rotation
20799 \begin_inset LatexCommand \index{Bit rotation}
20800
20801 \end_inset
20802
20803
20804 \layout Standard
20805
20806 A special case of the bit-shift operation is bit rotation
20807 \begin_inset LatexCommand \index{rotating bits}
20808
20809 \end_inset
20810
20811 , SDCC recognizes the following expression to be a left bit-rotation:
20812 \layout Verse
20813
20814
20815 \family typewriter
20816 \series bold
20817 unsigned
20818 \series default
20819 \SpecialChar ~
20820 \SpecialChar ~
20821 char i;\SpecialChar ~
20822 \SpecialChar ~
20823 \SpecialChar ~
20824 \SpecialChar ~
20825 \SpecialChar ~
20826 \SpecialChar ~
20827 \SpecialChar ~
20828 \SpecialChar ~
20829 \SpecialChar ~
20830 \SpecialChar ~
20831 \SpecialChar ~
20832 /* unsigned is needed for rotation */
20833 \newline
20834 ...
20835
20836 \newline
20837 i = ((i << 1) | (i >> 7));
20838 \family default
20839
20840 \newline
20841
20842 \family typewriter
20843 ...
20844 \layout Standard
20845
20846 will generate the following code:
20847 \layout Verse
20848
20849
20850 \family typewriter
20851 mov\SpecialChar ~
20852 \SpecialChar ~
20853 a,_i
20854 \newline
20855 rl\SpecialChar ~
20856 \SpecialChar ~
20857 \SpecialChar ~
20858 a
20859 \newline
20860 mov\SpecialChar ~
20861 \SpecialChar ~
20862 _i,a
20863 \layout Standard
20864
20865 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
20866 ns of this case will also be recognized as bit-rotation, i.e.:
20867 \layout Verse
20868
20869
20870 \family typewriter
20871 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
20872 \layout Subsection
20873
20874 Nibble and Byte Swapping
20875 \layout Standard
20876
20877 Other special cases of the bit-shift operations are nibble or byte swapping
20878 \begin_inset LatexCommand \index{swapping nibbles/bytes}
20879
20880 \end_inset
20881
20882 , SDCC recognizes the following expressions:
20883 \layout Verse
20884
20885
20886 \family typewriter
20887 \series bold
20888 unsigned
20889 \series default
20890 \SpecialChar ~
20891 \SpecialChar ~
20892 char i;
20893 \newline
20894
20895 \series bold
20896 unsigned
20897 \series default
20898 \SpecialChar ~
20899 \SpecialChar ~
20900 int j;
20901 \newline
20902 ...
20903
20904 \newline
20905 i = ((i << 4) | (i >> 4));
20906 \family default
20907
20908 \newline
20909
20910 \family typewriter
20911 j = ((j << 8) | (j >> 8));
20912 \layout Standard
20913
20914 and generates a swap instruction for the nibble swapping
20915 \begin_inset LatexCommand \index{Nibble swapping}
20916
20917 \end_inset
20918
20919  or move instructions for the byte swapping
20920 \begin_inset LatexCommand \index{Byte swapping}
20921
20922 \end_inset
20923
20924 .
20925  The
20926 \begin_inset Quotes sld
20927 \end_inset
20928
20929 j
20930 \begin_inset Quotes srd
20931 \end_inset
20932
20933  example can be used to convert from little to big-endian or vice versa.
20934  If you want to change the endianness of a
20935 \emph on
20936 signed
20937 \emph default
20938  integer you have to cast to
20939 \family typewriter
20940 (unsigned int)
20941 \family default
20942  first.
20943 \layout Standard
20944
20945 Note that SDCC stores numbers in little-endian
20946 \begin_inset Foot
20947 collapsed false
20948
20949 \layout Standard
20950
20951 Usually 8-bit processors don't care much about endianness.
20952  This is not the case for the standard 8051 which only has an instruction
20953  to increment its
20954 \emph on
20955 dptr
20956 \emph default
20957
20958 \begin_inset LatexCommand \index{DPTR}
20959
20960 \end_inset
20961
20962 -datapointer
20963 \emph on
20964
20965 \emph default
20966 so little-endian is the more efficient byte order.
20967 \end_inset
20968
20969
20970 \begin_inset LatexCommand \index{little-endian}
20971
20972 \end_inset
20973
20974
20975 \begin_inset LatexCommand \index{Endianness}
20976
20977 \end_inset
20978
20979  format (i.e.
20980  lowest order first).
20981 \layout Subsection
20982
20983 Highest Order Bit
20984 \begin_inset LatexCommand \index{Highest Order Bit}
20985
20986 \end_inset
20987
20988
20989 \layout Standard
20990
20991 It is frequently required to obtain the highest order bit of an integral
20992  type (long, int, short or char types).
20993  SDCC recognizes the following expression to yield the highest order bit
20994  and generates optimized code for it, e.g.:
20995 \layout Verse
20996
20997
20998 \family typewriter
20999 unsigned int gint;
21000 \newline
21001
21002 \newline
21003 foo () {
21004 \newline
21005 \SpecialChar ~
21006 \SpecialChar ~
21007 unsigned char hob;
21008 \newline
21009 \SpecialChar ~
21010 \SpecialChar ~
21011 ...
21012
21013 \newline
21014 \SpecialChar ~
21015 \SpecialChar ~
21016 hob = (gint >> 15) & 1;
21017 \newline
21018 \SpecialChar ~
21019 \SpecialChar ~
21020 ..
21021
21022 \newline
21023 }
21024 \layout Standard
21025
21026 will generate the following code:
21027 \layout Verse
21028
21029
21030 \family typewriter
21031 \SpecialChar ~
21032 \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 \SpecialChar ~
21048 \SpecialChar ~
21049 \SpecialChar ~
21050 \SpecialChar ~
21051 \SpecialChar ~
21052 \SpecialChar ~
21053 \SpecialChar ~
21054 \SpecialChar ~
21055 \SpecialChar ~
21056  61 ;\SpecialChar ~
21057  hob.c 7
21058 \newline
21059 000A E5*01\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  62\SpecialChar ~
21075 \SpecialChar ~
21076 \SpecialChar ~
21077 \SpecialChar ~
21078 \SpecialChar ~
21079 \SpecialChar ~
21080 \SpecialChar ~
21081 \SpecialChar ~
21082  mov\SpecialChar ~
21083 \SpecialChar ~
21084  a,(_gint + 1)
21085 \newline
21086 000C 23\SpecialChar ~
21087 \SpecialChar ~
21088 \SpecialChar ~
21089 \SpecialChar ~
21090 \SpecialChar ~
21091 \SpecialChar ~
21092 \SpecialChar ~
21093 \SpecialChar ~
21094 \SpecialChar ~
21095 \SpecialChar ~
21096 \SpecialChar ~
21097 \SpecialChar ~
21098 \SpecialChar ~
21099 \SpecialChar ~
21100 \SpecialChar ~
21101 \SpecialChar ~
21102 \SpecialChar ~
21103 \SpecialChar ~
21104  63\SpecialChar ~
21105 \SpecialChar ~
21106 \SpecialChar ~
21107 \SpecialChar ~
21108 \SpecialChar ~
21109 \SpecialChar ~
21110 \SpecialChar ~
21111 \SpecialChar ~
21112  rl\SpecialChar ~
21113 \SpecialChar ~
21114 \SpecialChar ~
21115  a
21116 \newline
21117 000D 54 01\SpecialChar ~
21118 \SpecialChar ~
21119 \SpecialChar ~
21120 \SpecialChar ~
21121 \SpecialChar ~
21122 \SpecialChar ~
21123 \SpecialChar ~
21124 \SpecialChar ~
21125 \SpecialChar ~
21126 \SpecialChar ~
21127 \SpecialChar ~
21128 \SpecialChar ~
21129 \SpecialChar ~
21130 \SpecialChar ~
21131 \SpecialChar ~
21132  64\SpecialChar ~
21133 \SpecialChar ~
21134 \SpecialChar ~
21135 \SpecialChar ~
21136 \SpecialChar ~
21137 \SpecialChar ~
21138 \SpecialChar ~
21139 \SpecialChar ~
21140  anl\SpecialChar ~
21141 \SpecialChar ~
21142  a,#0x01
21143 \newline
21144 000F F5*02\SpecialChar ~
21145 \SpecialChar ~
21146 \SpecialChar ~
21147 \SpecialChar ~
21148 \SpecialChar ~
21149 \SpecialChar ~
21150 \SpecialChar ~
21151 \SpecialChar ~
21152 \SpecialChar ~
21153 \SpecialChar ~
21154 \SpecialChar ~
21155 \SpecialChar ~
21156 \SpecialChar ~
21157 \SpecialChar ~
21158 \SpecialChar ~
21159  65\SpecialChar ~
21160 \SpecialChar ~
21161 \SpecialChar ~
21162 \SpecialChar ~
21163 \SpecialChar ~
21164 \SpecialChar ~
21165 \SpecialChar ~
21166 \SpecialChar ~
21167  mov\SpecialChar ~
21168 \SpecialChar ~
21169  _foo_hob_1_1,a
21170 \layout Standard
21171
21172 Variations of this case however will
21173 \emph on
21174 not
21175 \emph default
21176  be recognized.
21177  It is a standard C expression, so I heartily recommend this be the only
21178  way to get the highest order bit, (it is portable).
21179  Of course it will be recognized even if it is embedded in other expressions,
21180  e.g.:
21181 \layout Verse
21182
21183
21184 \family typewriter
21185 xyz = gint + ((gint >> 15) & 1);
21186 \layout Standard
21187
21188 will still be recognized.
21189 \layout Subsection
21190
21191 Peephole Optimizer
21192 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
21193
21194 \end_inset
21195
21196
21197 \begin_inset LatexCommand \index{Peephole optimizer}
21198
21199 \end_inset
21200
21201
21202 \layout Standard
21203
21204 The compiler uses a rule based, pattern matching and re-writing mechanism
21205  for peep-hole optimization.
21206  It is inspired by
21207 \emph on
21208 copt
21209 \emph default
21210  a peep-hole optimizer by Christopher W.
21211  Fraser (cwfraser@microsoft.com).
21212  A default set of rules are compiled into the compiler, additional rules
21213  may be added with the
21214 \emph on
21215 -
21216 \begin_inset ERT
21217 status Collapsed
21218
21219 \layout Standard
21220
21221 \backslash
21222 /
21223 \end_inset
21224
21225 -peep-file
21226 \begin_inset LatexCommand \index{-\/-peep-file}
21227
21228 \end_inset
21229
21230  <filename>
21231 \emph default
21232  option.
21233  The rule language is best illustrated with examples.
21234 \layout Verse
21235
21236
21237 \family typewriter
21238 replace {
21239 \newline
21240 \SpecialChar ~
21241 \SpecialChar ~
21242 mov %1,a
21243 \newline
21244 \SpecialChar ~
21245 \SpecialChar ~
21246 mov a,%1
21247 \newline
21248 } by {
21249 \newline
21250 \SpecialChar ~
21251 \SpecialChar ~
21252 mov %1,a
21253 \newline
21254 }
21255 \layout Standard
21256
21257 The above rule will change the following assembly
21258 \begin_inset LatexCommand \index{Assembler routines}
21259
21260 \end_inset
21261
21262  sequence:
21263 \layout Verse
21264
21265
21266 \family typewriter
21267 mov r1,a
21268 \newline
21269 mov a,r1
21270 \layout Standard
21271
21272 to
21273 \layout Verse
21274
21275
21276 \family typewriter
21277 mov r1,a
21278 \layout Standard
21279
21280 Note: All occurrences of a
21281 \emph on
21282 %n
21283 \emph default
21284  (pattern variable) must denote the same string.
21285  With the above rule, the assembly sequence:
21286 \layout Verse
21287
21288
21289 \family typewriter
21290 mov r1,a
21291 \newline
21292 mov a,r2
21293 \layout Standard
21294
21295 will remain unmodified.
21296 \newline
21297
21298 \newline
21299 Other special case optimizations may be added by the user (via
21300 \emph on
21301 -
21302 \begin_inset ERT
21303 status Collapsed
21304
21305 \layout Standard
21306
21307 \backslash
21308 /
21309 \end_inset
21310
21311 -peep-file option
21312 \emph default
21313 ).
21314  E.g.
21315  some variants of the 8051 MCU
21316 \begin_inset LatexCommand \index{MCS51 variants}
21317
21318 \end_inset
21319
21320  allow only
21321 \family typewriter
21322 ajmp
21323 \family default
21324  and
21325 \family typewriter
21326 acall
21327 \family default
21328 .
21329  The following two rules will change all
21330 \family typewriter
21331 ljmp
21332 \family default
21333  and
21334 \family typewriter
21335 lcall
21336 \family default
21337  to
21338 \family typewriter
21339 ajmp
21340 \family default
21341  and
21342 \family typewriter
21343 acall
21344 \layout Verse
21345
21346
21347 \family typewriter
21348 replace { lcall %1 } by { acall %1 }
21349 \newline
21350 replace { ljmp %1 } by { ajmp %1 }
21351 \layout Standard
21352
21353 The
21354 \emph on
21355 inline-assembler code
21356 \emph default
21357  is also passed through the peep hole optimizer, thus the peephole optimizer
21358  can also be used as an assembly level macro expander.
21359  The rules themselves are MCU dependent whereas the rule language infra-structur
21360 e is MCU independent.
21361  Peephole optimization rules for other MCU can be easily programmed using
21362  the rule language.
21363 \newline
21364
21365 \newline
21366 The syntax for a rule is as follows:
21367 \layout Verse
21368
21369
21370 \family typewriter
21371 rule := replace [ restart ] '{' <assembly sequence> '
21372 \backslash
21373 n'
21374 \newline
21375 \SpecialChar ~
21376  \SpecialChar ~
21377  \SpecialChar ~
21378  \SpecialChar ~
21379  \SpecialChar ~
21380  \SpecialChar ~
21381  \SpecialChar ~
21382  \SpecialChar ~
21383  \SpecialChar ~
21384  \SpecialChar ~
21385  \SpecialChar ~
21386  \SpecialChar ~
21387  \SpecialChar ~
21388  \SpecialChar ~
21389  '}' by '{' '
21390 \backslash
21391 n'
21392 \newline
21393 \SpecialChar ~
21394  \SpecialChar ~
21395  \SpecialChar ~
21396  \SpecialChar ~
21397  \SpecialChar ~
21398  \SpecialChar ~
21399  \SpecialChar ~
21400  \SpecialChar ~
21401  \SpecialChar ~
21402  \SpecialChar ~
21403  \SpecialChar ~
21404  \SpecialChar ~
21405  \SpecialChar ~
21406  \SpecialChar ~
21407  \SpecialChar ~
21408  \SpecialChar ~
21409  <assembly sequence> '
21410 \backslash
21411 n'
21412 \newline
21413 \SpecialChar ~
21414  \SpecialChar ~
21415  \SpecialChar ~
21416  \SpecialChar ~
21417  \SpecialChar ~
21418  \SpecialChar ~
21419  \SpecialChar ~
21420  \SpecialChar ~
21421  \SpecialChar ~
21422  \SpecialChar ~
21423  \SpecialChar ~
21424  \SpecialChar ~
21425  \SpecialChar ~
21426  \SpecialChar ~
21427  '}' [if <functionName> ] '
21428 \backslash
21429 n'
21430 \layout Standard
21431
21432 <assembly sequence> := assembly instruction (each instruction including
21433  labels must be on a separate line).
21434 \newline
21435
21436 \newline
21437 The optimizer will apply to the rules one by one from the top in the sequence
21438  of their appearance, it will terminate when all rules are exhausted.
21439  If the 'restart' option is specified, then the optimizer will start matching
21440  the rules again from the top, this option for a rule is expensive (performance)
21441 , it is intended to be used in situations where a transformation will trigger
21442  the same rule again.
21443  An example of this (not a good one, it has side effects) is the following
21444  rule:
21445 \layout Verse
21446
21447
21448 \family typewriter
21449 replace restart {
21450 \newline
21451 \SpecialChar ~
21452 \SpecialChar ~
21453 pop %1
21454 \newline
21455 \SpecialChar ~
21456 \SpecialChar ~
21457 push %1 } by {
21458 \newline
21459 \SpecialChar ~
21460 \SpecialChar ~
21461 ; nop
21462 \newline
21463 }
21464 \layout Standard
21465
21466 Note that the replace pattern cannot be a blank, but can be a comment line.
21467  Without the 'restart' option only the innermost 'pop' 'push' pair would
21468  be eliminated, i.e.:
21469 \layout Verse
21470
21471
21472 \family typewriter
21473 pop ar1
21474 \newline
21475 pop ar2
21476 \newline
21477 push ar2
21478 \newline
21479 push ar1
21480 \layout Standard
21481
21482 would result in:
21483 \layout Verse
21484
21485
21486 \family typewriter
21487 pop ar1
21488 \newline
21489 ; nop
21490 \newline
21491 push ar1
21492 \layout Standard
21493
21494
21495 \emph on
21496 with
21497 \emph default
21498  the restart option the rule will be applied again to the resulting code
21499  and then all the pop-push pairs will be eliminated to yield:
21500 \layout Verse
21501
21502
21503 \family typewriter
21504 ; nop
21505 \newline
21506 ; nop
21507 \layout Standard
21508
21509 A conditional function can be attached to a rule.
21510  Attaching rules are somewhat more involved, let me illustrate this with
21511  an example.
21512 \layout Verse
21513
21514
21515 \family typewriter
21516 replace {
21517 \newline
21518 \SpecialChar ~
21519  \SpecialChar ~
21520  \SpecialChar ~
21521 ljmp %5
21522 \newline
21523 %2:
21524 \newline
21525 } by {
21526 \newline
21527 \SpecialChar ~
21528  \SpecialChar ~
21529  \SpecialChar ~
21530 sjmp %5
21531 \newline
21532 %2:
21533 \newline
21534 } if labelInRange
21535 \layout Standard
21536
21537 The optimizer does a look-up of a function name table defined in function
21538
21539 \emph on
21540 callFuncByName
21541 \emph default
21542  in the source file SDCCpeeph.c, with the name
21543 \emph on
21544 labelInRange
21545 \emph default
21546 .
21547  If it finds a corresponding entry the function is called.
21548  Note there can be no parameters specified for these functions, in this
21549  case the use of
21550 \emph on
21551 %5
21552 \emph default
21553  is crucial, since the function
21554 \emph on
21555 labelInRange
21556 \emph default
21557  expects to find the label in that particular variable (the hash table containin
21558 g the variable bindings is passed as a parameter).
21559  If you want to code more such functions, take a close look at the function
21560  labelInRange and the calling mechanism in source file SDCCpeeph.c.
21561  Currently implemented are
21562 \emph on
21563 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
21564  24bitMode, portIsDS390, 24bitModeAndPortDS390
21565 \emph default
21566 and
21567 \emph on
21568  notVolatile
21569 \emph default
21570 .
21571 \layout Standard
21572
21573 I know this whole thing is a little kludgey, but maybe some day we will
21574  have some better means.
21575  If you are looking at this file, you will see the default rules that are
21576  compiled into the compiler, you can add your own rules in the default set
21577  there if you get tired of specifying the -
21578 \begin_inset ERT
21579 status Collapsed
21580
21581 \layout Standard
21582
21583 \backslash
21584 /
21585 \end_inset
21586
21587 -peep-file option.
21588 \layout Section
21589
21590 ANSI-Compliance
21591 \begin_inset LatexCommand \index{ANSI-compliance}
21592
21593 \end_inset
21594
21595
21596 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
21597
21598 \end_inset
21599
21600
21601 \layout Standard
21602
21603 Deviations from the compliance:
21604 \layout Itemize
21605
21606 functions are not always reentrant
21607 \begin_inset LatexCommand \index{reentrant}
21608
21609 \end_inset
21610
21611 .
21612 \layout Itemize
21613
21614 structures cannot be assigned values directly, cannot be passed as function
21615  parameters or assigned to each other and cannot be a return value from
21616  a function, e.g.:
21617 \begin_deeper
21618 \layout Verse
21619
21620
21621 \family typewriter
21622 struct s { ...
21623  };
21624 \newline
21625 struct s s1, s2;
21626 \newline
21627 foo()
21628 \newline
21629 {
21630 \newline
21631 \SpecialChar ~
21632 \SpecialChar ~
21633 \SpecialChar ~
21634 \SpecialChar ~
21635 ...
21636
21637 \newline
21638 \SpecialChar ~
21639 \SpecialChar ~
21640 \SpecialChar ~
21641 \SpecialChar ~
21642 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
21643 \newline
21644 \SpecialChar ~
21645 \SpecialChar ~
21646 \SpecialChar ~
21647 \SpecialChar ~
21648 ...
21649
21650 \newline
21651 }
21652 \newline
21653 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
21654  */
21655 \newline
21656 {
21657 \newline
21658 \SpecialChar ~
21659 \SpecialChar ~
21660 \SpecialChar ~
21661 \SpecialChar ~
21662 struct s rets;
21663 \newline
21664 \SpecialChar ~
21665 \SpecialChar ~
21666 \SpecialChar ~
21667 \SpecialChar ~
21668 ...
21669
21670 \newline
21671 \SpecialChar ~
21672 \SpecialChar ~
21673 \SpecialChar ~
21674 \SpecialChar ~
21675 return rets;/* is invalid in SDCC although allowed in ANSI */
21676 \newline
21677 }
21678 \end_deeper
21679 \layout Itemize
21680
21681 'long long
21682 \begin_inset LatexCommand \index{long long (not supported)}
21683
21684 \end_inset
21685
21686 ' (64 bit integers
21687 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
21688
21689 \end_inset
21690
21691 ) not supported.
21692 \layout Itemize
21693
21694 'double
21695 \begin_inset LatexCommand \index{double (not supported)}
21696
21697 \end_inset
21698
21699 ' precision floating point
21700 \begin_inset LatexCommand \index{Floating point support}
21701
21702 \end_inset
21703
21704 not supported.
21705 \layout Itemize
21706
21707 No support for setjmp
21708 \begin_inset LatexCommand \index{setjmp (not supported)}
21709
21710 \end_inset
21711
21712  and longjmp
21713 \begin_inset LatexCommand \index{longjmp (not supported)}
21714
21715 \end_inset
21716
21717  (for now).
21718 \layout Itemize
21719
21720 Old K&R style
21721 \begin_inset LatexCommand \index{K\&R style}
21722
21723 \end_inset
21724
21725  function declarations are NOT allowed.
21726 \begin_deeper
21727 \layout Verse
21728
21729
21730 \family typewriter
21731 foo(i,j) /* this old style of function declarations */
21732 \newline
21733 int i,j; /* are valid in ANSI but not valid in SDCC */
21734 \newline
21735 {
21736 \newline
21737 \SpecialChar ~
21738 \SpecialChar ~
21739 \SpecialChar ~
21740 \SpecialChar ~
21741 ...
21742
21743 \newline
21744 }
21745 \end_deeper
21746 \layout Section
21747
21748 Cyclomatic Complexity
21749 \begin_inset LatexCommand \index{Cyclomatic complexity}
21750
21751 \end_inset
21752
21753
21754 \layout Standard
21755
21756 Cyclomatic complexity of a function is defined as the number of independent
21757  paths the program can take during execution of the function.
21758  This is an important number since it defines the number test cases you
21759  have to generate to validate the function.
21760  The accepted industry standard for complexity number is 10, if the cyclomatic
21761  complexity reported by SDCC exceeds 10 you should think about simplification
21762  of the function logic.
21763  Note that the complexity level is not related to the number of lines of
21764  code in a function.
21765  Large functions can have low complexity, and small functions can have large
21766  complexity levels.
21767
21768 \newline
21769
21770 \newline
21771 SDCC uses the following formula to compute the complexity:
21772 \newline
21773
21774 \layout Standard
21775
21776 complexity = (number of edges in control flow graph) - (number of nodes
21777  in control flow graph) + 2;
21778 \newline
21779
21780 \newline
21781 Having said that the industry standard is 10, you should be aware that in
21782  some cases it be may unavoidable to have a complexity level of less than
21783  10.
21784  For example if you have switch statement with more than 10 case labels,
21785  each case label adds one to the complexity level.
21786  The complexity level is by no means an absolute measure of the algorithmic
21787  complexity of the function, it does however provide a good starting point
21788  for which functions you might look at for further optimization.
21789 \layout Section
21790
21791 Retargetting for other Processors
21792 \layout Standard
21793
21794 The issues for retargetting the compiler are far too numerous to be covered
21795  by this document.
21796  What follows is a brief description of each of the seven phases of the
21797  compiler and its MCU dependency.
21798 \layout Itemize
21799
21800 Parsing the source and building the annotated parse tree.
21801  This phase is largely MCU independent (except for the language extensions).
21802  Syntax & semantic checks are also done in this phase, along with some initial
21803  optimizations like back patching labels and the pattern matching optimizations
21804  like bit-rotation etc.
21805 \layout Itemize
21806
21807 The second phase involves generating an intermediate code which can be easy
21808  manipulated during the later phases.
21809  This phase is entirely MCU independent.
21810  The intermediate code generation assumes the target machine has unlimited
21811  number of registers, and designates them with the name iTemp.
21812  The compiler can be made to dump a human readable form of the code generated
21813  by using the -
21814 \begin_inset ERT
21815 status Collapsed
21816
21817 \layout Standard
21818
21819 \backslash
21820 /
21821 \end_inset
21822
21823 -dumpraw option.
21824 \layout Itemize
21825
21826 This phase does the bulk of the standard optimizations and is also MCU independe
21827 nt.
21828  This phase can be broken down into several sub-phases:
21829 \newline
21830
21831 \newline
21832 Break down intermediate code (iCode) into basic blocks.
21833 \newline
21834 Do control flow & data flow analysis on the basic blocks.
21835 \newline
21836 Do local common subexpression elimination, then global subexpression elimination
21837 \newline
21838 Dead code elimination
21839 \newline
21840 Loop optimizations
21841 \newline
21842 If loop optimizations caused any changes then do 'global subexpression eliminati
21843 on' and 'dead code elimination' again.
21844 \layout Itemize
21845
21846 This phase determines the live-ranges; by live range I mean those iTemp
21847  variables defined by the compiler that still survive after all the optimization
21848 s.
21849  Live range analysis
21850 \begin_inset LatexCommand \index{Live range analysis}
21851
21852 \end_inset
21853
21854  is essential for register allocation, since these computation determines
21855  which of these iTemps will be assigned to registers, and for how long.
21856 \layout Itemize
21857
21858 Phase five is register allocation.
21859  There are two parts to this process.
21860 \newline
21861
21862 \newline
21863 The first part I call 'register packing' (for lack of a better term).
21864  In this case several MCU specific expression folding is done to reduce
21865  register pressure.
21866 \newline
21867
21868 \newline
21869 The second part is more MCU independent and deals with allocating registers
21870  to the remaining live ranges.
21871  A lot of MCU specific code does creep into this phase because of the limited
21872  number of index registers available in the 8051.
21873 \layout Itemize
21874
21875 The Code generation phase is (unhappily), entirely MCU dependent and very
21876  little (if any at all) of this code can be reused for other MCU.
21877  However the scheme for allocating a homogenized assembler operand for each
21878  iCode operand may be reused.
21879 \layout Itemize
21880
21881 As mentioned in the optimization section the peep-hole optimizer is rule
21882  based system, which can reprogrammed for other MCUs.
21883 \layout Chapter
21884
21885 Compiler internals
21886 \begin_inset LatexCommand \index{Compiler internals}
21887
21888 \end_inset
21889
21890
21891 \layout Section
21892
21893 The anatomy of the compiler
21894 \begin_inset LatexCommand \label{sub:The-anatomy-of}
21895
21896 \end_inset
21897
21898
21899 \layout Standard
21900
21901
21902 \shape italic
21903 This is an excerpt from an article published in Circuit Cellar Magazine
21904  in august 2000.
21905  It's a little outdated (the compiler is much more efficient now and user/develo
21906 per friendly), but pretty well exposes the guts of it all.
21907 \shape default
21908
21909 \newline
21910
21911 \newline
21912 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
21913  It is fairly easy to retarget for other 8-bit MCU.
21914  Here we take a look at some of the internals of the compiler.
21915
21916 \layout Paragraph*
21917
21918 Parsing
21919 \begin_inset LatexCommand \index{Parsing}
21920
21921 \end_inset
21922
21923
21924 \layout Standard
21925
21926 Parsing the input source file and creating an AST (Annotated Syntax Tree
21927 \begin_inset LatexCommand \index{Annotated syntax tree}
21928
21929 \end_inset
21930
21931 ).
21932  This phase also involves propagating types (annotating each node of the
21933  parse tree with type information) and semantic analysis.
21934  There are some MCU specific parsing rules.
21935  For example the storage classes, the extended storage classes are MCU specific
21936  while there may be a xdata storage class for 8051 there is no such storage
21937  class for z80 or Atmel AVR.
21938  SDCC allows MCU specific storage class extensions, i.e.
21939  xdata will be treated as a storage class specifier when parsing 8051 C
21940  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
21941  C code.
21942 \layout Paragraph*
21943
21944 Generating iCode
21945 \begin_inset LatexCommand \index{iCode}
21946
21947 \end_inset
21948
21949
21950 \layout Standard
21951
21952 Intermediate code generation.
21953  In this phase the AST is broken down into three-operand form (iCode).
21954  These three operand forms are represented as doubly linked lists.
21955  ICode is the term given to the intermediate form generated by the compiler.
21956  ICode example section shows some examples of iCode generated for some simple
21957  C source functions.
21958 \layout Paragraph*
21959
21960 Optimizations
21961 \begin_inset LatexCommand \index{Optimizations}
21962
21963 \end_inset
21964
21965 .
21966 \layout Standard
21967
21968 Bulk of the target independent optimizations is performed in this phase.
21969  The optimizations include constant propagation, common sub-expression eliminati
21970 on, loop invariant code movement, strength reduction of loop induction variables
21971  and dead-code elimination.
21972 \layout Paragraph*
21973
21974 Live range analysis
21975 \begin_inset LatexCommand \index{Live range analysis}
21976
21977 \end_inset
21978
21979
21980 \layout Standard
21981
21982 During intermediate code generation phase, the compiler assumes the target
21983  machine has infinite number of registers and generates a lot of temporary
21984  variables.
21985  The live range computation determines the lifetime of each of these compiler-ge
21986 nerated temporaries.
21987  A picture speaks a thousand words.
21988  ICode example sections show the live range annotations for each of the
21989  operand.
21990  It is important to note here, each iCode is assigned a number in the order
21991  of its execution in the function.
21992  The live ranges are computed in terms of these numbers.
21993  The from number is the number of the iCode which first defines the operand
21994  and the to number signifies the iCode which uses this operand last.
21995 \layout Paragraph*
21996
21997 Register Allocation
21998 \begin_inset LatexCommand \index{Register allocation}
21999
22000 \end_inset
22001
22002
22003 \layout Standard
22004
22005 The register allocation determines the type and number of registers needed
22006  by each operand.
22007  In most MCUs only a few registers can be used for indirect addressing.
22008  In case of 8051 for example the registers R0 & R1 can be used to indirectly
22009  address the internal ram and DPTR to indirectly address the external ram.
22010  The compiler will try to allocate the appropriate register to pointer variables
22011  if it can.
22012  ICode example section shows the operands annotated with the registers assigned
22013  to them.
22014  The compiler will try to keep operands in registers as much as possible;
22015  there are several schemes the compiler uses to do achieve this.
22016  When the compiler runs out of registers the compiler will check to see
22017  if there are any live operands which is not used or defined in the current
22018  basic block being processed, if there are any found then it will push that
22019  operand and use the registers in this block, the operand will then be popped
22020  at the end of the basic block.
22021
22022 \layout Standard
22023
22024 There are other MCU specific considerations in this phase.
22025  Some MCUs have an accumulator; very short-lived operands could be assigned
22026  to the accumulator instead of a general-purpose register.
22027 \layout Paragraph*
22028
22029 Code generation
22030 \layout Standard
22031
22032 Figure II gives a table of iCode operations supported by the compiler.
22033  The code generation involves translating these operations into corresponding
22034  assembly code for the processor.
22035  This sounds overly simple but that is the essence of code generation.
22036  Some of the iCode operations are generated on a MCU specific manner for
22037  example, the z80 port does not use registers to pass parameters so the
22038  SEND and RECV iCode operations will not be generated, and it also does
22039  not support JUMPTABLES.
22040
22041 \newline
22042
22043 \series bold
22044 \shape italic
22045 \color red
22046 <Where is Figure II?>
22047 \layout Comment
22048
22049 In the original article Figure II was announced to be downloadable on
22050 \shape italic
22051 Circuit Cellar
22052 \shape default
22053 's web site.
22054  Unfortunately it never seemed to have shown up there, so: where is Figure
22055  II?
22056 \layout Paragraph*
22057
22058 ICode Example
22059 \begin_inset LatexCommand \index{iCode}
22060
22061 \end_inset
22062
22063
22064 \layout Standard
22065
22066 This section shows some details of iCode.
22067  The example C code does not do anything useful; it is used as an example
22068  to illustrate the intermediate code generated by the compiler.
22069 \layout Verse
22070
22071
22072 \family typewriter
22073 1.\SpecialChar ~
22074 xdata int * p;
22075 \newline
22076 2.\SpecialChar ~
22077 int gint;
22078 \newline
22079 3.\SpecialChar ~
22080 /* This function does nothing useful.
22081  It is used
22082 \newline
22083 4.\SpecialChar ~
22084 \SpecialChar ~
22085 \SpecialChar ~
22086 \SpecialChar ~
22087 for the purpose of explaining iCode */
22088 \newline
22089 5.\SpecialChar ~
22090 short function (data int *x)
22091 \newline
22092 6.\SpecialChar ~
22093 {
22094 \newline
22095 7.\SpecialChar ~
22096 \SpecialChar ~
22097 \SpecialChar ~
22098 short i=10; \SpecialChar ~
22099 \SpecialChar ~
22100 /* dead initialization eliminated */
22101 \newline
22102 8.\SpecialChar ~
22103 \SpecialChar ~
22104 \SpecialChar ~
22105 short sum=10; /* dead initialization eliminated */
22106 \newline
22107 9.\SpecialChar ~
22108 \SpecialChar ~
22109 \SpecialChar ~
22110 short mul;
22111 \newline
22112 10.\SpecialChar ~
22113 \SpecialChar ~
22114 int j ;
22115 \newline
22116 11.\SpecialChar ~
22117 \SpecialChar ~
22118 while (*x) *x++ = *p++;
22119 \newline
22120 12.\SpecialChar ~
22121 \SpecialChar ~
22122 \SpecialChar ~
22123 \SpecialChar ~
22124 sum = 0 ;
22125 \newline
22126 13.\SpecialChar ~
22127 \SpecialChar ~
22128 mul = 0;
22129 \newline
22130 14.\SpecialChar ~
22131 \SpecialChar ~
22132 /* compiler detects i,j to be induction variables */
22133 \newline
22134 15.\SpecialChar ~
22135 \SpecialChar ~
22136 for (i = 0, j = 10 ; i < 10 ; i++, j
22137 \family default
22138 -
22139 \begin_inset ERT
22140 status Collapsed
22141
22142 \layout Standard
22143
22144 \backslash
22145 /
22146 \end_inset
22147
22148 -
22149 \family typewriter
22150 ) {
22151 \newline
22152 16.\SpecialChar ~
22153 \SpecialChar ~
22154 \SpecialChar ~
22155 \SpecialChar ~
22156 sum += i;
22157 \newline
22158 17.\SpecialChar ~
22159 \SpecialChar ~
22160 \SpecialChar ~
22161 \SpecialChar ~
22162 mul += i * 3; \SpecialChar ~
22163 \SpecialChar ~
22164 /* this multiplication remains */
22165 \newline
22166 18.\SpecialChar ~
22167 \SpecialChar ~
22168 \SpecialChar ~
22169 \SpecialChar ~
22170 gint += j * 3;\SpecialChar ~
22171 \SpecialChar ~
22172 /* this multiplication changed to addition */
22173 \newline
22174 19.\SpecialChar ~
22175 \SpecialChar ~
22176 }
22177 \newline
22178 20.\SpecialChar ~
22179 \SpecialChar ~
22180 return sum+mul;
22181 \newline
22182 21.\SpecialChar ~
22183 }
22184 \layout Standard
22185
22186 In addition to the operands each iCode contains information about the filename
22187  and line it corresponds to in the source file.
22188  The first field in the listing should be interpreted as follows:
22189 \newline
22190
22191 \shape italic
22192 \size footnotesize
22193 Filename(linenumber: iCode Execution sequence number : ICode hash table
22194  key : loop depth of the iCode).
22195 \shape default
22196 \size default
22197
22198 \newline
22199 Then follows the human readable form of the ICode operation.
22200  Each operand of this triplet form can be of three basic types a) compiler
22201  generated temporary b) user defined variable c) a constant value.
22202  Note that local variables and parameters are replaced by compiler generated
22203  temporaries.
22204  Live ranges
22205 \begin_inset LatexCommand \index{Live range analysis}
22206
22207 \end_inset
22208
22209  are computed only for temporaries (i.e.
22210  live ranges are not computed for global variables).
22211  Registers
22212 \begin_inset LatexCommand \index{Register allocation}
22213
22214 \end_inset
22215
22216  are allocated for temporaries only.
22217  Operands are formatted in the following manner:
22218 \newline
22219
22220 \shape italic
22221 \size footnotesize
22222 Operand Name [lr live-from : live-to ] { type information } [ registers
22223  allocated ].
22224 \shape default
22225 \size default
22226
22227 \newline
22228 As mentioned earlier the live ranges are computed in terms of the execution
22229  sequence number of the iCodes, for example
22230 \newline
22231 the iTemp0 is live from (i.e.
22232  first defined in iCode with execution sequence number 3, and is last used
22233  in the iCode with sequence number 5).
22234  For induction variables such as iTemp21 the live range computation extends
22235  the lifetime from the start to the end of the loop.
22236 \newline
22237 The register allocator used the live range information to allocate registers,
22238  the same registers may be used for different temporaries if their live
22239  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
22240  iTemp17 since their live ranges do not overlap.
22241  In addition the allocator also takes into consideration the type and usage
22242  of a temporary, for example itemp6 is a pointer to near space and is used
22243  as to fetch data from (i.e.
22244  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
22245  Some short lived temporaries are allocated to special registers which have
22246  meaning to the code generator e.g.
22247  iTemp13 is allocated to a pseudo register CC which tells the back end that
22248  the temporary is used only for a conditional jump the code generation makes
22249  use of this information to optimize a compare and jump ICode.
22250 \newline
22251 There are several loop optimizations
22252 \begin_inset LatexCommand \index{Loop optimization}
22253
22254 \end_inset
22255
22256  performed by the compiler.
22257  It can detect induction variables iTemp21(i) and iTemp23(j).
22258  Also note the compiler does selective strength reduction
22259 \begin_inset LatexCommand \index{Strength reduction}
22260
22261 \end_inset
22262
22263 , i.e.
22264  the multiplication of an induction variable in line 18 (gint = j * 3) is
22265  changed to addition, a new temporary iTemp17 is allocated and assigned
22266  a initial value, a constant 3 is then added for each iteration of the loop.
22267  The compiler does not change the multiplication
22268 \begin_inset LatexCommand \index{Multiplication}
22269
22270 \end_inset
22271
22272  in line 17 however since the processor does support an 8 * 8 bit multiplication.
22273 \newline
22274 Note the dead code elimination
22275 \begin_inset LatexCommand \index{Dead-code elimination}
22276
22277 \end_inset
22278
22279  optimization eliminated the dead assignments in line 7 & 8 to I and sum
22280  respectively.
22281 \newline
22282
22283 \layout Standard
22284
22285
22286 \size footnotesize
22287 Sample.c (5:1:0:0) _entry($9) :
22288 \layout Standard
22289
22290
22291 \size footnotesize
22292 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
22293 \layout Standard
22294
22295
22296 \size footnotesize
22297 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
22298 \layout Standard
22299
22300
22301 \size footnotesize
22302 Sample.c(11:4:53:0) preHeaderLbl0($11) :
22303 \layout Standard
22304
22305
22306 \size footnotesize
22307 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
22308  * int}[r2]
22309 \layout Standard
22310
22311
22312 \size footnotesize
22313 Sample.c(11:6:5:1) _whilecontinue_0($1) :
22314 \layout Standard
22315
22316
22317 \size footnotesize
22318 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
22319  int}[r0]]
22320 \layout Standard
22321
22322
22323 \size footnotesize
22324 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
22325 \layout Standard
22326
22327
22328 \size footnotesize
22329 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
22330  * int}
22331 \layout Standard
22332
22333
22334 \size footnotesize
22335 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
22336  {short}
22337 \layout Standard
22338
22339
22340 \size footnotesize
22341 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
22342  * int}[DPTR]]
22343 \layout Standard
22344
22345
22346 \size footnotesize
22347 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
22348 }[r2 r3]
22349 \layout Standard
22350
22351
22352 \size footnotesize
22353 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
22354  * int}[r0] + 0x2 {short}
22355 \layout Standard
22356
22357
22358 \size footnotesize
22359 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
22360 \layout Standard
22361
22362
22363 \size footnotesize
22364 Sample.c(11:17:21:0)_whilebreak_0($3) :
22365 \layout Standard
22366
22367
22368 \size footnotesize
22369 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
22370 \layout Standard
22371
22372
22373 \size footnotesize
22374 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
22375 \layout Standard
22376
22377
22378 \size footnotesize
22379 Sample.c(15:20:54:0)preHeaderLbl1($13) :
22380 \layout Standard
22381
22382
22383 \size footnotesize
22384 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
22385 \layout Standard
22386
22387
22388 \size footnotesize
22389 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
22390 \layout Standard
22391
22392
22393 \size footnotesize
22394 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
22395 \layout Standard
22396
22397
22398 \size footnotesize
22399 Sample.c(15:24:26:1)_forcond_0($4) :
22400 \layout Standard
22401
22402
22403 \size footnotesize
22404 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
22405  < 0xa {short}
22406 \layout Standard
22407
22408
22409 \size footnotesize
22410 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
22411 \layout Standard
22412
22413
22414 \size footnotesize
22415 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
22416  + ITemp21 [lr21:38]{short}[r4]
22417 \layout Standard
22418
22419
22420 \size footnotesize
22421 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
22422  * 0x3 {short}
22423 \layout Standard
22424
22425
22426 \size footnotesize
22427 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
22428  + iTemp15 [lr29:30]{short}[r1]
22429 \layout Standard
22430
22431
22432 \size footnotesize
22433 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
22434  r0]- 0x3 {short}
22435 \layout Standard
22436
22437
22438 \size footnotesize
22439 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
22440 int}[r7 r0]
22441 \layout Standard
22442
22443
22444 \size footnotesize
22445 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
22446  + 0x1 {short}
22447 \layout Standard
22448
22449
22450 \size footnotesize
22451 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
22452  r6]- 0x1 {short}
22453 \layout Standard
22454
22455
22456 \size footnotesize
22457 Sample.c(19:38:47:1) goto _forcond_0($4)
22458 \layout Standard
22459
22460
22461 \size footnotesize
22462 Sample.c(19:39:48:0)_forbreak_0($7) :
22463 \layout Standard
22464
22465
22466 \size footnotesize
22467 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
22468  + ITemp11 [lr19:40]{short}[r3]
22469 \layout Standard
22470
22471
22472 \size footnotesize
22473 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
22474 \layout Standard
22475
22476
22477 \size footnotesize
22478 Sample.c(20:42:51:0)_return($8) :
22479 \layout Standard
22480
22481
22482 \size footnotesize
22483 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
22484 \size default
22485
22486 \newline
22487
22488 \newline
22489 Finally the code generated for this function:
22490 \newline
22491
22492 \layout Standard
22493
22494
22495 \size footnotesize
22496 .area DSEG (DATA)
22497 \layout Standard
22498
22499
22500 \size footnotesize
22501 _p::
22502 \layout Standard
22503
22504
22505 \size footnotesize
22506 \SpecialChar ~
22507 \SpecialChar ~
22508 .ds 2
22509 \layout Standard
22510
22511
22512 \size footnotesize
22513 _gint::
22514 \layout Standard
22515
22516
22517 \size footnotesize
22518 \SpecialChar ~
22519 \SpecialChar ~
22520 .ds 2
22521 \layout Standard
22522
22523
22524 \size footnotesize
22525 ; sample.c 5
22526 \layout Standard
22527
22528
22529 \size footnotesize
22530 ; ----------------------------------------------
22531 \layout Standard
22532
22533
22534 \size footnotesize
22535 ; function function
22536 \layout Standard
22537
22538
22539 \size footnotesize
22540 ; ----------------------------------------------
22541 \layout Standard
22542
22543
22544 \size footnotesize
22545 _function:
22546 \layout Standard
22547
22548
22549 \size footnotesize
22550 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
22551 \layout Standard
22552
22553
22554 \size footnotesize
22555 \SpecialChar ~
22556 \SpecialChar ~
22557 mov r2,dpl
22558 \layout Standard
22559
22560
22561 \size footnotesize
22562 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
22563 \layout Standard
22564
22565
22566 \size footnotesize
22567 \SpecialChar ~
22568 \SpecialChar ~
22569 mov ar0,r2
22570 \layout Standard
22571
22572
22573 \size footnotesize
22574 ;_whilecontinue_0($1) :
22575 \layout Standard
22576
22577
22578 \size footnotesize
22579 00101$:
22580 \layout Standard
22581
22582
22583 \size footnotesize
22584 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
22585 \layout Standard
22586
22587
22588 \size footnotesize
22589 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
22590 \layout Standard
22591
22592
22593 \size footnotesize
22594 \SpecialChar ~
22595 \SpecialChar ~
22596 mov ar2,@r0
22597 \layout Standard
22598
22599
22600 \size footnotesize
22601 \SpecialChar ~
22602 \SpecialChar ~
22603 inc r0
22604 \layout Standard
22605
22606
22607 \size footnotesize
22608 \SpecialChar ~
22609 \SpecialChar ~
22610 mov ar3,@r0
22611 \layout Standard
22612
22613
22614 \size footnotesize
22615 \SpecialChar ~
22616 \SpecialChar ~
22617 dec r0
22618 \layout Standard
22619
22620
22621 \size footnotesize
22622 \SpecialChar ~
22623 \SpecialChar ~
22624 mov a,r2
22625 \layout Standard
22626
22627
22628 \size footnotesize
22629 \SpecialChar ~
22630 \SpecialChar ~
22631 orl a,r3
22632 \layout Standard
22633
22634
22635 \size footnotesize
22636 \SpecialChar ~
22637 \SpecialChar ~
22638 jz 00103$
22639 \layout Standard
22640
22641
22642 \size footnotesize
22643 00114$:
22644 \layout Standard
22645
22646
22647 \size footnotesize
22648 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
22649 \layout Standard
22650
22651
22652 \size footnotesize
22653 \SpecialChar ~
22654 \SpecialChar ~
22655 mov dpl,_p
22656 \layout Standard
22657
22658
22659 \size footnotesize
22660 \SpecialChar ~
22661 \SpecialChar ~
22662 mov dph,(_p + 1)
22663 \layout Standard
22664
22665
22666 \size footnotesize
22667 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
22668 \layout Standard
22669
22670
22671 \size footnotesize
22672 \SpecialChar ~
22673 \SpecialChar ~
22674 mov a,#0x02
22675 \layout Standard
22676
22677
22678 \size footnotesize
22679 \SpecialChar ~
22680 \SpecialChar ~
22681 add a,_p
22682 \layout Standard
22683
22684
22685 \size footnotesize
22686 \SpecialChar ~
22687 \SpecialChar ~
22688 mov _p,a
22689 \layout Standard
22690
22691
22692 \size footnotesize
22693 \SpecialChar ~
22694 \SpecialChar ~
22695 clr a
22696 \layout Standard
22697
22698
22699 \size footnotesize
22700 \SpecialChar ~
22701 \SpecialChar ~
22702 addc a,(_p + 1)
22703 \layout Standard
22704
22705
22706 \size footnotesize
22707 \SpecialChar ~
22708 \SpecialChar ~
22709 mov (_p + 1),a
22710 \layout Standard
22711
22712
22713 \size footnotesize
22714 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
22715 \layout Standard
22716
22717
22718 \size footnotesize
22719 \SpecialChar ~
22720 \SpecialChar ~
22721 movx a,@dptr
22722 \layout Standard
22723
22724
22725 \size footnotesize
22726 \SpecialChar ~
22727 \SpecialChar ~
22728 mov r2,a
22729 \layout Standard
22730
22731
22732 \size footnotesize
22733 \SpecialChar ~
22734 \SpecialChar ~
22735 inc dptr
22736 \layout Standard
22737
22738
22739 \size footnotesize
22740 \SpecialChar ~
22741 \SpecialChar ~
22742 movx a,@dptr
22743 \layout Standard
22744
22745
22746 \size footnotesize
22747 \SpecialChar ~
22748 \SpecialChar ~
22749 mov r3,a
22750 \layout Standard
22751
22752
22753 \size footnotesize
22754 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
22755 \layout Standard
22756
22757
22758 \size footnotesize
22759 \SpecialChar ~
22760 \SpecialChar ~
22761 mov @r0,ar2
22762 \layout Standard
22763
22764
22765 \size footnotesize
22766 \SpecialChar ~
22767 \SpecialChar ~
22768 inc r0
22769 \layout Standard
22770
22771
22772 \size footnotesize
22773 \SpecialChar ~
22774 \SpecialChar ~
22775 mov @r0,ar3
22776 \layout Standard
22777
22778
22779 \size footnotesize
22780 ; iTemp6 [lr5:16]{_near * int}[r0] =
22781 \layout Standard
22782
22783
22784 \size footnotesize
22785 ; iTemp6 [lr5:16]{_near * int}[r0] +
22786 \layout Standard
22787
22788
22789 \size footnotesize
22790 ; 0x2 {short}
22791 \layout Standard
22792
22793
22794 \size footnotesize
22795 \SpecialChar ~
22796 \SpecialChar ~
22797 inc r0
22798 \layout Standard
22799
22800
22801 \size footnotesize
22802 ; goto _whilecontinue_0($1)
22803 \layout Standard
22804
22805
22806 \size footnotesize
22807 \SpecialChar ~
22808 \SpecialChar ~
22809 sjmp 00101$
22810 \layout Standard
22811
22812
22813 \size footnotesize
22814 ; _whilebreak_0($3) :
22815 \layout Standard
22816
22817
22818 \size footnotesize
22819 00103$:
22820 \layout Standard
22821
22822
22823 \size footnotesize
22824 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
22825 \layout Standard
22826
22827
22828 \size footnotesize
22829 \SpecialChar ~
22830 \SpecialChar ~
22831 mov r2,#0x00
22832 \layout Standard
22833
22834
22835 \size footnotesize
22836 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
22837 \layout Standard
22838
22839
22840 \size footnotesize
22841 \SpecialChar ~
22842 \SpecialChar ~
22843 mov r3,#0x00
22844 \layout Standard
22845
22846
22847 \size footnotesize
22848 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
22849 \layout Standard
22850
22851
22852 \size footnotesize
22853 \SpecialChar ~
22854 \SpecialChar ~
22855 mov r4,#0x00
22856 \layout Standard
22857
22858
22859 \size footnotesize
22860 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
22861 \layout Standard
22862
22863
22864 \size footnotesize
22865 \SpecialChar ~
22866 \SpecialChar ~
22867 mov r5,#0x0A
22868 \layout Standard
22869
22870
22871 \size footnotesize
22872 \SpecialChar ~
22873 \SpecialChar ~
22874 mov r6,#0x00
22875 \layout Standard
22876
22877
22878 \size footnotesize
22879 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
22880 \layout Standard
22881
22882
22883 \size footnotesize
22884 \SpecialChar ~
22885 \SpecialChar ~
22886 mov r7,#0x1E
22887 \layout Standard
22888
22889
22890 \size footnotesize
22891 \SpecialChar ~
22892 \SpecialChar ~
22893 mov r0,#0x00
22894 \layout Standard
22895
22896
22897 \size footnotesize
22898 ; _forcond_0($4) :
22899 \layout Standard
22900
22901
22902 \size footnotesize
22903 00104$:
22904 \layout Standard
22905
22906
22907 \size footnotesize
22908 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
22909 \layout Standard
22910
22911
22912 \size footnotesize
22913 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
22914 \layout Standard
22915
22916
22917 \size footnotesize
22918 \SpecialChar ~
22919 \SpecialChar ~
22920 clr c
22921 \layout Standard
22922
22923
22924 \size footnotesize
22925 \SpecialChar ~
22926 \SpecialChar ~
22927 mov a,r4
22928 \layout Standard
22929
22930
22931 \size footnotesize
22932 \SpecialChar ~
22933 \SpecialChar ~
22934 xrl a,#0x80
22935 \layout Standard
22936
22937
22938 \size footnotesize
22939 \SpecialChar ~
22940 \SpecialChar ~
22941 subb a,#0x8a
22942 \layout Standard
22943
22944
22945 \size footnotesize
22946 \SpecialChar ~
22947 \SpecialChar ~
22948 jnc 00107$
22949 \layout Standard
22950
22951
22952 \size footnotesize
22953 00115$:
22954 \layout Standard
22955
22956
22957 \size footnotesize
22958 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
22959 \layout Standard
22960
22961
22962 \size footnotesize
22963 ; iTemp21 [lr21:38]{short}[r4]
22964 \layout Standard
22965
22966
22967 \size footnotesize
22968 \SpecialChar ~
22969 \SpecialChar ~
22970 mov a,r4
22971 \layout Standard
22972
22973
22974 \size footnotesize
22975 \SpecialChar ~
22976 \SpecialChar ~
22977 add a,r2
22978 \layout Standard
22979
22980
22981 \size footnotesize
22982 \SpecialChar ~
22983 \SpecialChar ~
22984 mov r2,a
22985 \layout Standard
22986
22987
22988 \size footnotesize
22989 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
22990 \layout Standard
22991
22992
22993 \size footnotesize
22994 \SpecialChar ~
22995 \SpecialChar ~
22996 mov b,#0x03
22997 \layout Standard
22998
22999
23000 \size footnotesize
23001 \SpecialChar ~
23002 \SpecialChar ~
23003 mov a,r4
23004 \layout Standard
23005
23006
23007 \size footnotesize
23008 \SpecialChar ~
23009 \SpecialChar ~
23010 mul ab
23011 \layout Standard
23012
23013
23014 \size footnotesize
23015 \SpecialChar ~
23016 \SpecialChar ~
23017 mov r1,a
23018 \layout Standard
23019
23020
23021 \size footnotesize
23022 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
23023 \layout Standard
23024
23025
23026 \size footnotesize
23027 ; iTemp15 [lr29:30]{short}[r1]
23028 \layout Standard
23029
23030
23031 \size footnotesize
23032 \SpecialChar ~
23033 \SpecialChar ~
23034 add a,r3
23035 \layout Standard
23036
23037
23038 \size footnotesize
23039 \SpecialChar ~
23040 \SpecialChar ~
23041 mov r3,a
23042 \layout Standard
23043
23044
23045 \size footnotesize
23046 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
23047 \layout Standard
23048
23049
23050 \size footnotesize
23051 \SpecialChar ~
23052 \SpecialChar ~
23053 mov a,r7
23054 \layout Standard
23055
23056
23057 \size footnotesize
23058 \SpecialChar ~
23059 \SpecialChar ~
23060 add a,#0xfd
23061 \layout Standard
23062
23063
23064 \size footnotesize
23065 \SpecialChar ~
23066 \SpecialChar ~
23067 mov r7,a
23068 \layout Standard
23069
23070
23071 \size footnotesize
23072 \SpecialChar ~
23073 \SpecialChar ~
23074 mov a,r0
23075 \layout Standard
23076
23077
23078 \size footnotesize
23079 \SpecialChar ~
23080 \SpecialChar ~
23081 addc a,#0xff
23082 \layout Standard
23083
23084
23085 \size footnotesize
23086 \SpecialChar ~
23087 \SpecialChar ~
23088 mov r0,a
23089 \layout Standard
23090
23091
23092 \size footnotesize
23093 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
23094 \layout Standard
23095
23096
23097 \size footnotesize
23098 \SpecialChar ~
23099 \SpecialChar ~
23100 mov a,r7
23101 \layout Standard
23102
23103
23104 \size footnotesize
23105 \SpecialChar ~
23106 \SpecialChar ~
23107 add a,_gint
23108 \layout Standard
23109
23110
23111 \size footnotesize
23112 \SpecialChar ~
23113 \SpecialChar ~
23114 mov _gint,a
23115 \layout Standard
23116
23117
23118 \size footnotesize
23119 \SpecialChar ~
23120 \SpecialChar ~
23121 mov a,r0
23122 \layout Standard
23123
23124
23125 \size footnotesize
23126 \SpecialChar ~
23127 \SpecialChar ~
23128 addc a,(_gint + 1)
23129 \layout Standard
23130
23131
23132 \size footnotesize
23133 \SpecialChar ~
23134 \SpecialChar ~
23135 mov (_gint + 1),a
23136 \layout Standard
23137
23138
23139 \size footnotesize
23140 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
23141 \layout Standard
23142
23143
23144 \size footnotesize
23145 \SpecialChar ~
23146 \SpecialChar ~
23147 inc r4
23148 \layout Standard
23149
23150
23151 \size footnotesize
23152 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
23153 \layout Standard
23154
23155
23156 \size footnotesize
23157 \SpecialChar ~
23158 \SpecialChar ~
23159 dec r5
23160 \layout Standard
23161
23162
23163 \size footnotesize
23164 \SpecialChar ~
23165 \SpecialChar ~
23166 cjne r5,#0xff,00104$
23167 \layout Standard
23168
23169
23170 \size footnotesize
23171 \SpecialChar ~
23172 \SpecialChar ~
23173 dec r6
23174 \layout Standard
23175
23176
23177 \size footnotesize
23178 ; goto _forcond_0($4)
23179 \layout Standard
23180
23181
23182 \size footnotesize
23183 \SpecialChar ~
23184 \SpecialChar ~
23185 sjmp 00104$
23186 \layout Standard
23187
23188
23189 \size footnotesize
23190 ; _forbreak_0($7) :
23191 \layout Standard
23192
23193
23194 \size footnotesize
23195 00107$:
23196 \layout Standard
23197
23198
23199 \size footnotesize
23200 ; ret iTemp24 [lr40:41]{short}
23201 \layout Standard
23202
23203
23204 \size footnotesize
23205 \SpecialChar ~
23206 \SpecialChar ~
23207 mov a,r3
23208 \layout Standard
23209
23210
23211 \size footnotesize
23212 \SpecialChar ~
23213 \SpecialChar ~
23214 add a,r2
23215 \layout Standard
23216
23217
23218 \size footnotesize
23219 \SpecialChar ~
23220 \SpecialChar ~
23221 mov dpl,a
23222 \layout Standard
23223
23224
23225 \size footnotesize
23226 ; _return($8) :
23227 \layout Standard
23228
23229
23230 \size footnotesize
23231 00108$:
23232 \layout Standard
23233
23234
23235 \size footnotesize
23236 \SpecialChar ~
23237 \SpecialChar ~
23238 ret
23239 \newline
23240
23241 \layout Section
23242
23243 A few words about basic block successors, predecessors and dominators
23244 \layout Standard
23245
23246 Successors are basic blocks
23247 \begin_inset LatexCommand \index{Basic blocks}
23248
23249 \end_inset
23250
23251  that might execute after this basic block.
23252 \newline
23253 Predecessors are basic blocks that might execute before reaching this basic
23254  block.
23255 \newline
23256 Dominators are basic blocks that WILL execute before reaching this basic
23257  block.
23258 \newline
23259
23260 \layout Standard
23261
23262 [basic block 1]
23263 \layout Standard
23264
23265 if (something)
23266 \layout Standard
23267
23268 \SpecialChar ~
23269 \SpecialChar ~
23270 \SpecialChar ~
23271 \SpecialChar ~
23272 [basic block 2]
23273 \layout Standard
23274
23275 else
23276 \layout Standard
23277
23278 \SpecialChar ~
23279 \SpecialChar ~
23280 \SpecialChar ~
23281 \SpecialChar ~
23282 [basic block 3]
23283 \layout Standard
23284
23285 [basic block 4]
23286 \newline
23287
23288 \layout Standard
23289
23290 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
23291 \layout Standard
23292
23293 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
23294 \layout Standard
23295
23296 c) domVect of [BB4] = BB1 ...
23297  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
23298  was executed.
23299 \layout Chapter
23300
23301 Acknowledgments
23302 \layout Standard
23303
23304
23305 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
23306
23307 \end_inset
23308
23309
23310 \newline
23311
23312 \newline
23313
23314 \emph on
23315 Thanks to all the other volunteer developers who have helped with coding,
23316  testing, web-page creation, distribution sets, etc.
23317  You know who you are :-)
23318 \emph default
23319
23320 \newline
23321
23322 \layout Standard
23323
23324 This document was initially written by Sandeep Dutta
23325 \layout Standard
23326
23327 All product names mentioned herein may be trademarks
23328 \begin_inset LatexCommand \index{Trademarks}
23329
23330 \end_inset
23331
23332  of their respective companies.
23333
23334 \layout Section*
23335
23336 Alphabetical index
23337 \layout Standard
23338
23339 To avoid confusion, the installation and building options for SDCC itself
23340  (chapter 2) are not part of the index.
23341 \layout Standard
23342
23343
23344 \begin_inset LatexCommand \printindex{}
23345
23346 \end_inset
23347
23348
23349 \the_end