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 article
   4 \begin_preamble
   5 \usepackage[
   6   pdftitle={SDCC Compiler User Guide},
   7   pdfauthor={SDCC development team},
   8   pdfsubject={installation, user manual},
   9   pdfkeywords={8032, 8051, ansi, c, compiler, CPU, DS390,
  10                embedded, GPL, manual, mcs51, PIC, small, Z80},
  11   colorlinks=true,
  12   linkcolor=blue] {hyperref}
  13 \date{}
  14 \end_preamble
  15 \language english
  16 \inputencoding default
  17 \fontscheme pslatex
  18 \graphics default
  19 \paperfontsize default
  20 \spacing single
  21 \papersize letterpaper
  22 \paperpackage a4
  23 \use_geometry 1
  24 \use_amsmath 0
  25 \use_natbib 0
  26 \use_numerical_citations 0
  27 \paperorientation portrait
  28 \leftmargin 30mm
  29 \topmargin 10mm
  30 \rightmargin 25mm
  31 \bottommargin 15mm
  32 \secnumdepth 3
  33 \tocdepth 3
  34 \paragraph_separation indent
  35 \defskip medskip
  36 \quotes_language swedish
  37 \quotes_times 2
  38 \papercolumns 1
  39 \papersides 1
  40 \paperpagestyle fancy
  41
  42 \layout Comment
  43
  44 Please note: double dashed longoptions (e.g.
  45  --version) are written this way: -
  46 \begin_inset ERT
  47 status Collapsed
  48
  49 \layout Standard
  50
  51 \backslash
  52 /
  53 \end_inset
  54
  55 -
  56 \layout Comment
  57
  58 Two resp.
  59  three consecutive dashes simply result in a long resp.
  60  extra long dash.
  61 \layout Comment
  62
  63 Architecture specific stuff (like memory models, code examples) should maybe
  64  go
  65 \layout Comment
  66
  67 into seperate sections/chapters/appendices (it is hard to document PIC or
  68  Z80 in
  69 \layout Comment
  70
  71 a 8051 centered document)
  72 \layout Title
  73
  74 SDCC Compiler User Guide
  75 \layout Comment
  76
  77 The strings enclosed in $ are automatically updated by cvs:
  78 \layout Standard
  79 \align center
  80
  81 \size footnotesize
  82 $Date$
  83 \layout Standard
  84 \align center
  85
  86 \size footnotesize
  87 $Revision$
  88 \layout Standard
  89
  90
  91 \begin_inset LatexCommand \tableofcontents{}
  92
  93 \end_inset
  94
  95
  96 \layout Section
  97 \pagebreak_top
  98 Introduction
  99 \layout Subsection
 100
 101 About SDCC
 102 \layout Standard
 103
 104
 105 \series bold
 106 SDCC
 107 \series default
 108  is a Freeware, retargettable, optimizing ANSI-C compiler by
 109 \series bold
 110 Sandeep Dutta
 111 \series default
 112  designed for 8 bit Microprocessors.
 113  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 114  8051, 8052
 115 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052 CPU}
 116
 117 \end_inset
 118
 119 , etc), Zilog Z80 based MCUs, and the Dallas DS80C390 variant.
 120  It can be retargetted for other microprocessors, support for Microchip
 121  PIC, Atmel AVR is under development.
 122  The entire source code for the compiler is distributed under GPL.
 123  SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
 124  SDCC has extensive language extensions suitable for utilizing various microcont
 125 rollers and underlying hardware effectively.
 126
 127 \newline
 128
 129 \newline
 130 In addition to the MCU specific optimizations SDCC also does a host of standard
 131  optimizations like:
 132 \layout Itemize
 133
 134 global sub expression elimination,
 135 \layout Itemize
 136
 137 loop optimizations (loop invariant, strength reduction of induction variables
 138  and loop reversing),
 139 \layout Itemize
 140
 141 constant folding & propagation,
 142 \layout Itemize
 143
 144 copy propagation,
 145 \layout Itemize
 146
 147 dead code elimination
 148 \layout Itemize
 149
 150 jump tables for
 151 \emph on
 152 switch
 153 \emph default
 154  statements.
 155 \layout Standard
 156
 157 For the back-end SDCC uses a global register allocation scheme which should
 158  be well suited for other 8 bit MCUs.
 159
 160 \newline
 161
 162 \newline
 163 The peep hole optimizer uses a rule based substitution mechanism which is
 164  MCU independent.
 165
 166 \newline
 167
 168 \newline
 169 Supported data-types are:
 170 \layout Itemize
 171
 172 char (8 bits, 1 byte),
 173 \layout Itemize
 174
 175 short and int (16 bits, 2 bytes),
 176 \layout Itemize
 177
 178 long (32 bit, 4 bytes)
 179 \layout Itemize
 180
 181 float (4 byte IEEE).
 182
 183 \layout Standard
 184
 185 The compiler also allows
 186 \emph on
 187 inline assembler code
 188 \emph default
 189  to be embedded anywhere in a function.
 190  In addition, routines developed in assembly can also be called.
 191 \newline
 192
 193 \newline
 194 SDCC also provides an option (-
 195 \begin_inset ERT
 196 status Collapsed
 197
 198 \layout Standard
 199
 200 \backslash
 201 /
 202 \end_inset
 203
 204 -cyclomatic) to report the relative complexity of a function.
 205  These functions can then be further optimized, or hand coded in assembly
 206  if needed.
 207
 208 \newline
 209
 210 \newline
 211 SDCC also comes with a companion source level debugger SDCDB, the debugger
 212  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 213
 214 \newline
 215
 216 \newline
 217 The latest version can be downloaded from
 218 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 219
 220 \end_inset
 221
 222 .
 223
 224 \series bold
 225
 226 \series default
 227 \emph on
 228 Please note: the compiler will probably always be some steps ahead of this
 229  documentation
 230 \series bold
 231 \emph default
 232
 233 \begin_inset LatexCommand \index{Status of documentation}
 234
 235 \end_inset
 236
 237
 238 \begin_inset Foot
 239 collapsed false
 240
 241 \layout Standard
 242
 243 Obviously this has pros and cons
 244 \end_inset
 245
 246 .
 247 \layout Subsection
 248
 249 Open Source
 250 \layout Standard
 251
 252 All packages used in this compiler system are
 253 \emph on
 254 opensource
 255 \emph default
 256  and
 257 \emph on
 258 freeware
 259 \emph default
 260 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 261  etc) is distributed with the package.
 262  This documentation is maintained using a freeware word processor (LyX).
 263 \newline
 264 This program is free software; you can redistribute it and/or modify it
 265  under the terms of the GNU General Public License
 266 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 267
 268 \end_inset
 269
 270  as published by the Free Software Foundation; either version 2, or (at
 271  your option) any later version.
 272  This program is distributed in the hope that it will be useful, but WITHOUT
 273  ANY WARRANTY; without even the implied warranty
 274 \begin_inset LatexCommand \index{warranty}
 275
 276 \end_inset
 277
 278  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 279  See the GNU General Public License for more details.
 280  You should have received a copy of the GNU General Public License along
 281  with this program; if not, write to the Free Software Foundation, 59 Temple
 282  Place - Suite 330, Boston, MA 02111-1307, USA.
 283  In other words, you are welcome to use, share and improve this program.
 284  You are forbidden to forbid anyone else to use, share and improve what
 285  you give them.
 286  Help stamp out software-hoarding!
 287 \layout Subsection
 288
 289 Typographic conventions
 290 \begin_inset LatexCommand \index{Typographic conventions}
 291
 292 \end_inset
 293
 294
 295 \layout Standard
 296
 297 Throughout this manual, we will use the following convention.
 298  Commands you have to type in are printed in
 299 \family sans
 300 \series bold
 301 "sans serif"
 302 \series default
 303 .
 304
 305 \family default
 306  Code samples are printed in
 307 \family typewriter
 308 typewriter font.
 309
 310 \family default
 311  Interesting items and new terms are printed in
 312 \emph on
 313 italic.
 314 \layout Subsection
 315
 316 Compatibility with previous versions
 317 \layout Standard
 318
 319 This version has numerous bug fixes compared with the previous version.
 320  But we also introduced some incompatibilities with older versions.
 321  Not just for the fun of it, but to make the compiler more stable, efficient
 322  and ANSI compliant
 323 \begin_inset LatexCommand \index{ANSI-compliance}
 324
 325 \end_inset
 326
 327  (see section
 328 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 329
 330 \end_inset
 331
 332  for ANSI-Compliance).
 333
 334 \newline
 335
 336 \layout Itemize
 337
 338 short is now equivalent to int (16 bits), it used to be equivalent to char
 339  (8 bits) which is not ANSI compliant
 340 \layout Itemize
 341
 342 the default directory for gcc-builds where include, library and documentation
 343  files are stored is now in /usr/local/share
 344 \layout Itemize
 345
 346 char type parameters to vararg functions are casted to int unless explicitly
 347  casted, e.g.:
 348 \newline
 349
 350 \family typewriter
 351 \SpecialChar ~
 352 \SpecialChar ~
 353 char a=3;
 354 \newline
 355 \SpecialChar ~
 356 \SpecialChar ~
 357 printf ("%d %c
 358 \backslash
 359 n", a, (char)a);
 360 \family default
 361
 362 \newline
 363  will push a as an int and as a char resp.
 364 \layout Itemize
 365
 366 option -
 367 \begin_inset ERT
 368 status Collapsed
 369
 370 \layout Standard
 371
 372 \backslash
 373 /
 374 \end_inset
 375
 376 -regextend has been removed
 377 \layout Itemize
 378
 379 option -
 380 \begin_inset ERT
 381 status Collapsed
 382
 383 \layout Standard
 384
 385 \backslash
 386 /
 387 \end_inset
 388
 389 -noregparms has been removed
 390 \layout Itemize
 391
 392 option -
 393 \begin_inset ERT
 394 status Collapsed
 395
 396 \layout Standard
 397
 398 \backslash
 399 /
 400 \end_inset
 401
 402 -stack-after-data has been removed
 403 \layout Standard
 404
 405
 406 \emph on
 407 <pending: more incompatibilities?>
 408 \layout Subsection
 409
 410 System Requirements
 411 \layout Standard
 412
 413 What do you need before you start installation of SDCC? A computer, and
 414  a desire to compute.
 415  The preferred method of installation is to compile SDCC from source using
 416  GNU gcc and make.
 417  For Windows some pre-compiled binary distributions are available for your
 418  convenience.
 419  You should have some experience with command line tools and compiler use.
 420 \layout Subsection
 421
 422 Other Resources
 423 \layout Standard
 424
 425 The SDCC home page at
 426 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 427
 428 \end_inset
 429
 430  is a great place to find distribution sets.
 431  You can also find links to the user mailing lists that offer help or discuss
 432  SDCC with other SDCC users.
 433  Web links to other SDCC related sites can also be found here.
 434  This document can be found in the DOC directory of the source package as
 435  a text or HTML file.
 436  Some of the other tools (simulator and assembler) included with SDCC contain
 437  their own documentation and can be found in the source distribution.
 438  If you want the latest unreleased software, the complete source package
 439  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 440 \layout Subsection
 441
 442 Wishes for the future
 443 \layout Standard
 444
 445 There are (and always will be) some things that could be done.
 446  Here are some I can think of:
 447 \newline
 448
 449 \layout Standard
 450
 451
 452 \family typewriter
 453 char KernelFunction3(char p) at 0x340;
 454 \newline
 455
 456 \layout Standard
 457
 458
 459 \family typewriter
 460 code banking
 461 \begin_inset LatexCommand \index{code banking (not supported)}
 462
 463 \end_inset
 464
 465  support for mcs51
 466 \newline
 467
 468 \newline
 469
 470 \family default
 471 If you can think of some more, please see the chapter
 472 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 473
 474 \end_inset
 475
 476  about filing feature requests
 477 \begin_inset LatexCommand \index{Requesting features}
 478
 479 \end_inset
 480
 481
 482 \begin_inset LatexCommand \index{Feature request}
 483
 484 \end_inset
 485
 486 .
 487 \newline
 488
 489 \layout Section
 490 \pagebreak_top
 491 Installing SDCC
 492 \begin_inset LatexCommand \index{Installation}
 493
 494 \end_inset
 495
 496
 497 \layout Standard
 498
 499 For most users it is sufficient to skip to either section
 500 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 501
 502 \end_inset
 503
 504  or section
 505 \begin_inset LatexCommand \ref{sub:Windows-Install}
 506
 507 \end_inset
 508
 509 .
 510  More detailled instructions follow below.
 511 \layout Subsection
 512
 513 Configure Options
 514 \begin_inset LatexCommand \index{Options SDCC configuration}
 515
 516 \end_inset
 517
 518
 519 \layout Standard
 520
 521 The install paths, search paths and other options are defined when running
 522  'configure'.
 523  The defaults can be overridden by:
 524 \layout List
 525 \labelwidthstring 00.00.0000
 526
 527 -
 528 \begin_inset ERT
 529 status Collapsed
 530
 531 \layout Standard
 532
 533 \backslash
 534 /
 535 \end_inset
 536
 537 -prefix see table below
 538 \layout List
 539 \labelwidthstring 00.00.0000
 540
 541 -
 542 \begin_inset ERT
 543 status Collapsed
 544
 545 \layout Standard
 546
 547 \backslash
 548 /
 549 \end_inset
 550
 551 -exec_prefix see table below
 552 \layout List
 553 \labelwidthstring 00.00.0000
 554
 555 -
 556 \begin_inset ERT
 557 status Collapsed
 558
 559 \layout Standard
 560
 561 \backslash
 562 /
 563 \end_inset
 564
 565 -bindir see table below
 566 \layout List
 567 \labelwidthstring 00.00.0000
 568
 569 -
 570 \begin_inset ERT
 571 status Collapsed
 572
 573 \layout Standard
 574
 575 \backslash
 576 /
 577 \end_inset
 578
 579 -datadir see table below
 580 \layout List
 581 \labelwidthstring 00.00.0000
 582
 583 docdir environment variable, see table below
 584 \layout List
 585 \labelwidthstring 00.00.0000
 586
 587 include_dir_suffix environment variable, see table below
 588 \layout List
 589 \labelwidthstring 00.00.0000
 590
 591 lib_dir_suffix environment variable, see table below
 592 \layout List
 593 \labelwidthstring 00.00.0000
 594
 595 sdccconf_h_dir_separator environment variable, either / or
 596 \backslash
 597
 598 \backslash
 599  makes sense here.
 600  This character will only be used in sdccconf.h; don't forget it's a C-header,
 601  therefore a double-backslash is needed there.
 602 \layout List
 603 \labelwidthstring 00.00.0000
 604
 605 -
 606 \begin_inset ERT
 607 status Collapsed
 608
 609 \layout Standard
 610
 611 \backslash
 612 /
 613 \end_inset
 614
 615 -disable-mcs51-port Excludes the Intel mcs51 port
 616 \layout List
 617 \labelwidthstring 00.00.0000
 618
 619 -
 620 \begin_inset ERT
 621 status Collapsed
 622
 623 \layout Standard
 624
 625 \backslash
 626 /
 627 \end_inset
 628
 629 -disable-gbz80-port Excludes the Gameboy gbz80 port
 630 \layout List
 631 \labelwidthstring 00.00.0000
 632
 633 -
 634 \begin_inset ERT
 635 status Collapsed
 636
 637 \layout Standard
 638
 639 \backslash
 640 /
 641 \end_inset
 642
 643 -z80-port Excludes the z80 port
 644 \layout List
 645 \labelwidthstring 00.00.0000
 646
 647 -
 648 \begin_inset ERT
 649 status Collapsed
 650
 651 \layout Standard
 652
 653 \backslash
 654 /
 655 \end_inset
 656
 657 -disable-avr-port Excludes the AVR port
 658 \layout List
 659 \labelwidthstring 00.00.0000
 660
 661 -
 662 \begin_inset ERT
 663 status Collapsed
 664
 665 \layout Standard
 666
 667 \backslash
 668 /
 669 \end_inset
 670
 671 -disable-ds390-port Excludes the DS390 port
 672 \layout List
 673 \labelwidthstring 00.00.0000
 674
 675 -
 676 \begin_inset ERT
 677 status Collapsed
 678
 679 \layout Standard
 680
 681 \backslash
 682 /
 683 \end_inset
 684
 685 -disable-pic-port Excludes the PIC port
 686 \layout List
 687 \labelwidthstring 00.00.0000
 688
 689 -
 690 \begin_inset ERT
 691 status Collapsed
 692
 693 \layout Standard
 694
 695 \backslash
 696 /
 697 \end_inset
 698
 699 -disable-xa51-port Excludes the XA51 port
 700 \layout List
 701 \labelwidthstring 00.00.0000
 702
 703 -
 704 \begin_inset ERT
 705 status Collapsed
 706
 707 \layout Standard
 708
 709 \backslash
 710 /
 711 \end_inset
 712
 713 -disable-ucsim Disables configuring and building of ucsim
 714 \layout List
 715 \labelwidthstring 00.00.0000
 716
 717 -
 718 \begin_inset ERT
 719 status Collapsed
 720
 721 \layout Standard
 722
 723 \backslash
 724 /
 725 \end_inset
 726
 727 -disable-device-lib-build Disables automatically building device libraries
 728 \layout List
 729 \labelwidthstring 00.00.0000
 730
 731 -
 732 \begin_inset ERT
 733 status Collapsed
 734
 735 \layout Standard
 736
 737 \backslash
 738 /
 739 \end_inset
 740
 741 -disable-packihx Disables building packihx
 742 \layout List
 743 \labelwidthstring 00.00.0000
 744
 745 -
 746 \begin_inset ERT
 747 status Collapsed
 748
 749 \layout Standard
 750
 751 \backslash
 752 /
 753 \end_inset
 754
 755 -enable-libgc Use the Bohem memory allocator.
 756  Lower runtime footprint.
 757 \layout Standard
 758
 759 Furthermore the environment variables CC, CFLAGS, ...
 760  the tools and their arguments can be influenced.
 761  Please see `configure -
 762 \begin_inset ERT
 763 status Collapsed
 764
 765 \layout Standard
 766
 767 \backslash
 768 /
 769 \end_inset
 770
 771 -help` and the man/info pages of `configure` for details.
 772 \newline
 773
 774 \newline
 775 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 776  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 777 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 778  At the moment it's not possible to change the default settings (it was
 779  simply never required.
 780 \newline
 781
 782 \newline
 783 These configure options are compiled into the binaries, and can only be
 784  changed by rerunning 'configure' and recompiling SDCC.
 785  The configure options are written in
 786 \emph on
 787 italics
 788 \emph default
 789  to distinguish them from run time environment variables (see section search
 790  paths).
 791 \newline
 792
 793 \newline
 794 The settings for
 795 \begin_inset Quotes sld
 796 \end_inset
 797
 798 Win32 builds
 799 \begin_inset Quotes srd
 800 \end_inset
 801
 802  are used by the SDCC team to build the official Win32 binaries.
 803  The SDCC team uses Mingw32 to build the official Windows binaries, because
 804  it's
 805 \layout Enumerate
 806
 807 open source,
 808 \layout Enumerate
 809
 810 a gcc compiler and last but not least
 811 \layout Enumerate
 812
 813 the binaries can be built by cross compiling on Sourceforge's compile farm.
 814 \layout Standard
 815
 816 See the examples, how to pass the Win32 settings to 'configure'.
 817  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 818  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 819  for Win32.
 820 \newline
 821
 822 \newline
 823 These defaults are:
 824 \newline
 825
 826 \layout Standard
 827 \align center
 828
 829 \begin_inset  Tabular
 830 <lyxtabular version="3" rows="8" columns="3">
 831 <features>
 832 <column alignment="block" valignment="top" leftline="true" width="0in">
 833 <column alignment="block" valignment="top" leftline="true" width="0in">
 834 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 835 <row topline="true" bottomline="true">
 836 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 837 \begin_inset Text
 838
 839 \layout Standard
 840
 841 Variable
 842 \end_inset
 843 </cell>
 844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 845 \begin_inset Text
 846
 847 \layout Standard
 848
 849 default
 850 \end_inset
 851 </cell>
 852 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 853 \begin_inset Text
 854
 855 \layout Standard
 856
 857 Win32 builds
 858 \end_inset
 859 </cell>
 860 </row>
 861 <row topline="true">
 862 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 863 \begin_inset Text
 864
 865 \layout Standard
 866
 867
 868 \emph on
 869 PREFIX
 870 \end_inset
 871 </cell>
 872 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 873 \begin_inset Text
 874
 875 \layout Standard
 876
 877 /usr/local
 878 \end_inset
 879 </cell>
 880 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 881 \begin_inset Text
 882
 883 \layout Standard
 884
 885
 886 \backslash
 887 sdcc
 888 \end_inset
 889 </cell>
 890 </row>
 891 <row topline="true">
 892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 893 \begin_inset Text
 894
 895 \layout Standard
 896
 897
 898 \emph on
 899 EXEC_PREFIX
 900 \end_inset
 901 </cell>
 902 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 903 \begin_inset Text
 904
 905 \layout Standard
 906
 907
 908 \emph on
 909 $PREFIX
 910 \end_inset
 911 </cell>
 912 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 913 \begin_inset Text
 914
 915 \layout Standard
 916
 917
 918 \emph on
 919 $PREFIX
 920 \end_inset
 921 </cell>
 922 </row>
 923 <row topline="true">
 924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 925 \begin_inset Text
 926
 927 \layout Standard
 928
 929
 930 \emph on
 931 BINDIR
 932 \end_inset
 933 </cell>
 934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 935 \begin_inset Text
 936
 937 \layout Standard
 938
 939
 940 \emph on
 941 $EXECPREFIX
 942 \emph default
 943 /bin
 944 \end_inset
 945 </cell>
 946 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 947 \begin_inset Text
 948
 949 \layout Standard
 950
 951
 952 \emph on
 953 $EXECPREFIX
 954 \emph default
 955
 956 \backslash
 957 bin
 958 \end_inset
 959 </cell>
 960 </row>
 961 <row topline="true">
 962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 963 \begin_inset Text
 964
 965 \layout Standard
 966
 967
 968 \emph on
 969 DATADIR
 970 \end_inset
 971 </cell>
 972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 973 \begin_inset Text
 974
 975 \layout Standard
 976
 977
 978 \emph on
 979 $PREFIX
 980 \emph default
 981 /share
 982 \end_inset
 983 </cell>
 984 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 985 \begin_inset Text
 986
 987 \layout Standard
 988
 989
 990 \emph on
 991 $PREFIX
 992 \end_inset
 993 </cell>
 994 </row>
 995 <row topline="true">
 996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 997 \begin_inset Text
 998
 999 \layout Standard
1000
1001
1002 \emph on
1003 DOCDIR
1004 \end_inset
1005 </cell>
1006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1007 \begin_inset Text
1008
1009 \layout Standard
1010
1011
1012 \emph on
1013 $DATADIR
1014 \emph default
1015 /sdcc/doc
1016 \end_inset
1017 </cell>
1018 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1019 \begin_inset Text
1020
1021 \layout Standard
1022
1023
1024 \emph on
1025 $DATADIR
1026 \emph default
1027
1028 \backslash
1029 doc
1030 \end_inset
1031 </cell>
1032 </row>
1033 <row topline="true">
1034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1035 \begin_inset Text
1036
1037 \layout Standard
1038
1039
1040 \emph on
1041 INCLUDE_DIR_SUFFIX
1042 \end_inset
1043 </cell>
1044 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1045 \begin_inset Text
1046
1047 \layout Standard
1048
1049 sdcc/include
1050 \end_inset
1051 </cell>
1052 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1053 \begin_inset Text
1054
1055 \layout Standard
1056
1057 include
1058 \end_inset
1059 </cell>
1060 </row>
1061 <row topline="true" bottomline="true">
1062 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1063 \begin_inset Text
1064
1065 \layout Standard
1066
1067
1068 \emph on
1069 LIB_DIR_SUFFIX
1070 \end_inset
1071 </cell>
1072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1073 \begin_inset Text
1074
1075 \layout Standard
1076
1077 sdcc/lib
1078 \end_inset
1079 </cell>
1080 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1081 \begin_inset Text
1082
1083 \layout Standard
1084
1085 lib
1086 \end_inset
1087 </cell>
1088 </row>
1089 </lyxtabular>
1090
1091 \end_inset
1092
1093
1094 \newline
1095
1096 \layout Standard
1097 \noindent
1098 'configure' also computes relative paths.
1099  This is needed for full relocatability of a binary package and to complete
1100  search paths (see section search paths below):
1101 \newline
1102
1103 \layout Standard
1104 \align center
1105
1106 \begin_inset  Tabular
1107 <lyxtabular version="3" rows="4" columns="3">
1108 <features>
1109 <column alignment="block" valignment="top" leftline="true" width="0in">
1110 <column alignment="block" valignment="top" leftline="true" width="0in">
1111 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1112 <row topline="true" bottomline="true">
1113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1114 \begin_inset Text
1115
1116 \layout Standard
1117
1118 Variable (computed)
1119 \end_inset
1120 </cell>
1121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1122 \begin_inset Text
1123
1124 \layout Standard
1125
1126 default
1127 \end_inset
1128 </cell>
1129 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1130 \begin_inset Text
1131
1132 \layout Standard
1133
1134 Win32 builds
1135 \end_inset
1136 </cell>
1137 </row>
1138 <row topline="true" bottomline="true">
1139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1140 \begin_inset Text
1141
1142 \layout Standard
1143
1144
1145 \emph on
1146 BIN2DATA_DIR
1147 \end_inset
1148 </cell>
1149 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1150 \begin_inset Text
1151
1152 \layout Standard
1153
1154 ../share
1155 \end_inset
1156 </cell>
1157 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1158 \begin_inset Text
1159
1160 \layout Standard
1161
1162 ..
1163 \end_inset
1164 </cell>
1165 </row>
1166 <row bottomline="true">
1167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1168 \begin_inset Text
1169
1170 \layout Standard
1171
1172
1173 \emph on
1174 PREFIX2BIN_DIR
1175 \end_inset
1176 </cell>
1177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1178 \begin_inset Text
1179
1180 \layout Standard
1181
1182 bin
1183 \end_inset
1184 </cell>
1185 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1186 \begin_inset Text
1187
1188 \layout Standard
1189
1190 bin
1191 \end_inset
1192 </cell>
1193 </row>
1194 <row bottomline="true">
1195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1196 \begin_inset Text
1197
1198 \layout Standard
1199
1200
1201 \emph on
1202 PREFIX2DATA_DIR
1203 \end_inset
1204 </cell>
1205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1206 \begin_inset Text
1207
1208 \layout Standard
1209
1210 share/sdcc
1211 \end_inset
1212 </cell>
1213 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1214 \begin_inset Text
1215
1216 \layout Standard
1217
1218 \end_inset
1219 </cell>
1220 </row>
1221 </lyxtabular>
1222
1223 \end_inset
1224
1225
1226 \newline
1227
1228 \layout Standard
1229 \noindent
1230 Examples:
1231 \layout LyX-Code
1232
1233 ./configure
1234 \newline
1235 ./configure -
1236 \begin_inset ERT
1237 status Collapsed
1238
1239 \layout Standard
1240
1241 \backslash
1242 /
1243 \end_inset
1244
1245 -prefix=
1246 \begin_inset Quotes srd
1247 \end_inset
1248
1249 /usr/bin
1250 \begin_inset Quotes srd
1251 \end_inset
1252
1253  -
1254 \begin_inset ERT
1255 status Collapsed
1256
1257 \layout Standard
1258
1259 \backslash
1260 /
1261 \end_inset
1262
1263 -datadir=
1264 \begin_inset Quotes srd
1265 \end_inset
1266
1267 /usr/share
1268 \begin_inset Quotes srd
1269 \end_inset
1270
1271
1272 \newline
1273 ./configure -
1274 \begin_inset ERT
1275 status Collapsed
1276
1277 \layout Standard
1278
1279 \backslash
1280 /
1281 \end_inset
1282
1283 -disable-avr-port -
1284 \begin_inset ERT
1285 status Collapsed
1286
1287 \layout Standard
1288
1289 \backslash
1290 /
1291 \end_inset
1292
1293 -disable-xa51-port
1294 \layout Standard
1295
1296 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1297 32'):
1298 \layout LyX-Code
1299
1300 ./configure
1301 \backslash
1302
1303 \newline
1304 CC=
1305 \begin_inset Quotes srd
1306 \end_inset
1307
1308 i586-mingw32msvc-gcc
1309 \begin_inset Quotes srd
1310 \end_inset
1311
1312  CXX=
1313 \begin_inset Quotes srd
1314 \end_inset
1315
1316 i586-mingw32msvc-g++
1317 \begin_inset Quotes srd
1318 \end_inset
1319
1320
1321 \backslash
1322
1323 \newline
1324 RANLIB=
1325 \begin_inset Quotes srd
1326 \end_inset
1327
1328 i586-mingw32msvc-ranlib
1329 \begin_inset Quotes srd
1330 \end_inset
1331
1332
1333 \backslash
1334
1335 \newline
1336 STRIP=
1337 \begin_inset Quotes srd
1338 \end_inset
1339
1340 i586-mingw32msvc-strip
1341 \begin_inset Quotes srd
1342 \end_inset
1343
1344
1345 \backslash
1346
1347 \newline
1348 -
1349 \begin_inset ERT
1350 status Collapsed
1351
1352 \layout Standard
1353
1354 \backslash
1355 /
1356 \end_inset
1357
1358 -prefix=
1359 \begin_inset Quotes srd
1360 \end_inset
1361
1362 /sdcc
1363 \begin_inset Quotes srd
1364 \end_inset
1365
1366
1367 \backslash
1368
1369 \newline
1370 -
1371 \begin_inset ERT
1372 status Collapsed
1373
1374 \layout Standard
1375
1376 \backslash
1377 /
1378 \end_inset
1379
1380 -datadir=
1381 \begin_inset Quotes srd
1382 \end_inset
1383
1384 /sdcc
1385 \begin_inset Quotes srd
1386 \end_inset
1387
1388
1389 \backslash
1390
1391 \newline
1392 docdir=
1393 \begin_inset Quotes srd
1394 \end_inset
1395
1396 /sdcc/doc
1397 \begin_inset Quotes srd
1398 \end_inset
1399
1400
1401 \backslash
1402
1403 \newline
1404 include_dir_suffix=
1405 \begin_inset Quotes srd
1406 \end_inset
1407
1408 include
1409 \begin_inset Quotes srd
1410 \end_inset
1411
1412
1413 \backslash
1414
1415 \newline
1416 lib_dir_suffix=
1417 \begin_inset Quotes srd
1418 \end_inset
1419
1420 lib
1421 \begin_inset Quotes srd
1422 \end_inset
1423
1424
1425 \backslash
1426
1427 \newline
1428 sdccconf_h_dir_separator=
1429 \begin_inset Quotes srd
1430 \end_inset
1431
1432
1433 \backslash
1434
1435 \backslash
1436
1437 \backslash
1438
1439 \backslash
1440
1441 \begin_inset Quotes srd
1442 \end_inset
1443
1444
1445 \backslash
1446
1447 \newline
1448 -
1449 \begin_inset ERT
1450 status Collapsed
1451
1452 \layout Standard
1453
1454 \backslash
1455 /
1456 \end_inset
1457
1458 -disable-device-lib-build
1459 \backslash
1460
1461 \newline
1462 -
1463 \begin_inset ERT
1464 status Collapsed
1465
1466 \layout Standard
1467
1468 \backslash
1469 /
1470 \end_inset
1471
1472 -disable-ucsim
1473 \backslash
1474
1475 \newline
1476 -
1477 \begin_inset ERT
1478 status Collapsed
1479
1480 \layout Standard
1481
1482 \backslash
1483 /
1484 \end_inset
1485
1486 -host=i586-mingw32msvc -
1487 \begin_inset ERT
1488 status Collapsed
1489
1490 \layout Standard
1491
1492 \backslash
1493 /
1494 \end_inset
1495
1496 -build=unknown-unknown-linux-gnu
1497 \layout Standard
1498
1499 To
1500 \begin_inset Quotes sld
1501 \end_inset
1502
1503 cross
1504 \begin_inset Quotes srd
1505 \end_inset
1506
1507 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1508 ):
1509 \layout LyX-Code
1510
1511 ./configure -C
1512 \backslash
1513
1514 \newline
1515 CFLAGS=
1516 \begin_inset Quotes srd
1517 \end_inset
1518
1519 -mno-cygwin -O2
1520 \begin_inset Quotes srd
1521 \end_inset
1522
1523
1524 \backslash
1525
1526 \newline
1527 LDFLAGS=
1528 \begin_inset Quotes srd
1529 \end_inset
1530
1531 -mno-cygwin
1532 \begin_inset Quotes srd
1533 \end_inset
1534
1535
1536 \backslash
1537
1538 \newline
1539 -
1540 \begin_inset ERT
1541 status Collapsed
1542
1543 \layout Standard
1544
1545 \backslash
1546 /
1547 \end_inset
1548
1549 -prefix=
1550 \begin_inset Quotes srd
1551 \end_inset
1552
1553 /sdcc
1554 \begin_inset Quotes srd
1555 \end_inset
1556
1557
1558 \backslash
1559
1560 \newline
1561 -
1562 \begin_inset ERT
1563 status Collapsed
1564
1565 \layout Standard
1566
1567 \backslash
1568 /
1569 \end_inset
1570
1571 -datadir=
1572 \begin_inset Quotes srd
1573 \end_inset
1574
1575 /sdcc
1576 \begin_inset Quotes srd
1577 \end_inset
1578
1579
1580 \backslash
1581
1582 \newline
1583 docdir=
1584 \begin_inset Quotes srd
1585 \end_inset
1586
1587 /sdcc/doc
1588 \begin_inset Quotes srd
1589 \end_inset
1590
1591
1592 \backslash
1593
1594 \newline
1595 include_dir_suffix=
1596 \begin_inset Quotes srd
1597 \end_inset
1598
1599 include
1600 \begin_inset Quotes srd
1601 \end_inset
1602
1603
1604 \backslash
1605
1606 \newline
1607 lib_dir_suffix=
1608 \begin_inset Quotes srd
1609 \end_inset
1610
1611 lib
1612 \begin_inset Quotes srd
1613 \end_inset
1614
1615
1616 \backslash
1617
1618 \newline
1619 sdccconf_h_dir_separator=
1620 \begin_inset Quotes srd
1621 \end_inset
1622
1623
1624 \backslash
1625
1626 \backslash
1627
1628 \backslash
1629
1630 \backslash
1631
1632 \begin_inset Quotes srd
1633 \end_inset
1634
1635
1636 \backslash
1637
1638 \newline
1639 -
1640 \begin_inset ERT
1641 status Collapsed
1642
1643 \layout Standard
1644
1645 \backslash
1646 /
1647 \end_inset
1648
1649 -disable-ucsim
1650 \layout Standard
1651
1652 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1653  The option '-
1654 \begin_inset ERT
1655 status Collapsed
1656
1657 \layout Standard
1658
1659 \backslash
1660 /
1661 \end_inset
1662
1663 -C' turns on caching, which gives a little bit extra speed.
1664  However if options are changed, it can be necessary to delete the config.cache
1665  file.
1666 \layout Subsection
1667
1668 Install paths
1669 \begin_inset LatexCommand \label{sub:Install-paths}
1670
1671 \end_inset
1672
1673
1674 \begin_inset LatexCommand \index{Install paths}
1675
1676 \end_inset
1677
1678
1679 \layout Standard
1680 \added_space_top medskip \align center
1681
1682 \begin_inset  Tabular
1683 <lyxtabular version="3" rows="5" columns="4">
1684 <features>
1685 <column alignment="center" valignment="top" leftline="true" width="0">
1686 <column alignment="center" valignment="top" leftline="true" width="0">
1687 <column alignment="center" valignment="top" leftline="true" width="0">
1688 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1689 <row topline="true" bottomline="true">
1690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1691 \begin_inset Text
1692
1693 \layout Standard
1694
1695
1696 \series bold
1697 Description
1698 \end_inset
1699 </cell>
1700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1701 \begin_inset Text
1702
1703 \layout Standard
1704
1705
1706 \series bold
1707 Path
1708 \end_inset
1709 </cell>
1710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1711 \begin_inset Text
1712
1713 \layout Standard
1714
1715
1716 \series bold
1717 Default
1718 \end_inset
1719 </cell>
1720 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1721 \begin_inset Text
1722
1723 \layout Standard
1724
1725
1726 \series bold
1727 Win32 builds
1728 \end_inset
1729 </cell>
1730 </row>
1731 <row topline="true">
1732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1733 \begin_inset Text
1734
1735 \layout Standard
1736
1737 Binary files*
1738 \end_inset
1739 </cell>
1740 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1741 \begin_inset Text
1742
1743 \layout Standard
1744
1745
1746 \emph on
1747 $EXEC_PREFIX
1748 \end_inset
1749 </cell>
1750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1751 \begin_inset Text
1752
1753 \layout Standard
1754
1755 /usr/local/bin
1756 \end_inset
1757 </cell>
1758 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1759 \begin_inset Text
1760
1761 \layout Standard
1762
1763
1764 \backslash
1765 sdcc
1766 \backslash
1767 bin
1768 \end_inset
1769 </cell>
1770 </row>
1771 <row topline="true">
1772 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1773 \begin_inset Text
1774
1775 \layout Standard
1776
1777 Include files
1778 \end_inset
1779 </cell>
1780 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1781 \begin_inset Text
1782
1783 \layout Standard
1784
1785
1786 \emph on
1787 $DATADIR/ $INCLUDE_DIR_SUFFIX
1788 \end_inset
1789 </cell>
1790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1791 \begin_inset Text
1792
1793 \layout Standard
1794
1795 /usr/local/share/sdcc/include
1796 \end_inset
1797 </cell>
1798 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1799 \begin_inset Text
1800
1801 \layout Standard
1802
1803
1804 \backslash
1805 sdcc
1806 \backslash
1807 include
1808 \end_inset
1809 </cell>
1810 </row>
1811 <row topline="true">
1812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1813 \begin_inset Text
1814
1815 \layout Standard
1816
1817 Library file**
1818 \end_inset
1819 </cell>
1820 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1821 \begin_inset Text
1822
1823 \layout Standard
1824
1825
1826 \emph on
1827 $DATADIR/$LIB_DIR_SUFFIX
1828 \end_inset
1829 </cell>
1830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1831 \begin_inset Text
1832
1833 \layout Standard
1834
1835 /usr/local/share/sdcc/lib
1836 \end_inset
1837 </cell>
1838 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1839 \begin_inset Text
1840
1841 \layout Standard
1842
1843
1844 \backslash
1845 sdcc
1846 \backslash
1847 lib
1848 \end_inset
1849 </cell>
1850 </row>
1851 <row topline="true" bottomline="true">
1852 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1853 \begin_inset Text
1854
1855 \layout Standard
1856
1857 Documentation
1858 \end_inset
1859 </cell>
1860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1861 \begin_inset Text
1862
1863 \layout Standard
1864
1865
1866 \emph on
1867 $DOCDIR
1868 \end_inset
1869 </cell>
1870 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1871 \begin_inset Text
1872
1873 \layout Standard
1874
1875 /usr/local/share/sdcc/doc
1876 \end_inset
1877 </cell>
1878 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1879 \begin_inset Text
1880
1881 \layout Standard
1882
1883
1884 \backslash
1885 sdcc
1886 \backslash
1887 doc
1888 \end_inset
1889 </cell>
1890 </row>
1891 </lyxtabular>
1892
1893 \end_inset
1894
1895
1896 \layout Verse
1897
1898
1899 \size footnotesize
1900 *compiler, preprocessor, assembler, and linker
1901 \newline
1902 **the
1903 \shape italic
1904 model
1905 \shape default
1906  is auto-appended by the compiler, e.g.
1907  small, large, z80, ds390 etc
1908 \layout Standard
1909 \noindent
1910 The install paths can still be changed during `make install` with e.g.:
1911 \layout LyX-Code
1912
1913 make install prefix=$(HOME)/local/sdcc
1914 \layout Standard
1915
1916 Of course this doesn't change the search paths compiled into the binaries.
1917 \layout Subsection
1918
1919 Search Paths
1920 \begin_inset LatexCommand \label{sub:Search-Paths}
1921
1922 \end_inset
1923
1924
1925 \begin_inset LatexCommand \index{Search path}
1926
1927 \end_inset
1928
1929
1930 \layout Standard
1931
1932 Some search paths or parts of them are determined by configure variables
1933  (in
1934 \emph on
1935 italics
1936 \emph default
1937 , see section above).
1938  Further search paths are determined by environment variables during runtime.
1939
1940 \newline
1941 The paths searched when running the compiler are as follows (the first catch
1942  wins):
1943 \newline
1944
1945 \newline
1946 1.
1947  Binary files (preprocessor, assembler and linker)
1948 \newline
1949
1950 \layout Standard
1951 \align center
1952
1953 \begin_inset  Tabular
1954 <lyxtabular version="3" rows="4" columns="3">
1955 <features>
1956 <column alignment="block" valignment="top" leftline="true" width="0in">
1957 <column alignment="block" valignment="top" leftline="true" width="0in">
1958 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1959 <row topline="true" bottomline="true">
1960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1961 \begin_inset Text
1962
1963 \layout Standard
1964
1965 Search path
1966 \end_inset
1967 </cell>
1968 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1969 \begin_inset Text
1970
1971 \layout Standard
1972
1973 default
1974 \end_inset
1975 </cell>
1976 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1977 \begin_inset Text
1978
1979 \layout Standard
1980
1981 Win32 builds
1982 \end_inset
1983 </cell>
1984 </row>
1985 <row topline="true">
1986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1987 \begin_inset Text
1988
1989 \layout Standard
1990
1991 $SDCC_HOME/
1992 \emph on
1993 $PPREFIX2BIN_DIR
1994 \end_inset
1995 </cell>
1996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1997 \begin_inset Text
1998
1999 \layout Standard
2000
2001 $SDCC_HOME/bin
2002 \end_inset
2003 </cell>
2004 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2005 \begin_inset Text
2006
2007 \layout Standard
2008
2009 $SDCC_HOME
2010 \backslash
2011 bin
2012 \end_inset
2013 </cell>
2014 </row>
2015 <row topline="true">
2016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2017 \begin_inset Text
2018
2019 \layout Standard
2020
2021 Path of argv[0] (if available)
2022 \end_inset
2023 </cell>
2024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2025 \begin_inset Text
2026
2027 \layout Standard
2028
2029 Path of argv[0]
2030 \end_inset
2031 </cell>
2032 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2033 \begin_inset Text
2034
2035 \layout Standard
2036
2037 Path of argv[0]
2038 \end_inset
2039 </cell>
2040 </row>
2041 <row topline="true" bottomline="true">
2042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2043 \begin_inset Text
2044
2045 \layout Standard
2046
2047 $PATH
2048 \end_inset
2049 </cell>
2050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2051 \begin_inset Text
2052
2053 \layout Standard
2054
2055 $PATH
2056 \end_inset
2057 </cell>
2058 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2059 \begin_inset Text
2060
2061 \layout Standard
2062
2063 $PATH
2064 \end_inset
2065 </cell>
2066 </row>
2067 </lyxtabular>
2068
2069 \end_inset
2070
2071
2072 \newline
2073
2074 \layout Standard
2075 \noindent
2076 2.
2077  Include files
2078 \newline
2079
2080 \layout Standard
2081 \align center
2082
2083 \begin_inset  Tabular
2084 <lyxtabular version="3" rows="6" columns="3">
2085 <features>
2086 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2087 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2088 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2089 <row topline="true" bottomline="true">
2090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2091 \begin_inset Text
2092
2093 \layout Standard
2094
2095 Search path
2096 \end_inset
2097 </cell>
2098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2099 \begin_inset Text
2100
2101 \layout Standard
2102
2103 default
2104 \end_inset
2105 </cell>
2106 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2107 \begin_inset Text
2108
2109 \layout Standard
2110
2111 Win32 builds
2112 \end_inset
2113 </cell>
2114 </row>
2115 <row topline="true">
2116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2117 \begin_inset Text
2118
2119 \layout Standard
2120
2121 -
2122 \begin_inset ERT
2123 status Collapsed
2124
2125 \layout Standard
2126
2127 \backslash
2128 /
2129 \end_inset
2130
2131 -I dir
2132 \end_inset
2133 </cell>
2134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2135 \begin_inset Text
2136
2137 \layout Standard
2138
2139 -
2140 \begin_inset ERT
2141 status Collapsed
2142
2143 \layout Standard
2144
2145 \backslash
2146 /
2147 \end_inset
2148
2149 -I dir
2150 \end_inset
2151 </cell>
2152 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2153 \begin_inset Text
2154
2155 \layout Standard
2156
2157 -
2158 \begin_inset ERT
2159 status Collapsed
2160
2161 \layout Standard
2162
2163 \backslash
2164 /
2165 \end_inset
2166
2167 -I dir
2168 \end_inset
2169 </cell>
2170 </row>
2171 <row topline="true">
2172 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2173 \begin_inset Text
2174
2175 \layout Standard
2176
2177 $SDCC_INCLUDE
2178 \end_inset
2179 </cell>
2180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2181 \begin_inset Text
2182
2183 \layout Standard
2184
2185 $SDCC_INCLUDE
2186 \end_inset
2187 </cell>
2188 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2189 \begin_inset Text
2190
2191 \layout Standard
2192
2193 $SDCC_INCLUDE
2194 \end_inset
2195 </cell>
2196 </row>
2197 <row topline="true">
2198 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2199 \begin_inset Text
2200
2201 \layout Standard
2202
2203 $SDCC_HOME/
2204 \newline
2205
2206 \emph on
2207 $PREFIX2DATA_DIR/
2208 \newline
2209 $INCLUDE_DIR_SUFFIX
2210 \end_inset
2211 </cell>
2212 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2213 \begin_inset Text
2214
2215 \layout Standard
2216
2217 $SDCC_ HOME/
2218 \newline
2219 share/sdcc/
2220 \newline
2221 include
2222 \end_inset
2223 </cell>
2224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2225 \begin_inset Text
2226
2227 \layout Standard
2228
2229 $SDCC_HOME
2230 \backslash
2231 include
2232 \end_inset
2233 </cell>
2234 </row>
2235 <row topline="true">
2236 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2237 \begin_inset Text
2238
2239 \layout Standard
2240
2241 path(argv[0])/
2242 \newline
2243
2244 \emph on
2245 $BIN2DATADIR/
2246 \emph default
2247
2248 \newline
2249
2250 \emph on
2251 $INCLUDE_DIR_SUFFIX
2252 \end_inset
2253 </cell>
2254 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2255 \begin_inset Text
2256
2257 \layout Standard
2258
2259 path(argv[0])/
2260 \newline
2261 ../sdcc/include
2262 \newline
2263 \SpecialChar ~
2264 \SpecialChar ~
2265 \SpecialChar ~
2266 \SpecialChar ~
2267 \SpecialChar ~
2268 \SpecialChar ~
2269 \SpecialChar ~
2270 \SpecialChar ~
2271 \SpecialChar ~
2272 \SpecialChar ~
2273 \SpecialChar ~
2274 \SpecialChar ~
2275 \SpecialChar ~
2276 \SpecialChar ~
2277 \SpecialChar ~
2278 \SpecialChar ~
2279 \SpecialChar ~
2280 \SpecialChar ~
2281 \SpecialChar ~
2282 \SpecialChar ~
2283 \SpecialChar ~
2284 \SpecialChar ~
2285 \SpecialChar ~
2286 \SpecialChar ~
2287 \SpecialChar ~
2288 \SpecialChar ~
2289 \SpecialChar ~
2290 \SpecialChar ~
2291 \SpecialChar ~
2292 \SpecialChar ~
2293 \SpecialChar ~
2294 \SpecialChar ~
2295 \SpecialChar ~
2296 \SpecialChar ~
2297 \SpecialChar ~
2298 \SpecialChar ~
2299 \SpecialChar ~
2300 \SpecialChar ~
2301
2302 \end_inset
2303 </cell>
2304 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2305 \begin_inset Text
2306
2307 \layout Standard
2308
2309 path(argv[0])
2310 \backslash
2311 ..
2312 \backslash
2313 include
2314 \end_inset
2315 </cell>
2316 </row>
2317 <row topline="true" bottomline="true">
2318 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2319 \begin_inset Text
2320
2321 \layout Standard
2322
2323
2324 \emph on
2325 $DATADIR/
2326 \emph default
2327
2328 \newline
2329
2330 \emph on
2331 $INCLUDE_DIR_SUFFIX
2332 \end_inset
2333 </cell>
2334 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2335 \begin_inset Text
2336
2337 \layout Standard
2338
2339 /usr/local/share/sdcc/
2340 \newline
2341 include
2342 \end_inset
2343 </cell>
2344 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2345 \begin_inset Text
2346
2347 \layout Standard
2348
2349 (not on Win32)
2350 \end_inset
2351 </cell>
2352 </row>
2353 </lyxtabular>
2354
2355 \end_inset
2356
2357
2358 \newline
2359
2360 \layout Standard
2361 \noindent
2362 The option -
2363 \begin_inset ERT
2364 status Collapsed
2365
2366 \layout Standard
2367
2368 \backslash
2369 /
2370 \end_inset
2371
2372 -nostdinc disables the last two search paths.
2373 \newline
2374
2375 \newline
2376 3.
2377  Library files
2378 \newline
2379
2380 \layout Standard
2381
2382 With the exception of
2383 \begin_inset Quotes sld
2384 \end_inset
2385
2386 -
2387 \begin_inset ERT
2388 status Collapsed
2389
2390 \layout Standard
2391
2392 \backslash
2393 /
2394 \end_inset
2395
2396 -L dir
2397 \begin_inset Quotes srd
2398 \end_inset
2399
2400  the
2401 \shape italic
2402 model
2403 \shape default
2404  is auto-appended by the compiler (e.g.
2405  small, large, z80, ds390 etc.).
2406
2407 \newline
2408
2409 \layout Standard
2410 \align center
2411
2412 \begin_inset  Tabular
2413 <lyxtabular version="3" rows="6" columns="3">
2414 <features>
2415 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2416 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2417 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2418 <row topline="true" bottomline="true">
2419 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2420 \begin_inset Text
2421
2422 \layout Standard
2423
2424 Search path
2425 \end_inset
2426 </cell>
2427 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2428 \begin_inset Text
2429
2430 \layout Standard
2431
2432 default
2433 \end_inset
2434 </cell>
2435 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2436 \begin_inset Text
2437
2438 \layout Standard
2439
2440 Win32 builds
2441 \end_inset
2442 </cell>
2443 </row>
2444 <row topline="true">
2445 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2446 \begin_inset Text
2447
2448 \layout Standard
2449
2450 -
2451 \begin_inset ERT
2452 status Collapsed
2453
2454 \layout Standard
2455
2456 \backslash
2457 /
2458 \end_inset
2459
2460 -L dir
2461 \end_inset
2462 </cell>
2463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2464 \begin_inset Text
2465
2466 \layout Standard
2467
2468 -
2469 \begin_inset ERT
2470 status Collapsed
2471
2472 \layout Standard
2473
2474 \backslash
2475 /
2476 \end_inset
2477
2478 -L dir
2479 \end_inset
2480 </cell>
2481 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2482 \begin_inset Text
2483
2484 \layout Standard
2485
2486 -
2487 \begin_inset ERT
2488 status Collapsed
2489
2490 \layout Standard
2491
2492 \backslash
2493 /
2494 \end_inset
2495
2496 -L dir
2497 \end_inset
2498 </cell>
2499 </row>
2500 <row topline="true">
2501 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2502 \begin_inset Text
2503
2504 \layout Standard
2505
2506 $SDCC_LIB/
2507 \newline
2508
2509 \emph on
2510 <model>
2511 \end_inset
2512 </cell>
2513 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2514 \begin_inset Text
2515
2516 \layout Standard
2517
2518 $SDCC_LIB/
2519 \newline
2520
2521 \emph on
2522 <model>
2523 \end_inset
2524 </cell>
2525 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2526 \begin_inset Text
2527
2528 \layout Standard
2529
2530 $SDCC_LIB
2531 \backslash
2532
2533 \newline
2534
2535 \emph on
2536 <model>
2537 \end_inset
2538 </cell>
2539 </row>
2540 <row topline="true">
2541 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2542 \begin_inset Text
2543
2544 \layout Standard
2545
2546 $SDCC_HOME/
2547 \newline
2548
2549 \emph on
2550 $PREFIX2DATA_DIR/
2551 \newline
2552 $LIB_DIR_SUFFIX/<model>
2553 \end_inset
2554 </cell>
2555 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2556 \begin_inset Text
2557
2558 \layout Standard
2559
2560 $SDCC_HOME/
2561 \newline
2562 share/sdcc/
2563 \newline
2564 lib/
2565 \emph on
2566 <model>
2567 \end_inset
2568 </cell>
2569 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2570 \begin_inset Text
2571
2572 \layout Standard
2573
2574 $SDCC_HOME
2575 \backslash
2576 lib
2577 \backslash
2578
2579 \emph on
2580
2581 \newline
2582 <model>
2583 \end_inset
2584 </cell>
2585 </row>
2586 <row topline="true">
2587 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2588 \begin_inset Text
2589
2590 \layout Standard
2591
2592 path(argv[0])/
2593 \newline
2594
2595 \emph on
2596 $BIN2DATADIR/
2597 \emph default
2598
2599 \newline
2600
2601 \emph on
2602 $LIB_DIR_SUFFIX/<model>
2603 \end_inset
2604 </cell>
2605 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2606 \begin_inset Text
2607
2608 \layout Standard
2609
2610 path(argv[0])/
2611 \newline
2612 ../sdcc/lib/
2613 \emph on
2614 <model>
2615 \newline
2616 \SpecialChar ~
2617 \SpecialChar ~
2618 \SpecialChar ~
2619 \SpecialChar ~
2620 \SpecialChar ~
2621 \SpecialChar ~
2622 \SpecialChar ~
2623 \SpecialChar ~
2624 \SpecialChar ~
2625 \SpecialChar ~
2626 \SpecialChar ~
2627 \SpecialChar ~
2628 \SpecialChar ~
2629 \SpecialChar ~
2630 \SpecialChar ~
2631 \SpecialChar ~
2632 \SpecialChar ~
2633 \SpecialChar ~
2634 \SpecialChar ~
2635 \SpecialChar ~
2636 \SpecialChar ~
2637 \SpecialChar ~
2638 \SpecialChar ~
2639 \SpecialChar ~
2640 \SpecialChar ~
2641 \SpecialChar ~
2642 \SpecialChar ~
2643 \SpecialChar ~
2644 \SpecialChar ~
2645 \SpecialChar ~
2646 \SpecialChar ~
2647 \SpecialChar ~
2648 \SpecialChar ~
2649 \SpecialChar ~
2650 \SpecialChar ~
2651 \SpecialChar ~
2652 \SpecialChar ~
2653 \SpecialChar ~
2654 \SpecialChar ~
2655
2656 \end_inset
2657 </cell>
2658 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2659 \begin_inset Text
2660
2661 \layout Standard
2662
2663 path(argv[0])
2664 \backslash
2665
2666 \newline
2667 ..
2668 \backslash
2669 lib
2670 \backslash
2671
2672 \emph on
2673 <model>
2674 \newline
2675 \SpecialChar ~
2676 \SpecialChar ~
2677 \SpecialChar ~
2678 \SpecialChar ~
2679 \SpecialChar ~
2680 \SpecialChar ~
2681 \SpecialChar ~
2682 \SpecialChar ~
2683 \SpecialChar ~
2684 \SpecialChar ~
2685 \SpecialChar ~
2686 \SpecialChar ~
2687 \SpecialChar ~
2688 \SpecialChar ~
2689 \SpecialChar ~
2690 \SpecialChar ~
2691 \SpecialChar ~
2692 \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
2711 \end_inset
2712 </cell>
2713 </row>
2714 <row topline="true" bottomline="true">
2715 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2716 \begin_inset Text
2717
2718 \layout Standard
2719
2720
2721 \emph on
2722 $DATADIR/
2723 \newline
2724 $LIB_DIR_SUFFIX/<model>
2725 \end_inset
2726 </cell>
2727 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2728 \begin_inset Text
2729
2730 \layout Standard
2731
2732 /usr/local/share/sdcc/
2733 \newline
2734 lib/
2735 \emph on
2736 <model>
2737 \end_inset
2738 </cell>
2739 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2740 \begin_inset Text
2741
2742 \layout Standard
2743
2744 (not on Win32)
2745 \end_inset
2746 </cell>
2747 </row>
2748 </lyxtabular>
2749
2750 \end_inset
2751
2752
2753 \newline
2754
2755 \layout Comment
2756
2757 Don't delete any of the stray spaces in the table above without checking
2758  the HTML output (last line)!
2759 \layout Standard
2760
2761 \SpecialChar ~
2762
2763 \newline
2764 The option -
2765 \begin_inset ERT
2766 status Collapsed
2767
2768 \layout Standard
2769
2770 \backslash
2771 /
2772 \end_inset
2773
2774 -nostdlib disables the last two search paths.
2775 \layout Subsection
2776
2777 Building SDCC
2778 \begin_inset LatexCommand \index{Building SDCC}
2779
2780 \end_inset
2781
2782
2783 \layout Subsubsection
2784
2785 Building SDCC on Linux
2786 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2787
2788 \end_inset
2789
2790
2791 \layout Enumerate
2792
2793
2794 \series medium
2795 Download the source package
2796 \series default
2797  either from the SDCC CVS repository or from the
2798 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
2799
2800 \end_inset
2801
2802
2803 \series medium
2804 , it will be named something like sdcc
2805 \series default
2806 .src
2807 \series medium
2808 .t
2809 \series default
2810 ar.
2811 \series medium
2812 gz.
2813 \layout Enumerate
2814
2815
2816 \series medium
2817 Bring up a command line terminal, such as xterm.
2818 \layout Enumerate
2819
2820
2821 \series medium
2822 Unpack the file using a command like:
2823 \family sans
2824 \series bold
2825 "tar -xvzf sdcc.src.tar.gz
2826 \family default
2827 \series default
2828 "
2829 \series medium
2830 , this will create a sub-directory called sdcc with all of the sources.
2831 \layout Enumerate
2832
2833 Change directory into the main SDCC directory, for example type:
2834 \family sans
2835 \series bold
2836 "cd sdcc
2837 \series default
2838 ".
2839 \layout Enumerate
2840
2841
2842 \series medium
2843 Type
2844 \family sans
2845 \series bold
2846 "./configure
2847 \family default
2848 \series default
2849 ".
2850  This configures the package for compilation on your system.
2851 \layout Enumerate
2852
2853
2854 \series medium
2855 Type
2856 \family sans
2857 \series bold
2858 "make
2859 \family default
2860 \series default
2861 "
2862 \series medium
2863 .
2864
2865 \series default
2866  All of the source packages will compile, this can take a while.
2867 \layout Enumerate
2868
2869
2870 \series medium
2871 Type
2872 \family sans
2873 \series bold
2874 "make install"
2875 \family default
2876 \series default
2877  as root
2878 \series medium
2879 .
2880
2881 \series default
2882  This copies the binary executables, the include files, the libraries and
2883  the documentation to the install directories.
2884 \layout Subsubsection
2885
2886 Building SDCC on OSX 2.x
2887 \layout Standard
2888
2889 Follow the instruction for Linux.
2890 \newline
2891
2892 \newline
2893 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
2894 )) fails to compile SDCC.
2895  Fortunately there's also gcc 2.9.x installed, which works fine.
2896  This compiler can be selected by running 'configure' with:
2897 \layout LyX-Code
2898
2899 ./configure CC=gcc2 CXX=g++2
2900 \layout Subsubsection
2901
2902 Cross compiling SDCC on Linux for Windows
2903 \layout Standard
2904
2905 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
2906  See section 'Configure Options'.
2907 \layout Subsubsection
2908
2909 Building SDCC on Windows
2910 \layout Standard
2911
2912 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
2913  built on Windows.
2914  They use Unix-sockets, which are not available on Win32.
2915 \layout Subsubsection
2916
2917 Building SDCC using Cygwin and Mingw32
2918 \layout Standard
2919
2920 For building and installing a Cygwin executable follow the instructions
2921  for Linux.
2922 \newline
2923
2924 \newline
2925 On Cygwin a
2926 \begin_inset Quotes sld
2927 \end_inset
2928
2929 native
2930 \begin_inset Quotes srd
2931 \end_inset
2932
2933  Win32-binary can be built, which will not need the Cygwin-DLL.
2934  For the necessary 'configure' options see section 'configure options' or
2935  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
2936 \newline
2937
2938 \newline
2939 In order to install Cygwin on Windows download setup.exe from
2940 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
2941
2942 \end_inset
2943
2944 .
2945  Run it, set the
2946 \begin_inset Quotes sld
2947 \end_inset
2948
2949 default text file type
2950 \begin_inset Quotes srd
2951 \end_inset
2952
2953  to
2954 \begin_inset Quotes sld
2955 \end_inset
2956
2957 unix
2958 \begin_inset Quotes srd
2959 \end_inset
2960
2961  and download/install at least the following packages.
2962  Some packages are selected by default, others will be automatically selected
2963  because of dependencies with the manually selected packages.
2964  Never deselect these packages!
2965 \layout Itemize
2966
2967 flex
2968 \layout Itemize
2969
2970 bison
2971 \layout Itemize
2972
2973 gcc ; version 3.x is fine, no need to use the old 2.9x
2974 \layout Itemize
2975
2976 binutils ; selected with gcc
2977 \layout Itemize
2978
2979 make
2980 \layout Itemize
2981
2982 rxvt ; a nice console, which makes life much easier under windoze (see below)
2983 \layout Itemize
2984
2985 man ; not really needed for building SDCC, but you'll miss it sooner or
2986  later
2987 \layout Itemize
2988
2989 less ; not really needed for building SDCC, but you'll miss it sooner or
2990  later
2991 \layout Itemize
2992
2993 cvs ; only if you use CVS access
2994 \layout Standard
2995
2996 If you want to develop something you'll need:
2997 \layout Itemize
2998
2999 python ; for the regression tests
3000 \layout Itemize
3001
3002 gdb ; the gnu debugger, together with the nice GUI
3003 \begin_inset Quotes sld
3004 \end_inset
3005
3006 insight
3007 \begin_inset Quotes srd
3008 \end_inset
3009
3010
3011 \layout Itemize
3012
3013 openssh ; to access the CF or commit changes
3014 \layout Itemize
3015
3016 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3017  use autoconf-stable!
3018 \layout Standard
3019
3020 rxvt is a nice console with history.
3021  Replace in your cygwin.bat the line
3022 \layout LyX-Code
3023
3024 bash -
3025 \begin_inset ERT
3026 status Collapsed
3027
3028 \layout Standard
3029
3030 \backslash
3031 /
3032 \end_inset
3033
3034 -login -i
3035 \layout Standard
3036
3037 with (one line):
3038 \layout LyX-Code
3039
3040 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3041 \layout LyX-Code
3042
3043      -bg black -fg white -geometry 100x65 -e bash -
3044 \begin_inset ERT
3045 status Collapsed
3046
3047 \layout Standard
3048
3049 \backslash
3050 /
3051 \end_inset
3052
3053 -login
3054 \layout Standard
3055
3056 Text selected with the mouse is automatically copied to the clipboard, pasting
3057  works with shift-insert.
3058 \newline
3059
3060 \newline
3061 The other good tip is to make sure you have no //c/-style paths anywhere,
3062  use /cygdrive/c/ instead.
3063  Using // invokes a network lookup which is very slow.
3064  If you think
3065 \begin_inset Quotes sld
3066 \end_inset
3067
3068 cygdrive
3069 \begin_inset Quotes srd
3070 \end_inset
3071
3072  is too long, you can change it with e.g.
3073 \layout LyX-Code
3074
3075 mount -s -u -c /mnt
3076 \layout Standard
3077
3078 SDCC sources use the unix line ending LF.
3079  Life is much easier, if you store the source tree on a drive which is mounted
3080  in binary mode.
3081  And use an editor which can handle LF-only line endings.
3082  Make sure not to commit files with windows line endings.
3083  The tabulator spacing used in the project is 8.
3084 \layout Subsubsection
3085
3086 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3087 \layout Standard
3088
3089
3090 \series medium
3091 Download the source package
3092 \series default
3093  either from the SDCC CVS repository or from the
3094 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3095
3096 \end_inset
3097
3098
3099 \series medium
3100 , it will be named something like sdcc
3101 \series default
3102 .src
3103 \series medium
3104 .tgz.
3105
3106 \series default
3107  SDCC is distributed with all the projects, workspaces, and files you need
3108  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3109  doesn't build under MSVC).
3110  The workspace name is 'sdcc.dsw'.
3111  Please note that as it is now, all the executables are created in a folder
3112  called sdcc
3113 \backslash
3114 bin_vc.
3115  Once built you need to copy the executables from sdcc
3116 \backslash
3117 bin_vc to sdcc
3118 \backslash
3119 bin before running SDCC.
3120
3121 \newline
3122
3123 \newline
3124 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3125  flex.exe, and gawk.exe.
3126  One good place to get them is
3127 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3128
3129 \end_inset
3130
3131
3132 \newline
3133
3134 \newline
3135 Download the file UnxUtils
3136 \begin_inset LatexCommand \index{UnxUtils}
3137
3138 \end_inset
3139
3140 .zip.
3141  Now you have to install the utilities and setup MSVC so it can locate the
3142  required programs.
3143  Here there are two alternatives (choose one!):
3144 \layout Enumerate
3145
3146 The easy way:
3147 \newline
3148
3149 \newline
3150 a) Extract UnxUtils.zip to your C:
3151 \backslash
3152  hard disk PRESERVING the original paths, otherwise bison won't work.
3153  (If you are using WinZip make certain that 'Use folder names' is selected)
3154 \newline
3155
3156 \newline
3157 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3158  in 'Show directories for:' select 'Executable files', and in the directories
3159  window add a new path: 'C:
3160 \backslash
3161 user
3162 \backslash
3163 local
3164 \backslash
3165 wbin', click ok.
3166 \newline
3167
3168 \newline
3169 (As a side effect, you get a bunch of Unix utilities that could be useful,
3170  such as diff and patch.)
3171 \layout Enumerate
3172
3173 A more compact way:
3174 \newline
3175
3176 \newline
3177 This one avoids extracting a bunch of files you may not use, but requires
3178  some extra work:
3179 \newline
3180
3181 \newline
3182 a) Create a directory were to put the tools needed, or use a directory already
3183  present.
3184  Say for example 'C:
3185 \backslash
3186 util'.
3187 \newline
3188
3189 \newline
3190 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3191  to such directory WITHOUT preserving the original paths.
3192  (If you are using WinZip make certain that 'Use folder names' is not selected)
3193 \newline
3194
3195 \newline
3196 c) Rename bison.exe to '_bison.exe'.
3197 \newline
3198
3199 \newline
3200 d) Create a batch file 'bison.bat' in 'C:
3201 \backslash
3202 util
3203 \backslash
3204 ' and add these lines:
3205 \newline
3206 \SpecialChar ~
3207 \SpecialChar ~
3208 set BISON_SIMPLE=C:
3209 \backslash
3210 util
3211 \backslash
3212 bison.simple
3213 \newline
3214 \SpecialChar ~
3215 \SpecialChar ~
3216 set BISON_HAIRY=C:
3217 \backslash
3218 util
3219 \backslash
3220 bison.hairy
3221 \newline
3222 \SpecialChar ~
3223 \SpecialChar ~
3224 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3225 \newline
3226
3227 \newline
3228 Steps 'c' and 'd' are needed because bison requires by default that the
3229  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3230  '/usr/local/share/' I think.
3231  So it is necessary to tell bison where those files are located if they
3232  are not in such directory.
3233  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3234 \newline
3235
3236 \newline
3237 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3238  in 'Show directories for:' select 'Executable files', and in the directories
3239  window add a new path: 'c:
3240 \backslash
3241 util', click ok.
3242  Note that you can use any other path instead of 'c:
3243 \backslash
3244 util', even the path where the Visual C++ tools are, probably: 'C:
3245 \backslash
3246 Program Files
3247 \backslash
3248 Microsoft Visual Studio
3249 \backslash
3250 Common
3251 \backslash
3252 Tools'.
3253  So you don't have to execute step 'e' :)
3254 \layout Standard
3255
3256 That is it.
3257  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3258  the executables from sdcc
3259 \backslash
3260 bin_vc to sdcc
3261 \backslash
3262 bin, and you can compile using SDCC.
3263 \layout Subsubsection
3264
3265 Building SDCC Using Borland
3266 \layout Enumerate
3267
3268 From the sdcc directory, run the command "make -f Makefile.bcc".
3269  This should regenerate all the .exe files in the bin directory except for
3270  sdcdb.exe (which currently doesn't build under Borland C++).
3271 \layout Enumerate
3272
3273 If you modify any source files and need to rebuild, be aware that the dependenci
3274 es may not be correctly calculated.
3275  The safest option is to delete all .obj files and run the build again.
3276  From a Cygwin BASH prompt, this can easily be done with the command (be
3277  sure you are in the sdcc directory):
3278 \newline
3279
3280 \newline
3281
3282 \family sans
3283 \series bold
3284 find .
3285
3286 \backslash
3287 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3288 \backslash
3289 ) -print -exec rm {}
3290 \backslash
3291 ;
3292 \family default
3293 \series default
3294
3295 \newline
3296
3297 \newline
3298 or on Windows NT/2000/XP from the command prompt with the command:
3299 \newline
3300
3301 \family sans
3302 \series bold
3303
3304 \newline
3305 del /s *.obj *.lib *.rul
3306 \family default
3307 \series default
3308  from the sdcc directory.
3309 \layout Subsubsection
3310
3311 Windows Install Using a Binary Package
3312 \begin_inset LatexCommand \label{sub:Windows-Install}
3313
3314 \end_inset
3315
3316
3317 \layout Enumerate
3318
3319 Download the binary package from
3320 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3321
3322 \end_inset
3323
3324  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3325  This should unpack to a group of sub-directories.
3326  An example directory structure after unpacking the mingw32 package is:
3327  c:
3328 \backslash
3329 sdcc
3330 \backslash
3331 bin for the executables, c:
3332 \backslash
3333 sdcc
3334 \backslash
3335 include and c:
3336 \backslash
3337 sdcc
3338 \backslash
3339 lib for the include and libraries.
3340 \layout Enumerate
3341
3342 Adjust your environment variable PATH to include the location of the bin
3343  directory or start sdcc using the full path.
3344 \layout Subsection
3345
3346 Building the Documentation
3347 \layout Standard
3348
3349 If the necessary tools are installed it is as easy as changing into the
3350  doc directory and typing
3351 \family sans
3352 \series bold
3353
3354 \begin_inset Quotes srd
3355 \end_inset
3356
3357 make
3358 \begin_inset Quotes srd
3359 \end_inset
3360
3361
3362 \family default
3363 \series default
3364  there.
3365  If you want to avoid installing the tools you will have some success with
3366  a bootable Knoppix CD
3367 \begin_inset LatexCommand \url{http://www.knopper.net}
3368
3369 \end_inset
3370
3371 .
3372  Prebuilt documentation in html and pdf format is available from
3373 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3374
3375 \end_inset
3376
3377 .
3378 \layout Subsection
3379
3380 Reading the Documentation
3381 \layout Standard
3382
3383 Currently reading the document in pdf format is recommended, as for unknown
3384  reason the hyperlinks are working there whereas in the html version they
3385  are not.
3386 \newline
3387 This documentation is in some aspects different from a commercial documentation:
3388
3389 \layout Itemize
3390
3391 It tries to document SDCC for several processor architectures in one document
3392  (commercially these probably would be separate documents/products).
3393  This document currently matches SDCC for mcs51 and DS390 best and does
3394  give too few information about f.e.
3395  Z80 and PIC.
3396 \layout Itemize
3397
3398 There are many references pointing away from this documentation.
3399  Don't let this distract you.
3400  If there f.e.
3401  was a reference like
3402 \begin_inset LatexCommand \url{www.opencores.org}
3403
3404 \end_inset
3405
3406  together with a statement
3407 \begin_inset Quotes sld
3408 \end_inset
3409
3410 some processors which are targetted by SDCC can be implemented in a field
3411  programmable array
3412 \begin_inset LatexCommand \index{fpga (field programmable array)}
3413
3414 \end_inset
3415
3416
3417 \begin_inset Quotes srd
3418 \end_inset
3419
3420  we expect you to have a quick look there and come back.
3421  If you read this you are on the right track.
3422 \layout Itemize
3423
3424 Some sections attribute more space to problems, restrictions and warnings
3425  than to the solution.
3426 \layout Itemize
3427
3428 The installation section and the section about the debugger is intimidating.
3429 \layout Itemize
3430
3431 There are still lots of typos and there are more different writing styles
3432  than pictures.
3433 \layout Subsection
3434
3435 Testing the SDCC Compiler
3436 \layout Standard
3437
3438 The first thing you should do after installing your SDCC compiler is to
3439  see if it runs.
3440  Type
3441 \family sans
3442 \series bold
3443 "sdcc -
3444 \begin_inset ERT
3445 status Collapsed
3446
3447 \layout Standard
3448
3449 \backslash
3450 /
3451 \end_inset
3452
3453 -version"
3454 \begin_inset LatexCommand \index{version}
3455
3456 \end_inset
3457
3458
3459 \family default
3460 \series default
3461  at the prompt, and the program should run and tell you the version.
3462  If it doesn't run, or gives a message about not finding sdcc program, then
3463  you need to check over your installation.
3464  Make sure that the sdcc bin directory is in your executable search path
3465  defined by the PATH environment setting (
3466 \series medium
3467 see
3468 \series default
3469 section
3470 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3471
3472 \end_inset
3473
3474 \SpecialChar ~
3475
3476 \series medium
3477 Install trouble-shooting for suggestions
3478 \series default
3479 ).
3480  Make sure that the sdcc program is in the bin folder, if not perhaps something
3481  did not install correctly.
3482 \newline
3483
3484 \newline
3485
3486 \series medium
3487 SDCC
3488 \series default
3489 is commonly installed as described in section
3490 \begin_inset Quotes sld
3491 \end_inset
3492
3493 Install and search paths
3494 \begin_inset Quotes srd
3495 \end_inset
3496
3497
3498 \newline
3499
3500 \newline
3501
3502 \series medium
3503 Make sure the compiler works on a very simple example.
3504  Type in the following test.c program using your favorite
3505 \series default
3506 ASCII
3507 \series medium
3508 editor:
3509 \layout Verse
3510
3511
3512 \family typewriter
3513 char test;
3514 \newline
3515
3516 \newline
3517 void main(void) {
3518 \newline
3519 \SpecialChar ~
3520 \SpecialChar ~
3521 \SpecialChar ~
3522 \SpecialChar ~
3523 test=0;
3524 \newline
3525 }
3526 \layout Standard
3527
3528
3529 \series medium
3530 Compile this using the following command:
3531 \family sans
3532 \series bold
3533 "sdcc -c test.c".
3534
3535 \family default
3536 \series default
3537
3538 \series medium
3539 If all goes well, the compiler will generate a test.asm and test.rel file.
3540  Congratulations, you've just compiled your first program with SDCC.
3541  We used the -c option to tell SDCC not to link the generated code, just
3542  to keep things simple for this step.
3543 \series default
3544
3545 \newline
3546
3547 \newline
3548
3549 \series medium
3550 The next step is to try it with the linker.
3551  Type in
3552 \family sans
3553 \series bold
3554 "sdcc test.c
3555 \family default
3556 \series default
3557 "
3558 \series medium
3559 .
3560  If all goes well the compiler will link with the libraries and produce
3561  a test.ihx output file.
3562  If this step fails
3563 \series default
3564
3565 \series medium
3566 (no test.ihx, and the linker generates warnings), then the problem is most
3567  likely that
3568 \series default
3569 SDCC
3570 \series medium
3571  cannot find the
3572 \series default
3573 /
3574 \series medium
3575 usr/local/share/sdcc/lib directory
3576 \series default
3577
3578 \series medium
3579 (see
3580 \series default
3581 section
3582 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3583
3584 \end_inset
3585
3586 \SpecialChar ~
3587
3588 \series medium
3589 Install trouble-shooting for suggestions).
3590 \series default
3591
3592 \newline
3593
3594 \newline
3595
3596 \series medium
3597 The final test is to ensure
3598 \series default
3599 SDCC
3600 \series medium
3601  can use the
3602 \series default
3603 standard
3604 \series medium
3605  header files and libraries.
3606  Edit test.c and change it to the following:
3607 \layout Verse
3608
3609
3610 \family typewriter
3611 #include <string.h>
3612 \newline
3613
3614 \newline
3615 char str1[10];
3616 \newline
3617
3618 \newline
3619 void main(void) {
3620 \newline
3621 \SpecialChar ~
3622 \SpecialChar ~
3623 strcpy(str1, "testing");
3624 \newline
3625 }
3626 \layout Standard
3627
3628
3629 \series medium
3630 Compile this by typing
3631 \family sans
3632 \series bold
3633 "sdcc test.c"
3634 \family default
3635 \series medium
3636 .
3637  This should generate a test.ihx output file, and it should give no warnings
3638  such as not finding the string.h file.
3639  If it cannot find the string.h file, then the problem is that
3640 \series default
3641 SDCC
3642 \series medium
3643  cannot find the /usr/local/share/sdcc/include directory
3644 \series default
3645
3646 \series medium
3647 (see the
3648 \series default
3649 section
3650 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3651
3652 \end_inset
3653
3654 \SpecialChar ~
3655
3656 \series medium
3657 Install trouble-shooting section for suggestions).
3658
3659 \series default
3660  Use option
3661 \series bold
3662 -
3663 \begin_inset ERT
3664 status Collapsed
3665
3666 \layout Standard
3667
3668 \backslash
3669 /
3670 \end_inset
3671
3672 -print-search-dirs
3673 \series default
3674
3675 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3676
3677 \end_inset
3678
3679  to find exactly where SDCC is looking for the include and lib files.
3680 \layout Subsection
3681
3682 Install Trouble-shooting
3683 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3684
3685 \end_inset
3686
3687
3688 \begin_inset LatexCommand \index{Install trouble-shooting}
3689
3690 \end_inset
3691
3692
3693 \layout Subsubsection
3694
3695 SDCC does not build correctly.
3696 \layout Standard
3697
3698 A thing to try is starting from scratch by unpacking the .tgz source package
3699  again in an empty directory.
3700  Configure it like:
3701 \newline
3702
3703 \newline
3704
3705 \family sans
3706 \series bold
3707 ./configure 2>&1 | tee configure.log
3708 \family default
3709 \series default
3710
3711 \newline
3712
3713 \newline
3714 and build it like:
3715 \newline
3716
3717 \newline
3718
3719 \family sans
3720 \series bold
3721 make 2>&1 | tee make.log
3722 \family default
3723 \series default
3724
3725 \newline
3726
3727 \newline
3728 If anything goes wrong, you can review the log files to locate the problem.
3729  Or a relevant part of this can be attached to an email that could be helpful
3730  when requesting help from the mailing list.
3731 \layout Subsubsection
3732
3733 What the
3734 \begin_inset Quotes sld
3735 \end_inset
3736
3737 ./configure
3738 \begin_inset Quotes srd
3739 \end_inset
3740
3741  does
3742 \layout Standard
3743
3744 The
3745 \begin_inset Quotes sld
3746 \end_inset
3747
3748 ./configure
3749 \begin_inset Quotes srd
3750 \end_inset
3751
3752  command is a script that analyzes your system and performs some configuration
3753  to ensure the source package compiles on your system.
3754  It will take a few minutes to run, and will compile a few tests to determine
3755  what compiler features are installed.
3756 \layout Subsubsection
3757
3758 What the
3759 \begin_inset Quotes sld
3760 \end_inset
3761
3762 make
3763 \begin_inset Quotes srd
3764 \end_inset
3765
3766  does.
3767 \layout Standard
3768
3769 This runs the GNU make tool, which automatically compiles all the source
3770  packages into the final installed binary executables.
3771 \layout Subsubsection
3772
3773 What the
3774 \begin_inset Quotes sld
3775 \end_inset
3776
3777 make install
3778 \begin_inset Quotes erd
3779 \end_inset
3780
3781  command does.
3782 \layout Standard
3783
3784 This will install the compiler, other executables libraries and include
3785  files into the appropriate directories.
3786  See sections
3787 \begin_inset LatexCommand \ref{sub:Install-paths}
3788
3789 \end_inset
3790
3791 ,\SpecialChar ~
3792
3793 \begin_inset LatexCommand \ref{sub:Search-Paths}
3794
3795 \end_inset
3796
3797 \SpecialChar ~
3798 about install and search paths.
3799 \newline
3800 On most systems you will need super-user privileges to do this.
3801 \layout Subsection
3802
3803 Components of SDCC
3804 \layout Standard
3805
3806 SDCC is not just a compiler, but a collection of tools by various developers.
3807  These include linkers, assemblers, simulators and other components.
3808  Here is a summary of some of the components.
3809  Note that the included simulator and assembler have separate documentation
3810  which you can find in the source package in their respective directories.
3811  As SDCC grows to include support for other processors, other packages from
3812  various developers are included and may have their own sets of documentation.
3813 \newline
3814
3815 \newline
3816 You might want to look at the files which are installed in <installdir>.
3817  At the time of this writing, we find the following programs for gcc-builds:
3818 \newline
3819
3820 \newline
3821 In <installdir>/bin:
3822 \layout Itemize
3823
3824 sdcc - The compiler.
3825 \layout Itemize
3826
3827 sdcpp - The C preprocessor.
3828 \layout Itemize
3829
3830 asx8051 - The assembler for 8051 type processors.
3831 \layout Itemize
3832
3833 as-z80
3834 \series bold
3835 ,
3836 \series default
3837 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
3838 \layout Itemize
3839
3840 aslink -The linker for 8051 type processors.
3841 \layout Itemize
3842
3843 link-z80
3844 \series bold
3845 ,
3846 \series default
3847 link-gbz80 - The Z80 and GameBoy Z80 linkers.
3848 \layout Itemize
3849
3850 s51 - The ucSim 8051 simulator.
3851 \layout Itemize
3852
3853 sdcdb - The source debugger.
3854 \layout Itemize
3855
3856 packihx - A tool to pack (compress) Intel hex files.
3857 \layout Standard
3858
3859 In <installdir>/share/sdcc/include
3860 \layout Itemize
3861
3862 the include files
3863 \layout Standard
3864
3865 In <installdir>/share/sdcc/lib
3866 \layout Itemize
3867
3868 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
3869  relocatables.
3870 \layout Standard
3871
3872 In <installdir>/share/sdcc/doc
3873 \layout Itemize
3874
3875 the documentation
3876 \layout Standard
3877
3878 As development for other processors proceeds, this list will expand to include
3879  executables to support processors like AVR, PIC, etc.
3880 \layout Subsubsection
3881
3882 sdcc - The Compiler
3883 \layout Standard
3884
3885 This is the actual compiler, it in turn uses the c-preprocessor and invokes
3886  the assembler and linkage editor.
3887 \layout Subsubsection
3888
3889 sdcpp
3890 \begin_inset LatexCommand \index{sdcpp}
3891
3892 \end_inset
3893
3894  - The C-Preprocessor
3895 \layout Standard
3896
3897 The preprocessor is a modified version of the GNU preprocessor.
3898  The C preprocessor is used to pull in #include sources, process #ifdef
3899  statements, #defines and so on.
3900 \layout Subsubsection
3901
3902 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 - The Assemblers
3903  and Linkage Editors
3904 \layout Standard
3905
3906 This is retargettable assembler & linkage editor, it was developed by Alan
3907  Baldwin.
3908  John Hartman created the version for 8051, and I (Sandeep) have made some
3909  enhancements and bug fixes for it to work properly with SDCC.
3910 \layout Subsubsection
3911
3912 s51 - The Simulator
3913 \begin_inset LatexCommand \index{s51}
3914
3915 \end_inset
3916
3917
3918 \layout Standard
3919
3920 S51 is a freeware, opensource simulator developed by Daniel Drotos (
3921 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
3922
3923 \end_inset
3924
3925 ).
3926  The simulator is built as part of the build process.
3927  For more information visit Daniel's web site at:
3928 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
3929
3930 \end_inset
3931
3932 .
3933  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
3934  XA51 family.
3935 \layout Subsubsection
3936
3937 sdcdb
3938 \begin_inset LatexCommand \index{sdcdb}
3939
3940 \end_inset
3941
3942  - Source Level Debugger
3943 \layout Standard
3944
3945 Sdcdb is the companion source level debugger.
3946  The current version of the debugger uses Daniel's Simulator S51
3947 \begin_inset LatexCommand \index{s51}
3948
3949 \end_inset
3950
3951 , but can be easily changed to use other simulators.
3952 \layout Section
3953 \pagebreak_top
3954 Using SDCC
3955 \layout Subsection
3956
3957 Compiling
3958 \layout Subsubsection
3959
3960 Single Source File Projects
3961 \layout Standard
3962
3963 For single source file 8051 projects the process is very simple.
3964  Compile your programs with the following command
3965 \family sans
3966 \series bold
3967 "sdcc sourcefile.c".
3968
3969 \family default
3970 \series default
3971  This will compile, assemble and link your source file.
3972  Output files are as follows
3973 \layout Itemize
3974
3975 sourcefile.asm
3976 \begin_inset LatexCommand \index{.asm}
3977
3978 \end_inset
3979
3980  - Assembler source
3981 \begin_inset LatexCommand \index{Assembler source}
3982
3983 \end_inset
3984
3985  file created by the compiler
3986 \layout Itemize
3987
3988 sourcefile.lst
3989 \begin_inset LatexCommand \index{.lst}
3990
3991 \end_inset
3992
3993  - Assembler listing
3994 \begin_inset LatexCommand \index{Assembler listing}
3995
3996 \end_inset
3997
3998  file created by the Assembler
3999 \layout Itemize
4000
4001 sourcefile.rst
4002 \begin_inset LatexCommand \index{.rst}
4003
4004 \end_inset
4005
4006  - Assembler listing
4007 \begin_inset LatexCommand \index{Assembler listing}
4008
4009 \end_inset
4010
4011  file updated with linkedit information, created by linkage editor
4012 \layout Itemize
4013
4014 sourcefile.sym
4015 \begin_inset LatexCommand \index{.sym}
4016
4017 \end_inset
4018
4019  - symbol listing
4020 \begin_inset LatexCommand \index{Symbol listing}
4021
4022 \end_inset
4023
4024  for the sourcefile, created by the assembler
4025 \layout Itemize
4026
4027 sourcefile.rel
4028 \begin_inset LatexCommand \index{.rel}
4029
4030 \end_inset
4031
4032  - Object file
4033 \begin_inset LatexCommand \index{Object file}
4034
4035 \end_inset
4036
4037  created by the assembler, input to Linkage editor
4038 \layout Itemize
4039
4040 sourcefile.map
4041 \begin_inset LatexCommand \index{.map}
4042
4043 \end_inset
4044
4045  - The memory map
4046 \begin_inset LatexCommand \index{Memory map}
4047
4048 \end_inset
4049
4050  for the load module, created by the Linker
4051 \layout Itemize
4052
4053 sourcefile.mem
4054 \begin_inset LatexCommand \index{.mem}
4055
4056 \end_inset
4057
4058  - A file with a summary of the memory usage
4059 \layout Itemize
4060
4061 sourcefile.ihx
4062 \begin_inset LatexCommand \index{.ihx}
4063
4064 \end_inset
4065
4066  - The load module in Intel hex format
4067 \begin_inset LatexCommand \index{Intel hex format}
4068
4069 \end_inset
4070
4071  (you can select the Motorola S19 format
4072 \begin_inset LatexCommand \index{Motorola S19 format}
4073
4074 \end_inset
4075
4076  with -
4077 \begin_inset ERT
4078 status Collapsed
4079
4080 \layout Standard
4081
4082 \backslash
4083 /
4084 \end_inset
4085
4086 -out-fmt-s19
4087 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4088
4089 \end_inset
4090
4091 .
4092  If you need another format you might want to use
4093 \family sans
4094 \shape italic
4095 objdump
4096 \family default
4097 \shape default
4098
4099 \begin_inset LatexCommand \index{objdump}
4100
4101 \end_inset
4102
4103  or
4104 \family sans
4105 \shape italic
4106  srecord
4107 \family default
4108 \shape default
4109
4110 \begin_inset LatexCommand \index{srecord}
4111
4112 \end_inset
4113
4114 )
4115 \layout Itemize
4116
4117 sourcefile.adb
4118 \begin_inset LatexCommand \index{.adb}
4119
4120 \end_inset
4121
4122  - An intermediate file containing debug information needed to create the
4123  .cdb file (with -
4124 \begin_inset ERT
4125 status Collapsed
4126
4127 \layout Standard
4128
4129 \backslash
4130 /
4131 \end_inset
4132
4133 -debug
4134 \begin_inset LatexCommand \index{-\/-debug}
4135
4136 \end_inset
4137
4138 )
4139 \layout Itemize
4140
4141 sourcefile.cdb
4142 \begin_inset LatexCommand \index{.cdb}
4143
4144 \end_inset
4145
4146  - An optional file (with -
4147 \begin_inset ERT
4148 status Collapsed
4149
4150 \layout Standard
4151
4152 \backslash
4153 /
4154 \end_inset
4155
4156 -debug) containing debug information
4157 \layout Itemize
4158
4159 sourcefile.
4160  - (no extension)
4161 \begin_inset LatexCommand \index{. (no extension)}
4162
4163 \end_inset
4164
4165  An optional AOMF51
4166 \begin_inset LatexCommand \index{AOMF51}
4167
4168 \end_inset
4169
4170  file containing debug information (with -
4171 \begin_inset ERT
4172 status Collapsed
4173
4174 \layout Standard
4175
4176 \backslash
4177 /
4178 \end_inset
4179
4180 -debug).
4181  This format is commonly used by third party tools (debuggers
4182 \begin_inset LatexCommand \index{Debugger}
4183
4184 \end_inset
4185
4186 , simulators, emulators)
4187 \layout Itemize
4188
4189 sourcefile.dump*
4190 \begin_inset LatexCommand \index{.dump*}
4191
4192 \end_inset
4193
4194  - Dump file to debug the compiler it self (with -
4195 \begin_inset ERT
4196 status Collapsed
4197
4198 \layout Standard
4199
4200 \backslash
4201 /
4202 \end_inset
4203
4204 -dumpall) (see section
4205 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4206
4207 \end_inset
4208
4209 \SpecialChar ~
4210  and section
4211 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4212
4213 \end_inset
4214
4215 \SpecialChar ~
4216
4217 \begin_inset Quotes sld
4218 \end_inset
4219
4220 Anatomy of the compiler
4221 \begin_inset Quotes srd
4222 \end_inset
4223
4224 ).
4225 \layout Subsubsection
4226
4227 Projects with Multiple Source Files
4228 \layout Standard
4229
4230 SDCC can compile only ONE file at a time.
4231  Let us for example assume that you have a project containing the following
4232  files:
4233 \newline
4234
4235 \newline
4236 foo1.c (contains some functions)
4237 \newline
4238 foo2.c (contains some more functions)
4239 \newline
4240 foomain.c (contains more functions and the function main)
4241 \newline
4242
4243 \size footnotesize
4244
4245 \newline
4246
4247 \size default
4248 The first two files will need to be compiled separately with the commands:
4249 \size footnotesize
4250
4251 \size default
4252
4253 \newline
4254
4255 \newline
4256
4257 \family sans
4258 \series bold
4259 sdcc\SpecialChar ~
4260 -c\SpecialChar ~
4261 foo1.c
4262 \family default
4263 \series default
4264 \size footnotesize
4265
4266 \newline
4267
4268 \family sans
4269 \series bold
4270 \size default
4271 sdcc\SpecialChar ~
4272 -c\SpecialChar ~
4273 foo2.c
4274 \family default
4275 \series default
4276
4277 \newline
4278
4279 \newline
4280 Then compile the source file containing the
4281 \emph on
4282 main()
4283 \emph default
4284  function and link
4285 \begin_inset LatexCommand \index{Linker}
4286
4287 \end_inset
4288
4289  the files together with the following command:
4290 \newline
4291
4292 \newline
4293
4294 \family sans
4295 \series bold
4296 sdcc\SpecialChar ~
4297 foomain.c\SpecialChar ~
4298 foo1.rel\SpecialChar ~
4299 foo2.rel
4300 \family default
4301 \series default
4302
4303 \begin_inset LatexCommand \index{.rel}
4304
4305 \end_inset
4306
4307
4308 \newline
4309
4310 \newline
4311 Alternatively,
4312 \emph on
4313 foomain.c
4314 \emph default
4315 can be separately compiled as well:
4316 \family sans
4317 \series bold
4318
4319 \newline
4320
4321 \newline
4322 sdcc\SpecialChar ~
4323 -c\SpecialChar ~
4324 foomain.c
4325 \newline
4326 sdcc foomain.rel foo1.rel foo2.rel
4327 \newline
4328
4329 \newline
4330
4331 \family default
4332 \series default
4333 The file containing the
4334 \emph on
4335 main()
4336 \emph default
4337  function
4338 \emph on
4339
4340 \emph default
4341 \noun on
4342 must
4343 \noun default
4344  be the
4345 \noun on
4346 first
4347 \noun default
4348  file specified in the command line, since the linkage editor processes
4349  file in the order they are presented to it.
4350  The linker is invoked from SDCC using a script file with extension .lnk
4351 \begin_inset LatexCommand \index{.lnk}
4352
4353 \end_inset
4354
4355 .
4356  You can view this file to troubleshoot linking problems such as those arising
4357  from missing libraries.
4358 \layout Subsubsection
4359
4360 Projects with Additional Libraries
4361 \begin_inset LatexCommand \index{Libraries}
4362
4363 \end_inset
4364
4365
4366 \layout Standard
4367
4368 Some reusable routines may be compiled into a library, see the documentation
4369  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4370  for how to create a
4371 \emph on
4372 .lib
4373 \begin_inset LatexCommand \index{.lib}
4374
4375 \end_inset
4376
4377
4378 \emph default
4379  library file.
4380  Libraries created in this manner can be included in the command line.
4381  Make sure you include the -L <library-path> option to tell the linker where
4382  to look for these files if they are not in the current directory.
4383  Here is an example, assuming you have the source file
4384 \emph on
4385 foomain.c
4386 \emph default
4387  and a library
4388 \emph on
4389  foolib.lib
4390 \emph default
4391  in the directory
4392 \emph on
4393 mylib
4394 \emph default
4395  (if that is not the same as your current project):
4396 \newline
4397
4398 \newline
4399
4400 \family sans
4401 \series bold
4402 sdcc foomain.c foolib.lib -L mylib
4403 \newline
4404
4405 \newline
4406
4407 \family default
4408 \series default
4409 Note here that
4410 \emph on
4411  mylib
4412 \emph default
4413  must be an absolute path name.
4414 \newline
4415
4416 \newline
4417 The most efficient way to use libraries is to keep separate modules in separate
4418  source files.
4419  The lib file now should name all the modules.rel
4420 \begin_inset LatexCommand \index{rel}
4421
4422 \end_inset
4423
4424  files.
4425  For an example see the standard library file
4426 \emph on
4427 libsdcc.lib
4428 \emph default
4429  in the directory <installdir>/share/lib/small.
4430 \layout Subsection
4431
4432 Command Line Options
4433 \begin_inset LatexCommand \index{Command Line Options}
4434
4435 \end_inset
4436
4437
4438 \layout Subsubsection
4439
4440 Processor Selection Options
4441 \begin_inset LatexCommand \index{Options processor selection}
4442
4443 \end_inset
4444
4445
4446 \begin_inset LatexCommand \index{Processor selection options}
4447
4448 \end_inset
4449
4450
4451 \layout List
4452 \labelwidthstring 00.00.0000
4453
4454
4455 \series bold
4456 -mmcs51
4457 \begin_inset LatexCommand \index{-mmcs51}
4458
4459 \end_inset
4460
4461
4462 \series default
4463  Generate code for the Intel MCS51
4464 \begin_inset LatexCommand \index{MCS51}
4465
4466 \end_inset
4467
4468  family of processors.
4469  This is the default processor target.
4470 \layout List
4471 \labelwidthstring 00.00.0000
4472
4473
4474 \series bold
4475 -mds390
4476 \begin_inset LatexCommand \index{-mds390}
4477
4478 \end_inset
4479
4480
4481 \series default
4482  Generate code for the Dallas DS80C390
4483 \begin_inset LatexCommand \index{DS80C390}
4484
4485 \end_inset
4486
4487  processor.
4488 \layout List
4489 \labelwidthstring 00.00.0000
4490
4491
4492 \series bold
4493 -mds400
4494 \begin_inset LatexCommand \index{-mds400}
4495
4496 \end_inset
4497
4498
4499 \series default
4500  Generate code for the Dallas DS80C400
4501 \begin_inset LatexCommand \index{DS80C400}
4502
4503 \end_inset
4504
4505  processor.
4506 \layout List
4507 \labelwidthstring 00.00.0000
4508
4509
4510 \series bold
4511 -mz80
4512 \begin_inset LatexCommand \index{-mz80}
4513
4514 \end_inset
4515
4516
4517 \series default
4518  Generate code for the Zilog Z80
4519 \begin_inset LatexCommand \index{Z80}
4520
4521 \end_inset
4522
4523  family of processors.
4524 \layout List
4525 \labelwidthstring 00.00.0000
4526
4527
4528 \series bold
4529 -mgbz80
4530 \begin_inset LatexCommand \index{-mgbz80}
4531
4532 \end_inset
4533
4534
4535 \series default
4536  Generate code for the GameBoy Z80
4537 \begin_inset LatexCommand \index{GameBoy Z80}
4538
4539 \end_inset
4540
4541  processor.
4542 \layout List
4543 \labelwidthstring 00.00.0000
4544
4545
4546 \series bold
4547 -mavr
4548 \begin_inset LatexCommand \index{-mavr}
4549
4550 \end_inset
4551
4552
4553 \series default
4554  Generate code for the Atmel AVR
4555 \begin_inset LatexCommand \index{AVR}
4556
4557 \end_inset
4558
4559  processor (In development, not complete).
4560  AVR users should probably have a look at avr-gcc
4561 \begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
4562
4563 \end_inset
4564
4565 .
4566 \layout Comment
4567
4568 I think it is fair to direct users there for now.
4569  Open source is also about avoiding unnecessary work .
4570  But I didn't find the 'official' link.
4571 \layout List
4572 \labelwidthstring 00.00.0000
4573
4574
4575 \series bold
4576 -mpic14
4577 \begin_inset LatexCommand \index{-mpic14}
4578
4579 \end_inset
4580
4581
4582 \series default
4583  Generate code for the Microchip PIC 14
4584 \begin_inset LatexCommand \index{PIC14}
4585
4586 \end_inset
4587
4588 -bit processors (p16f84 and variants).
4589 \layout Comment
4590
4591 p16f627 p16f628 p16f84 p16f873 p16f877?
4592 \layout List
4593 \labelwidthstring 00.00.0000
4594
4595
4596 \series bold
4597 -mpic16
4598 \begin_inset LatexCommand \index{-mpic16}
4599
4600 \end_inset
4601
4602
4603 \series default
4604  Generate code for the Microchip PIC 16
4605 \begin_inset LatexCommand \index{PIC16}
4606
4607 \end_inset
4608
4609 -bit processors (p18f452 and variants).
4610 \layout List
4611 \labelwidthstring 00.00.0000
4612
4613
4614 \series bold
4615 -mtlcs900h
4616 \series default
4617  Generate code for the Toshiba TLCS-900H
4618 \begin_inset LatexCommand \index{TLCS-900H}
4619
4620 \end_inset
4621
4622  processor (In development, not complete).
4623 \layout List
4624 \labelwidthstring 00.00.0000
4625
4626
4627 \series bold
4628 -mxa51
4629 \begin_inset LatexCommand \index{-mxa51}
4630
4631 \end_inset
4632
4633
4634 \series default
4635  Generate code for the Phillips XA51
4636 \begin_inset LatexCommand \index{XA51}
4637
4638 \end_inset
4639
4640  processor (In development, not complete).
4641 \layout Subsubsection
4642
4643 Preprocessor Options
4644 \begin_inset LatexCommand \index{Options preprocessor}
4645
4646 \end_inset
4647
4648
4649 \begin_inset LatexCommand \index{Preprocessor options}
4650
4651 \end_inset
4652
4653
4654 \layout List
4655 \labelwidthstring 00.00.0000
4656
4657
4658 \series bold
4659 -I<path>
4660 \begin_inset LatexCommand \index{-I<path>}
4661
4662 \end_inset
4663
4664
4665 \series default
4666  The additional location where the pre processor will look for <..h> or
4667 \begin_inset Quotes eld
4668 \end_inset
4669
4670 ..h
4671 \begin_inset Quotes erd
4672 \end_inset
4673
4674  files.
4675 \layout List
4676 \labelwidthstring 00.00.0000
4677
4678
4679 \series bold
4680 -D<macro[=value]>
4681 \begin_inset LatexCommand \index{-D<macro[=value]>}
4682
4683 \end_inset
4684
4685
4686 \series default
4687  Command line definition of macros.
4688  Passed to the preprocessor.
4689 \layout List
4690 \labelwidthstring 00.00.0000
4691
4692
4693 \series bold
4694 -M
4695 \begin_inset LatexCommand \index{-M}
4696
4697 \end_inset
4698
4699
4700 \series default
4701  Tell the preprocessor to output a rule suitable for make describing the
4702  dependencies of each object file.
4703  For each source file, the preprocessor outputs one make-rule whose target
4704  is the object file name for that source file and whose dependencies are
4705  all the files `#include'd in it.
4706  This rule may be a single line or may be continued with `
4707 \backslash
4708 '-newline if it is long.
4709  The list of rules is printed on standard output instead of the preprocessed
4710  C program.
4711  `-M' implies `-E
4712 \begin_inset LatexCommand \index{-E}
4713
4714 \end_inset
4715
4716 '.
4717 \layout List
4718 \labelwidthstring 00.00.0000
4719
4720
4721 \series bold
4722 -C
4723 \begin_inset LatexCommand \index{-C}
4724
4725 \end_inset
4726
4727
4728 \series default
4729  Tell the preprocessor not to discard comments.
4730  Used with the `-E' option.
4731 \layout List
4732 \labelwidthstring 00.00.0000
4733
4734
4735 \series bold
4736 -MM
4737 \begin_inset LatexCommand \index{-MM}
4738
4739 \end_inset
4740
4741
4742 \size large
4743 \bar under
4744
4745 \series default
4746 \size default
4747 \bar default
4748 Like `-M' but the output mentions only the user header files included with
4749  `#include
4750 \begin_inset Quotes eld
4751 \end_inset
4752
4753 file"'.
4754  System header files included with `#include <file>' are omitted.
4755 \layout List
4756 \labelwidthstring 00.00.0000
4757
4758
4759 \series bold
4760 -Aquestion(answer)
4761 \begin_inset LatexCommand \index{-Aquestion(answer)}
4762
4763 \end_inset
4764
4765
4766 \series default
4767  Assert the answer answer for question, in case it is tested with a preprocessor
4768  conditional such as `#if #question(answer)'.
4769  `-A-' disables the standard assertions that normally describe the target
4770  machine.
4771 \layout List
4772 \labelwidthstring 00.00.0000
4773
4774
4775 \series bold
4776 -Umacro
4777 \begin_inset LatexCommand \index{-Umacro}
4778
4779 \end_inset
4780
4781
4782 \series default
4783  Undefine macro macro.
4784  `-U' options are evaluated after all `-D' options, but before any `-include'
4785  and `-imacros' options.
4786 \layout List
4787 \labelwidthstring 00.00.0000
4788
4789
4790 \series bold
4791 -dM
4792 \begin_inset LatexCommand \index{-dM}
4793
4794 \end_inset
4795
4796
4797 \series default
4798  Tell the preprocessor to output only a list of the macro definitions that
4799  are in effect at the end of preprocessing.
4800  Used with the `-E' option.
4801 \layout List
4802 \labelwidthstring 00.00.0000
4803
4804
4805 \series bold
4806 -dD
4807 \begin_inset LatexCommand \index{-dD}
4808
4809 \end_inset
4810
4811
4812 \series default
4813  Tell the preprocessor to pass all macro definitions into the output, in
4814  their proper sequence in the rest of the output.
4815 \layout List
4816 \labelwidthstring 00.00.0000
4817
4818
4819 \series bold
4820 -dN
4821 \begin_inset LatexCommand \index{-dN}
4822
4823 \end_inset
4824
4825
4826 \size large
4827 \bar under
4828
4829 \series default
4830 \size default
4831 \bar default
4832 Like `-dD' except that the macro arguments and contents are omitted.
4833  Only `#define name' is included in the output.
4834 \layout Subsubsection
4835
4836 Linker Options
4837 \begin_inset LatexCommand \index{Options linker}
4838
4839 \end_inset
4840
4841
4842 \begin_inset LatexCommand \index{Linker options}
4843
4844 \end_inset
4845
4846
4847 \layout List
4848 \labelwidthstring 00.00.0000
4849
4850
4851 \series bold
4852 -L\SpecialChar ~
4853 -
4854 \series default
4855
4856 \begin_inset ERT
4857 status Collapsed
4858
4859 \layout Standard
4860
4861 \backslash
4862 /
4863 \end_inset
4864
4865
4866 \series bold
4867 -lib-path
4868 \begin_inset LatexCommand \index{-\/-lib-path}
4869
4870 \end_inset
4871
4872
4873 \begin_inset LatexCommand \index{-L -\/-lib-path}
4874
4875 \end_inset
4876
4877
4878 \bar under
4879
4880 \series default
4881 \bar default
4882 <absolute path to additional libraries> This option is passed to the linkage
4883  editor's additional libraries
4884 \begin_inset LatexCommand \index{Libraries}
4885
4886 \end_inset
4887
4888  search path.
4889  The path name must be absolute.
4890  Additional library files may be specified in the command line.
4891  See section Compiling programs for more details.
4892 \layout List
4893 \labelwidthstring 00.00.0000
4894
4895
4896 \series bold
4897 -
4898 \begin_inset ERT
4899 status Collapsed
4900
4901 \layout Standard
4902
4903 \backslash
4904 /
4905 \end_inset
4906
4907 -xram-loc
4908 \series default
4909
4910 \begin_inset LatexCommand \index{-\/-xram-loc}
4911
4912 \end_inset
4913
4914 <Value> The start location of the external ram
4915 \begin_inset LatexCommand \index{xdata}
4916
4917 \end_inset
4918
4919 , default value is 0.
4920  The value entered can be in Hexadecimal or Decimal format, e.g.: -
4921 \begin_inset ERT
4922 status Collapsed
4923
4924 \layout Standard
4925
4926 \backslash
4927 /
4928 \end_inset
4929
4930 -xram-loc 0x8000 or -
4931 \begin_inset ERT
4932 status Collapsed
4933
4934 \layout Standard
4935
4936 \backslash
4937 /
4938 \end_inset
4939
4940 -xram-loc 32768.
4941 \layout List
4942 \labelwidthstring 00.00.0000
4943
4944
4945 \series bold
4946 -
4947 \begin_inset ERT
4948 status Collapsed
4949
4950 \layout Standard
4951
4952 \backslash
4953 /
4954 \end_inset
4955
4956 -code-loc
4957 \series default
4958
4959 \begin_inset LatexCommand \index{-\/-code-loc}
4960
4961 \end_inset
4962
4963 <Value> The start location of the code
4964 \begin_inset LatexCommand \index{code}
4965
4966 \end_inset
4967
4968  segment, default value 0.
4969  Note when this option is used the interrupt vector table is also relocated
4970  to the given address.
4971  The value entered can be in Hexadecimal or Decimal format, e.g.: -
4972 \begin_inset ERT
4973 status Collapsed
4974
4975 \layout Standard
4976
4977 \backslash
4978 /
4979 \end_inset
4980
4981 -code-loc 0x8000 or -
4982 \begin_inset ERT
4983 status Collapsed
4984
4985 \layout Standard
4986
4987 \backslash
4988 /
4989 \end_inset
4990
4991 -code-loc 32768.
4992 \layout List
4993 \labelwidthstring 00.00.0000
4994
4995
4996 \series bold
4997 -
4998 \begin_inset ERT
4999 status Collapsed
5000
5001 \layout Standard
5002
5003 \backslash
5004 /
5005 \end_inset
5006
5007 -stack-loc
5008 \series default
5009
5010 \begin_inset LatexCommand \index{-\/-stack-loc}
5011
5012 \end_inset
5013
5014 <Value> By default the stack
5015 \begin_inset LatexCommand \index{stack}
5016
5017 \end_inset
5018
5019  is placed after the data segment.
5020  Using this option the stack can be placed anywhere in the internal memory
5021  space of the 8051.
5022  The value entered can be in Hexadecimal or Decimal format, e.g.
5023  -
5024 \begin_inset ERT
5025 status Collapsed
5026
5027 \layout Standard
5028
5029 \backslash
5030 /
5031 \end_inset
5032
5033 -stack-loc 0x20 or -
5034 \begin_inset ERT
5035 status Collapsed
5036
5037 \layout Standard
5038
5039 \backslash
5040 /
5041 \end_inset
5042
5043 -stack-loc 32.
5044  Since the sp register is incremented before a push or call, the initial
5045  sp will be set to one byte prior the provided value.
5046  The provided value should not overlap any other memory areas such as used
5047  register banks or the data segment and with enough space for the current
5048  application.
5049 \layout List
5050 \labelwidthstring 00.00.0000
5051
5052
5053 \series bold
5054 -
5055 \begin_inset ERT
5056 status Collapsed
5057
5058 \layout Standard
5059
5060 \backslash
5061 /
5062 \end_inset
5063
5064 -data-loc
5065 \series default
5066
5067 \begin_inset LatexCommand \index{-\/-data-loc}
5068
5069 \end_inset
5070
5071 <Value> The start location of the internal ram data
5072 \begin_inset LatexCommand \index{data}
5073
5074 \end_inset
5075
5076  segment.
5077  The value entered can be in Hexadecimal or Decimal format, eg.
5078  -
5079 \begin_inset ERT
5080 status Collapsed
5081
5082 \layout Standard
5083
5084 \backslash
5085 /
5086 \end_inset
5087
5088 -data-loc 0x20 or -
5089 \begin_inset ERT
5090 status Collapsed
5091
5092 \layout Standard
5093
5094 \backslash
5095 /
5096 \end_inset
5097
5098 -data-loc 32.
5099  (By default, the start location of the internal ram data segment  is set
5100  as low as possible in memory, taking into account the used register banks
5101  and the bit segment at address 0x20.
5102  For example if register banks 0 and 1 are used without bit variables, the
5103  data segment will be set, if -
5104 \begin_inset ERT
5105 status Collapsed
5106
5107 \layout Standard
5108
5109 \backslash
5110 /
5111 \end_inset
5112
5113 -data-loc is not used, to location 0x10.)
5114 \layout List
5115 \labelwidthstring 00.00.0000
5116
5117
5118 \series bold
5119 -
5120 \begin_inset ERT
5121 status Collapsed
5122
5123 \layout Standard
5124
5125 \backslash
5126 /
5127 \end_inset
5128
5129 -idata-loc
5130 \series default
5131
5132 \begin_inset LatexCommand \index{-\/-idata-loc}
5133
5134 \end_inset
5135
5136 <Value> The start location of the indirectly addressable internal ram
5137 \begin_inset LatexCommand \index{idata}
5138
5139 \end_inset
5140
5141 , default value is 0x80.
5142  The value entered can be in Hexadecimal or Decimal format, eg.
5143  -
5144 \begin_inset ERT
5145 status Collapsed
5146
5147 \layout Standard
5148
5149 \backslash
5150 /
5151 \end_inset
5152
5153 -idata-loc 0x88 or -
5154 \begin_inset ERT
5155 status Collapsed
5156
5157 \layout Standard
5158
5159 \backslash
5160 /
5161 \end_inset
5162
5163 -idata-loc 136.
5164 \layout List
5165 \labelwidthstring 00.00.0000
5166
5167
5168 \series bold
5169 -
5170 \begin_inset ERT
5171 status Collapsed
5172
5173 \layout Standard
5174
5175 \backslash
5176 /
5177 \end_inset
5178
5179 -out-fmt-ihx
5180 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5181
5182 \end_inset
5183
5184
5185 \bar under
5186
5187 \series default
5188 \bar default
5189 The linker output (final object code) is in Intel Hex format.
5190 \begin_inset LatexCommand \index{Intel hex format}
5191
5192 \end_inset
5193
5194  (This is the default option).
5195 \layout List
5196 \labelwidthstring 00.00.0000
5197
5198
5199 \series bold
5200 -
5201 \begin_inset ERT
5202 status Collapsed
5203
5204 \layout Standard
5205
5206 \backslash
5207 /
5208 \end_inset
5209
5210 -out-fmt-s19
5211 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5212
5213 \end_inset
5214
5215
5216 \bar under
5217
5218 \series default
5219 \bar default
5220 The linker output (final object code) is in Motorola S19 format
5221 \begin_inset LatexCommand \index{Motorola S19 format}
5222
5223 \end_inset
5224
5225 .
5226 \layout Subsubsection
5227
5228 MCS51 Options
5229 \begin_inset LatexCommand \index{Options MCS51}
5230
5231 \end_inset
5232
5233
5234 \begin_inset LatexCommand \index{MCS51 options}
5235
5236 \end_inset
5237
5238
5239 \layout List
5240 \labelwidthstring 00.00.0000
5241
5242
5243 \series bold
5244 -
5245 \begin_inset ERT
5246 status Collapsed
5247
5248 \layout Standard
5249
5250 \backslash
5251 /
5252 \end_inset
5253
5254 -model-small
5255 \begin_inset LatexCommand \index{-\/-model-small}
5256
5257 \end_inset
5258
5259
5260 \series default
5261 \size large
5262 \emph on
5263
5264 \size default
5265 \emph default
5266 Generate code for Small Model programs see section Memory Models for more
5267  details.
5268  This is the default model.
5269 \layout List
5270 \labelwidthstring 00.00.0000
5271
5272
5273 \series bold
5274 -
5275 \begin_inset ERT
5276 status Collapsed
5277
5278 \layout Standard
5279
5280 \backslash
5281 /
5282 \end_inset
5283
5284 -model-large
5285 \begin_inset LatexCommand \index{-\/-model-large}
5286
5287 \end_inset
5288
5289
5290 \series default
5291  Generate code for Large model programs see section Memory Models for more
5292  details.
5293  If this option is used all source files in the project have to be compiled
5294  with this option.
5295 \layout List
5296 \labelwidthstring 00.00.0000
5297
5298
5299 \series bold
5300 -
5301 \begin_inset ERT
5302 status Collapsed
5303
5304 \layout Standard
5305
5306 \backslash
5307 /
5308 \end_inset
5309
5310 -xstack
5311 \begin_inset LatexCommand \index{-\/-xstack}
5312
5313 \end_inset
5314
5315
5316 \series default
5317  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
5318  variables and passing parameters.
5319  See section
5320 \begin_inset LatexCommand \ref{sub:External-Stack}
5321
5322 \end_inset
5323
5324 \SpecialChar ~
5325  External Stack for more details.
5326 \layout List
5327 \labelwidthstring 00.00.0000
5328
5329
5330 \series bold
5331 -
5332 \begin_inset ERT
5333 status Collapsed
5334
5335 \layout Standard
5336
5337 \backslash
5338 /
5339 \end_inset
5340
5341 -iram-size
5342 \series default
5343 <Value>
5344 \begin_inset LatexCommand \index{-\/-iram-size<Value>}
5345
5346 \end_inset
5347
5348  Causes the linker to check if the internal ram usage is within limits of
5349  the given value.
5350 \layout List
5351 \labelwidthstring 00.00.0000
5352
5353
5354 \series bold
5355 -
5356 \begin_inset ERT
5357 status Collapsed
5358
5359 \layout Standard
5360
5361 \backslash
5362 /
5363 \end_inset
5364
5365 -xram-size
5366 \series default
5367 <Value>
5368 \begin_inset LatexCommand \index{-\/-xram-size<Value>}
5369
5370 \end_inset
5371
5372  Causes the linker to check if the external ram usage is within limits of
5373  the given value.
5374 \layout List
5375 \labelwidthstring 00.00.0000
5376
5377
5378 \series bold
5379 -
5380 \begin_inset ERT
5381 status Collapsed
5382
5383 \layout Standard
5384
5385 \backslash
5386 /
5387 \end_inset
5388
5389 -code-size
5390 \series default
5391 <Value>
5392 \begin_inset LatexCommand \index{-\/-data-loc}
5393
5394 \end_inset
5395
5396  Causes the linker to check if the code memory usage is within limits of
5397  the given value.
5398 \layout Subsubsection
5399
5400 DS390 Options
5401 \begin_inset LatexCommand \index{Options DS390}
5402
5403 \end_inset
5404
5405
5406 \begin_inset LatexCommand \index{DS390 options}
5407
5408 \end_inset
5409
5410
5411 \layout List
5412 \labelwidthstring 00.00.0000
5413
5414
5415 \series bold
5416 -
5417 \begin_inset ERT
5418 status Collapsed
5419
5420 \layout Standard
5421
5422 \backslash
5423 /
5424 \end_inset
5425
5426 -model-flat24
5427 \series default
5428
5429 \begin_inset LatexCommand \index{-\/-model-flat24}
5430
5431 \end_inset
5432
5433
5434 \size large
5435 \emph on
5436
5437 \size default
5438 \emph default
5439 Generate 24-bit flat mode code.
5440  This is the one and only that the ds390 code generator supports right now
5441  and is default when using
5442 \emph on
5443 -mds390
5444 \emph default
5445 .
5446  See section Memory Models for more details.
5447 \layout List
5448 \labelwidthstring 00.00.0000
5449
5450
5451 \series bold
5452 -
5453 \begin_inset ERT
5454 status Collapsed
5455
5456 \layout Standard
5457
5458 \backslash
5459 /
5460 \end_inset
5461
5462 -stack-10bit
5463 \series default
5464
5465 \begin_inset LatexCommand \index{-\/-stack-10bit}
5466
5467 \end_inset
5468
5469  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
5470  This is the one and only that the ds390 code generator supports right now
5471  and is default when using
5472 \emph on
5473 -mds390
5474 \emph default
5475 .
5476  In this mode, the stack is located in the lower 1K of the internal RAM,
5477  which is mapped to 0x400000.
5478  Note that the support is incomplete, since it still uses a single byte
5479  as the stack pointer.
5480  This means that only the lower 256 bytes of the potential 1K stack space
5481  will actually be used.
5482  However, this does allow you to reclaim the precious 256 bytes of low RAM
5483  for use for the DATA and IDATA segments.
5484  The compiler will not generate any code to put the processor into 10 bit
5485  stack mode.
5486  It is important to ensure that the processor is in this mode before calling
5487  any re-entrant functions compiled with this option.
5488  In principle, this should work with the
5489 \emph on
5490 -
5491 \begin_inset ERT
5492 status Collapsed
5493
5494 \layout Standard
5495
5496 \backslash
5497 /
5498 \end_inset
5499
5500 -stack-auto
5501 \begin_inset LatexCommand \index{-\/-stack-auto}
5502
5503 \end_inset
5504
5505
5506 \emph default
5507  option, but that has not been tested.
5508  It is incompatible with the
5509 \emph on
5510 -
5511 \begin_inset ERT
5512 status Collapsed
5513
5514 \layout Standard
5515
5516 \backslash
5517 /
5518 \end_inset
5519
5520 -xstack
5521 \begin_inset LatexCommand \index{-\/-xstack}
5522
5523 \end_inset
5524
5525
5526 \emph default
5527  option.
5528  It also only makes sense if the processor is in 24 bit contiguous addressing
5529  mode (see the
5530 \emph on
5531 -
5532 \begin_inset ERT
5533 status Collapsed
5534
5535 \layout Standard
5536
5537 \backslash
5538 /
5539 \end_inset
5540
5541 -model-flat24 option
5542 \emph default
5543 ).
5544 \layout Subsubsection
5545
5546 Z80 Options
5547 \begin_inset LatexCommand \index{Options Z80}
5548
5549 \end_inset
5550
5551
5552 \begin_inset LatexCommand \index{Z80 options}
5553
5554 \end_inset
5555
5556
5557 \layout List
5558 \labelwidthstring 00.00.0000
5559
5560
5561 \series bold
5562 -
5563 \begin_inset ERT
5564 status Collapsed
5565
5566 \layout Standard
5567
5568 \backslash
5569 /
5570 \end_inset
5571
5572 -callee-saves-bc
5573 \series default
5574
5575 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
5576
5577 \end_inset
5578
5579
5580 \size large
5581 \emph on
5582
5583 \size default
5584 \emph default
5585 Force a called function to always save BC.
5586 \layout List
5587 \labelwidthstring 00.00.0000
5588
5589
5590 \series bold
5591 -
5592 \begin_inset ERT
5593 status Collapsed
5594
5595 \layout Standard
5596
5597 \backslash
5598 /
5599 \end_inset
5600
5601 -no-std-crt0
5602 \series default
5603
5604 \begin_inset LatexCommand \index{-\/-no-std-crt0}
5605
5606 \end_inset
5607
5608  When linking, skip the standard crt0.o object file.
5609  You must provide your own crt0.o for your system when linking.
5610
5611 \layout Subsubsection
5612
5613 Optimization Options
5614 \begin_inset LatexCommand \index{Options optimization}
5615
5616 \end_inset
5617
5618
5619 \begin_inset LatexCommand \index{Optimization options}
5620
5621 \end_inset
5622
5623
5624 \layout List
5625 \labelwidthstring 00.00.0000
5626
5627
5628 \series bold
5629 -
5630 \begin_inset ERT
5631 status Collapsed
5632
5633 \layout Standard
5634
5635 \backslash
5636 /
5637 \end_inset
5638
5639 -nogcse
5640 \begin_inset LatexCommand \index{-\/-nogcse}
5641
5642 \end_inset
5643
5644
5645 \series default
5646  Will not do global subexpression elimination, this option may be used when
5647  the compiler creates undesirably large stack/data spaces to store compiler
5648  temporaries.
5649  A warning message will be generated when this happens and the compiler
5650  will indicate the number of extra bytes it allocated.
5651  It recommended that this option NOT be used, #pragma\SpecialChar ~
5652 NOGCSE
5653 \begin_inset LatexCommand \index{\#pragma NOGCSE}
5654
5655 \end_inset
5656
5657  can be used to turn off global subexpression elimination
5658 \begin_inset LatexCommand \index{Subexpression elimination}
5659
5660 \end_inset
5661
5662  for a given function only.
5663 \layout List
5664 \labelwidthstring 00.00.0000
5665
5666
5667 \series bold
5668 -
5669 \begin_inset ERT
5670 status Collapsed
5671
5672 \layout Standard
5673
5674 \backslash
5675 /
5676 \end_inset
5677
5678 -noinvariant
5679 \begin_inset LatexCommand \index{-\/-noinvariant}
5680
5681 \end_inset
5682
5683
5684 \series default
5685  Will not do loop invariant optimizations, this may be turned off for reasons
5686  explained for the previous option.
5687  For more details of loop optimizations performed see section Loop Invariants.It
5688  recommended that this option NOT be used, #pragma\SpecialChar ~
5689 NOINVARIANT
5690 \begin_inset LatexCommand \index{\#pragma NOINVARIANT}
5691
5692 \end_inset
5693
5694  can be used to turn off invariant optimizations for a given function only.
5695 \layout List
5696 \labelwidthstring 00.00.0000
5697
5698
5699 \series bold
5700 -
5701 \begin_inset ERT
5702 status Collapsed
5703
5704 \layout Standard
5705
5706 \backslash
5707 /
5708 \end_inset
5709
5710 -noinduction
5711 \begin_inset LatexCommand \index{-\/-noinduction}
5712
5713 \end_inset
5714
5715
5716 \series default
5717  Will not do loop induction optimizations, see section strength reduction
5718  for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
5719 NOINDUCT
5720 ION
5721 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
5722
5723 \end_inset
5724
5725  can be used to turn off induction optimizations for a given function only.
5726 \layout List
5727 \labelwidthstring 00.00.0000
5728
5729
5730 \series bold
5731 -
5732 \begin_inset ERT
5733 status Collapsed
5734
5735 \layout Standard
5736
5737 \backslash
5738 /
5739 \end_inset
5740
5741 -nojtbound
5742 \begin_inset LatexCommand \index{-\/-nojtbound}
5743
5744 \end_inset
5745
5746
5747 \size large
5748 \bar under
5749
5750 \series default
5751 \size default
5752 \bar default
5753  Will not generate boundary condition check when switch statements
5754 \begin_inset LatexCommand \index{switch statement}
5755
5756 \end_inset
5757
5758  are implemented using jump-tables.
5759  See section
5760 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
5761
5762 \end_inset
5763
5764 \SpecialChar ~
5765 Switch Statements for more details.
5766  It is recommended that this option is NOT used, #pragma\SpecialChar ~
5767 NOJTBOUND
5768 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
5769
5770 \end_inset
5771
5772  can be used to turn off boundary checking for jump tables for a given function
5773  only.
5774 \layout List
5775 \labelwidthstring 00.00.0000
5776
5777
5778 \series bold
5779 -
5780 \begin_inset ERT
5781 status Collapsed
5782
5783 \layout Standard
5784
5785 \backslash
5786 /
5787 \end_inset
5788
5789 -noloopreverse
5790 \begin_inset LatexCommand \index{-\/-noloopreverse}
5791
5792 \end_inset
5793
5794
5795 \series default
5796 \size large
5797
5798 \size default
5799 Will not do loop reversal
5800 \begin_inset LatexCommand \index{Loop reversing}
5801
5802 \end_inset
5803
5804 optimization.
5805 \layout List
5806 \labelwidthstring 00.00.0000
5807
5808 -
5809 \begin_inset ERT
5810 status Collapsed
5811
5812 \layout Standard
5813
5814 \backslash
5815 /
5816 \end_inset
5817
5818 -
5819 \series bold
5820 nolabelopt
5821 \series default
5822
5823 \begin_inset LatexCommand \index{-\/-nolabelopt }
5824
5825 \end_inset
5826
5827 Will not optimize labels (makes the dumpfiles more readable).
5828 \layout List
5829 \labelwidthstring 00.00.0000
5830
5831
5832 \series bold
5833 -
5834 \begin_inset ERT
5835 status Collapsed
5836
5837 \layout Standard
5838
5839 \backslash
5840 /
5841 \end_inset
5842
5843 -no-xinit-opt
5844 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
5845
5846 \end_inset
5847
5848
5849 \series default
5850  Will not memcpy initialized data from code space into xdata space.
5851  This saves a few bytes in code space if you don't have initialized data.
5852 \layout Subsubsection
5853
5854 Other Options
5855 \begin_inset LatexCommand \index{Options other}
5856
5857 \end_inset
5858
5859
5860 \layout List
5861 \labelwidthstring 00.00.0000
5862
5863
5864 \series bold
5865 -c\SpecialChar ~
5866 -
5867 \begin_inset ERT
5868 status Collapsed
5869
5870 \layout Standard
5871
5872 \backslash
5873 /
5874 \end_inset
5875
5876 -compile-only
5877 \begin_inset LatexCommand \index{-\/-compile-only}
5878
5879 \end_inset
5880
5881
5882 \begin_inset LatexCommand \index{-c -\/-compile-only}
5883
5884 \end_inset
5885
5886
5887 \series default
5888  will compile and assemble the source, but will not call the linkage editor.
5889 \layout List
5890 \labelwidthstring 00.00.0000
5891
5892
5893 \series bold
5894 -
5895 \series default
5896
5897 \begin_inset ERT
5898 status Collapsed
5899
5900 \layout Standard
5901
5902 \backslash
5903 /
5904 \end_inset
5905
5906
5907 \series bold
5908 -c1mode
5909 \begin_inset LatexCommand \index{-\/-c1mode}
5910
5911 \end_inset
5912
5913
5914 \series default
5915  reads the preprocessed source from standard input and compiles it.
5916  The file name for the assembler output must be specified using the -o option.
5917 \layout List
5918 \labelwidthstring 00.00.0000
5919
5920
5921 \series bold
5922 -E
5923 \begin_inset LatexCommand \index{-E}
5924
5925 \end_inset
5926
5927
5928 \series default
5929  Run only the C preprocessor.
5930  Preprocess all the C source files specified and output the results to standard
5931  output.
5932 \layout List
5933 \labelwidthstring 00.00.0000
5934
5935
5936 \series bold
5937 -o\SpecialChar ~
5938 <path/file>
5939 \begin_inset LatexCommand \index{-o <path/file>}
5940
5941 \end_inset
5942
5943
5944 \series default
5945 The output path resp.
5946  file where everything will be placed.
5947  If the parameter is a path, it must have a trailing slash (or backslash
5948  for the Windows binaries) to be recognized as a path.
5949
5950 \layout List
5951 \labelwidthstring 00.00.0000
5952
5953
5954 \series bold
5955 -
5956 \begin_inset ERT
5957 status Collapsed
5958
5959 \layout Standard
5960
5961 \backslash
5962 /
5963 \end_inset
5964
5965 -stack-auto
5966 \begin_inset LatexCommand \index{-\/-stack-auto}
5967
5968 \end_inset
5969
5970
5971 \series default
5972 \size large
5973 \emph on
5974
5975 \size default
5976 \emph default
5977 All functions in the source file will be compiled as
5978 \emph on
5979 reentrant
5980 \emph default
5981
5982 \begin_inset LatexCommand \index{reentrant}
5983
5984 \end_inset
5985
5986 , i.e.
5987  the parameters and local variables will be allocated on the stack
5988 \begin_inset LatexCommand \index{stack}
5989
5990 \end_inset
5991
5992 .
5993  see section Parameters and Local Variables for more details.
5994  If this option is used all source files in the project should be compiled
5995  with this option.
5996
5997 \layout List
5998 \labelwidthstring 00.00.0000
5999
6000
6001 \series bold
6002 -
6003 \begin_inset ERT
6004 status Collapsed
6005
6006 \layout Standard
6007
6008 \backslash
6009 /
6010 \end_inset
6011
6012 -callee-saves
6013 \begin_inset LatexCommand \index{-\/-callee-saves}
6014
6015 \end_inset
6016
6017  function1[,function2][,function3]....
6018
6019 \series default
6020  The compiler by default uses a caller saves convention for register saving
6021  across function calls, however this can cause unnecessary register pushing
6022  & popping when calling small functions from larger functions.
6023  This option can be used to switch the register saving convention for the
6024  function names specified.
6025  The compiler will not save registers when calling these functions, no extra
6026  code will be generated at the entry & exit (function prologue
6027 \series bold
6028
6029 \begin_inset LatexCommand \index{function prologue}
6030
6031 \end_inset
6032
6033
6034 \series default
6035  & epilogue
6036 \series bold
6037
6038 \begin_inset LatexCommand \index{function epilogue}
6039
6040 \end_inset
6041
6042
6043 \series default
6044 ) for these functions to save & restore the registers used by these functions,
6045  this can SUBSTANTIALLY reduce code & improve run time performance of the
6046  generated code.
6047  In the future the compiler (with inter procedural analysis) will be able
6048  to determine the appropriate scheme to use for each function call.
6049  DO NOT use this option for built-in functions such as _mulint..., if this
6050  option is used for a library function the appropriate library function
6051  needs to be recompiled with the same option.
6052  If the project consists of multiple source files then all the source file
6053  should be compiled with the same -
6054 \begin_inset ERT
6055 status Collapsed
6056
6057 \layout Standard
6058
6059 \backslash
6060 /
6061 \end_inset
6062
6063 -callee-saves option string.
6064  Also see #pragma\SpecialChar ~
6065 CALLEE-SAVES
6066 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
6067
6068 \end_inset
6069
6070 .
6071 \layout List
6072 \labelwidthstring 00.00.0000
6073
6074
6075 \series bold
6076 -
6077 \begin_inset ERT
6078 status Collapsed
6079
6080 \layout Standard
6081
6082 \backslash
6083 /
6084 \end_inset
6085
6086 -debug
6087 \begin_inset LatexCommand \index{-\/-debug}
6088
6089 \end_inset
6090
6091
6092 \bar under
6093
6094 \series default
6095 \bar default
6096 When this option is used the compiler will generate debug information, that
6097  can be used with the SDCDB.
6098  The debug information is collected in a file with .cdb extension.
6099  For more information see documentation for SDCDB.
6100 \layout List
6101 \labelwidthstring 00.00.0000
6102
6103
6104 \series bold
6105 -S
6106 \begin_inset LatexCommand \index{-S}
6107
6108 \end_inset
6109
6110
6111 \size large
6112 \bar under
6113
6114 \series default
6115 \size default
6116 \bar default
6117 Stop after the stage of compilation proper; do not assemble.
6118  The output is an assembler code file for the input file specified.
6119 \layout List
6120 \labelwidthstring 00.00.0000
6121
6122
6123 \series bold
6124 -Wa_asmOption[,asmOption]
6125 \series default
6126
6127 \begin_inset LatexCommand \index{-Wa\_asmOption[,asmOption]}
6128
6129 \end_inset
6130
6131 ...
6132  Pass the asmOption to the assembler.
6133 \layout List
6134 \labelwidthstring 00.00.0000
6135
6136
6137 \series bold
6138 -Wl_linkOption[,linkOption]
6139 \series default
6140
6141 \begin_inset LatexCommand \index{-Wl\_linkOption[,linkOption]}
6142
6143 \end_inset
6144
6145 ...
6146  Pass the linkOption to the linker.
6147 \layout List
6148 \labelwidthstring 00.00.0000
6149
6150
6151 \series bold
6152 -
6153 \begin_inset ERT
6154 status Collapsed
6155
6156 \layout Standard
6157
6158 \backslash
6159 /
6160 \end_inset
6161
6162 -int-long-reent
6163 \begin_inset LatexCommand \index{-\/-int-long-reent}
6164
6165 \end_inset
6166
6167
6168 \series default
6169  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
6170  Note by default these libraries are compiled as non-reentrant.
6171  See section Installation for more details.
6172 \layout List
6173 \labelwidthstring 00.00.0000
6174
6175
6176 \series bold
6177 -
6178 \begin_inset ERT
6179 status Collapsed
6180
6181 \layout Standard
6182
6183 \backslash
6184 /
6185 \end_inset
6186
6187 -cyclomatic
6188 \begin_inset LatexCommand \index{-\/-cyclomatic}
6189
6190 \end_inset
6191
6192
6193 \bar under
6194
6195 \series default
6196 \bar default
6197 This option will cause the compiler to generate an information message for
6198  each function in the source file.
6199  The message contains some
6200 \emph on
6201 important
6202 \emph default
6203  information about the function.
6204  The number of edges and nodes the compiler detected in the control flow
6205  graph of the function, and most importantly the
6206 \emph on
6207 cyclomatic complexity
6208 \begin_inset LatexCommand \index{Cyclomatic complexity}
6209
6210 \end_inset
6211
6212
6213 \emph default
6214  see section on Cyclomatic Complexity for more details.
6215 \layout List
6216 \labelwidthstring 00.00.0000
6217
6218
6219 \series bold
6220 -
6221 \begin_inset ERT
6222 status Collapsed
6223
6224 \layout Standard
6225
6226 \backslash
6227 /
6228 \end_inset
6229
6230 -float-reent
6231 \begin_inset LatexCommand \index{-\/-float-reent}
6232
6233 \end_inset
6234
6235
6236 \bar under
6237
6238 \series default
6239 \bar default
6240  Floating point library is compiled as reentrant
6241 \begin_inset LatexCommand \index{reentrant}
6242
6243 \end_inset
6244
6245 .
6246  See section Installation for more details.
6247 \layout List
6248 \labelwidthstring 00.00.0000
6249
6250
6251 \series bold
6252 -
6253 \begin_inset ERT
6254 status Collapsed
6255
6256 \layout Standard
6257
6258 \backslash
6259 /
6260 \end_inset
6261
6262 -nooverlay
6263 \begin_inset LatexCommand \index{-\/-nooverlay}
6264
6265 \end_inset
6266
6267
6268 \series default
6269   The compiler will not overlay parameters and local variables of any function,
6270  see section Parameters and local variables for more details.
6271 \layout List
6272 \labelwidthstring 00.00.0000
6273
6274
6275 \series bold
6276 -
6277 \begin_inset ERT
6278 status Collapsed
6279
6280 \layout Standard
6281
6282 \backslash
6283 /
6284 \end_inset
6285
6286 -main-return
6287 \begin_inset LatexCommand \index{-\/-main-return}
6288
6289 \end_inset
6290
6291
6292 \series default
6293  This option can be used when the code generated is called by a monitor
6294  program.
6295  The compiler will generate a 'ret' upon return from the 'main'
6296 \begin_inset LatexCommand \index{main return}
6297
6298 \end_inset
6299
6300  function.
6301  The default setting is to lock up i.e.
6302  generate a '
6303 \family typewriter
6304 ljmp .
6305 \family default
6306 '.
6307 \layout List
6308 \labelwidthstring 00.00.0000
6309
6310
6311 \series bold
6312 -
6313 \begin_inset ERT
6314 status Collapsed
6315
6316 \layout Standard
6317
6318 \backslash
6319 /
6320 \end_inset
6321
6322 -peep-file
6323 \series default
6324
6325 \begin_inset LatexCommand \index{-\/-peep-file}
6326
6327 \end_inset
6328
6329 <filename> This option can be used to use additional rules to be used by
6330  the peep hole optimizer.
6331  See section
6332 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6333
6334 \end_inset
6335
6336 \SpecialChar ~
6337 Peep Hole optimizations for details on how to write these rules.
6338 \layout List
6339 \labelwidthstring 00.00.0000
6340
6341
6342 \series bold
6343 -
6344 \begin_inset ERT
6345 status Collapsed
6346
6347 \layout Standard
6348
6349 \backslash
6350 /
6351 \end_inset
6352
6353 -no-peep
6354 \begin_inset LatexCommand \index{-\/-no-peep}
6355
6356 \end_inset
6357
6358
6359 \series default
6360   Disable peep-hole optimization.
6361 \layout List
6362 \labelwidthstring 00.00.0000
6363
6364
6365 \series bold
6366 -
6367 \begin_inset ERT
6368 status Collapsed
6369
6370 \layout Standard
6371
6372 \backslash
6373 /
6374 \end_inset
6375
6376 -peep-asm
6377 \begin_inset LatexCommand \index{-\/-peep-asm}
6378
6379 \end_inset
6380
6381
6382 \series default
6383   Pass the inline assembler code through the peep hole optimizer.
6384  This can cause unexpected changes to inline assembler code, please go through
6385  the peephole optimizer
6386 \begin_inset LatexCommand \index{Peephole optimizer}
6387
6388 \end_inset
6389
6390  rules defined in the source file tree '<target>/peeph.def' before using
6391  this option.
6392 \layout List
6393 \labelwidthstring 00.00.0000
6394
6395
6396 \series bold
6397 -
6398 \begin_inset ERT
6399 status Collapsed
6400
6401 \layout Standard
6402
6403 \backslash
6404 /
6405 \end_inset
6406
6407 -nostdincl
6408 \begin_inset LatexCommand \index{-\/-nostdincl}
6409
6410 \end_inset
6411
6412
6413 \series default
6414  This will prevent the compiler from passing on the default include path
6415  to the preprocessor.
6416 \layout List
6417 \labelwidthstring 00.00.0000
6418
6419
6420 \series bold
6421 -
6422 \begin_inset ERT
6423 status Collapsed
6424
6425 \layout Standard
6426
6427 \backslash
6428 /
6429 \end_inset
6430
6431 -nostdlib
6432 \begin_inset LatexCommand \index{-\/-nostdlib}
6433
6434 \end_inset
6435
6436
6437 \series default
6438  This will prevent the compiler from passing on the default library
6439 \begin_inset LatexCommand \index{Libraries}
6440
6441 \end_inset
6442
6443  path to the linker.
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 -verbose
6460 \begin_inset LatexCommand \index{-\/-verbose}
6461
6462 \end_inset
6463
6464
6465 \series default
6466  Shows the various actions the compiler is performing.
6467 \layout List
6468 \labelwidthstring 00.00.0000
6469
6470
6471 \series bold
6472 -V
6473 \begin_inset LatexCommand \index{-V}
6474
6475 \end_inset
6476
6477
6478 \series default
6479  Shows the actual commands the compiler is executing.
6480 \layout List
6481 \labelwidthstring 00.00.0000
6482
6483
6484 \series bold
6485 -
6486 \begin_inset ERT
6487 status Collapsed
6488
6489 \layout Standard
6490
6491 \backslash
6492 /
6493 \end_inset
6494
6495 -no-c-code-in-asm
6496 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
6497
6498 \end_inset
6499
6500
6501 \series default
6502  Hides your ugly and inefficient c-code from the asm file, so you can always
6503  blame the compiler :).
6504 \layout List
6505 \labelwidthstring 00.00.0000
6506
6507
6508 \series bold
6509 -
6510 \begin_inset ERT
6511 status Collapsed
6512
6513 \layout Standard
6514
6515 \backslash
6516 /
6517 \end_inset
6518
6519 -i-code-in-asm
6520 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
6521
6522 \end_inset
6523
6524
6525 \series default
6526  Include i-codes in the asm file.
6527  Sounds like noise but is most helpful for debugging the compiler itself.
6528 \layout List
6529 \labelwidthstring 00.00.0000
6530
6531
6532 \series bold
6533 -
6534 \begin_inset ERT
6535 status Collapsed
6536
6537 \layout Standard
6538
6539 \backslash
6540 /
6541 \end_inset
6542
6543 -less-pedantic
6544 \begin_inset LatexCommand \index{-\/-less-pedantic}
6545
6546 \end_inset
6547
6548
6549 \series default
6550  Disable some of the more pedantic warnings
6551 \begin_inset LatexCommand \index{Warnings}
6552
6553 \end_inset
6554
6555  (jwk burps: please be more specific here, please!).
6556  If you want rather more than less warnings you should consider using a
6557  separate tool dedicated to syntax checking like
6558 \begin_inset LatexCommand \url{www.splint.org}
6559
6560 \end_inset
6561
6562 .
6563 \layout List
6564 \labelwidthstring 00.00.0000
6565
6566
6567 \series bold
6568 -
6569 \begin_inset ERT
6570 status Collapsed
6571
6572 \layout Standard
6573
6574 \backslash
6575 /
6576 \end_inset
6577
6578 -print-search-dirs
6579 \begin_inset LatexCommand \index{-\/-print-search-dirs}
6580
6581 \end_inset
6582
6583
6584 \series default
6585  Display the directories in the compiler's search path
6586 \layout List
6587 \labelwidthstring 00.00.0000
6588
6589
6590 \series bold
6591 -
6592 \begin_inset ERT
6593 status Collapsed
6594
6595 \layout Standard
6596
6597 \backslash
6598 /
6599 \end_inset
6600
6601 -vc
6602 \begin_inset LatexCommand \index{-\/-vc}
6603
6604 \end_inset
6605
6606
6607 \series default
6608  Display errors and warnings using MSVC style, so you can use SDCC with
6609  visual studio.
6610 \layout List
6611 \labelwidthstring 00.00.0000
6612
6613
6614 \series bold
6615 -
6616 \begin_inset ERT
6617 status Collapsed
6618
6619 \layout Standard
6620
6621 \backslash
6622 /
6623 \end_inset
6624
6625 -use-stdout
6626 \begin_inset LatexCommand \index{-\/-use-stdout}
6627
6628 \end_inset
6629
6630
6631 \series default
6632  Send errors and warnings to stdout instead of stderr.
6633 \layout Subsubsection
6634
6635 Intermediate Dump Options
6636 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
6637
6638 \end_inset
6639
6640
6641 \begin_inset LatexCommand \index{Options intermediate dump}
6642
6643 \end_inset
6644
6645
6646 \begin_inset LatexCommand \index{Intermediate dump options}
6647
6648 \end_inset
6649
6650
6651 \layout Standard
6652
6653 The following options are provided for the purpose of retargetting and debugging
6654  the compiler.
6655  These provided a means to dump the intermediate code (iCode
6656 \begin_inset LatexCommand \index{iCode}
6657
6658 \end_inset
6659
6660 ) generated by the compiler in human readable form at various stages of
6661  the compilation process.
6662
6663 \layout List
6664 \labelwidthstring 00.00.0000
6665
6666
6667 \series bold
6668 -
6669 \begin_inset ERT
6670 status Collapsed
6671
6672 \layout Standard
6673
6674 \backslash
6675 /
6676 \end_inset
6677
6678 -dumpraw
6679 \begin_inset LatexCommand \index{-\/-dumpraw}
6680
6681 \end_inset
6682
6683
6684 \series default
6685  This option will cause the compiler to dump the intermediate code into
6686  a file of named
6687 \emph on
6688 <source filename>.dumpraw
6689 \emph default
6690  just after the intermediate code has been generated for a function, i.e.
6691  before any optimizations are done.
6692  The basic blocks
6693 \begin_inset LatexCommand \index{Basic blocks}
6694
6695 \end_inset
6696
6697  at this stage ordered in the depth first number, so they may not be in
6698  sequence of execution.
6699 \layout List
6700 \labelwidthstring 00.00.0000
6701
6702
6703 \series bold
6704 -
6705 \begin_inset ERT
6706 status Collapsed
6707
6708 \layout Standard
6709
6710 \backslash
6711 /
6712 \end_inset
6713
6714 -dumpgcse
6715 \begin_inset LatexCommand \index{-\/-dumpgcse}
6716
6717 \end_inset
6718
6719
6720 \series default
6721  Will create a dump of iCode's, after global subexpression elimination
6722 \begin_inset LatexCommand \index{Global subexpression elimination}
6723
6724 \end_inset
6725
6726 , into a file named
6727 \emph on
6728 <source filename>.dumpgcse.
6729 \layout List
6730 \labelwidthstring 00.00.0000
6731
6732
6733 \series bold
6734 -
6735 \begin_inset ERT
6736 status Collapsed
6737
6738 \layout Standard
6739
6740 \backslash
6741 /
6742 \end_inset
6743
6744 -dumpdeadcode
6745 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
6746
6747 \end_inset
6748
6749
6750 \series default
6751  Will create a dump of iCode's, after deadcode elimination
6752 \begin_inset LatexCommand \index{Dead-code elimination}
6753
6754 \end_inset
6755
6756 , into a file named
6757 \emph on
6758 <source filename>.dumpdeadcode.
6759 \layout List
6760 \labelwidthstring 00.00.0000
6761
6762
6763 \series bold
6764 -
6765 \begin_inset ERT
6766 status Collapsed
6767
6768 \layout Standard
6769
6770 \backslash
6771 /
6772 \end_inset
6773
6774 -dumploop
6775 \begin_inset LatexCommand \index{-\/-dumploop}
6776
6777 \end_inset
6778
6779
6780 \series default
6781 \size large
6782
6783 \size default
6784 Will create a dump of iCode's, after loop optimizations
6785 \begin_inset LatexCommand \index{Loop optimization}
6786
6787 \end_inset
6788
6789 , into a file named
6790 \emph on
6791 <source filename>.dumploop.
6792 \layout List
6793 \labelwidthstring 00.00.0000
6794
6795
6796 \series bold
6797 -
6798 \begin_inset ERT
6799 status Collapsed
6800
6801 \layout Standard
6802
6803 \backslash
6804 /
6805 \end_inset
6806
6807 -dumprange
6808 \begin_inset LatexCommand \index{-\/-dumprange}
6809
6810 \end_inset
6811
6812
6813 \series default
6814 \size large
6815
6816 \size default
6817 Will create a dump of iCode's, after live range analysis
6818 \begin_inset LatexCommand \index{Live range analysis}
6819
6820 \end_inset
6821
6822 , into a file named
6823 \emph on
6824 <source filename>.dumprange.
6825 \layout List
6826 \labelwidthstring 00.00.0000
6827
6828
6829 \series bold
6830 -
6831 \begin_inset ERT
6832 status Collapsed
6833
6834 \layout Standard
6835
6836 \backslash
6837 /
6838 \end_inset
6839
6840 -dumlrange
6841 \begin_inset LatexCommand \index{-\/-dumlrange}
6842
6843 \end_inset
6844
6845
6846 \series default
6847  Will dump the life ranges
6848 \begin_inset LatexCommand \index{Live range analysis}
6849
6850 \end_inset
6851
6852  for all symbols.
6853 \layout List
6854 \labelwidthstring 00.00.0000
6855
6856
6857 \series bold
6858 -
6859 \begin_inset ERT
6860 status Collapsed
6861
6862 \layout Standard
6863
6864 \backslash
6865 /
6866 \end_inset
6867
6868 -dumpregassign
6869 \begin_inset LatexCommand \index{-\/-dumpregassign}
6870
6871 \end_inset
6872
6873
6874 \bar under
6875
6876 \series default
6877 \bar default
6878 Will create a dump of iCode's, after register assignment
6879 \begin_inset LatexCommand \index{Register assignment}
6880
6881 \end_inset
6882
6883 , into a file named
6884 \emph on
6885 <source filename>.dumprassgn.
6886 \layout List
6887 \labelwidthstring 00.00.0000
6888
6889
6890 \series bold
6891 -
6892 \begin_inset ERT
6893 status Collapsed
6894
6895 \layout Standard
6896
6897 \backslash
6898 /
6899 \end_inset
6900
6901 -dumplrange
6902 \begin_inset LatexCommand \index{-\/-dumplrange}
6903
6904 \end_inset
6905
6906
6907 \series default
6908  Will create a dump of the live ranges of iTemp's
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 -dumpall
6925 \begin_inset LatexCommand \index{-\/-dumpall}
6926
6927 \end_inset
6928
6929
6930 \size large
6931 \bar under
6932
6933 \series default
6934 \size default
6935 \bar default
6936 Will cause all the above mentioned dumps to be created.
6937 \layout Subsubsection
6938
6939 Redirecting output on Windows Shells
6940 \layout Standard
6941
6942 By default SDCC writes it's error messages to
6943 \begin_inset Quotes sld
6944 \end_inset
6945
6946 standard error
6947 \begin_inset Quotes srd
6948 \end_inset
6949
6950 .
6951  To force all messages to
6952 \begin_inset Quotes sld
6953 \end_inset
6954
6955 standard output
6956 \begin_inset Quotes srd
6957 \end_inset
6958
6959  use
6960 \series bold
6961 -
6962 \series default
6963 \emph on
6964
6965 \begin_inset ERT
6966 status Collapsed
6967
6968 \layout Standard
6969
6970 \backslash
6971 /
6972 \end_inset
6973
6974
6975 \series bold
6976 \emph default
6977 -
6978 \series default
6979 use-stdout
6980 \begin_inset LatexCommand \index{-\/-use-stdout}
6981
6982 \end_inset
6983
6984 .
6985  Aditionaly, if you happen to have visual studio installed in your windows
6986  machine, you can use it to compile your sources using a custom build and
6987  the SDCC -
6988 \emph on
6989
6990 \begin_inset ERT
6991 status Collapsed
6992
6993 \layout Standard
6994
6995 \backslash
6996 /
6997 \end_inset
6998
6999
7000 \emph default
7001 -vc
7002 \begin_inset LatexCommand \index{-\/-vc}
7003
7004 \end_inset
7005
7006  option.
7007  Something like this should work:
7008 \newline
7009
7010 \newline
7011
7012 \series bold
7013 c:
7014 \backslash
7015 sdcc
7016 \backslash
7017 bin
7018 \backslash
7019 sdcc.exe -
7020 \series default
7021 \emph on
7022
7023 \begin_inset ERT
7024 status Collapsed
7025
7026 \layout Standard
7027
7028 \backslash
7029 /
7030 \end_inset
7031
7032
7033 \series bold
7034 \emph default
7035 -vc -
7036 \series default
7037 \emph on
7038
7039 \begin_inset ERT
7040 status Collapsed
7041
7042 \layout Standard
7043
7044 \backslash
7045 /
7046 \end_inset
7047
7048
7049 \series bold
7050 \emph default
7051 -model-large -c $(InputPath)
7052 \layout Subsection
7053
7054 Environment variables
7055 \begin_inset LatexCommand \index{Environment variables}
7056
7057 \end_inset
7058
7059
7060 \layout Standard
7061
7062 SDCC recognizes the following environment variables:
7063 \layout List
7064 \labelwidthstring 00.00.0000
7065
7066
7067 \series bold
7068 SDCC_LEAVE_SIGNALS
7069 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
7070
7071 \end_inset
7072
7073
7074 \series default
7075  SDCC installs a signal handler
7076 \begin_inset LatexCommand \index{signal handler}
7077
7078 \end_inset
7079
7080  to be able to delete temporary files after an user break (^C) or an exception.
7081  If this environment variable is set, SDCC won't install the signal handler
7082  in order to be able to debug SDCC.
7083 \layout List
7084 \labelwidthstring 00.00.0000
7085
7086
7087 \series bold
7088 TMP,\SpecialChar ~
7089 TEMP,\SpecialChar ~
7090 TMPDIR
7091 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
7092
7093 \end_inset
7094
7095
7096 \series default
7097  Path, where temporary files will be created.
7098  The order of the variables is the search order.
7099  In a standard *nix environment these variables are not set, and there's
7100  no need to set them.
7101  On Windows it's recommended to set one of them.
7102 \layout List
7103 \labelwidthstring 00.00.0000
7104
7105
7106 \series bold
7107 SDCC_HOME
7108 \begin_inset LatexCommand \index{SDCC\_HOME}
7109
7110 \end_inset
7111
7112
7113 \series default
7114  Path, see section
7115 \begin_inset LatexCommand \ref{sub:Install-paths}
7116
7117 \end_inset
7118
7119 \SpecialChar ~
7120
7121 \begin_inset Quotes sld
7122 \end_inset
7123
7124  Install Paths
7125 \begin_inset Quotes srd
7126 \end_inset
7127
7128 .
7129 \layout List
7130 \labelwidthstring 00.00.0000
7131
7132
7133 \series bold
7134 SDCC_INCLUDE
7135 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
7136
7137 \end_inset
7138
7139
7140 \series default
7141  Path, see section
7142 \begin_inset LatexCommand \ref{sub:Search-Paths}
7143
7144 \end_inset
7145
7146 \SpecialChar ~
7147
7148 \begin_inset Quotes sld
7149 \end_inset
7150
7151 Search Paths
7152 \begin_inset Quotes srd
7153 \end_inset
7154
7155 .
7156 \layout List
7157 \labelwidthstring 00.00.0000
7158
7159
7160 \series bold
7161 SDCC_LIB
7162 \begin_inset LatexCommand \index{SDCC\_LIB}
7163
7164 \end_inset
7165
7166
7167 \series default
7168  Path, see section
7169 \begin_inset LatexCommand \ref{sub:Search-Paths}
7170
7171 \end_inset
7172
7173 \SpecialChar ~
7174
7175 \begin_inset Quotes sld
7176 \end_inset
7177
7178 Search Paths
7179 \begin_inset Quotes srd
7180 \end_inset
7181
7182 ..
7183 \layout Standard
7184
7185 There are some more environment variables recognized by SDCC, but these
7186  are solely used for debugging purposes.
7187  They can change or disappear very quickly, and will never be documented.
7188 \layout Subsection
7189
7190 MCS51/DS390 Storage Class
7191 \begin_inset LatexCommand \index{Storage class}
7192
7193 \end_inset
7194
7195  Language Extensions
7196 \layout Standard
7197
7198 In addition to the ANSI storage classes SDCC allows the following MCS51
7199  specific storage classes.
7200 \layout Subsubsection
7201
7202 data
7203 \begin_inset LatexCommand \index{data}
7204
7205 \end_inset
7206
7207
7208 \layout Standard
7209
7210 This is the
7211 \series bold
7212 default
7213 \series default
7214  storage class for the Small Memory model.
7215  Variables declared with this storage class will be allocated in the directly
7216  addressable portion of the internal RAM of a 8051, e.g.:
7217 \layout Verse
7218
7219
7220 \family typewriter
7221 data unsigned char test_data;
7222 \layout Standard
7223
7224 Writing 0x01 to this variable generates the assembly code:
7225 \layout Verse
7226
7227
7228 \family typewriter
7229 75*00 01\SpecialChar ~
7230 \SpecialChar ~
7231 \SpecialChar ~
7232 mov\SpecialChar ~
7233 \SpecialChar ~
7234 _test_data,#0x01
7235 \layout Subsubsection
7236
7237 xdata
7238 \begin_inset LatexCommand \index{xdata}
7239
7240 \end_inset
7241
7242
7243 \layout Standard
7244
7245 Variables declared with this storage class will be placed in the external
7246  RAM.
7247  This is the
7248 \series bold
7249 default
7250 \series default
7251  storage class for the Large Memory model, e.g.:
7252 \layout Verse
7253
7254
7255 \family typewriter
7256 xdata unsigned char test_xdata;
7257 \layout Standard
7258
7259 Writing 0x01 to this variable generates the assembly code:
7260 \layout Verse
7261
7262
7263 \family typewriter
7264 90s00r00\SpecialChar ~
7265 \SpecialChar ~
7266 \SpecialChar ~
7267 mov\SpecialChar ~
7268 \SpecialChar ~
7269 dptr,#_test_xdata
7270 \newline
7271 74\SpecialChar ~
7272 01\SpecialChar ~
7273 \SpecialChar ~
7274 \SpecialChar ~
7275 \SpecialChar ~
7276 \SpecialChar ~
7277 \SpecialChar ~
7278 mov\SpecialChar ~
7279 \SpecialChar ~
7280 a,#0x01
7281 \newline
7282 F0\SpecialChar ~
7283 \SpecialChar ~
7284 \SpecialChar ~
7285 \SpecialChar ~
7286 \SpecialChar ~
7287 \SpecialChar ~
7288 \SpecialChar ~
7289 \SpecialChar ~
7290 \SpecialChar ~
7291 movx\SpecialChar ~
7292 @dptr,a
7293 \layout Subsubsection
7294
7295 idata
7296 \begin_inset LatexCommand \index{idata}
7297
7298 \end_inset
7299
7300
7301 \layout Standard
7302
7303 Variables declared with this storage class will be allocated into the indirectly
7304  addressable portion of the internal ram of a 8051, e.g.:
7305 \layout Verse
7306
7307
7308 \family typewriter
7309 idata unsigned char test_idata;
7310 \layout Standard
7311
7312 Writing 0x01 to this variable generates the assembly code:
7313 \layout Verse
7314
7315
7316 \family typewriter
7317 78r00\SpecialChar ~
7318 \SpecialChar ~
7319 \SpecialChar ~
7320 \SpecialChar ~
7321 \SpecialChar ~
7322 \SpecialChar ~
7323 \SpecialChar ~
7324 mov\SpecialChar ~
7325 \SpecialChar ~
7326 r0,#_test_idata
7327 \newline
7328 76\SpecialChar ~
7329 01\SpecialChar ~
7330 \SpecialChar ~
7331 \SpecialChar ~
7332 \SpecialChar ~
7333 \SpecialChar ~
7334 \SpecialChar ~
7335 \SpecialChar ~
7336 mov\SpecialChar ~
7337 \SpecialChar ~
7338 @r0,#0x01
7339 \layout Subsubsection
7340
7341 pdata
7342 \begin_inset LatexCommand \index{pdata}
7343
7344 \end_inset
7345
7346
7347 \layout Standard
7348
7349 Paged xdata access is currently not as straightforward as using the other
7350  addressing modes of a 8051.
7351  The following example writes 0x01 to the address pointed to.
7352  Please note, pdata access physically accesses xdata memory.
7353  The high byte of the address is determined by port P2 (or in case of some
7354  8051 variants by a separate Special Function Register).
7355 \layout Verse
7356
7357
7358 \family typewriter
7359 pdata unsigned char *test_pdata_ptr;
7360 \newline
7361
7362 \newline
7363 void main()
7364 \newline
7365 {
7366 \newline
7367 \SpecialChar ~
7368 \SpecialChar ~
7369 \SpecialChar ~
7370 \SpecialChar ~
7371 test_pdata_ptr = (pdata *)0xfe;
7372 \newline
7373 \SpecialChar ~
7374 \SpecialChar ~
7375 \SpecialChar ~
7376 \SpecialChar ~
7377 *test_pdata_ptr = 1;
7378 \newline
7379 }
7380 \layout Standard
7381
7382 Generates the assembly code:
7383 \layout Verse
7384
7385
7386 \family typewriter
7387 75*01 FE\SpecialChar ~
7388 \SpecialChar ~
7389 \SpecialChar ~
7390 mov\SpecialChar ~
7391  _test_pdata_ptr,#0xFE
7392 \newline
7393 78 FE\SpecialChar ~
7394 \SpecialChar ~
7395 \SpecialChar ~
7396 \SpecialChar ~
7397 \SpecialChar ~
7398 \SpecialChar ~
7399 mov\SpecialChar ~
7400  r0,#0xFE
7401 \newline
7402 74 01\SpecialChar ~
7403 \SpecialChar ~
7404 \SpecialChar ~
7405 \SpecialChar ~
7406 \SpecialChar ~
7407 \SpecialChar ~
7408 mov\SpecialChar ~
7409  a,#0x01
7410 \newline
7411 F2\SpecialChar ~
7412 \SpecialChar ~
7413 \SpecialChar ~
7414 \SpecialChar ~
7415 \SpecialChar ~
7416 \SpecialChar ~
7417 \SpecialChar ~
7418 \SpecialChar ~
7419 \SpecialChar ~
7420 movx @r0,a
7421 \layout Standard
7422
7423 Be extremely carefull if you use pdata together with the -
7424 \begin_inset ERT
7425 status Collapsed
7426
7427 \layout Standard
7428
7429 \backslash
7430 /
7431 \end_inset
7432
7433 -xstack
7434 \begin_inset LatexCommand \index{-\/-xstack}
7435
7436 \end_inset
7437
7438  option.
7439 \layout Subsubsection
7440
7441 code
7442 \begin_inset LatexCommand \index{code}
7443
7444 \end_inset
7445
7446
7447 \layout Standard
7448
7449 'Variables' declared with this storage class will be placed in the code
7450  memory:
7451 \layout Verse
7452
7453
7454 \family typewriter
7455 code unsigned char test_code;
7456 \layout Standard
7457
7458 Read access to this variable generates the assembly code:
7459 \layout Verse
7460
7461
7462 \family typewriter
7463 90s00r6F\SpecialChar ~
7464 \SpecialChar ~
7465 \SpecialChar ~
7466 mov dptr,#_test_code
7467 \newline
7468 E4\SpecialChar ~
7469 \SpecialChar ~
7470 \SpecialChar ~
7471 \SpecialChar ~
7472 \SpecialChar ~
7473 \SpecialChar ~
7474 \SpecialChar ~
7475 \SpecialChar ~
7476 \SpecialChar ~
7477 clr a
7478 \newline
7479 93\SpecialChar ~
7480 \SpecialChar ~
7481 \SpecialChar ~
7482 \SpecialChar ~
7483 \SpecialChar ~
7484 \SpecialChar ~
7485 \SpecialChar ~
7486 \SpecialChar ~
7487 \SpecialChar ~
7488 movc a,@a+dptr
7489 \layout Subsubsection
7490
7491 bit
7492 \begin_inset LatexCommand \index{bit}
7493
7494 \end_inset
7495
7496
7497 \layout Standard
7498
7499 This is a data-type and a storage class specifier.
7500  When a variable is declared as a bit, it is allocated into the bit addressable
7501  memory of 8051, e.g.:
7502 \layout Verse
7503
7504
7505 \family typewriter
7506 bit test_bit;
7507 \layout Standard
7508
7509 Writing 1 to this variable generates the assembly code:
7510 \layout Verse
7511
7512
7513 \family typewriter
7514 D2*00\SpecialChar ~
7515 \SpecialChar ~
7516 \SpecialChar ~
7517 \SpecialChar ~
7518 \SpecialChar ~
7519 \SpecialChar ~
7520 \SpecialChar ~
7521 setb\SpecialChar ~
7522 _test_bit
7523 \layout Subsubsection
7524
7525 sfr
7526 \begin_inset LatexCommand \index{sfr}
7527
7528 \end_inset
7529
7530  / sbit
7531 \begin_inset LatexCommand \index{sbit}
7532
7533 \end_inset
7534
7535
7536 \layout Standard
7537
7538 Like the bit keyword,
7539 \emph on
7540 sfr / sbit
7541 \emph default
7542 signifies both a data-type and storage class, they are used to describe
7543  the special function registers and special bit variables of a 8051, eg:
7544 \layout Verse
7545
7546
7547 \family typewriter
7548 sfr at
7549 \begin_inset LatexCommand \index{at}
7550
7551 \end_inset
7552
7553  0x80 P0;\SpecialChar ~
7554  /* special function register P0 at location 0x80 */
7555 \newline
7556 sbit at 0xd7 CY; /* CY (Carry Flag
7557 \begin_inset LatexCommand \index{Flags}
7558
7559 \end_inset
7560
7561
7562 \begin_inset LatexCommand \index{Carry flag}
7563
7564 \end_inset
7565
7566 ) */
7567 \layout Subsubsection
7568
7569 Pointers
7570 \begin_inset LatexCommand \index{Pointers}
7571
7572 \end_inset
7573
7574  to MCS51/DS390 specific memory spaces
7575 \layout Standard
7576
7577 SDCC allows (via language extensions) pointers to explicitly point to any
7578  of the memory spaces
7579 \begin_inset LatexCommand \index{Memory model}
7580
7581 \end_inset
7582
7583  of the 8051.
7584  In addition to the explicit pointers, the compiler uses (by default) generic
7585  pointers which can be used to point to any of the memory spaces.
7586 \newline
7587
7588 \newline
7589 Pointer declaration examples:
7590 \layout Verse
7591
7592
7593 \family typewriter
7594 /* pointer physically in internal ram pointing to object in external ram
7595  */
7596 \newline
7597 xdata unsigned char * data p;
7598 \newline
7599
7600 \newline
7601 /* pointer physically in external ram pointing to object in internal ram
7602  */
7603 \newline
7604 data unsigned char * xdata p;
7605 \newline
7606
7607 \newline
7608 /* pointer physically in code rom pointing to data in xdata space */
7609 \newline
7610 xdata unsigned char * code p;
7611 \newline
7612
7613 \newline
7614 /* pointer physically in code space pointing to data in code space */
7615 \newline
7616 code unsigned char * code p;
7617 \newline
7618
7619 \newline
7620 /* the following is a generic pointer physically located in xdata space
7621  */
7622 \newline
7623 char * xdata p;
7624 \layout Standard
7625
7626 Well you get the idea.
7627
7628 \newline
7629
7630 \newline
7631 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
7632 \emph on
7633 generic
7634 \emph default
7635  pointers.
7636
7637 \size small
7638
7639 \newline
7640
7641 \newline
7642
7643 \size default
7644 The highest order byte of the
7645 \emph on
7646 generic
7647 \emph default
7648  pointers contains the data space information.
7649  Assembler support routines are called whenever data is stored or retrieved
7650  using
7651 \emph on
7652 generic
7653 \emph default
7654  pointers.
7655  These are useful for developing reusable library
7656 \begin_inset LatexCommand \index{Libraries}
7657
7658 \end_inset
7659
7660  routines.
7661  Explicitly specifying the pointer type will generate the most efficient
7662  code.
7663 \layout Subsection
7664
7665 Absolute Addressing
7666 \begin_inset LatexCommand \index{Absolute addressing}
7667
7668 \end_inset
7669
7670
7671 \layout Standard
7672
7673 Data items can be assigned an absolute address with the
7674 \emph on
7675 at
7676 \begin_inset LatexCommand \index{at}
7677
7678 \end_inset
7679
7680  <address>
7681 \emph default
7682  keyword, in addition to a storage class, e.g.:
7683 \layout Verse
7684
7685
7686 \family typewriter
7687 xdata
7688 \begin_inset LatexCommand \index{xdata}
7689
7690 \end_inset
7691
7692  at
7693 \begin_inset LatexCommand \index{at}
7694
7695 \end_inset
7696
7697  0x7ffe unsigned int chksum;
7698 \layout Standard
7699
7700 In the above example the variable chksum will located at 0x7ffe and 0x7fff
7701  of the external ram.
7702  The compiler does not actually reserve any space for variables declared
7703  in this way (they are implemented with an equate in the assembler).
7704  Thus it is left to the programmer to make sure there are no overlaps with
7705  other variables that are declared without the absolute address.
7706  The assembler listing file (.lst
7707 \begin_inset LatexCommand \index{.lst}
7708
7709 \end_inset
7710
7711 ) and the linker output files (.rst
7712 \begin_inset LatexCommand \index{.rst}
7713
7714 \end_inset
7715
7716 ) and (.map
7717 \begin_inset LatexCommand \index{.map}
7718
7719 \end_inset
7720
7721 ) are good places to look for such overlaps.
7722 \layout Standard
7723
7724 In case of memory mapped I/O devices the keyword
7725 \emph on
7726 volatile
7727 \emph default
7728  should be used to tell the compiler that accesses might not be optimized
7729  away:
7730 \layout Verse
7731
7732
7733 \family typewriter
7734 volatile
7735 \begin_inset LatexCommand \index{volatile}
7736
7737 \end_inset
7738
7739  xdata
7740 \begin_inset LatexCommand \index{xdata}
7741
7742 \end_inset
7743
7744  at
7745 \begin_inset LatexCommand \index{at}
7746
7747 \end_inset
7748
7749  0x8000 unsigned char PORTA_8255;
7750 \layout Standard
7751
7752 Absolute address can be specified for variables in all storage classes,
7753  e.g.:
7754 \layout Verse
7755
7756
7757 \family typewriter
7758 bit
7759 \begin_inset LatexCommand \index{bit}
7760
7761 \end_inset
7762
7763  at
7764 \begin_inset LatexCommand \index{at}
7765
7766 \end_inset
7767
7768  0x02 bvar;
7769 \layout Standard
7770
7771 The above example will allocate the variable at offset 0x02 in the bit-addressab
7772 le space.
7773  There is no real advantage to assigning absolute addresses to variables
7774  in this manner, unless you want strict control over all the variables allocated.
7775  One possible use would be to write hardware portable code.
7776  For example, if you have a routine that uses one or more of the microcontroller
7777  I/O pins, and such pins are different for two different hardwares, you
7778  can declare the I/O pins in your routine using:
7779 \layout Verse
7780
7781
7782 \family typewriter
7783 extern volatile bit SDI;
7784 \newline
7785 extern volatile bit SCLK;
7786 \newline
7787 extern volatile bit CPOL;
7788 \newline
7789
7790 \newline
7791 void DS1306_put(unsigned char value)
7792 \newline
7793 {
7794 \newline
7795 \SpecialChar ~
7796 \SpecialChar ~
7797 \SpecialChar ~
7798 \SpecialChar ~
7799 unsigned char mask=0x80;
7800 \newline
7801
7802 \newline
7803 \SpecialChar ~
7804 \SpecialChar ~
7805 \SpecialChar ~
7806 \SpecialChar ~
7807 while(mask)
7808 \newline
7809 \SpecialChar ~
7810 \SpecialChar ~
7811 \SpecialChar ~
7812 \SpecialChar ~
7813 {
7814 \newline
7815 \SpecialChar ~
7816 \SpecialChar ~
7817 \SpecialChar ~
7818 \SpecialChar ~
7819 \SpecialChar ~
7820 \SpecialChar ~
7821 \SpecialChar ~
7822 \SpecialChar ~
7823 SDI=(value & mask)?1:0;
7824 \newline
7825 \SpecialChar ~
7826 \SpecialChar ~
7827 \SpecialChar ~
7828 \SpecialChar ~
7829 \SpecialChar ~
7830 \SpecialChar ~
7831 \SpecialChar ~
7832 \SpecialChar ~
7833 SCLK=!CPOL;
7834 \newline
7835 \SpecialChar ~
7836 \SpecialChar ~
7837 \SpecialChar ~
7838 \SpecialChar ~
7839 \SpecialChar ~
7840 \SpecialChar ~
7841 \SpecialChar ~
7842 \SpecialChar ~
7843 SCLK=CPOL;
7844 \newline
7845 \SpecialChar ~
7846 \SpecialChar ~
7847 \SpecialChar ~
7848 \SpecialChar ~
7849 \SpecialChar ~
7850 \SpecialChar ~
7851 \SpecialChar ~
7852 \SpecialChar ~
7853 mask/=2;
7854 \newline
7855 \SpecialChar ~
7856 \SpecialChar ~
7857 \SpecialChar ~
7858 \SpecialChar ~
7859 }
7860 \newline
7861 }
7862 \layout Standard
7863
7864 Then, someplace in the code for the first hardware you would use
7865 \layout Verse
7866
7867
7868 \family typewriter
7869 bit at 0x80 SDI;\SpecialChar ~
7870 \SpecialChar ~
7871 \SpecialChar ~
7872 \SpecialChar ~
7873 /* I/O port 0, bit 0 */
7874 \newline
7875 bit at 0x81 SCLK;\SpecialChar ~
7876 \SpecialChar ~
7877 \SpecialChar ~
7878 /* I/O port 0, bit 1 */
7879 \newline
7880 bit CPOL;\SpecialChar ~
7881 \SpecialChar ~
7882 \SpecialChar ~
7883 \SpecialChar ~
7884 \SpecialChar ~
7885 \SpecialChar ~
7886 \SpecialChar ~
7887 \SpecialChar ~
7888 \SpecialChar ~
7889 \SpecialChar ~
7890 \SpecialChar ~
7891 /* This is a variable, let the linker allocate this one */
7892 \layout Standard
7893
7894 Similarly, for the second hardware you would use
7895 \layout Verse
7896
7897
7898 \family typewriter
7899 bit at 0x83 SDI;\SpecialChar ~
7900 \SpecialChar ~
7901 \SpecialChar ~
7902 \SpecialChar ~
7903 /* I/O port 0, bit 3 */
7904 \newline
7905 bit at 0x91 SCLK;\SpecialChar ~
7906 \SpecialChar ~
7907 \SpecialChar ~
7908 /* I/O port 1, bit 1 */
7909 \newline
7910 bit CPOL;\SpecialChar ~
7911 \SpecialChar ~
7912 \SpecialChar ~
7913 \SpecialChar ~
7914 \SpecialChar ~
7915 \SpecialChar ~
7916 \SpecialChar ~
7917 \SpecialChar ~
7918 \SpecialChar ~
7919 \SpecialChar ~
7920 \SpecialChar ~
7921 /* This is a variable, let the linker allocate this one */
7922 \layout Standard
7923
7924 and you can use the same hardware dependent routine without changes, as
7925  for example in a library.
7926  This is somehow similar to sbit, but only one absolute address has to be
7927  specified in the whole project.
7928 \layout Subsection
7929
7930 Parameters
7931 \begin_inset LatexCommand \index{Parameters}
7932
7933 \end_inset
7934
7935  & Local Variables
7936 \begin_inset LatexCommand \index{Local variable}
7937
7938 \end_inset
7939
7940
7941 \layout Standard
7942
7943 Automatic (local) variables and parameters to functions can either be placed
7944  on the stack or in data-space.
7945  The default action of the compiler is to place these variables in the internal
7946  RAM (for small model) or external RAM (for large model).
7947  This in fact makes them similar to
7948 \emph on
7949 static
7950 \begin_inset LatexCommand \index{static}
7951
7952 \end_inset
7953
7954
7955 \emph default
7956  so by default functions are non-reentrant
7957 \begin_inset LatexCommand \index{reentrant}
7958
7959 \end_inset
7960
7961 .
7962
7963 \newline
7964
7965 \newline
7966 They can be placed on the stack
7967 \begin_inset LatexCommand \index{stack}
7968
7969 \end_inset
7970
7971  either by using the
7972 \emph on
7973  -
7974 \begin_inset ERT
7975 status Collapsed
7976
7977 \layout Standard
7978
7979 \backslash
7980 /
7981 \end_inset
7982
7983 -stack-auto
7984 \begin_inset LatexCommand \index{-\/-stack-auto}
7985
7986 \end_inset
7987
7988
7989 \emph default
7990  option or by using the
7991 \emph on
7992 reentrant
7993 \begin_inset LatexCommand \index{reentrant}
7994
7995 \end_inset
7996
7997
7998 \emph default
7999  keyword in the function declaration, e.g.:
8000 \layout Verse
8001
8002
8003 \family typewriter
8004 unsigned char foo(char i) reentrant
8005 \newline
8006 {
8007 \newline
8008 \SpecialChar ~
8009 \SpecialChar ~
8010 \SpecialChar ~
8011 \SpecialChar ~
8012 ...
8013
8014 \newline
8015 }
8016 \layout Standard
8017
8018 Since stack space on 8051 is limited, the
8019 \emph on
8020 reentrant
8021 \emph default
8022 keyword or the
8023 \emph on
8024  -
8025 \begin_inset ERT
8026 status Collapsed
8027
8028 \layout Standard
8029
8030 \backslash
8031 /
8032 \end_inset
8033
8034 -stack-auto
8035 \emph default
8036  option should be used sparingly.
8037  Note that the reentrant keyword just means that the parameters & local
8038  variables will be allocated to the stack, it
8039 \emph on
8040 does not
8041 \emph default
8042  mean that the function is register bank independent.
8043 \newline
8044
8045 \newline
8046 Local variables can be assigned storage classes and absolute
8047 \begin_inset LatexCommand \index{Absolute addressing}
8048
8049 \end_inset
8050
8051  addresses, e.g.:
8052 \layout Verse
8053
8054
8055 \family typewriter
8056 unsigned char foo()
8057 \newline
8058 {
8059 \newline
8060 \SpecialChar ~
8061 \SpecialChar ~
8062 \SpecialChar ~
8063 \SpecialChar ~
8064 xdata unsigned char i;
8065 \newline
8066 \SpecialChar ~
8067 \SpecialChar ~
8068 \SpecialChar ~
8069 \SpecialChar ~
8070 bit bvar;
8071 \newline
8072 \SpecialChar ~
8073 \SpecialChar ~
8074 \SpecialChar ~
8075 \SpecialChar ~
8076 data at 0x31 unsigned char j;
8077 \newline
8078 \SpecialChar ~
8079 \SpecialChar ~
8080 \SpecialChar ~
8081 \SpecialChar ~
8082 ...
8083
8084 \newline
8085 }
8086 \layout Standard
8087
8088 In the above example the variable
8089 \emph on
8090 i
8091 \emph default
8092  will be allocated in the external ram,
8093 \emph on
8094 bvar
8095 \emph default
8096  in bit addressable space and
8097 \emph on
8098  j
8099 \emph default
8100  in internal ram.
8101  When compiled with
8102 \emph on
8103 -
8104 \begin_inset ERT
8105 status Collapsed
8106
8107 \layout Standard
8108
8109 \backslash
8110 /
8111 \end_inset
8112
8113 -stack-auto
8114 \emph default
8115  or when a function is declared as
8116 \emph on
8117 reentrant
8118 \emph default
8119  this should only be done for static variables.
8120 \layout Standard
8121
8122 Parameters however are not allowed any storage class, (storage classes for
8123  parameters will be ignored), their allocation is governed by the memory
8124  model in use, and the reentrancy options.
8125 \layout Subsection
8126
8127 Overlaying
8128 \begin_inset LatexCommand \label{sub:Overlaying}
8129
8130 \end_inset
8131
8132
8133 \begin_inset LatexCommand \index{Overlaying}
8134
8135 \end_inset
8136
8137
8138 \layout Standard
8139
8140 For non-reentrant
8141 \begin_inset LatexCommand \index{reentrant}
8142
8143 \end_inset
8144
8145  functions SDCC will try to reduce internal ram space usage by overlaying
8146  parameters and local variables of a function (if possible).
8147  Parameters and local variables of a function will be allocated to an overlayabl
8148 e segment if the function has
8149 \emph on
8150 no other function calls and the function is non-reentrant and the memory
8151  model
8152 \begin_inset LatexCommand \index{Memory model}
8153
8154 \end_inset
8155
8156  is small.
8157
8158 \emph default
8159  If an explicit storage class
8160 \begin_inset LatexCommand \index{Storage class}
8161
8162 \end_inset
8163
8164  is specified for a local variable, it will NOT be overlayed.
8165 \layout Standard
8166
8167 Note that the compiler (not the linkage editor) makes the decision for overlayin
8168 g the data items.
8169  Functions that are called from an interrupt service routine should be preceded
8170  by a #pragma\SpecialChar ~
8171 NOOVERLAY
8172 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
8173
8174 \end_inset
8175
8176  if they are not reentrant.
8177 \layout Standard
8178
8179 Also note that the compiler does not do any processing of inline
8180 \begin_inset LatexCommand \index{inline}
8181
8182 \end_inset
8183
8184  assembler code, so the compiler might incorrectly assign local variables
8185  and parameters of a function into the overlay segment if the inline assembler
8186  code calls other c-functions that might use the overlay.
8187  In that case the #pragma\SpecialChar ~
8188 NOOVERLAY should be used.
8189 \layout Standard
8190
8191 Parameters and Local variables of functions that contain 16 or 32 bit multiplica
8192 tion
8193 \begin_inset LatexCommand \index{Multiplication}
8194
8195 \end_inset
8196
8197  or division
8198 \begin_inset LatexCommand \index{Division}
8199
8200 \end_inset
8201
8202  will NOT be overlayed since these are implemented using external functions,
8203  e.g.:
8204 \layout Verse
8205
8206
8207 \family typewriter
8208 #pragma SAVE
8209 \newline
8210 #pragma NOOVERLAY
8211 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
8212
8213 \end_inset
8214
8215
8216 \newline
8217 void set_error(unsigned char errcd)
8218 \newline
8219 {
8220 \newline
8221 \SpecialChar ~
8222 \SpecialChar ~
8223 \SpecialChar ~
8224 \SpecialChar ~
8225 P3 = errcd;
8226 \newline
8227 }
8228 \newline
8229 #pragma RESTORE
8230 \newline
8231
8232 \newline
8233 void some_isr () interrupt
8234 \begin_inset LatexCommand \index{interrupt}
8235
8236 \end_inset
8237
8238  2
8239 \newline
8240 {
8241 \newline
8242 \SpecialChar ~
8243 \SpecialChar ~
8244 \SpecialChar ~
8245 \SpecialChar ~
8246 ...
8247 \newline
8248 \SpecialChar ~
8249 \SpecialChar ~
8250 \SpecialChar ~
8251 \SpecialChar ~
8252 set_error(10);
8253 \newline
8254 \SpecialChar ~
8255 \SpecialChar ~
8256 \SpecialChar ~
8257 \SpecialChar ~
8258 ...
8259
8260 \newline
8261 }
8262 \layout Standard
8263
8264 In the above example the parameter
8265 \emph on
8266 errcd
8267 \emph default
8268  for the function
8269 \emph on
8270 set_error
8271 \emph default
8272  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
8273 NOOVERLAY was
8274  not present, this could cause unpredictable runtime behavior when called
8275  from an ISR.
8276  The #pragma\SpecialChar ~
8277 NOOVERLAY ensures that the parameters and local variables for
8278  the function are NOT overlayed.
8279 \layout Subsection
8280
8281 Interrupt Service Routines
8282 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
8283
8284 \end_inset
8285
8286
8287 \layout Standard
8288
8289 SDCC allows interrupt service routines to be coded in C, with some extended
8290  keywords.
8291 \layout Verse
8292
8293
8294 \family typewriter
8295 void timer_isr (void) interrupt 1 using 1
8296 \newline
8297 {
8298 \newline
8299 \SpecialChar ~
8300 \SpecialChar ~
8301 \SpecialChar ~
8302 \SpecialChar ~
8303 ...
8304
8305 \newline
8306 }
8307 \layout Standard
8308
8309 The optional number following the
8310 \emph on
8311 interrupt
8312 \begin_inset LatexCommand \index{interrupt}
8313
8314 \end_inset
8315
8316
8317 \emph default
8318  keyword is the interrupt number this routine will service.
8319  When present, the compiler will insert a call to this routine in the interrupt
8320  vector table for the interrupt number specified.
8321  The
8322 \emph on
8323 using
8324 \emph default
8325  keyword can be used to tell the compiler to use the specified register
8326  bank (8051 specific) when generating code for this function.
8327
8328 \newline
8329
8330 \layout Standard
8331
8332 If you have multiple source files in your project, interrupt service routines
8333  can be present in any of them, but a prototype of the isr MUST be present
8334  or included in the file that contains the function
8335 \emph on
8336 main
8337 \emph default
8338 .
8339 \layout Standard
8340
8341 Interrupt numbers and the corresponding address & descriptions for the Standard
8342  8051/8052 are listed below.
8343  SDCC will automatically adjust the interrupt vector table to the maximum
8344  interrupt number specified.
8345 \newline
8346
8347 \layout Standard
8348 \align center
8349
8350 \begin_inset  Tabular
8351 <lyxtabular version="3" rows="7" columns="3">
8352 <features>
8353 <column alignment="center" valignment="top" leftline="true" width="0in">
8354 <column alignment="center" valignment="top" leftline="true" width="0in">
8355 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
8356 <row topline="true" bottomline="true">
8357 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8358 \begin_inset Text
8359
8360 \layout Standard
8361
8362 Interrupt #
8363 \end_inset
8364 </cell>
8365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8366 \begin_inset Text
8367
8368 \layout Standard
8369
8370 Description
8371 \end_inset
8372 </cell>
8373 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8374 \begin_inset Text
8375
8376 \layout Standard
8377
8378 Vector Address
8379 \end_inset
8380 </cell>
8381 </row>
8382 <row topline="true">
8383 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8384 \begin_inset Text
8385
8386 \layout Standard
8387
8388 0
8389 \end_inset
8390 </cell>
8391 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8392 \begin_inset Text
8393
8394 \layout Standard
8395
8396 External 0
8397 \end_inset
8398 </cell>
8399 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8400 \begin_inset Text
8401
8402 \layout Standard
8403
8404 0x0003
8405 \end_inset
8406 </cell>
8407 </row>
8408 <row topline="true">
8409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8410 \begin_inset Text
8411
8412 \layout Standard
8413
8414 1
8415 \end_inset
8416 </cell>
8417 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8418 \begin_inset Text
8419
8420 \layout Standard
8421
8422 Timer 0
8423 \end_inset
8424 </cell>
8425 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8426 \begin_inset Text
8427
8428 \layout Standard
8429
8430 0x000B
8431 \end_inset
8432 </cell>
8433 </row>
8434 <row topline="true">
8435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8436 \begin_inset Text
8437
8438 \layout Standard
8439
8440 2
8441 \end_inset
8442 </cell>
8443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8444 \begin_inset Text
8445
8446 \layout Standard
8447
8448 External 1
8449 \end_inset
8450 </cell>
8451 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8452 \begin_inset Text
8453
8454 \layout Standard
8455
8456 0x0013
8457 \end_inset
8458 </cell>
8459 </row>
8460 <row topline="true">
8461 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8462 \begin_inset Text
8463
8464 \layout Standard
8465
8466 3
8467 \end_inset
8468 </cell>
8469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8470 \begin_inset Text
8471
8472 \layout Standard
8473
8474 Timer 1
8475 \end_inset
8476 </cell>
8477 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8478 \begin_inset Text
8479
8480 \layout Standard
8481
8482 0x001B
8483 \end_inset
8484 </cell>
8485 </row>
8486 <row topline="true">
8487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8488 \begin_inset Text
8489
8490 \layout Standard
8491
8492 4
8493 \end_inset
8494 </cell>
8495 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8496 \begin_inset Text
8497
8498 \layout Standard
8499
8500 Serial
8501 \end_inset
8502 </cell>
8503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8504 \begin_inset Text
8505
8506 \layout Standard
8507
8508 0x0023
8509 \end_inset
8510 </cell>
8511 </row>
8512 <row topline="true" bottomline="true">
8513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8514 \begin_inset Text
8515
8516 \layout Standard
8517
8518 5
8519 \end_inset
8520 </cell>
8521 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8522 \begin_inset Text
8523
8524 \layout Standard
8525
8526 Timer 2 (8052)
8527 \end_inset
8528 </cell>
8529 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8530 \begin_inset Text
8531
8532 \layout Standard
8533
8534 0x002B
8535 \end_inset
8536 </cell>
8537 </row>
8538 </lyxtabular>
8539
8540 \end_inset
8541
8542
8543 \newline
8544
8545 \layout Standard
8546
8547 If the interrupt service routine is defined without
8548 \emph on
8549 using
8550 \begin_inset LatexCommand \index{using}
8551
8552 \end_inset
8553
8554
8555 \emph default
8556  a register bank or with register bank 0 (using 0), the compiler will save
8557  the registers used by itself on the stack upon entry and restore them at
8558  exit, however if such an interrupt service routine calls another function
8559  then the entire register bank will be saved on the stack.
8560  This scheme may be advantageous for small interrupt service routines which
8561  have low register usage.
8562 \layout Standard
8563
8564 If the interrupt service routine is defined to be using a specific register
8565  bank then only
8566 \emph on
8567 a, b & dptr
8568 \emph default
8569  are save and restored, if such an interrupt service routine calls another
8570  function (using another register bank) then the entire register bank of
8571  the called function will be saved on the stack.
8572  This scheme is recommended for larger interrupt service routines.
8573 \layout Standard
8574
8575 Using interrupts opens the door for some very interesting bugs:
8576 \layout Standard
8577
8578 If the interrupt service routines changes variables which are accessed by
8579  other functions these variables should be declared
8580 \emph on
8581 volatile
8582 \emph default
8583
8584 \begin_inset LatexCommand \index{volatile}
8585
8586 \end_inset
8587
8588 .
8589  If the access to these variables is not
8590 \emph on
8591 atomic
8592 \begin_inset LatexCommand \index{atomic access}
8593
8594 \end_inset
8595
8596
8597 \emph default
8598  (i.e.
8599  the processor needs more than one instruction for the access and could
8600  be interrupted while accessing the variable) the interrupt must disabled
8601  during the access to avoid inconsistent data.
8602  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
8603  and should be protected by disabling interrupts.
8604  You're not automatically on the safe side if you use 8 bit variables though.
8605  We need an example here: f.e.
8606  on the 8051 the harmless looking
8607 \begin_inset Quotes srd
8608 \end_inset
8609
8610
8611 \family typewriter
8612 flags\SpecialChar ~
8613 |=\SpecialChar ~
8614 0x80;
8615 \family default
8616
8617 \begin_inset Quotes sld
8618 \end_inset
8619
8620  is not atomic if
8621 \family typewriter
8622 flags
8623 \family default
8624  resides in xdata.
8625  Setting
8626 \begin_inset Quotes srd
8627 \end_inset
8628
8629
8630 \family typewriter
8631 flags\SpecialChar ~
8632 |=\SpecialChar ~
8633 0x40;
8634 \family default
8635
8636 \begin_inset Quotes sld
8637 \end_inset
8638
8639  from within an interrupt routine might get lost if the interrupt occurs
8640  at the wrong time.
8641
8642 \begin_inset Quotes sld
8643 \end_inset
8644
8645
8646 \family typewriter
8647 counter\SpecialChar ~
8648 +=\SpecialChar ~
8649 8;
8650 \family default
8651
8652 \begin_inset Quotes srd
8653 \end_inset
8654
8655  is not atomic on the 8051 even if
8656 \family typewriter
8657 counter
8658 \family default
8659  is located in data memory.
8660  Bugs like these are hard to reproduce and can cause a lot of trouble.
8661
8662 \layout Standard
8663
8664 A special note here, int (16 bit) and long (32 bit) integer division
8665 \begin_inset LatexCommand \index{Division}
8666
8667 \end_inset
8668
8669 , multiplication
8670 \begin_inset LatexCommand \index{Multiplication}
8671
8672 \end_inset
8673
8674  & modulus
8675 \begin_inset LatexCommand \index{Modulus}
8676
8677 \end_inset
8678
8679  and floating-point
8680 \begin_inset LatexCommand \index{Floating point support}
8681
8682 \end_inset
8683
8684  operations are implemented using external support routines developed in
8685  ANSI-C.
8686  If an interrupt service routine needs to do any of these operations then
8687  the support routines (as mentioned in a following section) will have to
8688  be recompiled using the
8689 \emph on
8690  -
8691 \begin_inset ERT
8692 status Collapsed
8693
8694 \layout Standard
8695
8696 \backslash
8697 /
8698 \end_inset
8699
8700 -stack-auto
8701 \begin_inset LatexCommand \index{-\/-stack-auto}
8702
8703 \end_inset
8704
8705
8706 \emph default
8707  option and the source file will need to be compiled using the
8708 \emph on
8709 -
8710 \begin_inset ERT
8711 status Collapsed
8712
8713 \layout Standard
8714
8715 \backslash
8716 /
8717 \end_inset
8718
8719 -int-long-ren
8720 \emph default
8721 t
8722 \begin_inset LatexCommand \index{-\/-int-long-rent}
8723
8724 \end_inset
8725
8726  compiler option.
8727 \layout Standard
8728
8729 Calling other functions from an interrupt service routine is not recommended,
8730  avoid it if possible.
8731  Note that when some function is called from an interrupt service routine
8732  it should be preceded by a #pragma\SpecialChar ~
8733 NOOVERLAY
8734 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
8735
8736 \end_inset
8737
8738  if it is not reentrant.
8739  Furthermore nonreentrant functions should not be called from the main program
8740  while the interrupt service routine might be active.
8741
8742 \newline
8743
8744 \newline
8745 Also see section
8746 \begin_inset LatexCommand \ref{sub:Overlaying}
8747
8748 \end_inset
8749
8750 \SpecialChar ~
8751 about Overlaying and section
8752 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
8753
8754 \end_inset
8755
8756 \SpecialChar ~
8757 about Functions using private banks.
8758 \newline
8759
8760 \layout Subsection
8761
8762 Critical Functions
8763 \layout Standard
8764
8765 A special keyword may be associated with a function declaring it as
8766 \emph on
8767 critical
8768 \emph default
8769 .
8770  SDCC will generate code to disable all interrupts
8771 \begin_inset LatexCommand \index{interrupt}
8772
8773 \end_inset
8774
8775  upon entry to a critical function and restore the interrupt enable to the
8776  previous state before returning.
8777  Note that nesting critical functions will need one additional byte on the
8778  stack
8779 \begin_inset LatexCommand \index{stack}
8780
8781 \end_inset
8782
8783  for each call.
8784 \layout Verse
8785
8786
8787 \family typewriter
8788 int foo () critical
8789 \begin_inset LatexCommand \index{critical}
8790
8791 \end_inset
8792
8793
8794 \newline
8795 {
8796 \newline
8797 \SpecialChar ~
8798 \SpecialChar ~
8799 \SpecialChar ~
8800 \SpecialChar ~
8801 ...
8802
8803 \newline
8804 \SpecialChar ~
8805 \SpecialChar ~
8806 \SpecialChar ~
8807 \SpecialChar ~
8808 ...
8809
8810 \newline
8811 }
8812 \layout Standard
8813
8814 The critical attribute maybe used with other attributes like
8815 \emph on
8816 reentrant.
8817 \layout Subsection
8818
8819 Functions using private banks
8820 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
8821
8822 \end_inset
8823
8824
8825 \begin_inset LatexCommand \index{bank}
8826
8827 \end_inset
8828
8829
8830 \layout Standard
8831
8832 The
8833 \emph on
8834 using
8835 \begin_inset LatexCommand \index{using}
8836
8837 \end_inset
8838
8839
8840 \emph default
8841  attribute (which tells the compiler to use a register bank other than the
8842  default bank zero) should only be applied to
8843 \emph on
8844 interrupt
8845 \begin_inset LatexCommand \index{interrupt}
8846
8847 \end_inset
8848
8849
8850 \emph default
8851  functions (see note 1 below).
8852  This will in most circumstances make the generated ISR code more efficient
8853  since it will not have to save registers on the stack.
8854 \layout Standard
8855
8856 The
8857 \emph on
8858 using
8859 \emph default
8860  attribute will have no effect on the generated code for a
8861 \emph on
8862 non-interrupt
8863 \emph default
8864  function (but may occasionally be useful anyway
8865 \begin_inset Foot
8866 collapsed false
8867
8868 \layout Standard
8869
8870 possible exception: if a function is called ONLY from 'interrupt' functions
8871  using a particular bank, it can be declared with the same 'using' attribute
8872  as the calling 'interrupt' functions.
8873  For instance, if you have several ISRs using bank one, and all of them
8874  call memcpy(), it might make sense to create a specialized version of memcpy()
8875  'using 1', since this would prevent the ISR from having to save bank zero
8876  to the stack on entry and switch to bank zero before calling the function
8877 \end_inset
8878
8879 ).
8880 \newline
8881
8882 \emph on
8883 (pending: I don't think this has been done yet)
8884 \layout Standard
8885
8886 An
8887 \emph on
8888 interrupt
8889 \emph default
8890  function using a non-zero bank will assume that it can trash that register
8891  bank, and will not save it.
8892  Since high-priority interrupts
8893 \begin_inset LatexCommand \index{interrupt priority}
8894
8895 \end_inset
8896
8897  can interrupt low-priority ones on the 8051 and friends, this means that
8898  if a high-priority ISR
8899 \emph on
8900 using
8901 \emph default
8902  a particular bank occurs while processing a low-priority ISR
8903 \emph on
8904 using
8905 \emph default
8906  the same bank, terrible and bad things can happen.
8907  To prevent this, no single register bank should be
8908 \emph on
8909 used
8910 \emph default
8911  by both a high priority and a low priority ISR.
8912  This is probably most easily done by having all high priority ISRs use
8913  one bank and all low priority ISRs use another.
8914  If you have an ISR which can change priority at runtime, you're on your
8915  own: I suggest using the default bank zero and taking the small performance
8916  hit.
8917 \layout Standard
8918
8919 It is most efficient if your ISR calls no other functions.
8920  If your ISR must call other functions, it is most efficient if those functions
8921  use the same bank as the ISR (see note 1 below); the next best is if the
8922  called functions use bank zero.
8923  It is very inefficient to call a function using a different, non-zero bank
8924  from an ISR.
8925
8926 \layout Subsection
8927
8928 Startup Code
8929 \begin_inset LatexCommand \label{sub:Startup-Code}
8930
8931 \end_inset
8932
8933
8934 \begin_inset LatexCommand \index{Startup code}
8935
8936 \end_inset
8937
8938
8939 \layout Subsubsection
8940
8941 MCS51/DS390 Startup Code
8942 \layout Standard
8943
8944 The compiler inserts a call to the C routine
8945 \emph on
8946 _sdcc_external_startup()
8947 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
8948
8949 \end_inset
8950
8951
8952 \series bold
8953 \emph default
8954
8955 \series default
8956 at the start of the CODE area.
8957  This routine is in the runtime library
8958 \begin_inset LatexCommand \index{Runtime library}
8959
8960 \end_inset
8961
8962 .
8963  By default this routine returns 0, if this routine returns a non-zero value,
8964  the static & global variable initialization will be skipped and the function
8965  main will be invoked.
8966  Otherwise static & global variables will be initialized before the function
8967  main is invoked.
8968  You could add a
8969 \emph on
8970 _sdcc_external_startup()
8971 \emph default
8972  routine to your program to override the default if you need to setup hardware
8973  or perform some other critical operation prior to static & global variable
8974  initialization.
8975  See also the compiler option
8976 \emph on
8977 -
8978 \begin_inset ERT
8979 status Collapsed
8980
8981 \layout Standard
8982
8983 \backslash
8984 /
8985 \end_inset
8986
8987 -no-xinit
8988 \emph default
8989 -
8990 \emph on
8991 opt
8992 \emph default
8993
8994 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
8995
8996 \end_inset
8997
8998  and section
8999 \begin_inset LatexCommand \ref{sub:MCS51-variants}
9000
9001 \end_inset
9002
9003 \SpecialChar ~
9004 about MCS51-variants.
9005 \layout Subsubsection
9006
9007 Z80 Startup Code
9008 \layout Standard
9009
9010 On the Z80 the startup code is inserted by linking with crt0.o which is generated
9011  from sdcc/device/lib/z80/crt0.s.
9012  If you need a different startup code you can use the compiler option
9013 \emph on
9014 -
9015 \series bold
9016 \emph default
9017
9018 \begin_inset ERT
9019 status Collapsed
9020
9021 \layout Standard
9022
9023 \backslash
9024 /
9025 \end_inset
9026
9027
9028 \series default
9029 \emph on
9030 -no-std-crt0
9031 \emph default
9032
9033 \begin_inset LatexCommand \index{-\/-no-std-crt0}
9034
9035 \end_inset
9036
9037  and provide your own crt0.o.
9038
9039 \layout Subsection
9040
9041 Inline Assembler Code
9042 \begin_inset LatexCommand \index{Assembler routines}
9043
9044 \end_inset
9045
9046
9047 \layout Subsubsection
9048
9049 A Step by Step Introduction
9050 \layout Standard
9051
9052 Starting from a small snippet of c-code this example shows for the MCS51
9053  how to use inline assembly, access variables, a function parameter and
9054  an array in xdata memory.
9055  This is a buffer routine which should be optimized:
9056 \layout Verse
9057
9058
9059 \family typewriter
9060 \size footnotesize
9061 unsigned char xdata at 0x7f00 buf[0x100];
9062 \newline
9063 unsigned char head,tail;
9064 \newline
9065
9066 \newline
9067 void to_buffer( unsigned char c )
9068 \newline
9069 {
9070 \newline
9071 \SpecialChar ~
9072 \SpecialChar ~
9073 \SpecialChar ~
9074 \SpecialChar ~
9075 if( head != tail-1 )
9076 \newline
9077 \SpecialChar ~
9078 \SpecialChar ~
9079 \SpecialChar ~
9080 \SpecialChar ~
9081 \SpecialChar ~
9082 \SpecialChar ~
9083 \SpecialChar ~
9084 \SpecialChar ~
9085 buf[ head++ ] = c;
9086 \newline
9087 }
9088 \layout Standard
9089
9090 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
9091  then a corresponding buffer.asm file is generated.
9092  We define a new function
9093 \family typewriter
9094 to_buffer_asm()
9095 \family default
9096  in file buffer.c in which we cut and paste the generated code, removing
9097  unwanted comments and some ':'.
9098  Then add
9099 \begin_inset Quotes sld
9100 \end_inset
9101
9102 _asm
9103 \begin_inset Quotes srd
9104 \end_inset
9105
9106  and
9107 \begin_inset Quotes sld
9108 \end_inset
9109
9110 _endasm;
9111 \begin_inset Quotes srd
9112 \end_inset
9113
9114  to the beginning and the end of the function body:
9115 \layout Verse
9116
9117
9118 \family typewriter
9119 \size footnotesize
9120 /* With a cut and paste from the .asm file, we have something to start with.
9121 \newline
9122 \SpecialChar ~
9123 \SpecialChar ~
9124 \SpecialChar ~
9125 The function is not yet OK! (registers aren't saved) */
9126 \newline
9127 void to_buffer_asm( unsigned char c )
9128 \newline
9129 {
9130 \newline
9131 \SpecialChar ~
9132 \SpecialChar ~
9133 \SpecialChar ~
9134 \SpecialChar ~
9135 _asm
9136 \begin_inset LatexCommand \index{\_asm}
9137
9138 \end_inset
9139
9140
9141 \newline
9142 \SpecialChar ~
9143 \SpecialChar ~
9144 \SpecialChar ~
9145 \SpecialChar ~
9146 mov\SpecialChar ~
9147 \SpecialChar ~
9148 r2,dpl
9149 \newline
9150 ;buffer.c if( head != tail-1 )
9151 \newline
9152 \SpecialChar ~
9153 \SpecialChar ~
9154 \SpecialChar ~
9155 \SpecialChar ~
9156 mov\SpecialChar ~
9157 \SpecialChar ~
9158 a,_tail
9159 \newline
9160 \SpecialChar ~
9161 \SpecialChar ~
9162 \SpecialChar ~
9163 \SpecialChar ~
9164 dec\SpecialChar ~
9165 \SpecialChar ~
9166 a
9167 \newline
9168 \SpecialChar ~
9169 \SpecialChar ~
9170 \SpecialChar ~
9171 \SpecialChar ~
9172 mov\SpecialChar ~
9173 \SpecialChar ~
9174 r3,a
9175 \newline
9176 \SpecialChar ~
9177 \SpecialChar ~
9178 \SpecialChar ~
9179 \SpecialChar ~
9180 mov\SpecialChar ~
9181 \SpecialChar ~
9182 a,_head
9183 \newline
9184 \SpecialChar ~
9185 \SpecialChar ~
9186 \SpecialChar ~
9187 \SpecialChar ~
9188 cjne a,ar3,00106$
9189 \newline
9190 ret 00106$:
9191 \newline
9192 ;buffer.c buf[ head++ ] = c;
9193 \newline
9194 \SpecialChar ~
9195 \SpecialChar ~
9196 \SpecialChar ~
9197 \SpecialChar ~
9198 mov\SpecialChar ~
9199 \SpecialChar ~
9200 r3,_head
9201 \newline
9202 \SpecialChar ~
9203 \SpecialChar ~
9204 \SpecialChar ~
9205 \SpecialChar ~
9206 inc\SpecialChar ~
9207 \SpecialChar ~
9208 _head
9209 \newline
9210 \SpecialChar ~
9211 \SpecialChar ~
9212 \SpecialChar ~
9213 \SpecialChar ~
9214 mov\SpecialChar ~
9215 \SpecialChar ~
9216 a,r3
9217 \newline
9218 \SpecialChar ~
9219 \SpecialChar ~
9220 \SpecialChar ~
9221 \SpecialChar ~
9222 add\SpecialChar ~
9223 \SpecialChar ~
9224 a,#_buf
9225 \newline
9226 \SpecialChar ~
9227 \SpecialChar ~
9228 \SpecialChar ~
9229 \SpecialChar ~
9230 mov\SpecialChar ~
9231 \SpecialChar ~
9232 dpl,a
9233 \newline
9234 \SpecialChar ~
9235 \SpecialChar ~
9236 \SpecialChar ~
9237 \SpecialChar ~
9238 clr\SpecialChar ~
9239 \SpecialChar ~
9240 a
9241 \newline
9242 \SpecialChar ~
9243 \SpecialChar ~
9244 \SpecialChar ~
9245 \SpecialChar ~
9246 addc\SpecialChar ~
9247 a,#(_buf >> 8)
9248 \newline
9249 \SpecialChar ~
9250 \SpecialChar ~
9251 \SpecialChar ~
9252 \SpecialChar ~
9253 mov\SpecialChar ~
9254 \SpecialChar ~
9255 dph,a
9256 \newline
9257 \SpecialChar ~
9258 \SpecialChar ~
9259 \SpecialChar ~
9260 \SpecialChar ~
9261 mov\SpecialChar ~
9262 \SpecialChar ~
9263 a,r2
9264 \newline
9265 \SpecialChar ~
9266 \SpecialChar ~
9267 \SpecialChar ~
9268 \SpecialChar ~
9269 movx @dptr,a
9270 \newline
9271 00103$:
9272 \newline
9273 \SpecialChar ~
9274 \SpecialChar ~
9275 \SpecialChar ~
9276 \SpecialChar ~
9277 ret
9278 \newline
9279 \SpecialChar ~
9280 \SpecialChar ~
9281 \SpecialChar ~
9282 \SpecialChar ~
9283 _endasm;
9284 \newline
9285 }
9286 \layout Standard
9287
9288 The new file buffer.c should compile with only one warning about the unreferenced
9289  function argument 'c'.
9290  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
9291  and finally have:
9292 \layout Verse
9293
9294
9295 \family typewriter
9296 \size footnotesize
9297 unsigned char xdata at 0x7f00 buf[0x100];
9298 \newline
9299 unsigned char head,tail;
9300 \newline
9301 #define USE_ASSEMBLY (1)
9302 \newline
9303
9304 \newline
9305 #ifndef USE_ASSEMBLY
9306 \newline
9307 void to_buffer( unsigned char c )
9308 \newline
9309 {
9310 \newline
9311 \SpecialChar ~
9312 \SpecialChar ~
9313 \SpecialChar ~
9314 \SpecialChar ~
9315 if( head != tail-1 )
9316 \newline
9317 \SpecialChar ~
9318 \SpecialChar ~
9319 \SpecialChar ~
9320 \SpecialChar ~
9321 \SpecialChar ~
9322 \SpecialChar ~
9323 \SpecialChar ~
9324 \SpecialChar ~
9325 buf[ head++ ] = c;
9326 \newline
9327 }
9328 \newline
9329
9330 \newline
9331 #else
9332 \newline
9333
9334 \newline
9335 void to_buffer( unsigned char c )
9336 \newline
9337 {
9338 \newline
9339 \SpecialChar ~
9340 \SpecialChar ~
9341 \SpecialChar ~
9342 \SpecialChar ~
9343 c; // to avoid warning: unreferenced function argument
9344 \newline
9345 \SpecialChar ~
9346 \SpecialChar ~
9347 \SpecialChar ~
9348 \SpecialChar ~
9349 _asm
9350 \begin_inset LatexCommand \index{\_asm}
9351
9352 \end_inset
9353
9354
9355 \newline
9356 \SpecialChar ~
9357 \SpecialChar ~
9358 \SpecialChar ~
9359 \SpecialChar ~
9360 \SpecialChar ~
9361 \SpecialChar ~
9362 \SpecialChar ~
9363 \SpecialChar ~
9364 ; save used registers here.
9365
9366 \newline
9367 \SpecialChar ~
9368 \SpecialChar ~
9369 \SpecialChar ~
9370 \SpecialChar ~
9371 \SpecialChar ~
9372 \SpecialChar ~
9373 \SpecialChar ~
9374 \SpecialChar ~
9375 ; If we were still using r2,r3 we would have to push them here.
9376
9377 \newline
9378 ; if( head != tail-1 )
9379 \newline
9380 \SpecialChar ~
9381 \SpecialChar ~
9382 \SpecialChar ~
9383 \SpecialChar ~
9384 \SpecialChar ~
9385 \SpecialChar ~
9386 \SpecialChar ~
9387 \SpecialChar ~
9388 mov\SpecialChar ~
9389  a,_tail
9390 \newline
9391 \SpecialChar ~
9392 \SpecialChar ~
9393 \SpecialChar ~
9394 \SpecialChar ~
9395 \SpecialChar ~
9396 \SpecialChar ~
9397 \SpecialChar ~
9398 \SpecialChar ~
9399 dec\SpecialChar ~
9400  a
9401 \newline
9402 \SpecialChar ~
9403 \SpecialChar ~
9404 \SpecialChar ~
9405 \SpecialChar ~
9406 \SpecialChar ~
9407 \SpecialChar ~
9408 \SpecialChar ~
9409 \SpecialChar ~
9410 xrl\SpecialChar ~
9411  a,_head
9412 \newline
9413 \SpecialChar ~
9414 \SpecialChar ~
9415 \SpecialChar ~
9416 \SpecialChar ~
9417 \SpecialChar ~
9418 \SpecialChar ~
9419 \SpecialChar ~
9420 \SpecialChar ~
9421 ; we could do an ANL a,#0x0f here to use a smaller buffer
9422 \newline
9423 \SpecialChar ~
9424 \SpecialChar ~
9425 \SpecialChar ~
9426 \SpecialChar ~
9427 \SpecialChar ~
9428 \SpecialChar ~
9429 \SpecialChar ~
9430 \SpecialChar ~
9431 jz\SpecialChar ~
9432 \SpecialChar ~
9433  t_b_end$
9434 \newline
9435 \SpecialChar ~
9436 \SpecialChar ~
9437 \SpecialChar ~
9438 \SpecialChar ~
9439 \SpecialChar ~
9440 \SpecialChar ~
9441 \SpecialChar ~
9442 \SpecialChar ~
9443 ;
9444 \newline
9445 ; buf[ head++ ] = c;
9446 \newline
9447 \SpecialChar ~
9448 \SpecialChar ~
9449 \SpecialChar ~
9450 \SpecialChar ~
9451 \SpecialChar ~
9452 \SpecialChar ~
9453 \SpecialChar ~
9454 \SpecialChar ~
9455 mov\SpecialChar ~
9456  a,dpl \SpecialChar ~
9457 \SpecialChar ~
9458 \SpecialChar ~
9459 \SpecialChar ~
9460 \SpecialChar ~
9461 \SpecialChar ~
9462 \SpecialChar ~
9463 ; dpl holds lower byte of function argument
9464 \newline
9465 \SpecialChar ~
9466 \SpecialChar ~
9467 \SpecialChar ~
9468 \SpecialChar ~
9469 \SpecialChar ~
9470 \SpecialChar ~
9471 \SpecialChar ~
9472 \SpecialChar ~
9473 mov\SpecialChar ~
9474  dpl,_head \SpecialChar ~
9475 \SpecialChar ~
9476 \SpecialChar ~
9477 ; buf is 0x100 byte aligned so head can be used directly
9478 \newline
9479 \SpecialChar ~
9480 \SpecialChar ~
9481 \SpecialChar ~
9482 \SpecialChar ~
9483 \SpecialChar ~
9484 \SpecialChar ~
9485 \SpecialChar ~
9486 \SpecialChar ~
9487 mov\SpecialChar ~
9488  dph,#(_buf>>8)
9489 \newline
9490 \SpecialChar ~
9491 \SpecialChar ~
9492 \SpecialChar ~
9493 \SpecialChar ~
9494 \SpecialChar ~
9495 \SpecialChar ~
9496 \SpecialChar ~
9497 \SpecialChar ~
9498 movx @dptr,a
9499 \newline
9500 \SpecialChar ~
9501 \SpecialChar ~
9502 \SpecialChar ~
9503 \SpecialChar ~
9504 \SpecialChar ~
9505 \SpecialChar ~
9506 \SpecialChar ~
9507 \SpecialChar ~
9508 inc \SpecialChar ~
9509 _head
9510 \newline
9511 \SpecialChar ~
9512 \SpecialChar ~
9513 \SpecialChar ~
9514 \SpecialChar ~
9515 \SpecialChar ~
9516 \SpecialChar ~
9517 \SpecialChar ~
9518 \SpecialChar ~
9519 ;
9520 \newline
9521 t_b_end$:
9522 \newline
9523 \SpecialChar ~
9524 \SpecialChar ~
9525 \SpecialChar ~
9526 \SpecialChar ~
9527 \SpecialChar ~
9528 \SpecialChar ~
9529 \SpecialChar ~
9530 \SpecialChar ~
9531 ; restore used registers here
9532 \newline
9533 \SpecialChar ~
9534 \SpecialChar ~
9535 \SpecialChar ~
9536 \SpecialChar ~
9537 _endasm;
9538 \newline
9539 }
9540 \newline
9541 #endif
9542 \layout Standard
9543
9544 The inline assembler code can contain any valid code understood by the assembler
9545 , this includes any assembler directives and comment lines
9546 \begin_inset Foot
9547 collapsed false
9548
9549 \layout Standard
9550
9551 The assembler does not like some characters like ':' or ''' in comments.
9552 \end_inset
9553
9554 .
9555  The compiler does not do any validation of the code within the
9556 \family typewriter
9557 _asm
9558 \begin_inset LatexCommand \index{\_asm}
9559
9560 \end_inset
9561
9562  ...
9563  _endasm;
9564 \family default
9565  keyword pair.
9566  Specifically it will not know which registers are used and thus register
9567  pushing/popping
9568 \begin_inset LatexCommand \index{push/pop}
9569
9570 \end_inset
9571
9572  has to be done manually.
9573
9574 \layout Standard
9575
9576 It is strongly recommended that each assembly instruction (including labels)
9577  be placed in a separate line (as the example shows).
9578  When the -
9579 \begin_inset ERT
9580 status Collapsed
9581
9582 \layout Standard
9583
9584 \backslash
9585 /
9586 \end_inset
9587
9588 -
9589 \emph on
9590 peep-asm
9591 \begin_inset LatexCommand \index{-\/-peep-asm}
9592
9593 \end_inset
9594
9595
9596 \emph default
9597  command line option is used, the inline assembler code will be passed through
9598  the peephole optimizer
9599 \begin_inset LatexCommand \index{Peephole optimizer}
9600
9601 \end_inset
9602
9603 .
9604  There are only a few (if any) cases where this option makes sense, it might
9605  cause some unexpected changes in the inline assembler code.
9606  Please go through the peephole optimizer rules defined in file
9607 \emph on
9608 SDCCpeeph.def
9609 \emph default
9610  carefully before using this option.
9611 \layout Subsubsection
9612
9613 Naked Functions
9614 \begin_inset LatexCommand \label{sub:Naked-Functions}
9615
9616 \end_inset
9617
9618
9619 \begin_inset LatexCommand \index{Naked functions}
9620
9621 \end_inset
9622
9623
9624 \layout Standard
9625
9626 A special keyword may be associated with a function declaring it as
9627 \emph on
9628 _naked
9629 \begin_inset LatexCommand \index{\_naked}
9630
9631 \end_inset
9632
9633 .
9634
9635 \emph default
9636 The
9637 \emph on
9638 _naked
9639 \emph default
9640  function modifier attribute prevents the compiler from generating prologue
9641 \begin_inset LatexCommand \index{function prologue}
9642
9643 \end_inset
9644
9645  and epilogue
9646 \begin_inset LatexCommand \index{function epilogue}
9647
9648 \end_inset
9649
9650  code for that function.
9651  This means that the user is entirely responsible for such things as saving
9652  any registers that may need to be preserved, selecting the proper register
9653  bank, generating the
9654 \emph on
9655 return
9656 \emph default
9657  instruction at the end, etc.
9658  Practically, this means that the contents of the function must be written
9659  in inline assembler.
9660  This is particularly useful for interrupt functions, which can have a large
9661  (and often unnecessary) prologue/epilogue.
9662  For example, compare the code generated by these two functions:
9663 \layout Verse
9664
9665
9666 \family typewriter
9667 volatile
9668 \begin_inset LatexCommand \index{volatile}
9669
9670 \end_inset
9671
9672  data unsigned char counter;
9673 \newline
9674
9675 \newline
9676 void simpleInterrupt(void) interrupt
9677 \begin_inset LatexCommand \index{interrupt}
9678
9679 \end_inset
9680
9681  1
9682 \newline
9683 {
9684 \newline
9685 \SpecialChar ~
9686 \SpecialChar ~
9687 \SpecialChar ~
9688 \SpecialChar ~
9689 counter++;
9690 \newline
9691 }
9692 \newline
9693
9694 \newline
9695 void nakedInterrupt(void) interrupt 2 _naked
9696 \newline
9697 {
9698 \newline
9699 \SpecialChar ~
9700 \SpecialChar ~
9701 \SpecialChar ~
9702 \SpecialChar ~
9703 _asm
9704 \begin_inset LatexCommand \index{\_asm}
9705
9706 \end_inset
9707
9708
9709 \newline
9710 \SpecialChar ~
9711 \SpecialChar ~
9712 \SpecialChar ~
9713 \SpecialChar ~
9714 \SpecialChar ~
9715 \SpecialChar ~
9716 inc\SpecialChar ~
9717 \SpecialChar ~
9718 \SpecialChar ~
9719 \SpecialChar ~
9720 \SpecialChar ~
9721 _counter
9722 \newline
9723 \SpecialChar ~
9724 \SpecialChar ~
9725 \SpecialChar ~
9726 \SpecialChar ~
9727 \SpecialChar ~
9728 \SpecialChar ~
9729 reti\SpecialChar ~
9730 \SpecialChar ~
9731 \SpecialChar ~
9732 \SpecialChar ~
9733 ; MUST explicitly include ret or reti in _naked function.
9734 \newline
9735 \SpecialChar ~
9736 \SpecialChar ~
9737 \SpecialChar ~
9738 \SpecialChar ~
9739 _endasm
9740 \begin_inset LatexCommand \index{\_endasm}
9741
9742 \end_inset
9743
9744 ;
9745 \newline
9746 }
9747 \layout Standard
9748
9749 For an 8051 target, the generated simpleInterrupt looks like:
9750 \layout Verse
9751
9752
9753 \family typewriter
9754 _simpleInterrupt:
9755 \newline
9756 \SpecialChar ~
9757 \SpecialChar ~
9758 \SpecialChar ~
9759 \SpecialChar ~
9760 push\SpecialChar ~
9761 \SpecialChar ~
9762 \SpecialChar ~
9763 \SpecialChar ~
9764 acc
9765 \newline
9766 \SpecialChar ~
9767 \SpecialChar ~
9768 \SpecialChar ~
9769 \SpecialChar ~
9770 push\SpecialChar ~
9771 \SpecialChar ~
9772 \SpecialChar ~
9773 \SpecialChar ~
9774 b
9775 \newline
9776 \SpecialChar ~
9777 \SpecialChar ~
9778 \SpecialChar ~
9779 \SpecialChar ~
9780 push\SpecialChar ~
9781 \SpecialChar ~
9782 \SpecialChar ~
9783 \SpecialChar ~
9784 dpl
9785 \newline
9786 \SpecialChar ~
9787 \SpecialChar ~
9788 \SpecialChar ~
9789 \SpecialChar ~
9790 push\SpecialChar ~
9791 \SpecialChar ~
9792 \SpecialChar ~
9793 \SpecialChar ~
9794 dph
9795 \newline
9796 \SpecialChar ~
9797 \SpecialChar ~
9798 \SpecialChar ~
9799 \SpecialChar ~
9800 push\SpecialChar ~
9801 \SpecialChar ~
9802 \SpecialChar ~
9803 \SpecialChar ~
9804 psw
9805 \newline
9806 \SpecialChar ~
9807 \SpecialChar ~
9808 \SpecialChar ~
9809 \SpecialChar ~
9810 mov\SpecialChar ~
9811 \SpecialChar ~
9812 \SpecialChar ~
9813 \SpecialChar ~
9814 \SpecialChar ~
9815 psw,#0x00
9816 \newline
9817 \SpecialChar ~
9818 \SpecialChar ~
9819 \SpecialChar ~
9820 \SpecialChar ~
9821 inc\SpecialChar ~
9822 \SpecialChar ~
9823 \SpecialChar ~
9824 \SpecialChar ~
9825 \SpecialChar ~
9826 _counter
9827 \newline
9828 \SpecialChar ~
9829 \SpecialChar ~
9830 \SpecialChar ~
9831 \SpecialChar ~
9832 pop\SpecialChar ~
9833 \SpecialChar ~
9834 \SpecialChar ~
9835 \SpecialChar ~
9836 \SpecialChar ~
9837 psw
9838 \newline
9839 \SpecialChar ~
9840 \SpecialChar ~
9841 \SpecialChar ~
9842 \SpecialChar ~
9843 pop\SpecialChar ~
9844 \SpecialChar ~
9845 \SpecialChar ~
9846 \SpecialChar ~
9847 \SpecialChar ~
9848 dph
9849 \newline
9850 \SpecialChar ~
9851 \SpecialChar ~
9852 \SpecialChar ~
9853 \SpecialChar ~
9854 pop\SpecialChar ~
9855 \SpecialChar ~
9856 \SpecialChar ~
9857 \SpecialChar ~
9858 \SpecialChar ~
9859 dpl
9860 \newline
9861 \SpecialChar ~
9862 \SpecialChar ~
9863 \SpecialChar ~
9864 \SpecialChar ~
9865 pop\SpecialChar ~
9866 \SpecialChar ~
9867 \SpecialChar ~
9868 \SpecialChar ~
9869 \SpecialChar ~
9870 b
9871 \newline
9872 \SpecialChar ~
9873 \SpecialChar ~
9874 \SpecialChar ~
9875 \SpecialChar ~
9876 pop\SpecialChar ~
9877 \SpecialChar ~
9878 \SpecialChar ~
9879 \SpecialChar ~
9880 \SpecialChar ~
9881 acc
9882 \newline
9883 \SpecialChar ~
9884 \SpecialChar ~
9885 \SpecialChar ~
9886 \SpecialChar ~
9887 reti
9888 \layout Standard
9889
9890 whereas nakedInterrupt looks like:
9891 \layout Verse
9892
9893
9894 \family typewriter
9895 _nakedInterrupt:
9896 \newline
9897 \SpecialChar ~
9898 \SpecialChar ~
9899 \SpecialChar ~
9900 \SpecialChar ~
9901 inc\SpecialChar ~
9902 \SpecialChar ~
9903 \SpecialChar ~
9904 \SpecialChar ~
9905 _counter
9906 \newline
9907 \SpecialChar ~
9908 \SpecialChar ~
9909 \SpecialChar ~
9910 \SpecialChar ~
9911 reti\SpecialChar ~
9912 \SpecialChar ~
9913 \SpecialChar ~
9914 ; MUST explicitly include ret or reti in _naked function.
9915 \layout Standard
9916
9917 The #pragma directive EXCLUDE
9918 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
9919
9920 \end_inset
9921
9922  allows a more fine grained control over pushing & popping
9923 \begin_inset LatexCommand \index{push/pop}
9924
9925 \end_inset
9926
9927  the registers.
9928 \layout Standard
9929
9930 While there is nothing preventing you from writing C code inside a _naked
9931  function, there are many ways to shoot yourself in the foot doing this,
9932  and it is recommended that you stick to inline assembler.
9933 \layout Subsubsection
9934
9935 Use of Labels within Inline Assembler
9936 \layout Standard
9937
9938 SDCC allows the use of in-line assembler with a few restriction as regards
9939  labels.
9940  In older versions of the compiler all labels defined within inline assembler
9941  code
9942 \emph on
9943 had to be
9944 \emph default
9945  of the form
9946 \emph on
9947 nnnnn$
9948 \emph default
9949  where nnnn is a number less than 100 (which implies a limit of utmost 100
9950  inline assembler labels
9951 \emph on
9952 per function
9953 \emph default
9954 \noun on
9955 )
9956 \noun default
9957 .
9958
9959 \layout Verse
9960
9961
9962 \family typewriter
9963 _asm
9964 \begin_inset LatexCommand \index{\_asm}
9965
9966 \end_inset
9967
9968
9969 \newline
9970 \SpecialChar ~
9971 \SpecialChar ~
9972 \SpecialChar ~
9973 \SpecialChar ~
9974 mov\SpecialChar ~
9975 \SpecialChar ~
9976 \SpecialChar ~
9977 \SpecialChar ~
9978 \SpecialChar ~
9979 b,#10
9980 \newline
9981 00001$:
9982 \newline
9983 \SpecialChar ~
9984 \SpecialChar ~
9985 \SpecialChar ~
9986 \SpecialChar ~
9987 djnz\SpecialChar ~
9988 \SpecialChar ~
9989 \SpecialChar ~
9990 \SpecialChar ~
9991 b,00001$
9992 \newline
9993 _endasm
9994 \begin_inset LatexCommand \index{\_endasm}
9995
9996 \end_inset
9997
9998  ;
9999 \layout Standard
10000
10001 Inline assembler code cannot reference any C-Labels, however it can reference
10002  labels
10003 \begin_inset LatexCommand \index{Labels}
10004
10005 \end_inset
10006
10007  defined by the inline assembler, e.g.:
10008 \layout Verse
10009
10010
10011 \family typewriter
10012 foo() {
10013 \newline
10014 \SpecialChar ~
10015 \SpecialChar ~
10016 \SpecialChar ~
10017 \SpecialChar ~
10018 /* some c code */
10019 \newline
10020 \SpecialChar ~
10021 \SpecialChar ~
10022 \SpecialChar ~
10023 \SpecialChar ~
10024 _asm
10025 \newline
10026 \SpecialChar ~
10027 \SpecialChar ~
10028 \SpecialChar ~
10029 \SpecialChar ~
10030 \SpecialChar ~
10031 \SpecialChar ~
10032 ; some assembler code
10033 \newline
10034 \SpecialChar ~
10035 \SpecialChar ~
10036 \SpecialChar ~
10037 \SpecialChar ~
10038 \SpecialChar ~
10039 \SpecialChar ~
10040 ljmp $0003
10041 \newline
10042 \SpecialChar ~
10043 \SpecialChar ~
10044 \SpecialChar ~
10045 \SpecialChar ~
10046 _endasm;
10047 \newline
10048 \SpecialChar ~
10049 \SpecialChar ~
10050 \SpecialChar ~
10051 \SpecialChar ~
10052 /* some more c code */
10053 \newline
10054 clabel:\SpecialChar ~
10055 \SpecialChar ~
10056 /* inline assembler cannot reference this label */
10057 \newline
10058 \SpecialChar ~
10059 \SpecialChar ~
10060 \SpecialChar ~
10061 \SpecialChar ~
10062 _asm
10063 \newline
10064 \SpecialChar ~
10065 \SpecialChar ~
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 $0003: ;label (can be reference by inline assembler only)
10069 \newline
10070 \SpecialChar ~
10071 \SpecialChar ~
10072 \SpecialChar ~
10073 \SpecialChar ~
10074 _endasm ;
10075 \newline
10076 \SpecialChar ~
10077 \SpecialChar ~
10078 \SpecialChar ~
10079 \SpecialChar ~
10080 /* some more c code */
10081 \newline
10082 }
10083 \layout Standard
10084
10085 In other words inline assembly code can access labels defined in inline
10086  assembly within the scope of the function.
10087  The same goes the other way, ie.
10088  labels defines in inline assembly can not be accessed by C statements.
10089 \layout Subsection
10090
10091 Interfacing with Assembler Code
10092 \begin_inset LatexCommand \index{Assembler routines}
10093
10094 \end_inset
10095
10096
10097 \layout Subsubsection
10098
10099 Global Registers used for Parameter Passing
10100 \begin_inset LatexCommand \index{Parameter passing}
10101
10102 \end_inset
10103
10104
10105 \layout Standard
10106
10107 The compiler always uses the global registers
10108 \emph on
10109 DPL, DPH
10110 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
10111
10112 \end_inset
10113
10114 , B
10115 \begin_inset LatexCommand \index{B (register)}
10116
10117 \end_inset
10118
10119
10120 \emph default
10121 and
10122 \emph on
10123  ACC
10124 \begin_inset LatexCommand \index{ACC}
10125
10126 \end_inset
10127
10128
10129 \emph default
10130  to pass the first parameter to a routine.
10131  The second parameter onwards is either allocated on the stack (for reentrant
10132  routines or if -
10133 \begin_inset ERT
10134 status Collapsed
10135
10136 \layout Standard
10137
10138 \backslash
10139 /
10140 \end_inset
10141
10142 -stack-auto is used) or in data / xdata memory (depending on the memory
10143  model).
10144
10145 \layout Subsubsection
10146
10147 Assembler Routine(non-reentrant
10148 \begin_inset LatexCommand \index{reentrant}
10149
10150 \end_inset
10151
10152 )
10153 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
10154
10155 \end_inset
10156
10157
10158 \layout Standard
10159
10160 In the following example the function c_func calls an assembler routine
10161  asm_func, which takes two parameters.
10162 \layout Verse
10163
10164
10165 \family typewriter
10166 extern int asm_func(unsigned char, unsigned char);
10167 \newline
10168
10169 \newline
10170 int c_func (unsigned char i, unsigned char j)
10171 \newline
10172 {
10173 \newline
10174 \SpecialChar ~
10175 \SpecialChar ~
10176 \SpecialChar ~
10177 \SpecialChar ~
10178 return asm_func(i,j);
10179 \newline
10180 }
10181 \newline
10182
10183 \newline
10184 int main()
10185 \newline
10186 {
10187 \newline
10188 \SpecialChar ~
10189 \SpecialChar ~
10190 \SpecialChar ~
10191 \SpecialChar ~
10192 return c_func(10,9);
10193 \newline
10194 }
10195 \layout Standard
10196
10197 The corresponding assembler function is:
10198 \layout Verse
10199
10200
10201 \family typewriter
10202 .globl _asm_func_PARM_2
10203 \newline
10204 \SpecialChar ~
10205 \SpecialChar ~
10206 \SpecialChar ~
10207 \SpecialChar ~
10208 \SpecialChar ~
10209 \SpecialChar ~
10210 \SpecialChar ~
10211 \SpecialChar ~
10212 .globl _asm_func
10213 \newline
10214 \SpecialChar ~
10215 \SpecialChar ~
10216 \SpecialChar ~
10217 \SpecialChar ~
10218 \SpecialChar ~
10219 \SpecialChar ~
10220 \SpecialChar ~
10221 \SpecialChar ~
10222 .area OSEG
10223 \newline
10224 _asm_func_PARM_2:
10225 \newline
10226 \SpecialChar ~
10227 \SpecialChar ~
10228 \SpecialChar ~
10229 \SpecialChar ~
10230 \SpecialChar ~
10231 \SpecialChar ~
10232 \SpecialChar ~
10233 \SpecialChar ~
10234 .ds     1
10235 \newline
10236 \SpecialChar ~
10237 \SpecialChar ~
10238 \SpecialChar ~
10239 \SpecialChar ~
10240 \SpecialChar ~
10241 \SpecialChar ~
10242 \SpecialChar ~
10243 \SpecialChar ~
10244 .area CSEG
10245 \newline
10246 _asm_func:
10247 \newline
10248 \SpecialChar ~
10249 \SpecialChar ~
10250 \SpecialChar ~
10251 \SpecialChar ~
10252 \SpecialChar ~
10253 \SpecialChar ~
10254 \SpecialChar ~
10255 \SpecialChar ~
10256 mov    a,dpl
10257 \newline
10258 \SpecialChar ~
10259 \SpecialChar ~
10260 \SpecialChar ~
10261 \SpecialChar ~
10262 \SpecialChar ~
10263 \SpecialChar ~
10264 \SpecialChar ~
10265 \SpecialChar ~
10266 add    a,_asm_func_PARM_2
10267 \newline
10268 \SpecialChar ~
10269 \SpecialChar ~
10270 \SpecialChar ~
10271 \SpecialChar ~
10272 \SpecialChar ~
10273 \SpecialChar ~
10274 \SpecialChar ~
10275 \SpecialChar ~
10276 mov    dpl,a
10277 \newline
10278 \SpecialChar ~
10279 \SpecialChar ~
10280 \SpecialChar ~
10281 \SpecialChar ~
10282 \SpecialChar ~
10283 \SpecialChar ~
10284 \SpecialChar ~
10285 \SpecialChar ~
10286 mov\SpecialChar ~
10287 \SpecialChar ~
10288 \SpecialChar ~
10289 \SpecialChar ~
10290 dph
10291 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
10292
10293 \end_inset
10294
10295 ,#0x00
10296 \newline
10297 \SpecialChar ~
10298 \SpecialChar ~
10299 \SpecialChar ~
10300 \SpecialChar ~
10301 \SpecialChar ~
10302 \SpecialChar ~
10303 \SpecialChar ~
10304 \SpecialChar ~
10305 ret
10306 \layout Standard
10307
10308 Note here that the return values are placed in 'dpl' - One byte return value,
10309  'dpl' LSB & 'dph' MSB for two byte values.
10310  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
10311 b' & 'acc' for four byte values.
10312 \layout Standard
10313
10314 The parameter naming convention is _<function_name>_PARM_<n>, where n is
10315  the parameter number starting from 1, and counting from the left.
10316  The first parameter is passed in
10317 \begin_inset Quotes eld
10318 \end_inset
10319
10320 dpl
10321 \begin_inset Quotes erd
10322 \end_inset
10323
10324  for One bye parameter,
10325 \begin_inset Quotes eld
10326 \end_inset
10327
10328 dptr
10329 \begin_inset Quotes erd
10330 \end_inset
10331
10332  if two bytes,
10333 \begin_inset Quotes eld
10334 \end_inset
10335
10336 b,dptr
10337 \begin_inset Quotes erd
10338 \end_inset
10339
10340  for three bytes and
10341 \begin_inset Quotes eld
10342 \end_inset
10343
10344 acc,b,dptr
10345 \begin_inset Quotes erd
10346 \end_inset
10347
10348  for four bytes, the variable name for the second parameter will be _<function_n
10349 ame>_PARM_2.
10350 \newline
10351
10352 \newline
10353 Assemble the assembler routine with the following command:
10354 \newline
10355
10356 \newline
10357
10358 \family sans
10359 \series bold
10360 asx8051 -losg asmfunc.asm
10361 \newline
10362
10363 \newline
10364
10365 \family default
10366 \series default
10367 Then compile and link the assembler routine to the C source file with the
10368  following command:
10369 \newline
10370
10371 \newline
10372
10373 \family sans
10374 \series bold
10375 sdcc cfunc.c asmfunc.rel
10376 \layout Subsubsection
10377
10378 Assembler Routine(reentrant
10379 \begin_inset LatexCommand \index{reentrant}
10380
10381 \end_inset
10382
10383 )
10384 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
10385
10386 \end_inset
10387
10388
10389 \layout Standard
10390
10391 In this case the second parameter onwards will be passed on the stack, the
10392  parameters are pushed from right to left i.e.
10393  after the call the left most parameter will be on the top of the stack.
10394  Here is an example:
10395 \layout Verse
10396
10397
10398 \family typewriter
10399 extern int asm_func(unsigned char, unsigned char);
10400 \newline
10401
10402 \newline
10403 int c_func (unsigned char i, unsigned char j) reentrant
10404 \newline
10405 {
10406 \newline
10407 \SpecialChar ~
10408 \SpecialChar ~
10409 \SpecialChar ~
10410 \SpecialChar ~
10411 return asm_func(i,j);
10412 \newline
10413 }
10414 \newline
10415
10416 \newline
10417 int main()
10418 \newline
10419 {
10420 \newline
10421 \SpecialChar ~
10422 \SpecialChar ~
10423 \SpecialChar ~
10424 \SpecialChar ~
10425 return c_func(10,9);
10426 \newline
10427 }
10428 \layout Standard
10429
10430 The corresponding assembler routine is:
10431 \layout Verse
10432
10433
10434 \family typewriter
10435 .globl _asm_func
10436 \newline
10437 _asm_func:
10438 \newline
10439 \SpecialChar ~
10440 \SpecialChar ~
10441 \SpecialChar ~
10442 \SpecialChar ~
10443 push  _bp
10444 \newline
10445 \SpecialChar ~
10446 \SpecialChar ~
10447 \SpecialChar ~
10448 \SpecialChar ~
10449 mov _bp,sp
10450 \newline
10451 \SpecialChar ~
10452 \SpecialChar ~
10453 \SpecialChar ~
10454 \SpecialChar ~
10455 mov  r2,dpl
10456 \newline
10457 \SpecialChar ~
10458 \SpecialChar ~
10459 \SpecialChar ~
10460 \SpecialChar ~
10461 mov  a,_bp
10462 \newline
10463 \SpecialChar ~
10464 \SpecialChar ~
10465 \SpecialChar ~
10466 \SpecialChar ~
10467 clr  c
10468 \newline
10469 \SpecialChar ~
10470 \SpecialChar ~
10471 \SpecialChar ~
10472 \SpecialChar ~
10473 add  a,#0xfd
10474 \newline
10475 \SpecialChar ~
10476 \SpecialChar ~
10477 \SpecialChar ~
10478 \SpecialChar ~
10479 mov  r0,a
10480 \newline
10481 \SpecialChar ~
10482 \SpecialChar ~
10483 \SpecialChar ~
10484 \SpecialChar ~
10485 add  a,#0xfc
10486 \newline
10487 \SpecialChar ~
10488 \SpecialChar ~
10489 \SpecialChar ~
10490 \SpecialChar ~
10491 mov  r1,a
10492 \newline
10493 \SpecialChar ~
10494 \SpecialChar ~
10495 \SpecialChar ~
10496 \SpecialChar ~
10497 mov  a,@r0
10498 \newline
10499 \SpecialChar ~
10500 \SpecialChar ~
10501 \SpecialChar ~
10502 \SpecialChar ~
10503 add  a,r2
10504 \newline
10505 \SpecialChar ~
10506 \SpecialChar ~
10507 \SpecialChar ~
10508 \SpecialChar ~
10509 mov  dpl,a
10510 \newline
10511 \SpecialChar ~
10512 \SpecialChar ~
10513 \SpecialChar ~
10514 \SpecialChar ~
10515 mov  dph,#0x00
10516 \newline
10517 \SpecialChar ~
10518 \SpecialChar ~
10519 \SpecialChar ~
10520 \SpecialChar ~
10521 mov  sp,_bp
10522 \newline
10523 \SpecialChar ~
10524 \SpecialChar ~
10525 \SpecialChar ~
10526 \SpecialChar ~
10527 pop  _bp
10528 \newline
10529 \SpecialChar ~
10530 \SpecialChar ~
10531 \SpecialChar ~
10532 \SpecialChar ~
10533 ret
10534 \layout Standard
10535
10536 The compiling and linking procedure remains the same, however note the extra
10537  entry & exit linkage required for the assembler code, _bp is the stack
10538  frame pointer and is used to compute the offset into the stack for parameters
10539  and local variables.
10540 \layout Subsection
10541
10542 int (16 bit)
10543 \begin_inset LatexCommand \index{int (16 bit)}
10544
10545 \end_inset
10546
10547  and long (32 bit)
10548 \begin_inset LatexCommand \index{long (32 bit)}
10549
10550 \end_inset
10551
10552  Support
10553 \layout Standard
10554
10555 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
10556  multiplication and modulus operations are implemented by support routines.
10557  These support routines are all developed in ANSI-C to facilitate porting
10558  to other MCUs, although some model specific assembler optimizations are
10559  used.
10560  The following files contain the described routines, all of them can be
10561  found in <installdir>/share/sdcc/lib.
10562 \newline
10563
10564 \layout Standard
10565 \align center
10566
10567 \begin_inset  Tabular
10568 <lyxtabular version="3" rows="11" columns="2">
10569 <features>
10570 <column alignment="center" valignment="top" leftline="true" width="0">
10571 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
10572 <row topline="true" bottomline="true">
10573 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10574 \begin_inset Text
10575
10576 \layout Standard
10577
10578
10579 \series bold
10580 Function
10581 \end_inset
10582 </cell>
10583 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10584 \begin_inset Text
10585
10586 \layout Standard
10587
10588
10589 \series bold
10590 Description
10591 \end_inset
10592 </cell>
10593 </row>
10594 <row topline="true">
10595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10596 \begin_inset Text
10597
10598 \layout Standard
10599
10600 _mulint.c
10601 \end_inset
10602 </cell>
10603 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10604 \begin_inset Text
10605
10606 \layout Standard
10607
10608 16 bit multiplication
10609 \end_inset
10610 </cell>
10611 </row>
10612 <row topline="true">
10613 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10614 \begin_inset Text
10615
10616 \layout Standard
10617
10618 _divsint.c
10619 \end_inset
10620 </cell>
10621 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10622 \begin_inset Text
10623
10624 \layout Standard
10625
10626  signed 16 bit division (calls _divuint)
10627 \end_inset
10628 </cell>
10629 </row>
10630 <row topline="true">
10631 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10632 \begin_inset Text
10633
10634 \layout Standard
10635
10636 _divuint.c
10637 \end_inset
10638 </cell>
10639 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10640 \begin_inset Text
10641
10642 \layout Standard
10643
10644  unsigned 16 bit division
10645 \end_inset
10646 </cell>
10647 </row>
10648 <row topline="true">
10649 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10650 \begin_inset Text
10651
10652 \layout Standard
10653
10654 _modsint.c
10655 \end_inset
10656 </cell>
10657 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10658 \begin_inset Text
10659
10660 \layout Standard
10661
10662 signed 16 bit modulus (calls _moduint)
10663 \end_inset
10664 </cell>
10665 </row>
10666 <row topline="true">
10667 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10668 \begin_inset Text
10669
10670 \layout Standard
10671
10672 _moduint.c
10673 \end_inset
10674 </cell>
10675 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10676 \begin_inset Text
10677
10678 \layout Standard
10679
10680 unsigned 16 bit modulus
10681 \end_inset
10682 </cell>
10683 </row>
10684 <row topline="true">
10685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10686 \begin_inset Text
10687
10688 \layout Standard
10689
10690 _mullong.c
10691 \end_inset
10692 </cell>
10693 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10694 \begin_inset Text
10695
10696 \layout Standard
10697
10698 32 bit multiplication
10699 \end_inset
10700 </cell>
10701 </row>
10702 <row topline="true">
10703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10704 \begin_inset Text
10705
10706 \layout Standard
10707
10708 _divslong.c
10709 \end_inset
10710 </cell>
10711 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10712 \begin_inset Text
10713
10714 \layout Standard
10715
10716  signed 32 division (calls _divulong)
10717 \end_inset
10718 </cell>
10719 </row>
10720 <row topline="true">
10721 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10722 \begin_inset Text
10723
10724 \layout Standard
10725
10726 _divulong.c
10727 \end_inset
10728 </cell>
10729 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10730 \begin_inset Text
10731
10732 \layout Standard
10733
10734 unsigned 32 division
10735 \end_inset
10736 </cell>
10737 </row>
10738 <row topline="true">
10739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10740 \begin_inset Text
10741
10742 \layout Standard
10743
10744 _modslong.c
10745 \end_inset
10746 </cell>
10747 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10748 \begin_inset Text
10749
10750 \layout Standard
10751
10752  signed 32 bit modulus (calls _modulong)
10753 \end_inset
10754 </cell>
10755 </row>
10756 <row topline="true" bottomline="true">
10757 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10758 \begin_inset Text
10759
10760 \layout Standard
10761
10762 _modulong.c
10763 \end_inset
10764 </cell>
10765 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10766 \begin_inset Text
10767
10768 \layout Standard
10769
10770 unsigned 32 bit modulus
10771 \end_inset
10772 </cell>
10773 </row>
10774 </lyxtabular>
10775
10776 \end_inset
10777
10778
10779 \newline
10780
10781 \layout Standard
10782
10783 Since they are compiled as
10784 \emph on
10785 non-reentrant
10786 \emph default
10787
10788 \begin_inset LatexCommand \index{reentrant}
10789
10790 \end_inset
10791
10792 , interrupt
10793 \begin_inset LatexCommand \index{interrupt}
10794
10795 \end_inset
10796
10797  service routines should not do any of the above operations.
10798  If this is unavoidable then the above routines will need to be compiled
10799  with the
10800 \emph on
10801 -
10802 \begin_inset ERT
10803 status Collapsed
10804
10805 \layout Standard
10806
10807 \backslash
10808 /
10809 \end_inset
10810
10811 -stack-auto
10812 \begin_inset LatexCommand \index{-\/-stack-auto}
10813
10814 \end_inset
10815
10816
10817 \emph default
10818  option, after which the source program will have to be compiled with
10819 \emph on
10820 -
10821 \begin_inset ERT
10822 status Collapsed
10823
10824 \layout Standard
10825
10826 \backslash
10827 /
10828 \end_inset
10829
10830 -int-long-rent
10831 \begin_inset LatexCommand \index{-\/-int-long-rent}
10832
10833 \end_inset
10834
10835
10836 \emph default
10837  option.
10838  Notice that you don't have to call this routines directly.
10839  The compiler will use them automatically every time an integer operation
10840  is required.
10841 \layout Subsection
10842
10843 Floating Point Support
10844 \begin_inset LatexCommand \index{Floating point support}
10845
10846 \end_inset
10847
10848
10849 \layout Standard
10850
10851 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
10852  floating point support routines are derived from gcc's floatlib.c and consist
10853  of the following routines:
10854 \newline
10855
10856 \layout Standard
10857 \align center
10858
10859 \size footnotesize
10860
10861 \begin_inset  Tabular
10862 <lyxtabular version="3" rows="17" columns="2">
10863 <features>
10864 <column alignment="center" valignment="top" leftline="true" width="0">
10865 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
10866 <row topline="true" bottomline="true">
10867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10868 \begin_inset Text
10869
10870 \layout Standard
10871
10872
10873 \family roman
10874 \series medium
10875 \shape up
10876 \size normal
10877 \emph off
10878 \bar no
10879 \noun off
10880 \color none
10881 Function
10882 \end_inset
10883 </cell>
10884 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10885 \begin_inset Text
10886
10887 \layout Standard
10888
10889 Description
10890 \end_inset
10891 </cell>
10892 </row>
10893 <row topline="true">
10894 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10895 \begin_inset Text
10896
10897 \layout Standard
10898
10899
10900 \family roman
10901 \series medium
10902 \shape up
10903 \size normal
10904 \emph off
10905 \bar no
10906 \noun off
10907 \color none
10908 _fsadd.c
10909 \end_inset
10910 </cell>
10911 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10912 \begin_inset Text
10913
10914 \layout Standard
10915
10916
10917 \family roman
10918 \series medium
10919 \shape up
10920 \size normal
10921 \emph off
10922 \bar no
10923 \noun off
10924 \color none
10925 add floating point numbers
10926 \end_inset
10927 </cell>
10928 </row>
10929 <row topline="true">
10930 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10931 \begin_inset Text
10932
10933 \layout Standard
10934
10935
10936 \family roman
10937 \series medium
10938 \shape up
10939 \size normal
10940 \emph off
10941 \bar no
10942 \noun off
10943 \color none
10944 _fssub.c
10945 \end_inset
10946 </cell>
10947 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10948 \begin_inset Text
10949
10950 \layout Standard
10951
10952
10953 \family roman
10954 \series medium
10955 \shape up
10956 \size normal
10957 \emph off
10958 \bar no
10959 \noun off
10960 \color none
10961 subtract floating point numbers
10962 \end_inset
10963 </cell>
10964 </row>
10965 <row topline="true">
10966 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10967 \begin_inset Text
10968
10969 \layout Standard
10970
10971
10972 \family roman
10973 \series medium
10974 \shape up
10975 \size normal
10976 \emph off
10977 \bar no
10978 \noun off
10979 \color none
10980 _fsdiv.c
10981 \end_inset
10982 </cell>
10983 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10984 \begin_inset Text
10985
10986 \layout Standard
10987
10988
10989 \family roman
10990 \series medium
10991 \shape up
10992 \size normal
10993 \emph off
10994 \bar no
10995 \noun off
10996 \color none
10997 divide floating point numbers
10998 \end_inset
10999 </cell>
11000 </row>
11001 <row topline="true">
11002 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11003 \begin_inset Text
11004
11005 \layout Standard
11006
11007
11008 \family roman
11009 \series medium
11010 \shape up
11011 \size normal
11012 \emph off
11013 \bar no
11014 \noun off
11015 \color none
11016 _fsmul.c
11017 \end_inset
11018 </cell>
11019 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11020 \begin_inset Text
11021
11022 \layout Standard
11023
11024
11025 \family roman
11026 \series medium
11027 \shape up
11028 \size normal
11029 \emph off
11030 \bar no
11031 \noun off
11032 \color none
11033 multiply floating point numbers
11034 \end_inset
11035 </cell>
11036 </row>
11037 <row topline="true">
11038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11039 \begin_inset Text
11040
11041 \layout Standard
11042
11043
11044 \family roman
11045 \series medium
11046 \shape up
11047 \size normal
11048 \emph off
11049 \bar no
11050 \noun off
11051 \color none
11052 _fs2uchar.c
11053 \end_inset
11054 </cell>
11055 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11056 \begin_inset Text
11057
11058 \layout Standard
11059
11060
11061 \family roman
11062 \series medium
11063 \shape up
11064 \size normal
11065 \emph off
11066 \bar no
11067 \noun off
11068 \color none
11069 convert floating point to unsigned char
11070 \end_inset
11071 </cell>
11072 </row>
11073 <row topline="true">
11074 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11075 \begin_inset Text
11076
11077 \layout Standard
11078
11079
11080 \family roman
11081 \series medium
11082 \shape up
11083 \size normal
11084 \emph off
11085 \bar no
11086 \noun off
11087 \color none
11088 _fs2char.c
11089 \end_inset
11090 </cell>
11091 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11092 \begin_inset Text
11093
11094 \layout Standard
11095
11096
11097 \family roman
11098 \series medium
11099 \shape up
11100 \size normal
11101 \emph off
11102 \bar no
11103 \noun off
11104 \color none
11105 convert floating point to signed char
11106 \end_inset
11107 </cell>
11108 </row>
11109 <row topline="true">
11110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11111 \begin_inset Text
11112
11113 \layout Standard
11114
11115
11116 \family roman
11117 \series medium
11118 \shape up
11119 \size normal
11120 \emph off
11121 \bar no
11122 \noun off
11123 \color none
11124 _fs2uint.c
11125 \end_inset
11126 </cell>
11127 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11128 \begin_inset Text
11129
11130 \layout Standard
11131
11132
11133 \family roman
11134 \series medium
11135 \shape up
11136 \size normal
11137 \emph off
11138 \bar no
11139 \noun off
11140 \color none
11141 convert floating point to unsigned int
11142 \end_inset
11143 </cell>
11144 </row>
11145 <row topline="true">
11146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11147 \begin_inset Text
11148
11149 \layout Standard
11150
11151
11152 \family roman
11153 \series medium
11154 \shape up
11155 \size normal
11156 \emph off
11157 \bar no
11158 \noun off
11159 \color none
11160 _fs2int.c
11161 \end_inset
11162 </cell>
11163 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11164 \begin_inset Text
11165
11166 \layout Standard
11167
11168
11169 \family roman
11170 \series medium
11171 \shape up
11172 \size normal
11173 \emph off
11174 \bar no
11175 \noun off
11176 \color none
11177 convert floating point to signed int
11178 \end_inset
11179 </cell>
11180 </row>
11181 <row topline="true">
11182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11183 \begin_inset Text
11184
11185 \layout Standard
11186
11187
11188 \family roman
11189 \series medium
11190 \shape up
11191 \size normal
11192 \emph off
11193 \bar no
11194 \noun off
11195 \color none
11196 _fs2ulong.
11197 \family default
11198 \series default
11199 \shape default
11200 \size default
11201 \emph default
11202 \bar default
11203 \noun default
11204 \color default
11205 c
11206 \end_inset
11207 </cell>
11208 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11209 \begin_inset Text
11210
11211 \layout Standard
11212
11213
11214 \family roman
11215 \series medium
11216 \shape up
11217 \size normal
11218 \emph off
11219 \bar no
11220 \noun off
11221 \color none
11222 convert floating point to unsigned long
11223 \end_inset
11224 </cell>
11225 </row>
11226 <row topline="true">
11227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11228 \begin_inset Text
11229
11230 \layout Standard
11231
11232
11233 \family roman
11234 \series medium
11235 \shape up
11236 \size normal
11237 \emph off
11238 \bar no
11239 \noun off
11240 \color none
11241 _fs2long.c
11242 \end_inset
11243 </cell>
11244 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11245 \begin_inset Text
11246
11247 \layout Standard
11248
11249
11250 \family roman
11251 \series medium
11252 \shape up
11253 \size normal
11254 \emph off
11255 \bar no
11256 \noun off
11257 \color none
11258 convert floating point to signed long
11259 \end_inset
11260 </cell>
11261 </row>
11262 <row topline="true">
11263 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11264 \begin_inset Text
11265
11266 \layout Standard
11267
11268
11269 \family roman
11270 \series medium
11271 \shape up
11272 \size normal
11273 \emph off
11274 \bar no
11275 \noun off
11276 \color none
11277 _uchar2fs.c
11278 \end_inset
11279 </cell>
11280 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11281 \begin_inset Text
11282
11283 \layout Standard
11284
11285
11286 \family roman
11287 \series medium
11288 \shape up
11289 \size normal
11290 \emph off
11291 \bar no
11292 \noun off
11293 \color none
11294 convert unsigned char to floating point
11295 \end_inset
11296 </cell>
11297 </row>
11298 <row topline="true">
11299 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11300 \begin_inset Text
11301
11302 \layout Standard
11303
11304
11305 \family roman
11306 \series medium
11307 \shape up
11308 \size normal
11309 \emph off
11310 \bar no
11311 \noun off
11312 \color none
11313 _char2fs.c
11314 \end_inset
11315 </cell>
11316 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11317 \begin_inset Text
11318
11319 \layout Standard
11320
11321
11322 \family roman
11323 \series medium
11324 \shape up
11325 \size normal
11326 \emph off
11327 \bar no
11328 \noun off
11329 \color none
11330 convert char to floating point number
11331 \end_inset
11332 </cell>
11333 </row>
11334 <row topline="true">
11335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11336 \begin_inset Text
11337
11338 \layout Standard
11339
11340
11341 \family roman
11342 \series medium
11343 \shape up
11344 \size normal
11345 \emph off
11346 \bar no
11347 \noun off
11348 \color none
11349 _uint2fs.c
11350 \end_inset
11351 </cell>
11352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11353 \begin_inset Text
11354
11355 \layout Standard
11356
11357
11358 \family roman
11359 \series medium
11360 \shape up
11361 \size normal
11362 \emph off
11363 \bar no
11364 \noun off
11365 \color none
11366 convert unsigned int to floating point
11367 \end_inset
11368 </cell>
11369 </row>
11370 <row topline="true">
11371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11372 \begin_inset Text
11373
11374 \layout Standard
11375
11376
11377 \family roman
11378 \series medium
11379 \shape up
11380 \size normal
11381 \emph off
11382 \bar no
11383 \noun off
11384 \color none
11385 _int2fs.c
11386 \end_inset
11387 </cell>
11388 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11389 \begin_inset Text
11390
11391 \layout Standard
11392
11393
11394 \family roman
11395 \series medium
11396 \shape up
11397 \size normal
11398 \emph off
11399 \bar no
11400 \noun off
11401 \color none
11402 convert int to floating point numbers
11403 \end_inset
11404 </cell>
11405 </row>
11406 <row topline="true">
11407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11408 \begin_inset Text
11409
11410 \layout Standard
11411
11412
11413 \family roman
11414 \series medium
11415 \shape up
11416 \size normal
11417 \emph off
11418 \bar no
11419 \noun off
11420 \color none
11421 _ulong2fs.c
11422 \end_inset
11423 </cell>
11424 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11425 \begin_inset Text
11426
11427 \layout Standard
11428
11429
11430 \family roman
11431 \series medium
11432 \shape up
11433 \size normal
11434 \emph off
11435 \bar no
11436 \noun off
11437 \color none
11438 convert unsigned long to floating point number
11439 \end_inset
11440 </cell>
11441 </row>
11442 <row topline="true" bottomline="true">
11443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11444 \begin_inset Text
11445
11446 \layout Standard
11447
11448
11449 \family roman
11450 \series medium
11451 \shape up
11452 \size normal
11453 \emph off
11454 \bar no
11455 \noun off
11456 \color none
11457 _long2fs.c
11458 \end_inset
11459 </cell>
11460 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11461 \begin_inset Text
11462
11463 \layout Standard
11464
11465
11466 \family roman
11467 \series medium
11468 \shape up
11469 \size normal
11470 \emph off
11471 \bar no
11472 \noun off
11473 \color none
11474 convert long to floating point number
11475 \end_inset
11476 </cell>
11477 </row>
11478 </lyxtabular>
11479
11480 \end_inset
11481
11482
11483 \newline
11484
11485 \layout Standard
11486
11487 Note if all these routines are used simultaneously the data space might
11488  overflow.
11489  For serious floating point usage it is strongly recommended that the large
11490  model be used.
11491  Also notice that you don't have to call this routines directly.
11492  The compiler will use them automatically every time a floating point operation
11493  is required.
11494 \layout Subsection
11495
11496 MCS51 Memory Models
11497 \begin_inset LatexCommand \index{Memory model}
11498
11499 \end_inset
11500
11501
11502 \begin_inset LatexCommand \index{MCS51 memory}
11503
11504 \end_inset
11505
11506
11507 \layout Standard
11508
11509 SDCC allows two memory models for MCS51 code,
11510 \shape slanted
11511 small
11512 \shape default
11513  and
11514 \shape slanted
11515 large
11516 \shape default
11517 .
11518  Modules compiled with different memory models should
11519 \emph on
11520 never
11521 \emph default
11522  be combined together or the results would be unpredictable.
11523  The library routines supplied with the compiler are compiled as both small
11524  and large.
11525  The compiled library modules are contained in separate directories as small
11526  and large so that you can link to either set.
11527
11528 \layout Standard
11529
11530 When the large model is used all variables declared without a storage class
11531  will be allocated into the external ram, this includes all parameters and
11532  local variables (for non-reentrant
11533 \begin_inset LatexCommand \index{reentrant}
11534
11535 \end_inset
11536
11537  functions).
11538  When the small model is used variables without storage class are allocated
11539  in the internal ram.
11540 \layout Standard
11541
11542 Judicious usage of the processor specific storage classes
11543 \begin_inset LatexCommand \index{Storage class}
11544
11545 \end_inset
11546
11547  and the 'reentrant' function type will yield much more efficient code,
11548  than using the large model.
11549  Several optimizations are disabled when the program is compiled using the
11550  large model, it is therefore strongly recommended that the small model
11551  be used unless absolutely required.
11552 \layout Subsection
11553
11554 DS390 Memory Models
11555 \begin_inset LatexCommand \index{Memory model}
11556
11557 \end_inset
11558
11559
11560 \begin_inset LatexCommand \index{DS390 memory model}
11561
11562 \end_inset
11563
11564
11565 \layout Standard
11566
11567 The only model supported is Flat 24
11568 \begin_inset LatexCommand \index{Flat 24 (memory model)}
11569
11570 \end_inset
11571
11572 .
11573  This generates code for the 24 bit contiguous addressing mode of the Dallas
11574  DS80C390 part.
11575  In this mode, up to four meg of external RAM or code space can be directly
11576  addressed.
11577  See the data sheets at www.dalsemi.com for further information on this part.
11578 \newline
11579
11580 \newline
11581 Note that the compiler does not generate any code to place the processor
11582  into 24 bitmode (although
11583 \emph on
11584 tinibios
11585 \emph default
11586  in the ds390 libraries will do that for you).
11587  If you don't use
11588 \emph on
11589 tinibios
11590 \emph default
11591
11592 \begin_inset LatexCommand \index{Tinibios (DS390)}
11593
11594 \end_inset
11595
11596 , the boot loader or similar code must ensure that the processor is in 24
11597  bit contiguous addressing mode before calling the SDCC startup code.
11598 \newline
11599
11600 \newline
11601 Like the
11602 \emph on
11603 -
11604 \begin_inset ERT
11605 status Collapsed
11606
11607 \layout Standard
11608
11609 \backslash
11610 /
11611 \end_inset
11612
11613 -model-large
11614 \emph default
11615  option, variables will by default be placed into the XDATA segment.
11616
11617 \newline
11618
11619 \newline
11620 Segments may be placed anywhere in the 4 meg address space using the usual
11621  -
11622 \begin_inset ERT
11623 status Collapsed
11624
11625 \layout Standard
11626
11627 \backslash
11628 /
11629 \end_inset
11630
11631 -*-loc options.
11632  Note that if any segments are located above 64K, the -r flag must be passed
11633  to the linker to generate the proper segment relocations, and the Intel
11634  HEX output format must be used.
11635  The -r flag can be passed to the linker by using the option
11636 \emph on
11637 -Wl-r
11638 \emph default
11639  on the SDCC command line.
11640  However, currently the linker can not handle code segments > 64k.
11641 \layout Subsection
11642
11643 Pragmas
11644 \begin_inset LatexCommand \index{Pragmas}
11645
11646 \end_inset
11647
11648
11649 \layout Standard
11650
11651 SDCC supports the following #pragma directives.
11652 \layout Itemize
11653
11654 SAVE
11655 \begin_inset LatexCommand \index{\#pragma SAVE}
11656
11657 \end_inset
11658
11659  - this will save all current options to the SAVE/RESTORE stack.
11660  See RESTORE.
11661 \layout Itemize
11662
11663 RESTORE
11664 \begin_inset LatexCommand \index{\#pragma RESTORE}
11665
11666 \end_inset
11667
11668  - will restore saved options from the last save.
11669  SAVEs & RESTOREs can be nested.
11670  SDCC uses a SAVE/RESTORE stack: SAVE pushes current options to the stack,
11671  RESTORE pulls current options from the stack.
11672  See SAVE.
11673 \layout Itemize
11674
11675 NOGCSE
11676 \begin_inset LatexCommand \index{\#pragma NOGCSE}
11677
11678 \end_inset
11679
11680  - will stop global common subexpression elimination.
11681 \layout Itemize
11682
11683 NOINDUCTION
11684 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
11685
11686 \end_inset
11687
11688  - will stop loop induction optimizations.
11689 \layout Itemize
11690
11691 NOJTBOUND
11692 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
11693
11694 \end_inset
11695
11696  - will not generate code for boundary value checking, when switch statements
11697  are turned into jump-tables (dangerous).
11698  For more details see section
11699 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
11700
11701 \end_inset
11702
11703 .
11704 \layout Itemize
11705
11706 NOOVERLAY
11707 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
11708
11709 \end_inset
11710
11711  - the compiler will not overlay the parameters and local variables of a
11712  function.
11713 \layout Itemize
11714
11715 LESS_PEDANTIC
11716 \begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
11717
11718 \end_inset
11719
11720  - the compiler will not warn you anymore for obvious mistakes, you'r on
11721  your own now ;-(
11722 \layout Itemize
11723
11724 NOLOOPREVERSE
11725 \begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
11726
11727 \end_inset
11728
11729  - Will not do loop reversal optimization
11730 \layout Itemize
11731
11732 EXCLUDE
11733 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
11734
11735 \end_inset
11736
11737  NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
11738  pair of push/pop
11739 \begin_inset LatexCommand \index{push/pop}
11740
11741 \end_inset
11742
11743  instruction in ISR function (using interrupt
11744 \begin_inset LatexCommand \index{interrupt}
11745
11746 \end_inset
11747
11748  keyword).
11749  The directive should be placed immediately before the ISR function definition
11750  and it affects ALL ISR functions following it.
11751  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
11752 EXCLUDE\SpecialChar ~
11753 none
11754 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
11755
11756 \end_inset
11757
11758 .
11759 \layout Itemize
11760
11761 NOIV
11762 \begin_inset LatexCommand \index{\#pragma NOIV}
11763
11764 \end_inset
11765
11766  - Do not generate interrupt vector table entries for all ISR functions
11767  defined after the pragma.
11768  This is useful in cases where the interrupt vector table must be defined
11769  manually, or when there is a secondary, manually defined interrupt vector
11770  table (e.g.
11771  for the autovector feature of the Cypress EZ-USB FX2).
11772  More elegantly this can be achieved by obmitting the optional interrupt
11773  number after the interrupt keyword, see section
11774 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
11775
11776 \end_inset
11777
11778 \SpecialChar ~
11779 about interrupts.
11780 \layout Itemize
11781
11782 CALLEE-SAVES
11783 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
11784
11785 \end_inset
11786
11787
11788 \begin_inset LatexCommand \index{function prologue}
11789
11790 \end_inset
11791
11792  function1[,function2[,function3...]] - The compiler by default uses a caller
11793  saves convention for register saving across function calls, however this
11794  can cause unnecessary register pushing & popping when calling small functions
11795  from larger functions.
11796  This option can be used to switch off the register saving convention for
11797  the function names specified.
11798  The compiler will not save registers when calling these functions, extra
11799  code need to be manually inserted at the entry & exit for these functions
11800  to save & restore the registers used by these functions, this can SUBSTANTIALLY
11801  reduce code & improve run time performance of the generated code.
11802  In the future the compiler (with inter procedural analysis) may be able
11803  to determine the appropriate scheme to use for each function call.
11804  If -
11805 \begin_inset ERT
11806 status Collapsed
11807
11808 \layout Standard
11809
11810 \backslash
11811 /
11812 \end_inset
11813
11814 -callee-saves command line option is used, the function names specified
11815  in #pragma\SpecialChar ~
11816 CALLEE-SAVES
11817 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
11818
11819 \end_inset
11820
11821  is appended to the list of functions specified in the command line.
11822 \layout Standard
11823
11824 The pragma's are intended to be used to turn-on or off certain optimizations
11825  which might cause the compiler to generate extra stack / data space to
11826  store compiler generated temporary variables.
11827  This usually happens in large functions.
11828  Pragma directives should be used as shown in the following example, they
11829  are used to control options & optimizations for a given function; pragmas
11830  should be placed before and/or after a function, placing pragma's inside
11831  a function body could have unpredictable results.
11832 \layout Verse
11833
11834
11835 \family typewriter
11836 #pragma SAVE
11837 \begin_inset LatexCommand \index{\#pragma SAVE}
11838
11839 \end_inset
11840
11841  \SpecialChar ~
11842 \SpecialChar ~
11843 \SpecialChar ~
11844 \SpecialChar ~
11845 \SpecialChar ~
11846 \SpecialChar ~
11847 \SpecialChar ~
11848 /* save the current settings */
11849 \newline
11850 #pragma NOGCSE
11851 \begin_inset LatexCommand \index{\#pragma NOGCSE}
11852
11853 \end_inset
11854
11855  \SpecialChar ~
11856 \SpecialChar ~
11857 \SpecialChar ~
11858 \SpecialChar ~
11859 \SpecialChar ~
11860 /* turnoff global subexpression elimination */
11861 \newline
11862 #pragma NOINDUCTION
11863 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
11864
11865 \end_inset
11866
11867  /* turn off induction optimizations */
11868 \newline
11869 int foo ()
11870 \newline
11871 {
11872 \newline
11873 \SpecialChar ~
11874  \SpecialChar ~
11875  ...
11876
11877 \newline
11878 \SpecialChar ~
11879  \SpecialChar ~
11880  /* large code */
11881 \newline
11882 \SpecialChar ~
11883  \SpecialChar ~
11884  ...
11885
11886 \newline
11887 }
11888 \newline
11889 #pragma RESTORE
11890 \begin_inset LatexCommand \index{\#pragma RESTORE}
11891
11892 \end_inset
11893
11894  /* turn the optimizations back on */
11895 \layout Standard
11896
11897 The compiler will generate a warning message when extra space is allocated.
11898  It is strongly recommended that the SAVE and RESTORE pragma's be used when
11899  changing options for a function.
11900 \layout Subsection
11901
11902 Defines Created by the Compiler
11903 \begin_inset LatexCommand \index{Defines created by the compiler}
11904
11905 \end_inset
11906
11907
11908 \layout Standard
11909
11910 The compiler creates the following #defines
11911 \begin_inset LatexCommand \index{\#defines}
11912
11913 \end_inset
11914
11915 :
11916 \newline
11917
11918 \layout Standard
11919
11920
11921 \begin_inset  Tabular
11922 <lyxtabular version="3" rows="10" columns="2">
11923 <features>
11924 <column alignment="center" valignment="top" leftline="true" width="0">
11925 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
11926 <row topline="true" bottomline="true">
11927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11928 \begin_inset Text
11929
11930 \layout Standard
11931
11932
11933 \series bold
11934 #define
11935 \end_inset
11936 </cell>
11937 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11938 \begin_inset Text
11939
11940 \layout Standard
11941
11942
11943 \series bold
11944 Description
11945 \end_inset
11946 </cell>
11947 </row>
11948 <row topline="true">
11949 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11950 \begin_inset Text
11951
11952 \layout Standard
11953
11954 SDCC
11955 \begin_inset LatexCommand \index{SDCC}
11956
11957 \end_inset
11958
11959
11960 \end_inset
11961 </cell>
11962 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11963 \begin_inset Text
11964
11965 \layout Standard
11966
11967 this Symbol is always defined
11968 \end_inset
11969 </cell>
11970 </row>
11971 <row topline="true">
11972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11973 \begin_inset Text
11974
11975 \layout Standard
11976
11977 SDCC_mcs51
11978 \begin_inset LatexCommand \index{SDCC\_mcs51}
11979
11980 \end_inset
11981
11982  or SDCC_ds390
11983 \begin_inset LatexCommand \index{SDCC\_ds390}
11984
11985 \end_inset
11986
11987  or SDCC_z80
11988 \begin_inset LatexCommand \index{SDCC\_z80}
11989
11990 \end_inset
11991
11992 , etc
11993 \end_inset
11994 </cell>
11995 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11996 \begin_inset Text
11997
11998 \layout Standard
11999
12000 depending on the model used (e.g.: -mds390
12001 \end_inset
12002 </cell>
12003 </row>
12004 <row topline="true">
12005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12006 \begin_inset Text
12007
12008 \layout Standard
12009
12010 __mcs51
12011 \begin_inset LatexCommand \index{\_\_mcs51}
12012
12013 \end_inset
12014
12015  or __ds390
12016 \begin_inset LatexCommand \index{\_\_ds390}
12017
12018 \end_inset
12019
12020  or __z80
12021 \begin_inset LatexCommand \index{\_\_z80}
12022
12023 \end_inset
12024
12025 , etc
12026 \end_inset
12027 </cell>
12028 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12029 \begin_inset Text
12030
12031 \layout Standard
12032
12033 depending on the model used (e.g.
12034  -mz80)
12035 \end_inset
12036 </cell>
12037 </row>
12038 <row topline="true">
12039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12040 \begin_inset Text
12041
12042 \layout Standard
12043
12044 SDCC_STACK_AUTO
12045 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
12046
12047 \end_inset
12048
12049
12050 \end_inset
12051 </cell>
12052 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12053 \begin_inset Text
12054
12055 \layout Standard
12056
12057 when
12058 \emph on
12059 -
12060 \begin_inset ERT
12061 status Collapsed
12062
12063 \layout Standard
12064
12065 \backslash
12066 /
12067 \end_inset
12068
12069 -stack-auto
12070 \emph default
12071  option is used
12072 \end_inset
12073 </cell>
12074 </row>
12075 <row topline="true">
12076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12077 \begin_inset Text
12078
12079 \layout Standard
12080
12081 SDCC_MODEL_SMALL
12082 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
12083
12084 \end_inset
12085
12086
12087 \end_inset
12088 </cell>
12089 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12090 \begin_inset Text
12091
12092 \layout Standard
12093
12094 when
12095 \emph on
12096 -
12097 \begin_inset ERT
12098 status Collapsed
12099
12100 \layout Standard
12101
12102 \backslash
12103 /
12104 \end_inset
12105
12106 -model-small
12107 \emph default
12108  is used
12109 \end_inset
12110 </cell>
12111 </row>
12112 <row topline="true">
12113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12114 \begin_inset Text
12115
12116 \layout Standard
12117
12118 SDCC_MODEL_LARGE
12119 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
12120
12121 \end_inset
12122
12123
12124 \end_inset
12125 </cell>
12126 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12127 \begin_inset Text
12128
12129 \layout Standard
12130
12131 when
12132 \emph on
12133 -
12134 \begin_inset ERT
12135 status Collapsed
12136
12137 \layout Standard
12138
12139 \backslash
12140 /
12141 \end_inset
12142
12143 -model-large
12144 \emph default
12145  is used
12146 \end_inset
12147 </cell>
12148 </row>
12149 <row topline="true">
12150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12151 \begin_inset Text
12152
12153 \layout Standard
12154
12155 SDCC_USE_XSTACK
12156 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
12157
12158 \end_inset
12159
12160
12161 \end_inset
12162 </cell>
12163 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12164 \begin_inset Text
12165
12166 \layout Standard
12167
12168 when
12169 \emph on
12170 -
12171 \begin_inset ERT
12172 status Collapsed
12173
12174 \layout Standard
12175
12176 \backslash
12177 /
12178 \end_inset
12179
12180 -xstack
12181 \emph default
12182  option is used
12183 \end_inset
12184 </cell>
12185 </row>
12186 <row topline="true">
12187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12188 \begin_inset Text
12189
12190 \layout Standard
12191
12192 SDCC_STACK_TENBIT
12193 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
12194
12195 \end_inset
12196
12197
12198 \end_inset
12199 </cell>
12200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12201 \begin_inset Text
12202
12203 \layout Standard
12204
12205 when
12206 \emph on
12207 -mds390
12208 \emph default
12209  is used
12210 \end_inset
12211 </cell>
12212 </row>
12213 <row topline="true" bottomline="true">
12214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12215 \begin_inset Text
12216
12217 \layout Standard
12218
12219 SDCC_MODEL_FLAT24
12220 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
12221
12222 \end_inset
12223
12224
12225 \end_inset
12226 </cell>
12227 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12228 \begin_inset Text
12229
12230 \layout Standard
12231
12232 when
12233 \emph on
12234 -mds390
12235 \emph default
12236  is used
12237 \end_inset
12238 </cell>
12239 </row>
12240 </lyxtabular>
12241
12242 \end_inset
12243
12244
12245 \newline
12246
12247 \layout Section
12248 \pagebreak_top
12249 Debugging with SDCDB
12250 \begin_inset LatexCommand \index{sdcdb}
12251
12252 \end_inset
12253
12254
12255 \layout Standard
12256
12257 SDCC is distributed with a source level debugger
12258 \begin_inset LatexCommand \index{Debugger}
12259
12260 \end_inset
12261
12262 .
12263  The debugger uses a command line interface, the command repertoire of the
12264  debugger has been kept as close to gdb
12265 \begin_inset LatexCommand \index{gdb}
12266
12267 \end_inset
12268
12269  (the GNU debugger) as possible.
12270  The configuration and build process is part of the standard compiler installati
12271 on, which also builds and installs the debugger in the target directory
12272  specified during configuration.
12273  The debugger allows you debug BOTH at the C source and at the ASM source
12274  level.
12275  Sdcdb is available on Unix platforms only.
12276 \layout Subsection
12277
12278 Compiling for Debugging
12279 \layout Standard
12280
12281 The \SpecialChar \-
12282 \SpecialChar \-
12283 debug option must be specified for all files for which debug information
12284  is to be generated.
12285  The complier generates a .adb file for each of these files.
12286  The linker creates the .cdb file from the .adb files and the address information.
12287  This .cdb is used by the debugger.
12288 \layout Subsection
12289
12290 How the Debugger Works
12291 \layout Standard
12292
12293 When the -
12294 \begin_inset ERT
12295 status Collapsed
12296
12297 \layout Standard
12298
12299 \backslash
12300 /
12301 \end_inset
12302
12303 -debug option is specified the compiler generates extra symbol information
12304  some of which are put into the assembler source and some are put into the
12305  .adb file.
12306   Then the linker creates the .cdb file from the individual .adb files with
12307  the address information for the symbols.
12308  The debugger reads the symbolic information generated by the compiler &
12309  the address information generated by the linker.
12310  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
12311  execution is controlled by the debugger.
12312  When a command is issued for the debugger, it translates it into appropriate
12313  commands for the simulator.
12314 \layout Subsection
12315
12316 Starting the Debugger
12317 \layout Standard
12318
12319 The debugger can be started using the following command line.
12320  (Assume the file you are debugging has the file name foo).
12321 \newline
12322
12323 \newline
12324
12325 \family sans
12326 \series bold
12327 sdcdb foo
12328 \newline
12329
12330 \family default
12331 \series default
12332
12333 \newline
12334 The debugger will look for the following files.
12335 \layout Itemize
12336
12337 foo.c - the source file.
12338 \layout Itemize
12339
12340 foo.cdb - the debugger symbol information file.
12341 \layout Itemize
12342
12343 foo.ihx - the Intel hex format
12344 \begin_inset LatexCommand \index{Intel hex format}
12345
12346 \end_inset
12347
12348  object file.
12349 \layout Subsection
12350
12351 Command Line Options.
12352 \layout Itemize
12353
12354 -
12355 \begin_inset ERT
12356 status Collapsed
12357
12358 \layout Standard
12359
12360 \backslash
12361 /
12362 \end_inset
12363
12364 -directory=<source file directory> this option can used to specify the directory
12365  search list.
12366  The debugger will look into the directory list specified for source, cdb
12367  & ihx files.
12368  The items in the directory list must be separated by ':', e.g.
12369  if the source files can be in the directories /home/src1 and /home/src2,
12370  the -
12371 \begin_inset ERT
12372 status Collapsed
12373
12374 \layout Standard
12375
12376 \backslash
12377 /
12378 \end_inset
12379
12380 -directory option should be -
12381 \begin_inset ERT
12382 status Collapsed
12383
12384 \layout Standard
12385
12386 \backslash
12387 /
12388 \end_inset
12389
12390 -directory=/home/src1:/home/src2.
12391  Note there can be no spaces in the option.
12392
12393 \layout Itemize
12394
12395 -cd <directory> - change to the <directory>.
12396 \layout Itemize
12397
12398 -fullname - used by GUI front ends.
12399 \layout Itemize
12400
12401 -cpu <cpu-type> - this argument is passed to the simulator please see the
12402  simulator docs for details.
12403 \layout Itemize
12404
12405 -X <Clock frequency > this options is passed to the simulator please see
12406  the simulator docs for details.
12407 \layout Itemize
12408
12409 -s <serial port file> passed to simulator see the simulator docs for details.
12410 \layout Itemize
12411
12412 -S <serial in,out> passed to simulator see the simulator docs for details.
12413 \layout Subsection
12414
12415 Debugger Commands.
12416 \layout Standard
12417
12418 As mentioned earlier the command interface for the debugger has been deliberatel
12419 y kept as close the GNU debugger gdb, as possible.
12420  This will help the integration with existing graphical user interfaces
12421  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
12422  If you use a graphical user interface for the debugger you can skip the
12423  next sections.
12424 \layout Subsubsection*
12425
12426 break [line | file:line | function | file:function]
12427 \layout Standard
12428
12429 Set breakpoint at specified line or function:
12430 \newline
12431
12432 \newline
12433
12434 \family sans
12435 \series bold
12436 sdcdb>break 100
12437 \newline
12438 sdcdb>break foo.c:100
12439 \newline
12440 sdcdb>break funcfoo
12441 \newline
12442 sdcdb>break foo.c:funcfoo
12443 \layout Subsubsection*
12444
12445 clear [line | file:line | function | file:function ]
12446 \layout Standard
12447
12448 Clear breakpoint at specified line or function:
12449 \newline
12450
12451 \newline
12452
12453 \family sans
12454 \series bold
12455 sdcdb>clear 100
12456 \newline
12457 sdcdb>clear foo.c:100
12458 \newline
12459 sdcdb>clear funcfoo
12460 \newline
12461 sdcdb>clear foo.c:funcfoo
12462 \layout Subsubsection*
12463
12464 continue
12465 \layout Standard
12466
12467 Continue program being debugged, after breakpoint.
12468 \layout Subsubsection*
12469
12470 finish
12471 \layout Standard
12472
12473 Execute till the end of the current function.
12474 \layout Subsubsection*
12475
12476 delete [n]
12477 \layout Standard
12478
12479 Delete breakpoint number 'n'.
12480  If used without any option clear ALL user defined break points.
12481 \layout Subsubsection*
12482
12483 info [break | stack | frame | registers ]
12484 \layout Itemize
12485
12486 info break - list all breakpoints
12487 \layout Itemize
12488
12489 info stack - show the function call stack.
12490 \layout Itemize
12491
12492 info frame - show information about the current execution frame.
12493 \layout Itemize
12494
12495 info registers - show content of all registers.
12496 \layout Subsubsection*
12497
12498 step
12499 \layout Standard
12500
12501 Step program until it reaches a different source line.
12502 \layout Subsubsection*
12503
12504 next
12505 \layout Standard
12506
12507 Step program, proceeding through subroutine calls.
12508 \layout Subsubsection*
12509
12510 run
12511 \layout Standard
12512
12513 Start debugged program.
12514 \layout Subsubsection*
12515
12516 ptype variable
12517 \layout Standard
12518
12519 Print type information of the variable.
12520 \layout Subsubsection*
12521
12522 print variable
12523 \layout Standard
12524
12525 print value of variable.
12526 \layout Subsubsection*
12527
12528 file filename
12529 \layout Standard
12530
12531 load the given file name.
12532  Note this is an alternate method of loading file for debugging.
12533 \layout Subsubsection*
12534
12535 frame
12536 \layout Standard
12537
12538 print information about current frame.
12539 \layout Subsubsection*
12540
12541 set srcmode
12542 \layout Standard
12543
12544 Toggle between C source & assembly source.
12545 \layout Subsubsection*
12546
12547 ! simulator command
12548 \layout Standard
12549
12550 Send the string following '!' to the simulator, the simulator response is
12551  displayed.
12552  Note the debugger does not interpret the command being sent to the simulator,
12553  so if a command like 'go' is sent the debugger can loose its execution
12554  context and may display incorrect values.
12555 \layout Subsubsection*
12556
12557 quit.
12558 \layout Standard
12559
12560 "Watch me now.
12561  Iam going Down.
12562  My name is Bobby Brown"
12563 \layout Subsection
12564
12565 Interfacing with XEmacs
12566 \begin_inset LatexCommand \index{XEmacs}
12567
12568 \end_inset
12569
12570
12571 \begin_inset LatexCommand \index{Emacs}
12572
12573 \end_inset
12574
12575 .
12576 \layout Standard
12577
12578 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
12579  sdcdb.el and sdcdbsrc.el.
12580  These two files can be found in the $(prefix)/bin directory after the installat
12581 ion is complete.
12582  These files need to be loaded into XEmacs for the interface to work.
12583  This can be done at XEmacs startup time by inserting the following into
12584  your '.xemacs' file (which can be found in your HOME directory):
12585 \newline
12586
12587 \newline
12588
12589 \family typewriter
12590 (load-file sdcdbsrc.el)
12591 \family default
12592
12593 \newline
12594
12595 \newline
12596 .xemacs is a lisp file so the () around the command is REQUIRED.
12597  The files can also be loaded dynamically while XEmacs is running, set the
12598  environment variable 'EMACSLOADPATH' to the installation bin directory
12599  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
12600  To start the interface enter the following command:
12601 \newline
12602
12603 \newline
12604
12605 \family sans
12606 \series bold
12607 ESC-x sdcdbsrc
12608 \family default
12609 \series default
12610
12611 \newline
12612
12613 \newline
12614 You will prompted to enter the file name to be debugged.
12615
12616 \newline
12617
12618 \newline
12619 The command line options that are passed to the simulator directly are bound
12620  to default values in the file sdcdbsrc.el.
12621  The variables are listed below, these values maybe changed as required.
12622 \layout Itemize
12623
12624 sdcdbsrc-cpu-type '51
12625 \layout Itemize
12626
12627 sdcdbsrc-frequency '11059200
12628 \layout Itemize
12629
12630 sdcdbsrc-serial nil
12631 \layout Standard
12632
12633 The following is a list of key mapping for the debugger interface.
12634 \layout Standard
12635
12636 \SpecialChar ~
12637
12638 \family typewriter
12639
12640 \newline
12641 ;; Current Listing ::
12642 \newline
12643 ;;key\SpecialChar ~
12644 \SpecialChar ~
12645 \SpecialChar ~
12646 \SpecialChar ~
12647 \SpecialChar ~
12648 \SpecialChar ~
12649 \SpecialChar ~
12650 \SpecialChar ~
12651 \SpecialChar ~
12652 \SpecialChar ~
12653 \SpecialChar ~
12654 \SpecialChar ~
12655 \SpecialChar ~
12656 \SpecialChar ~
12657 \SpecialChar ~
12658 binding\SpecialChar ~
12659 \SpecialChar ~
12660 \SpecialChar ~
12661 \SpecialChar ~
12662 \SpecialChar ~
12663 \SpecialChar ~
12664 \SpecialChar ~
12665 \SpecialChar ~
12666 \SpecialChar ~
12667 \SpecialChar ~
12668 \SpecialChar ~
12669 \SpecialChar ~
12670 \SpecialChar ~
12671 \SpecialChar ~
12672 \SpecialChar ~
12673 \SpecialChar ~
12674 \SpecialChar ~
12675 \SpecialChar ~
12676 \SpecialChar ~
12677 \SpecialChar ~
12678 \SpecialChar ~
12679 \SpecialChar ~
12680 Comment
12681 \newline
12682 ;;---\SpecialChar ~
12683 \SpecialChar ~
12684 \SpecialChar ~
12685 \SpecialChar ~
12686 \SpecialChar ~
12687 \SpecialChar ~
12688 \SpecialChar ~
12689 \SpecialChar ~
12690 \SpecialChar ~
12691 \SpecialChar ~
12692 \SpecialChar ~
12693 \SpecialChar ~
12694 \SpecialChar ~
12695 \SpecialChar ~
12696 \SpecialChar ~
12697 ------\SpecialChar ~
12698 \SpecialChar ~
12699 \SpecialChar ~
12700 \SpecialChar ~
12701 \SpecialChar ~
12702 \SpecialChar ~
12703 \SpecialChar ~
12704 \SpecialChar ~
12705 \SpecialChar ~
12706 \SpecialChar ~
12707 \SpecialChar ~
12708 \SpecialChar ~
12709 \SpecialChar ~
12710 \SpecialChar ~
12711 \SpecialChar ~
12712 \SpecialChar ~
12713 \SpecialChar ~
12714 \SpecialChar ~
12715 \SpecialChar ~
12716 \SpecialChar ~
12717 \SpecialChar ~
12718 \SpecialChar ~
12719 --------
12720 \newline
12721 ;;
12722 \newline
12723 ;; n\SpecialChar ~
12724 \SpecialChar ~
12725 \SpecialChar ~
12726 \SpecialChar ~
12727 \SpecialChar ~
12728 \SpecialChar ~
12729 \SpecialChar ~
12730 \SpecialChar ~
12731 \SpecialChar ~
12732 \SpecialChar ~
12733 \SpecialChar ~
12734 \SpecialChar ~
12735 \SpecialChar ~
12736 \SpecialChar ~
12737  sdcdb-next-from-src\SpecialChar ~
12738 \SpecialChar ~
12739 \SpecialChar ~
12740 \SpecialChar ~
12741 \SpecialChar ~
12742 \SpecialChar ~
12743 \SpecialChar ~
12744 \SpecialChar ~
12745 \SpecialChar ~
12746 \SpecialChar ~
12747 SDCDB next command
12748 \newline
12749 ;; b\SpecialChar ~
12750 \SpecialChar ~
12751 \SpecialChar ~
12752 \SpecialChar ~
12753 \SpecialChar ~
12754 \SpecialChar ~
12755 \SpecialChar ~
12756 \SpecialChar ~
12757 \SpecialChar ~
12758 \SpecialChar ~
12759 \SpecialChar ~
12760 \SpecialChar ~
12761 \SpecialChar ~
12762 \SpecialChar ~
12763  sdcdb-back-from-src\SpecialChar ~
12764 \SpecialChar ~
12765 \SpecialChar ~
12766 \SpecialChar ~
12767 \SpecialChar ~
12768 \SpecialChar ~
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 \SpecialChar ~
12773 SDCDB back command
12774 \newline
12775 ;; c\SpecialChar ~
12776 \SpecialChar ~
12777 \SpecialChar ~
12778 \SpecialChar ~
12779 \SpecialChar ~
12780 \SpecialChar ~
12781 \SpecialChar ~
12782 \SpecialChar ~
12783 \SpecialChar ~
12784 \SpecialChar ~
12785 \SpecialChar ~
12786 \SpecialChar ~
12787 \SpecialChar ~
12788 \SpecialChar ~
12789  sdcdb-cont-from-src\SpecialChar ~
12790 \SpecialChar ~
12791 \SpecialChar ~
12792 \SpecialChar ~
12793 \SpecialChar ~
12794 \SpecialChar ~
12795 \SpecialChar ~
12796 \SpecialChar ~
12797 \SpecialChar ~
12798 \SpecialChar ~
12799 SDCDB continue command
12800 \newline
12801 ;; s\SpecialChar ~
12802 \SpecialChar ~
12803 \SpecialChar ~
12804 \SpecialChar ~
12805 \SpecialChar ~
12806 \SpecialChar ~
12807 \SpecialChar ~
12808 \SpecialChar ~
12809 \SpecialChar ~
12810 \SpecialChar ~
12811 \SpecialChar ~
12812 \SpecialChar ~
12813 \SpecialChar ~
12814 \SpecialChar ~
12815  sdcdb-step-from-src\SpecialChar ~
12816 \SpecialChar ~
12817 \SpecialChar ~
12818 \SpecialChar ~
12819 \SpecialChar ~
12820 \SpecialChar ~
12821 \SpecialChar ~
12822 \SpecialChar ~
12823 \SpecialChar ~
12824 \SpecialChar ~
12825 SDCDB step command
12826 \newline
12827 ;; ?\SpecialChar ~
12828 \SpecialChar ~
12829 \SpecialChar ~
12830 \SpecialChar ~
12831 \SpecialChar ~
12832 \SpecialChar ~
12833 \SpecialChar ~
12834 \SpecialChar ~
12835 \SpecialChar ~
12836 \SpecialChar ~
12837 \SpecialChar ~
12838 \SpecialChar ~
12839 \SpecialChar ~
12840 \SpecialChar ~
12841  sdcdb-whatis-c-sexp\SpecialChar ~
12842 \SpecialChar ~
12843 \SpecialChar ~
12844 \SpecialChar ~
12845 \SpecialChar ~
12846 \SpecialChar ~
12847 \SpecialChar ~
12848 \SpecialChar ~
12849 \SpecialChar ~
12850 \SpecialChar ~
12851 SDCDB ptypecommand for data at
12852 \newline
12853 ;;\SpecialChar ~
12854 \SpecialChar ~
12855 \SpecialChar ~
12856 \SpecialChar ~
12857 \SpecialChar ~
12858 \SpecialChar ~
12859 \SpecialChar ~
12860 \SpecialChar ~
12861 \SpecialChar ~
12862 \SpecialChar ~
12863 \SpecialChar ~
12864 \SpecialChar ~
12865 \SpecialChar ~
12866 \SpecialChar ~
12867 \SpecialChar ~
12868 \SpecialChar ~
12869 \SpecialChar ~
12870 \SpecialChar ~
12871 \SpecialChar ~
12872 \SpecialChar ~
12873 \SpecialChar ~
12874 \SpecialChar ~
12875 \SpecialChar ~
12876 \SpecialChar ~
12877 \SpecialChar ~
12878 \SpecialChar ~
12879 \SpecialChar ~
12880 \SpecialChar ~
12881 \SpecialChar ~
12882 \SpecialChar ~
12883 \SpecialChar ~
12884 \SpecialChar ~
12885 \SpecialChar ~
12886 \SpecialChar ~
12887 \SpecialChar ~
12888 \SpecialChar ~
12889 \SpecialChar ~
12890 \SpecialChar ~
12891 \SpecialChar ~
12892 \SpecialChar ~
12893 \SpecialChar ~
12894 \SpecialChar ~
12895 \SpecialChar ~
12896 \SpecialChar ~
12897 \SpecialChar ~
12898 \SpecialChar ~
12899  buffer point
12900 \newline
12901 ;; x\SpecialChar ~
12902 \SpecialChar ~
12903 \SpecialChar ~
12904 \SpecialChar ~
12905 \SpecialChar ~
12906 \SpecialChar ~
12907 \SpecialChar ~
12908 \SpecialChar ~
12909 \SpecialChar ~
12910 \SpecialChar ~
12911 \SpecialChar ~
12912 \SpecialChar ~
12913 \SpecialChar ~
12914 \SpecialChar ~
12915  sdcdbsrc-delete\SpecialChar ~
12916 \SpecialChar ~
12917 \SpecialChar ~
12918 \SpecialChar ~
12919 \SpecialChar ~
12920 \SpecialChar ~
12921 \SpecialChar ~
12922 \SpecialChar ~
12923 \SpecialChar ~
12924 \SpecialChar ~
12925 \SpecialChar ~
12926 \SpecialChar ~
12927 \SpecialChar ~
12928 \SpecialChar ~
12929 SDCDB Delete all breakpoints if no arg
12930 \newline
12931 ;;\SpecialChar ~
12932 \SpecialChar ~
12933 \SpecialChar ~
12934 \SpecialChar ~
12935 \SpecialChar ~
12936 \SpecialChar ~
12937 \SpecialChar ~
12938 \SpecialChar ~
12939 \SpecialChar ~
12940 \SpecialChar ~
12941 \SpecialChar ~
12942 \SpecialChar ~
12943 \SpecialChar ~
12944 \SpecialChar ~
12945 \SpecialChar ~
12946 \SpecialChar ~
12947 \SpecialChar ~
12948 \SpecialChar ~
12949 \SpecialChar ~
12950 \SpecialChar ~
12951 \SpecialChar ~
12952 \SpecialChar ~
12953 \SpecialChar ~
12954 \SpecialChar ~
12955 \SpecialChar ~
12956 \SpecialChar ~
12957 \SpecialChar ~
12958 \SpecialChar ~
12959 \SpecialChar ~
12960 \SpecialChar ~
12961 \SpecialChar ~
12962 \SpecialChar ~
12963 \SpecialChar ~
12964 \SpecialChar ~
12965 \SpecialChar ~
12966 \SpecialChar ~
12967 \SpecialChar ~
12968 \SpecialChar ~
12969 \SpecialChar ~
12970 \SpecialChar ~
12971 \SpecialChar ~
12972 \SpecialChar ~
12973 \SpecialChar ~
12974 \SpecialChar ~
12975 \SpecialChar ~
12976 \SpecialChar ~
12977 given or delete arg (C-u arg x)
12978 \newline
12979 ;; m\SpecialChar ~
12980 \SpecialChar ~
12981 \SpecialChar ~
12982 \SpecialChar ~
12983 \SpecialChar ~
12984 \SpecialChar ~
12985 \SpecialChar ~
12986 \SpecialChar ~
12987 \SpecialChar ~
12988 \SpecialChar ~
12989 \SpecialChar ~
12990 \SpecialChar ~
12991 \SpecialChar ~
12992 \SpecialChar ~
12993  sdcdbsrc-frame\SpecialChar ~
12994 \SpecialChar ~
12995 \SpecialChar ~
12996 \SpecialChar ~
12997 \SpecialChar ~
12998 \SpecialChar ~
12999 \SpecialChar ~
13000 \SpecialChar ~
13001 \SpecialChar ~
13002 \SpecialChar ~
13003 \SpecialChar ~
13004 \SpecialChar ~
13005 \SpecialChar ~
13006 \SpecialChar ~
13007 \SpecialChar ~
13008 SDCDB Display current frame if no arg,
13009 \newline
13010 ;;\SpecialChar ~
13011 \SpecialChar ~
13012 \SpecialChar ~
13013 \SpecialChar ~
13014 \SpecialChar ~
13015 \SpecialChar ~
13016 \SpecialChar ~
13017 \SpecialChar ~
13018 \SpecialChar ~
13019 \SpecialChar ~
13020 \SpecialChar ~
13021 \SpecialChar ~
13022 \SpecialChar ~
13023 \SpecialChar ~
13024 \SpecialChar ~
13025 \SpecialChar ~
13026 \SpecialChar ~
13027 \SpecialChar ~
13028 \SpecialChar ~
13029 \SpecialChar ~
13030 \SpecialChar ~
13031 \SpecialChar ~
13032 \SpecialChar ~
13033 \SpecialChar ~
13034 \SpecialChar ~
13035 \SpecialChar ~
13036 \SpecialChar ~
13037 \SpecialChar ~
13038 \SpecialChar ~
13039 \SpecialChar ~
13040 \SpecialChar ~
13041 \SpecialChar ~
13042 \SpecialChar ~
13043 \SpecialChar ~
13044 \SpecialChar ~
13045 \SpecialChar ~
13046 \SpecialChar ~
13047 \SpecialChar ~
13048 \SpecialChar ~
13049 \SpecialChar ~
13050 \SpecialChar ~
13051 \SpecialChar ~
13052 \SpecialChar ~
13053 \SpecialChar ~
13054 \SpecialChar ~
13055 \SpecialChar ~
13056 \SpecialChar ~
13057 given or display frame arg
13058 \newline
13059 ;;\SpecialChar ~
13060 \SpecialChar ~
13061 \SpecialChar ~
13062 \SpecialChar ~
13063 \SpecialChar ~
13064 \SpecialChar ~
13065 \SpecialChar ~
13066 \SpecialChar ~
13067 \SpecialChar ~
13068 \SpecialChar ~
13069 \SpecialChar ~
13070 \SpecialChar ~
13071 \SpecialChar ~
13072 \SpecialChar ~
13073 \SpecialChar ~
13074 \SpecialChar ~
13075 \SpecialChar ~
13076 \SpecialChar ~
13077 \SpecialChar ~
13078 \SpecialChar ~
13079 \SpecialChar ~
13080 \SpecialChar ~
13081 \SpecialChar ~
13082 \SpecialChar ~
13083 \SpecialChar ~
13084 \SpecialChar ~
13085 \SpecialChar ~
13086 \SpecialChar ~
13087 \SpecialChar ~
13088 \SpecialChar ~
13089 \SpecialChar ~
13090 \SpecialChar ~
13091 \SpecialChar ~
13092 \SpecialChar ~
13093 \SpecialChar ~
13094 \SpecialChar ~
13095 \SpecialChar ~
13096 \SpecialChar ~
13097 \SpecialChar ~
13098 \SpecialChar ~
13099 \SpecialChar ~
13100 \SpecialChar ~
13101 \SpecialChar ~
13102 \SpecialChar ~
13103 \SpecialChar ~
13104 \SpecialChar ~
13105 \SpecialChar ~
13106 buffer point
13107 \newline
13108 ;; !\SpecialChar ~
13109 \SpecialChar ~
13110 \SpecialChar ~
13111 \SpecialChar ~
13112 \SpecialChar ~
13113 \SpecialChar ~
13114 \SpecialChar ~
13115 \SpecialChar ~
13116 \SpecialChar ~
13117 \SpecialChar ~
13118 \SpecialChar ~
13119 \SpecialChar ~
13120 \SpecialChar ~
13121 \SpecialChar ~
13122  sdcdbsrc-goto-sdcdb\SpecialChar ~
13123 \SpecialChar ~
13124 \SpecialChar ~
13125 \SpecialChar ~
13126 \SpecialChar ~
13127 \SpecialChar ~
13128 \SpecialChar ~
13129 \SpecialChar ~
13130 \SpecialChar ~
13131 \SpecialChar ~
13132 Goto the SDCDB output buffer
13133 \newline
13134 ;; p\SpecialChar ~
13135 \SpecialChar ~
13136 \SpecialChar ~
13137 \SpecialChar ~
13138 \SpecialChar ~
13139 \SpecialChar ~
13140 \SpecialChar ~
13141 \SpecialChar ~
13142 \SpecialChar ~
13143 \SpecialChar ~
13144 \SpecialChar ~
13145 \SpecialChar ~
13146 \SpecialChar ~
13147 \SpecialChar ~
13148  sdcdb-print-c-sexp\SpecialChar ~
13149 \SpecialChar ~
13150 \SpecialChar ~
13151 \SpecialChar ~
13152 \SpecialChar ~
13153 \SpecialChar ~
13154 \SpecialChar ~
13155 \SpecialChar ~
13156 \SpecialChar ~
13157 \SpecialChar ~
13158 \SpecialChar ~
13159 SDCDB print command for data at
13160 \newline
13161 ;;\SpecialChar ~
13162 \SpecialChar ~
13163 \SpecialChar ~
13164 \SpecialChar ~
13165 \SpecialChar ~
13166 \SpecialChar ~
13167 \SpecialChar ~
13168 \SpecialChar ~
13169 \SpecialChar ~
13170 \SpecialChar ~
13171 \SpecialChar ~
13172 \SpecialChar ~
13173 \SpecialChar ~
13174 \SpecialChar ~
13175 \SpecialChar ~
13176 \SpecialChar ~
13177 \SpecialChar ~
13178 \SpecialChar ~
13179 \SpecialChar ~
13180 \SpecialChar ~
13181 \SpecialChar ~
13182 \SpecialChar ~
13183 \SpecialChar ~
13184 \SpecialChar ~
13185 \SpecialChar ~
13186 \SpecialChar ~
13187 \SpecialChar ~
13188 \SpecialChar ~
13189 \SpecialChar ~
13190 \SpecialChar ~
13191 \SpecialChar ~
13192 \SpecialChar ~
13193 \SpecialChar ~
13194 \SpecialChar ~
13195 \SpecialChar ~
13196 \SpecialChar ~
13197 \SpecialChar ~
13198 \SpecialChar ~
13199 \SpecialChar ~
13200 \SpecialChar ~
13201 \SpecialChar ~
13202 \SpecialChar ~
13203 \SpecialChar ~
13204 \SpecialChar ~
13205 \SpecialChar ~
13206 \SpecialChar ~
13207  buffer point
13208 \newline
13209 ;; g\SpecialChar ~
13210 \SpecialChar ~
13211 \SpecialChar ~
13212 \SpecialChar ~
13213 \SpecialChar ~
13214 \SpecialChar ~
13215 \SpecialChar ~
13216 \SpecialChar ~
13217 \SpecialChar ~
13218 \SpecialChar ~
13219 \SpecialChar ~
13220 \SpecialChar ~
13221 \SpecialChar ~
13222 \SpecialChar ~
13223  sdcdbsrc-goto-sdcdb\SpecialChar ~
13224 \SpecialChar ~
13225 \SpecialChar ~
13226 \SpecialChar ~
13227 \SpecialChar ~
13228 \SpecialChar ~
13229 \SpecialChar ~
13230 \SpecialChar ~
13231 \SpecialChar ~
13232 \SpecialChar ~
13233 Goto the SDCDB output buffer
13234 \newline
13235 ;; t\SpecialChar ~
13236 \SpecialChar ~
13237 \SpecialChar ~
13238 \SpecialChar ~
13239 \SpecialChar ~
13240 \SpecialChar ~
13241 \SpecialChar ~
13242 \SpecialChar ~
13243 \SpecialChar ~
13244 \SpecialChar ~
13245 \SpecialChar ~
13246 \SpecialChar ~
13247 \SpecialChar ~
13248 \SpecialChar ~
13249  sdcdbsrc-mode\SpecialChar ~
13250 \SpecialChar ~
13251 \SpecialChar ~
13252 \SpecialChar ~
13253 \SpecialChar ~
13254 \SpecialChar ~
13255 \SpecialChar ~
13256 \SpecialChar ~
13257 \SpecialChar ~
13258 \SpecialChar ~
13259 \SpecialChar ~
13260 \SpecialChar ~
13261 \SpecialChar ~
13262 \SpecialChar ~
13263 \SpecialChar ~
13264 \SpecialChar ~
13265 Toggles Sdcdbsrc mode (turns it off)
13266 \newline
13267 ;;
13268 \newline
13269 ;; C-c C-f\SpecialChar ~
13270 \SpecialChar ~
13271 \SpecialChar ~
13272 \SpecialChar ~
13273 \SpecialChar ~
13274 \SpecialChar ~
13275 \SpecialChar ~
13276 \SpecialChar ~
13277  sdcdb-finish-from-src\SpecialChar ~
13278 \SpecialChar ~
13279 \SpecialChar ~
13280 \SpecialChar ~
13281 \SpecialChar ~
13282 \SpecialChar ~
13283 \SpecialChar ~
13284 \SpecialChar ~
13285 SDCDB finish command
13286 \newline
13287 ;;
13288 \newline
13289 ;; C-x SPC\SpecialChar ~
13290 \SpecialChar ~
13291 \SpecialChar ~
13292 \SpecialChar ~
13293 \SpecialChar ~
13294 \SpecialChar ~
13295 \SpecialChar ~
13296 \SpecialChar ~
13297  sdcdb-break\SpecialChar ~
13298 \SpecialChar ~
13299 \SpecialChar ~
13300 \SpecialChar ~
13301 \SpecialChar ~
13302 \SpecialChar ~
13303 \SpecialChar ~
13304 \SpecialChar ~
13305 \SpecialChar ~
13306 \SpecialChar ~
13307 \SpecialChar ~
13308 \SpecialChar ~
13309 \SpecialChar ~
13310 \SpecialChar ~
13311 \SpecialChar ~
13312 \SpecialChar ~
13313 \SpecialChar ~
13314 \SpecialChar ~
13315 Set break for line with point
13316 \newline
13317 ;; ESC t\SpecialChar ~
13318 \SpecialChar ~
13319 \SpecialChar ~
13320 \SpecialChar ~
13321 \SpecialChar ~
13322 \SpecialChar ~
13323 \SpecialChar ~
13324 \SpecialChar ~
13325 \SpecialChar ~
13326 \SpecialChar ~
13327  sdcdbsrc-mode\SpecialChar ~
13328 \SpecialChar ~
13329 \SpecialChar ~
13330 \SpecialChar ~
13331 \SpecialChar ~
13332 \SpecialChar ~
13333 \SpecialChar ~
13334 \SpecialChar ~
13335 \SpecialChar ~
13336 \SpecialChar ~
13337 \SpecialChar ~
13338 \SpecialChar ~
13339 \SpecialChar ~
13340 \SpecialChar ~
13341 \SpecialChar ~
13342 \SpecialChar ~
13343 Toggle Sdcdbsrc mode
13344 \newline
13345 ;; ESC m\SpecialChar ~
13346 \SpecialChar ~
13347 \SpecialChar ~
13348 \SpecialChar ~
13349 \SpecialChar ~
13350 \SpecialChar ~
13351 \SpecialChar ~
13352 \SpecialChar ~
13353 \SpecialChar ~
13354 \SpecialChar ~
13355  sdcdbsrc-srcmode\SpecialChar ~
13356 \SpecialChar ~
13357 \SpecialChar ~
13358 \SpecialChar ~
13359 \SpecialChar ~
13360 \SpecialChar ~
13361 \SpecialChar ~
13362 \SpecialChar ~
13363 \SpecialChar ~
13364 \SpecialChar ~
13365 \SpecialChar ~
13366 \SpecialChar ~
13367  Toggle list mode
13368 \newline
13369 ;;
13370 \newline
13371
13372 \layout Section
13373 \pagebreak_top
13374 TIPS
13375 \layout Standard
13376
13377 Here are a few guidelines that will help the compiler generate more efficient
13378  code, some of the tips are specific to this compiler others are generally
13379  good programming practice.
13380 \layout Itemize
13381
13382 Use the smallest data type to represent your data-value.
13383  If it is known in advance that the value is going to be less than 256 then
13384  use an 'unsigned char' instead of a 'short' or 'int'.
13385 \layout Itemize
13386
13387 Use unsigned when it is known in advance that the value is not going to
13388  be negative.
13389  This helps especially if you are doing division or multiplication.
13390 \layout Itemize
13391
13392 NEVER jump into a LOOP.
13393 \layout Itemize
13394
13395 Declare the variables to be local whenever possible, especially loop control
13396  variables (induction).
13397 \layout Itemize
13398
13399 Since the compiler does not always do implicit integral promotion, the programme
13400 r should do an explicit cast when integral promotion is required.
13401 \layout Itemize
13402
13403 Reducing the size of division, multiplication & modulus operations can reduce
13404  code size substantially.
13405  Take the following code for example.
13406 \begin_deeper
13407 \layout Verse
13408
13409
13410 \family typewriter
13411 foobar(unsigned int p1, unsigned char ch)
13412 \newline
13413 {
13414 \newline
13415 \SpecialChar ~
13416 \SpecialChar ~
13417 \SpecialChar ~
13418 \SpecialChar ~
13419 unsigned char ch1 = p1 % ch ;
13420 \newline
13421 \SpecialChar ~
13422 \SpecialChar ~
13423 \SpecialChar ~
13424 \SpecialChar ~
13425 ....
13426 \newline
13427 }
13428 \layout Standard
13429
13430 For the modulus operation the variable ch will be promoted to unsigned int
13431  first then the modulus operation will be performed (this will lead to a
13432  call to support routine _moduint()), and the result will be casted to a
13433  char.
13434  If the code is changed to
13435 \layout Verse
13436
13437
13438 \family typewriter
13439 foobar(unsigned int p1, unsigned char ch)
13440 \newline
13441 {
13442 \newline
13443 \SpecialChar ~
13444 \SpecialChar ~
13445 \SpecialChar ~
13446 \SpecialChar ~
13447 unsigned char ch1 = (unsigned char)p1 % ch ;
13448 \newline
13449 \SpecialChar ~
13450 \SpecialChar ~
13451 \SpecialChar ~
13452 \SpecialChar ~
13453 ....
13454 \newline
13455 }
13456 \layout Standard
13457
13458 It would substantially reduce the code generated (future versions of the
13459  compiler will be smart enough to detect such optimization opportunities).
13460 \end_deeper
13461 \layout Itemize
13462
13463 Have a look at the assembly listing to get a
13464 \begin_inset Quotes sld
13465 \end_inset
13466
13467 feeling
13468 \begin_inset Quotes srd
13469 \end_inset
13470
13471  for the code generation.
13472 \layout Subsection
13473
13474 Notes on MCS51 memory
13475 \begin_inset LatexCommand \index{MCS51 memory}
13476
13477 \end_inset
13478
13479  layout
13480 \layout Standard
13481
13482 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
13483  RAM memory which is structured as follows
13484 \newline
13485
13486 \newline
13487 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
13488
13489 \newline
13490 - Bytes 20-2F - 16 bytes to hold 128 bit
13491 \begin_inset LatexCommand \index{bit}
13492
13493 \end_inset
13494
13495  variables and,
13496 \newline
13497 - Bytes 30-7F - 80 bytes for general purpose use.
13498 \newline
13499
13500 \layout Standard
13501
13502 Additionally some members of the MCS51 family may have up to 128 bytes of
13503  additional, indirectly addressable, internal RAM memory (
13504 \emph on
13505 idata
13506 \emph default
13507
13508 \begin_inset LatexCommand \index{idata}
13509
13510 \end_inset
13511
13512 ).
13513  Furthermore, some chips may have some built in external memory (
13514 \emph on
13515 xdata
13516 \emph default
13517
13518 \begin_inset LatexCommand \index{xdata}
13519
13520 \end_inset
13521
13522 ) which should not be confused with the internal, directly addressable RAM
13523  memory (
13524 \emph on
13525 data
13526 \emph default
13527
13528 \begin_inset LatexCommand \index{data}
13529
13530 \end_inset
13531
13532 ).
13533  Sometimes this built in
13534 \emph on
13535 xdata
13536 \emph default
13537  memory has to be activated before using it (you can probably find this
13538  information on the datasheet of the microcontroller your are using).
13539 \layout Standard
13540
13541 Normally SDCC will only use the first bank
13542 \begin_inset LatexCommand \index{bank}
13543
13544 \end_inset
13545
13546  of registers (register bank 0), but it is possible to specify that other
13547  banks of registers should be used in interrupt
13548 \begin_inset LatexCommand \index{interrupt}
13549
13550 \end_inset
13551
13552  routines.
13553  By default, the compiler will place the stack after the last byte of allocated
13554  memory for variables.
13555  For example, if the first 2 banks of registers are used, and only four
13556  bytes are used for
13557 \emph on
13558 data
13559 \emph default
13560  variables, it will position the base of the internal stack at address 20
13561  (0x14).
13562  This implies that as the stack
13563 \begin_inset LatexCommand \index{stack}
13564
13565 \end_inset
13566
13567  grows, it will use up the remaining register banks, and the 16 bytes used
13568  by the 128 bit variables, and 80 bytes for general purpose use.
13569  If any bit variables are used, the data variables will be placed after
13570  the byte holding the last bit variable.
13571  For example, if register banks 0 and 1 are used, and there are 9 bit variables
13572  (two bytes used),
13573 \emph on
13574 data
13575 \emph default
13576  variables will be placed starting at address 0x22.
13577  You can also use -
13578 \begin_inset ERT
13579 status Collapsed
13580
13581 \layout Standard
13582
13583 \backslash
13584 /
13585 \end_inset
13586
13587 -data-loc
13588 \begin_inset LatexCommand \index{-\/-data-loc}
13589
13590 \end_inset
13591
13592  to specify the start address of the
13593 \emph on
13594 data
13595 \emph default
13596  and -
13597 \begin_inset ERT
13598 status Collapsed
13599
13600 \layout Standard
13601
13602 \backslash
13603 /
13604 \end_inset
13605
13606 -iram-size to specify the size of the total internal RAM (
13607 \emph on
13608 data
13609 \emph default
13610 +
13611 \emph on
13612 idata
13613 \emph default
13614 ).
13615
13616 \layout Standard
13617
13618 By default the 8051 linker will place the stack after the last byte of data
13619  variables.
13620  Option -
13621 \begin_inset ERT
13622 status Collapsed
13623
13624 \layout Standard
13625
13626 \backslash
13627 /
13628 \end_inset
13629
13630 -stack-loc
13631 \begin_inset LatexCommand \index{-\/-stack-loc}
13632
13633 \end_inset
13634
13635  allows you to specify the start of the stack, i.e.
13636  you could start it after any data in the general purpose area.
13637  If your microcontroller has additional indirectly addressable internal
13638  RAM (
13639 \emph on
13640 idata
13641 \emph default
13642 ) you can place the stack on it.
13643  You may also need to use -
13644 \begin_inset ERT
13645 status Collapsed
13646
13647 \layout Standard
13648
13649 \backslash
13650 /
13651 \end_inset
13652
13653 -xdata-loc
13654 \begin_inset LatexCommand \index{-\/-data-loc}
13655
13656 \end_inset
13657
13658  to set the start address of the external RAM (
13659 \emph on
13660 xdata
13661 \emph default
13662 ) and -
13663 \begin_inset ERT
13664 status Collapsed
13665
13666 \layout Standard
13667
13668 \backslash
13669 /
13670 \end_inset
13671
13672 -xram-size
13673 \begin_inset LatexCommand \index{-\/-data-loc}
13674
13675 \end_inset
13676
13677  to specify its size.
13678  Same goes for the code memory, using -
13679 \begin_inset ERT
13680 status Collapsed
13681
13682 \layout Standard
13683
13684 \backslash
13685 /
13686 \end_inset
13687
13688 -code-loc
13689 \begin_inset LatexCommand \index{-\/-data-loc}
13690
13691 \end_inset
13692
13693  and -
13694 \begin_inset ERT
13695 status Collapsed
13696
13697 \layout Standard
13698
13699 \backslash
13700 /
13701 \end_inset
13702
13703 -code-size
13704 \begin_inset LatexCommand \index{-\/-data-loc}
13705
13706 \end_inset
13707
13708 .
13709  If in doubt, don't specify any options and see if the resulting memory
13710  layout is appropriate, then you can adjust it.
13711 \layout Standard
13712
13713 The 8051 linker generates two files with memory allocation information.
13714  The first, with extension .map shows all the variables and segments.
13715  The second with extension .mem shows the final memory layout.
13716  The linker will complaint either if memory segments overlap, there is not
13717  enough memory, or there is not enough space for stack.
13718  If you get any linking warnings and/or errors related to stack or segments
13719  allocation, take a look at either the .map or .mem files to find out what
13720  the problem is.
13721  The .mem file may even suggest a solution to the problem.
13722 \layout Subsection
13723
13724 Tools
13725 \begin_inset LatexCommand \index{Tools}
13726
13727 \end_inset
13728
13729  included in the distribution
13730 \layout Standard
13731 \align center
13732
13733 \begin_inset  Tabular
13734 <lyxtabular version="3" rows="12" columns="3">
13735 <features>
13736 <column alignment="center" valignment="top" leftline="true" width="0pt">
13737 <column alignment="center" valignment="top" leftline="true" width="0pt">
13738 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
13739 <row topline="true" bottomline="true">
13740 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13741 \begin_inset Text
13742
13743 \layout Standard
13744
13745 Name
13746 \end_inset
13747 </cell>
13748 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13749 \begin_inset Text
13750
13751 \layout Standard
13752
13753 Purpose
13754 \end_inset
13755 </cell>
13756 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13757 \begin_inset Text
13758
13759 \layout Standard
13760
13761 Directory
13762 \end_inset
13763 </cell>
13764 </row>
13765 <row topline="true">
13766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13767 \begin_inset Text
13768
13769 \layout Standard
13770
13771 uCsim
13772 \end_inset
13773 </cell>
13774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13775 \begin_inset Text
13776
13777 \layout Standard
13778
13779 Simulator for various architectures
13780 \end_inset
13781 </cell>
13782 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13783 \begin_inset Text
13784
13785 \layout Standard
13786
13787 sdcc/sim/ucsim
13788 \end_inset
13789 </cell>
13790 </row>
13791 <row topline="true">
13792 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13793 \begin_inset Text
13794
13795 \layout Standard
13796
13797 keil2sdcc.pl
13798 \end_inset
13799 </cell>
13800 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13801 \begin_inset Text
13802
13803 \layout Standard
13804
13805 header file conversion
13806 \end_inset
13807 </cell>
13808 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13809 \begin_inset Text
13810
13811 \layout Standard
13812
13813 sdcc/support/scripts
13814 \end_inset
13815 </cell>
13816 </row>
13817 <row topline="true">
13818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13819 \begin_inset Text
13820
13821 \layout Standard
13822
13823 mh2h.c
13824 \end_inset
13825 </cell>
13826 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13827 \begin_inset Text
13828
13829 \layout Standard
13830
13831 header file conversion
13832 \end_inset
13833 </cell>
13834 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13835 \begin_inset Text
13836
13837 \layout Standard
13838
13839 sdcc/support/scripts
13840 \end_inset
13841 </cell>
13842 </row>
13843 <row topline="true">
13844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13845 \begin_inset Text
13846
13847 \layout Standard
13848
13849 as-gbz80
13850 \end_inset
13851 </cell>
13852 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13853 \begin_inset Text
13854
13855 \layout Standard
13856
13857 Assembler
13858 \end_inset
13859 </cell>
13860 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13861 \begin_inset Text
13862
13863 \layout Standard
13864
13865
13866 \family roman
13867 \series medium
13868 \shape up
13869 \size normal
13870 \emph off
13871 \bar no
13872 \noun off
13873 \color none
13874 sdcc/bin
13875 \end_inset
13876 </cell>
13877 </row>
13878 <row topline="true">
13879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13880 \begin_inset Text
13881
13882 \layout Standard
13883
13884 as-z80
13885 \end_inset
13886 </cell>
13887 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13888 \begin_inset Text
13889
13890 \layout Standard
13891
13892 Assembler
13893 \end_inset
13894 </cell>
13895 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13896 \begin_inset Text
13897
13898 \layout Standard
13899
13900
13901 \family roman
13902 \series medium
13903 \shape up
13904 \size normal
13905 \emph off
13906 \bar no
13907 \noun off
13908 \color none
13909 sdcc/bin
13910 \end_inset
13911 </cell>
13912 </row>
13913 <row topline="true">
13914 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13915 \begin_inset Text
13916
13917 \layout Standard
13918
13919 asx8051
13920 \end_inset
13921 </cell>
13922 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13923 \begin_inset Text
13924
13925 \layout Standard
13926
13927 Assembler
13928 \end_inset
13929 </cell>
13930 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13931 \begin_inset Text
13932
13933 \layout Standard
13934
13935
13936 \family roman
13937 \series medium
13938 \shape up
13939 \size normal
13940 \emph off
13941 \bar no
13942 \noun off
13943 \color none
13944 sdcc/bin
13945 \end_inset
13946 </cell>
13947 </row>
13948 <row topline="true">
13949 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13950 \begin_inset Text
13951
13952 \layout Standard
13953
13954 sdcdb
13955 \end_inset
13956 </cell>
13957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13958 \begin_inset Text
13959
13960 \layout Standard
13961
13962 Simulator
13963 \end_inset
13964 </cell>
13965 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13966 \begin_inset Text
13967
13968 \layout Standard
13969
13970
13971 \family roman
13972 \series medium
13973 \shape up
13974 \size normal
13975 \emph off
13976 \bar no
13977 \noun off
13978 \color none
13979 sdcc/bin
13980 \end_inset
13981 </cell>
13982 </row>
13983 <row topline="true">
13984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13985 \begin_inset Text
13986
13987 \layout Standard
13988
13989 aslink
13990 \end_inset
13991 </cell>
13992 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13993 \begin_inset Text
13994
13995 \layout Standard
13996
13997 Linker
13998 \end_inset
13999 </cell>
14000 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14001 \begin_inset Text
14002
14003 \layout Standard
14004
14005
14006 \family roman
14007 \series medium
14008 \shape up
14009 \size normal
14010 \emph off
14011 \bar no
14012 \noun off
14013 \color none
14014 sdcc/bin
14015 \end_inset
14016 </cell>
14017 </row>
14018 <row topline="true">
14019 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14020 \begin_inset Text
14021
14022 \layout Standard
14023
14024 link-z80
14025 \end_inset
14026 </cell>
14027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14028 \begin_inset Text
14029
14030 \layout Standard
14031
14032 Linker
14033 \end_inset
14034 </cell>
14035 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14036 \begin_inset Text
14037
14038 \layout Standard
14039
14040
14041 \family roman
14042 \series medium
14043 \shape up
14044 \size normal
14045 \emph off
14046 \bar no
14047 \noun off
14048 \color none
14049 sdcc/bin
14050 \end_inset
14051 </cell>
14052 </row>
14053 <row topline="true">
14054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14055 \begin_inset Text
14056
14057 \layout Standard
14058
14059 link-gbz80
14060 \end_inset
14061 </cell>
14062 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14063 \begin_inset Text
14064
14065 \layout Standard
14066
14067 Linker
14068 \end_inset
14069 </cell>
14070 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14071 \begin_inset Text
14072
14073 \layout Standard
14074
14075
14076 \family roman
14077 \series medium
14078 \shape up
14079 \size normal
14080 \emph off
14081 \bar no
14082 \noun off
14083 \color none
14084 sdcc/bin
14085 \end_inset
14086 </cell>
14087 </row>
14088 <row topline="true" bottomline="true">
14089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14090 \begin_inset Text
14091
14092 \layout Standard
14093
14094 packihx
14095 \end_inset
14096 </cell>
14097 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14098 \begin_inset Text
14099
14100 \layout Standard
14101
14102 ihx packer
14103 \end_inset
14104 </cell>
14105 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14106 \begin_inset Text
14107
14108 \layout Standard
14109
14110
14111 \family roman
14112 \series medium
14113 \shape up
14114 \size normal
14115 \emph off
14116 \bar no
14117 \noun off
14118 \color none
14119 sdcc/bin
14120 \end_inset
14121 </cell>
14122 </row>
14123 </lyxtabular>
14124
14125 \end_inset
14126
14127
14128 \newline
14129
14130 \layout Subsection
14131
14132 Related open source tools
14133 \begin_inset LatexCommand \index{Related tools}
14134
14135 \end_inset
14136
14137
14138 \layout Standard
14139 \align center
14140
14141 \begin_inset  Tabular
14142 <lyxtabular version="3" rows="8" columns="3">
14143 <features>
14144 <column alignment="center" valignment="top" leftline="true" width="0pt">
14145 <column alignment="block" valignment="top" leftline="true" width="30line%">
14146 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
14147 <row topline="true" bottomline="true">
14148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14149 \begin_inset Text
14150
14151 \layout Standard
14152
14153 Name
14154 \end_inset
14155 </cell>
14156 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14157 \begin_inset Text
14158
14159 \layout Standard
14160
14161 Purpose
14162 \end_inset
14163 </cell>
14164 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14165 \begin_inset Text
14166
14167 \layout Standard
14168
14169 Where to get
14170 \end_inset
14171 </cell>
14172 </row>
14173 <row topline="true">
14174 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14175 \begin_inset Text
14176
14177 \layout Standard
14178
14179 gpsim
14180 \begin_inset LatexCommand \index{gpsim}
14181
14182 \end_inset
14183
14184
14185 \end_inset
14186 </cell>
14187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14188 \begin_inset Text
14189
14190 \layout Standard
14191
14192 PIC simulator
14193 \end_inset
14194 </cell>
14195 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14196 \begin_inset Text
14197
14198 \layout Standard
14199
14200
14201 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
14202
14203 \end_inset
14204
14205
14206 \end_inset
14207 </cell>
14208 </row>
14209 <row topline="true">
14210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14211 \begin_inset Text
14212
14213 \layout Standard
14214
14215 flP5
14216 \end_inset
14217 </cell>
14218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14219 \begin_inset Text
14220
14221 \layout Standard
14222
14223 PIC programmer
14224 \end_inset
14225 </cell>
14226 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14227 \begin_inset Text
14228
14229 \layout Standard
14230
14231
14232 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
14233
14234 \end_inset
14235
14236
14237 \end_inset
14238 </cell>
14239 </row>
14240 <row topline="true">
14241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14242 \begin_inset Text
14243
14244 \layout Standard
14245
14246 srecord
14247 \begin_inset LatexCommand \index{srecord}
14248
14249 \end_inset
14250
14251
14252 \end_inset
14253 </cell>
14254 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14255 \begin_inset Text
14256
14257 \layout Standard
14258
14259 Object file conversion, checksumming, ...
14260 \end_inset
14261 </cell>
14262 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14263 \begin_inset Text
14264
14265 \layout Standard
14266
14267
14268 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
14269
14270 \end_inset
14271
14272
14273 \end_inset
14274 </cell>
14275 </row>
14276 <row topline="true">
14277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14278 \begin_inset Text
14279
14280 \layout Standard
14281
14282 objdump
14283 \begin_inset LatexCommand \index{objdump}
14284
14285 \end_inset
14286
14287
14288 \end_inset
14289 </cell>
14290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14291 \begin_inset Text
14292
14293 \layout Standard
14294
14295 Object file conversion, ...
14296 \end_inset
14297 </cell>
14298 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14299 \begin_inset Text
14300
14301 \layout Standard
14302
14303 Part of binutils (should be there anyway)
14304 \end_inset
14305 </cell>
14306 </row>
14307 <row topline="true">
14308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14309 \begin_inset Text
14310
14311 \layout Standard
14312
14313 doxygen
14314 \begin_inset LatexCommand \index{doxygen}
14315
14316 \end_inset
14317
14318
14319 \end_inset
14320 </cell>
14321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14322 \begin_inset Text
14323
14324 \layout Standard
14325
14326 Source code documentation system
14327 \end_inset
14328 </cell>
14329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14330 \begin_inset Text
14331
14332 \layout Standard
14333
14334
14335 \begin_inset LatexCommand \url{http://www.doxygen.org}
14336
14337 \end_inset
14338
14339
14340 \end_inset
14341 </cell>
14342 </row>
14343 <row topline="true">
14344 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14345 \begin_inset Text
14346
14347 \layout Standard
14348
14349 splint
14350 \begin_inset LatexCommand \index{splint}
14351
14352 \end_inset
14353
14354
14355 \end_inset
14356 </cell>
14357 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14358 \begin_inset Text
14359
14360 \layout Standard
14361
14362 Statically checks c sources
14363 \end_inset
14364 </cell>
14365 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14366 \begin_inset Text
14367
14368 \layout Standard
14369
14370
14371 \begin_inset LatexCommand \url{http://www.splint.org}
14372
14373 \end_inset
14374
14375
14376 \end_inset
14377 </cell>
14378 </row>
14379 <row topline="true" bottomline="true">
14380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14381 \begin_inset Text
14382
14383 \layout Standard
14384
14385 ddd
14386 \begin_inset LatexCommand \index{ddd}
14387
14388 \end_inset
14389
14390
14391 \end_inset
14392 </cell>
14393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14394 \begin_inset Text
14395
14396 \layout Standard
14397
14398 Debugger, serves nicely as GUI to sdcdb
14399 \begin_inset LatexCommand \index{sdcdb}
14400
14401 \end_inset
14402
14403  (Unix only)
14404 \end_inset
14405 </cell>
14406 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14407 \begin_inset Text
14408
14409 \layout Standard
14410
14411
14412 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
14413
14414 \end_inset
14415
14416
14417 \end_inset
14418 </cell>
14419 </row>
14420 </lyxtabular>
14421
14422 \end_inset
14423
14424
14425 \newline
14426
14427 \layout Subsection
14428
14429 Related documentation / recommended reading
14430 \layout Standard
14431 \align center
14432
14433 \begin_inset  Tabular
14434 <lyxtabular version="3" rows="5" columns="3">
14435 <features>
14436 <column alignment="center" valignment="top" leftline="true" width="0pt">
14437 <column alignment="block" valignment="top" leftline="true" width="30line%">
14438 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
14439 <row topline="true" bottomline="true">
14440 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14441 \begin_inset Text
14442
14443 \layout Standard
14444
14445 Name
14446 \end_inset
14447 </cell>
14448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14449 \begin_inset Text
14450
14451 \layout Standard
14452
14453 Subject / Title
14454 \end_inset
14455 </cell>
14456 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14457 \begin_inset Text
14458
14459 \layout Standard
14460
14461 Where to get
14462 \end_inset
14463 </cell>
14464 </row>
14465 <row topline="true">
14466 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14467 \begin_inset Text
14468
14469 \layout Standard
14470
14471 S.
14472  S.
14473  Muchnick
14474 \end_inset
14475 </cell>
14476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14477 \begin_inset Text
14478
14479 \layout Standard
14480
14481 Advanced Compiler Design and Implementation
14482 \end_inset
14483 </cell>
14484 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14485 \begin_inset Text
14486
14487 \layout Standard
14488
14489 bookstore
14490 \end_inset
14491 </cell>
14492 </row>
14493 <row topline="true">
14494 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14495 \begin_inset Text
14496
14497 \layout Standard
14498
14499
14500 \family roman
14501 \series medium
14502 \shape up
14503 \size normal
14504 \emph off
14505 \bar no
14506 \noun off
14507 \color none
14508 c-refcard.pdf
14509 \end_inset
14510 </cell>
14511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14512 \begin_inset Text
14513
14514 \layout Standard
14515
14516 C Reference Card
14517 \begin_inset LatexCommand \index{C Reference card}
14518
14519 \end_inset
14520
14521 , 2 pages
14522 \end_inset
14523 </cell>
14524 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14525 \begin_inset Text
14526
14527 \layout Standard
14528
14529
14530 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
14531
14532 \end_inset
14533
14534
14535 \end_inset
14536 </cell>
14537 </row>
14538 <row topline="true">
14539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14540 \begin_inset Text
14541
14542 \layout Standard
14543
14544 test_suite_spec.pdf
14545 \end_inset
14546 </cell>
14547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14548 \begin_inset Text
14549
14550 \layout Standard
14551
14552 sdcc regression test
14553 \begin_inset LatexCommand \index{Regression test}
14554
14555 \end_inset
14556
14557
14558 \end_inset
14559 </cell>
14560 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14561 \begin_inset Text
14562
14563 \layout Standard
14564
14565 sdcc/doc
14566 \end_inset
14567 </cell>
14568 </row>
14569 <row topline="true" bottomline="true">
14570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14571 \begin_inset Text
14572
14573 \layout Standard
14574
14575
14576 \family roman
14577 \series medium
14578 \shape up
14579 \size normal
14580 \emph off
14581 \bar no
14582 \noun off
14583 \color none
14584 cdbfileformat.pd
14585 \family default
14586 \series default
14587 \shape default
14588 \size default
14589 \emph default
14590 \bar default
14591 \noun default
14592 \color default
14593 f
14594 \end_inset
14595 </cell>
14596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14597 \begin_inset Text
14598
14599 \layout Standard
14600
14601 sdcc internal documentation
14602 \end_inset
14603 </cell>
14604 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14605 \begin_inset Text
14606
14607 \layout Standard
14608
14609 sdcc/doc
14610 \end_inset
14611 </cell>
14612 </row>
14613 </lyxtabular>
14614
14615 \end_inset
14616
14617
14618 \newline
14619
14620 \layout Section
14621 \pagebreak_top
14622 Support
14623 \begin_inset LatexCommand \index{Support}
14624
14625 \end_inset
14626
14627
14628 \layout Standard
14629
14630 SDCC has grown to be a large project.
14631  The compiler alone (without the preprocessor, assembler and linker) is
14632  well over 100,000 lines of code (blank stripped).
14633  The open source nature of this project is a key to its continued growth
14634  and support.
14635  You gain the benefit and support of many active software developers and
14636  end users.
14637  Is SDCC perfect? No, that's why we need your help.
14638  The developers take pride in fixing reported bugs.
14639  You can help by reporting the bugs and helping other SDCC users.
14640  There are lots of ways to contribute, and we encourage you to take part
14641  in making SDCC a great software package.
14642
14643 \layout Standard
14644
14645 The SDCC project is hosted on the SDCC sourceforge site at
14646 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
14647
14648 \end_inset
14649
14650 .
14651  You'll find the complete set of mailing lists
14652 \begin_inset LatexCommand \index{Mailing list}
14653
14654 \end_inset
14655
14656 , forums, bug reporting system, patch submission
14657 \begin_inset LatexCommand \index{Patch submission}
14658
14659 \end_inset
14660
14661  system, download
14662 \begin_inset LatexCommand \index{download}
14663
14664 \end_inset
14665
14666  area and cvs code repository
14667 \begin_inset LatexCommand \index{cvs code repository}
14668
14669 \end_inset
14670
14671  there.
14672 \layout Subsection
14673
14674 Reporting Bugs
14675 \begin_inset LatexCommand \index{Bugs}
14676
14677 \end_inset
14678
14679
14680 \begin_inset LatexCommand \index{Reporting bugs}
14681
14682 \end_inset
14683
14684
14685 \layout Standard
14686
14687 The recommended way of reporting bugs is using the infrastructure of the
14688  sourceforge site.
14689  You can follow the status of bug reports there and have an overview about
14690  the known bugs.
14691 \layout Standard
14692
14693 Bug reports are automatically forwarded to the developer mailing list and
14694  will be fixed ASAP.
14695  When reporting a bug, it is very useful to include a small test program
14696  (the smaller the better) which reproduces the problem.
14697  If you can isolate the problem by looking at the generated assembly code,
14698  this can be very helpful.
14699  Compiling your program with the -
14700 \begin_inset ERT
14701 status Collapsed
14702
14703 \layout Standard
14704
14705 \backslash
14706 /
14707 \end_inset
14708
14709 -dumpall
14710 \begin_inset LatexCommand \index{-\/-dumpall}
14711
14712 \end_inset
14713
14714  option can sometimes be useful in locating optimization problems.
14715  When reporting a bug please maker sure you:
14716 \layout Enumerate
14717
14718 Attach the code you are compiling with SDCC.
14719
14720 \layout Enumerate
14721
14722 Specify the exact command you use to run SDCC, or attach your Makefile.
14723
14724 \layout Enumerate
14725
14726 Specify the SDCC version (type "sdcc -v"), your platform, and operating
14727  system.
14728
14729 \layout Enumerate
14730
14731 Provide an exact copy of any error message or incorrect output.
14732
14733 \layout Enumerate
14734
14735 Put something meaningful in the subject of your message.
14736 \layout Standard
14737
14738 Please attempt to include these 5 important parts, as applicable, in all
14739  requests for support or when reporting any problems or bugs with SDCC.
14740  Though this will make your message lengthy, it will greatly improve your
14741  chance that SDCC users and developers will be able to help you.
14742  Some SDCC developers are frustrated by bug reports without code provided
14743  that they can use to reproduce and ultimately fix the problem, so please
14744  be sure to provide sample code if you are reporting a bug!
14745 \layout Standard
14746
14747 Please have a short check that you are using a recent version of SDCC and
14748  the bug is not yet known.
14749  This is the link for reporting bugs:
14750 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
14751
14752 \end_inset
14753
14754 .
14755 \layout Subsection
14756
14757 Requesting Features
14758 \begin_inset LatexCommand \label{sub:Requesting-Features}
14759
14760 \end_inset
14761
14762
14763 \begin_inset LatexCommand \index{Feature request}
14764
14765 \end_inset
14766
14767
14768 \begin_inset LatexCommand \index{Requesting features}
14769
14770 \end_inset
14771
14772
14773 \layout Standard
14774
14775 Like bug reports feature requests are forwarded to the developer mailing
14776  list.
14777  This is the link for requesting features:
14778 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
14779
14780 \end_inset
14781
14782 .
14783 \layout Subsection
14784
14785 Getting Help
14786 \layout Standard
14787
14788 These links should take you directly to the
14789 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
14790
14791 \end_inset
14792
14793
14794 \begin_inset Foot
14795 collapsed false
14796
14797 \layout Standard
14798
14799 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
14800  automated messages (mid 2003)
14801 \end_inset
14802
14803  and the
14804 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
14805
14806 \end_inset
14807
14808 , lists and forums are archived so if you are lucky someone already had
14809  a similar problem.
14810 \layout Subsection
14811
14812 ChangeLog
14813 \begin_inset LatexCommand \index{Changelog}
14814
14815 \end_inset
14816
14817
14818 \layout Standard
14819
14820 You can follow the status of the cvs version
14821 \begin_inset LatexCommand \index{version}
14822
14823 \end_inset
14824
14825  of SDCC by watching the file
14826 \begin_inset LatexCommand \htmlurl[ChangeLog]{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
14827
14828 \end_inset
14829
14830  in the cvs-repository.
14831 \layout Subsection
14832
14833 Release policy
14834 \begin_inset LatexCommand \index{Release policy}
14835
14836 \end_inset
14837
14838
14839 \layout Standard
14840
14841 Historically there often were long delays between official releases and
14842  the sourceforge download area tends to get not updated at all.
14843  Current excuses might refer to problems with live range analysis, but if
14844  this is fixed, the next problem rising is that another excuse will have
14845  to be found.
14846  Kidding aside, we have to get better there! On the other hand there are
14847  daily snapshots available at
14848 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
14849
14850 \end_inset
14851
14852 , and you can always built the very last version (hopefully with many bugs
14853  fixed, and features added) from the source code available at
14854 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
14855
14856 \end_inset
14857
14858 .
14859 \layout Subsection
14860
14861 Examples
14862 \begin_inset LatexCommand \index{Examples}
14863
14864 \end_inset
14865
14866
14867 \layout Standard
14868
14869 You'll find some small examples in the directory
14870 \emph on
14871 sdcc/device/examples/.
14872
14873 \emph default
14874 More examples and libraries are available at
14875 \emph on
14876  The SDCC Open Knowledge Resource
14877 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
14878
14879 \end_inset
14880
14881
14882 \emph default
14883 web site or at
14884 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
14885
14886 \end_inset
14887
14888 .
14889 \layout Comment
14890
14891 I did insert a reference to Paul's web site here although it seems rather
14892  dedicated to a specific 8032 board (I think it's okay because it f.e.
14893  shows LCD/Harddisc interface and has a free 8051 monitor.
14894  Independent 8032 board vendors face hard competition of heavily subsidized
14895  development boards anyway).
14896 \layout Comment
14897
14898 Maybe we should include some links to real world applications.
14899  Preferably pointer to pointers (one for each architecture) so this stays
14900  manageable here?
14901 \layout Subsection
14902
14903 Quality control
14904 \begin_inset LatexCommand \index{Quality control}
14905
14906 \end_inset
14907
14908
14909 \layout Standard
14910
14911 The compiler is passed through nightly compile and build checks.
14912  The so called
14913 \shape italic
14914 regression tests
14915 \shape default
14916
14917 \begin_inset LatexCommand \index{Regression test}
14918
14919 \end_inset
14920
14921  check that SDCC itself compiles flawlessly on several platforms and checks
14922  the quality of the code generated by SDCC by running the code through simulator
14923 s.
14924  There is a separate document
14925 \shape italic
14926 test_suite.pdf
14927 \begin_inset LatexCommand \index{Test suite}
14928
14929 \end_inset
14930
14931
14932 \shape default
14933  about this.
14934 \layout Standard
14935
14936 You'll find the test code in the directory
14937 \shape italic
14938 sdcc/support/regression
14939 \shape default
14940 .
14941  You can run these tests manually by running
14942 \family sans
14943 make
14944 \family default
14945  in this directory (or f.e.
14946
14947 \family sans
14948 make test-mcs51
14949 \family default
14950  if you don't want to run the complete tests).
14951  The test code might also be interesting if you want to look for examples
14952 \begin_inset LatexCommand \index{Examples}
14953
14954 \end_inset
14955
14956  checking corner cases of SDCC or if you plan to submit patches
14957 \begin_inset LatexCommand \index{Patch submission}
14958
14959 \end_inset
14960
14961 .
14962 \layout Standard
14963
14964 The pic port uses a different set of regression tests, you'll find them
14965  in the directory
14966 \shape italic
14967 sdcc/src/regression
14968 \shape default
14969 .
14970 \layout Section
14971 \pagebreak_top
14972 SDCC Technical Data
14973 \layout Subsection
14974
14975 Optimizations
14976 \begin_inset LatexCommand \index{Optimizations}
14977
14978 \end_inset
14979
14980
14981 \layout Standard
14982
14983 SDCC performs a host of standard optimizations in addition to some MCU specific
14984  optimizations.
14985
14986 \layout Subsubsection
14987
14988 Sub-expression Elimination
14989 \begin_inset LatexCommand \index{Subexpression elimination}
14990
14991 \end_inset
14992
14993
14994 \layout Standard
14995
14996 The compiler does local and global common subexpression elimination, e.g.:
14997
14998 \layout Verse
14999
15000
15001 \family typewriter
15002 i = x + y + 1;
15003 \newline
15004 j = x + y;
15005 \layout Standard
15006
15007 will be translated to
15008 \layout Verse
15009
15010
15011 \family typewriter
15012 iTemp = x + y;
15013 \newline
15014 i = iTemp + 1;
15015 \newline
15016 j = iTemp;
15017 \layout Standard
15018
15019 Some subexpressions are not as obvious as the above example, e.g.:
15020 \layout Verse
15021
15022
15023 \family typewriter
15024 a->b[i].c = 10;
15025 \newline
15026 a->b[i].d = 11;
15027 \layout Standard
15028
15029 In this case the address arithmetic a->b[i] will be computed only once;
15030  the equivalent code in C would be.
15031 \layout Verse
15032
15033
15034 \family typewriter
15035 iTemp = a->b[i];
15036 \newline
15037 iTemp.c = 10;
15038 \newline
15039 iTemp.d = 11;
15040 \layout Standard
15041
15042 The compiler will try to keep these temporary variables in registers.
15043 \layout Subsubsection
15044
15045 Dead-Code Elimination
15046 \begin_inset LatexCommand \index{Dead-code elimination}
15047
15048 \end_inset
15049
15050
15051 \layout Verse
15052
15053
15054 \family typewriter
15055 int global;
15056 \newline
15057
15058 \newline
15059 void f () {
15060 \newline
15061 \SpecialChar ~
15062 \SpecialChar ~
15063 int i;
15064 \newline
15065 \SpecialChar ~
15066 \SpecialChar ~
15067 i = 1; \SpecialChar ~
15068 \SpecialChar ~
15069 \SpecialChar ~
15070 \SpecialChar ~
15071 \SpecialChar ~
15072 /* dead store */
15073 \newline
15074 \SpecialChar ~
15075 \SpecialChar ~
15076 global = 1;\SpecialChar ~
15077 /* dead store */
15078 \newline
15079 \SpecialChar ~
15080 \SpecialChar ~
15081 global = 2;
15082 \newline
15083 \SpecialChar ~
15084 \SpecialChar ~
15085 return;
15086 \newline
15087 \SpecialChar ~
15088 \SpecialChar ~
15089 global = 3;\SpecialChar ~
15090 /* unreachable */
15091 \newline
15092 }
15093 \layout Standard
15094
15095 will be changed to
15096 \layout Verse
15097
15098
15099 \family typewriter
15100 int global;
15101 \newline
15102
15103 \newline
15104 void f () {
15105 \newline
15106 \SpecialChar ~
15107 \SpecialChar ~
15108 global = 2;
15109 \newline
15110 \SpecialChar ~
15111 \SpecialChar ~
15112 return;
15113 \newline
15114 }
15115 \layout Subsubsection
15116
15117 Copy-Propagation
15118 \begin_inset LatexCommand \index{Copy propagation}
15119
15120 \end_inset
15121
15122
15123 \layout Verse
15124
15125
15126 \family typewriter
15127 int f() {
15128 \newline
15129 \SpecialChar ~
15130 \SpecialChar ~
15131 int i, j;
15132 \newline
15133 \SpecialChar ~
15134 \SpecialChar ~
15135 i = 10;
15136 \newline
15137 \SpecialChar ~
15138 \SpecialChar ~
15139 j = i;
15140 \newline
15141 \SpecialChar ~
15142 \SpecialChar ~
15143 return j;
15144 \newline
15145 }
15146 \layout Standard
15147
15148 will be changed to
15149 \layout Verse
15150
15151
15152 \family typewriter
15153 int f() {
15154 \newline
15155 \SpecialChar ~
15156 \SpecialChar ~
15157 int i, j;
15158 \newline
15159 \SpecialChar ~
15160 \SpecialChar ~
15161 i = 10;
15162 \newline
15163 \SpecialChar ~
15164 \SpecialChar ~
15165 j = 10;
15166 \newline
15167 \SpecialChar ~
15168 \SpecialChar ~
15169 return 10;
15170 \newline
15171 }
15172 \layout Standard
15173
15174 Note: the dead stores created by this copy propagation will be eliminated
15175  by dead-code elimination.
15176 \layout Subsubsection
15177
15178 Loop Optimizations
15179 \begin_inset LatexCommand \index{Loop optimization}
15180
15181 \end_inset
15182
15183
15184 \layout Standard
15185
15186 Two types of loop optimizations are done by SDCC loop invariant lifting
15187  and strength reduction of loop induction variables.
15188  In addition to the strength reduction the optimizer marks the induction
15189  variables and the register allocator tries to keep the induction variables
15190  in registers for the duration of the loop.
15191  Because of this preference of the register allocator
15192 \begin_inset LatexCommand \index{Register allocation}
15193
15194 \end_inset
15195
15196 , loop induction optimization causes an increase in register pressure, which
15197  may cause unwanted spilling of other temporary variables into the stack
15198 \begin_inset LatexCommand \index{stack}
15199
15200 \end_inset
15201
15202  / data space.
15203  The compiler will generate a warning message when it is forced to allocate
15204  extra space either on the stack or data space.
15205  If this extra space allocation is undesirable then induction optimization
15206  can be eliminated either for the entire source file (with -
15207 \begin_inset ERT
15208 status Collapsed
15209
15210 \layout Standard
15211
15212 \backslash
15213 /
15214 \end_inset
15215
15216 -noinduction option) or for a given function only using #pragma\SpecialChar ~
15217 NOINDUCTION
15218 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
15219
15220 \end_inset
15221
15222 .
15223 \newline
15224
15225 \newline
15226 Loop Invariant:
15227 \layout Verse
15228
15229
15230 \family typewriter
15231 for (i = 0 ; i < 100 ; i ++)
15232 \newline
15233 \SpecialChar ~
15234 \SpecialChar ~
15235 \SpecialChar ~
15236 \SpecialChar ~
15237 f += k + l;
15238 \layout Standard
15239
15240 changed to
15241 \layout Verse
15242
15243
15244 \family typewriter
15245 itemp = k + l;
15246 \newline
15247 for (i = 0; i < 100; i++)
15248 \newline
15249 \SpecialChar ~
15250 \SpecialChar ~
15251 \SpecialChar ~
15252 \SpecialChar ~
15253 f += itemp;
15254 \layout Standard
15255
15256 As mentioned previously some loop invariants are not as apparent, all static
15257  address computations are also moved out of the loop.
15258 \newline
15259
15260 \newline
15261 Strength Reduction
15262 \begin_inset LatexCommand \index{Strength reduction}
15263
15264 \end_inset
15265
15266 , this optimization substitutes an expression by a cheaper expression:
15267 \layout Verse
15268
15269
15270 \family typewriter
15271 for (i=0;i < 100; i++)
15272 \newline
15273 \SpecialChar ~
15274 \SpecialChar ~
15275 \SpecialChar ~
15276 \SpecialChar ~
15277 ar[i*5] = i*3;
15278 \layout Standard
15279
15280 changed to
15281 \layout Verse
15282
15283
15284 \family typewriter
15285 itemp1 = 0;
15286 \newline
15287 itemp2 = 0;
15288 \newline
15289 for (i=0;i< 100;i++) {
15290 \newline
15291 \SpecialChar ~
15292 \SpecialChar ~
15293 \SpecialChar ~
15294 \SpecialChar ~
15295 ar[itemp1] = itemp2;
15296 \newline
15297 \SpecialChar ~
15298 \SpecialChar ~
15299 \SpecialChar ~
15300 \SpecialChar ~
15301 itemp1 += 5;
15302 \newline
15303 \SpecialChar ~
15304 \SpecialChar ~
15305 \SpecialChar ~
15306 \SpecialChar ~
15307 itemp2 += 3;
15308 \newline
15309 }
15310 \layout Standard
15311
15312 The more expensive multiplication
15313 \begin_inset LatexCommand \index{Multiplication}
15314
15315 \end_inset
15316
15317  is changed to a less expensive addition.
15318 \layout Subsubsection
15319
15320 Loop Reversing
15321 \begin_inset LatexCommand \index{Loop reversing}
15322
15323 \end_inset
15324
15325
15326 \layout Standard
15327
15328 This optimization is done to reduce the overhead of checking loop boundaries
15329  for every iteration.
15330  Some simple loops can be reversed and implemented using a
15331 \begin_inset Quotes eld
15332 \end_inset
15333
15334 decrement and jump if not zero
15335 \begin_inset Quotes erd
15336 \end_inset
15337
15338  instruction.
15339  SDCC checks for the following criterion to determine if a loop is reversible
15340  (note: more sophisticated compilers use data-dependency analysis to make
15341  this determination, SDCC uses a more simple minded analysis).
15342 \layout Itemize
15343
15344 The 'for' loop is of the form
15345 \newline
15346
15347 \newline
15348
15349 \family typewriter
15350 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
15351  += 1])
15352 \newline
15353 \SpecialChar ~
15354 \SpecialChar ~
15355 \SpecialChar ~
15356 \SpecialChar ~
15357 <for body>
15358 \layout Itemize
15359
15360 The <for body> does not contain
15361 \begin_inset Quotes eld
15362 \end_inset
15363
15364 continue
15365 \begin_inset Quotes erd
15366 \end_inset
15367
15368  or 'break
15369 \begin_inset Quotes erd
15370 \end_inset
15371
15372 .
15373 \layout Itemize
15374
15375 All goto's are contained within the loop.
15376 \layout Itemize
15377
15378 No function calls within the loop.
15379 \layout Itemize
15380
15381 The loop control variable <sym> is not assigned any value within the loop
15382 \layout Itemize
15383
15384 The loop control variable does NOT participate in any arithmetic operation
15385  within the loop.
15386 \layout Itemize
15387
15388 There are NO switch statements in the loop.
15389 \layout Subsubsection
15390
15391 Algebraic Simplifications
15392 \layout Standard
15393
15394 SDCC does numerous algebraic simplifications, the following is a small sub-set
15395  of these optimizations.
15396 \layout Verse
15397
15398
15399 \family typewriter
15400 i = j + 0 ; /* changed to */ i = j;
15401 \newline
15402 i /= 2;\SpecialChar ~
15403 \SpecialChar ~
15404 \SpecialChar ~
15405 \SpecialChar ~
15406  /* changed to */ i >>= 1;
15407 \newline
15408 i = j - j ; /* changed to */ i = 0;
15409 \newline
15410 i = j / 1 ; /* changed to */ i = j;
15411 \layout Standard
15412
15413 Note the subexpressions
15414 \begin_inset LatexCommand \index{Subexpression}
15415
15416 \end_inset
15417
15418  given above are generally introduced by macro expansions or as a result
15419  of copy/constant propagation.
15420 \layout Subsubsection
15421
15422 'switch' Statements
15423 \begin_inset LatexCommand \label{sub:'switch'-Statements}
15424
15425 \end_inset
15426
15427
15428 \begin_inset LatexCommand \index{switch statement}
15429
15430 \end_inset
15431
15432
15433 \layout Standard
15434
15435 SDCC changes switch statements to jump tables
15436 \begin_inset LatexCommand \index{jump tables}
15437
15438 \end_inset
15439
15440  when the following conditions are true.
15441
15442 \layout Itemize
15443
15444 The case labels are in numerical sequence, the labels need not be in order,
15445  and the starting number need not be one or zero.
15446 \begin_deeper
15447 \layout Verse
15448
15449
15450 \family typewriter
15451 switch(i) {\SpecialChar ~
15452 \SpecialChar ~
15453 \SpecialChar ~
15454 \SpecialChar ~
15455 \SpecialChar ~
15456 \SpecialChar ~
15457 \SpecialChar ~
15458 \SpecialChar ~
15459 \SpecialChar ~
15460 \SpecialChar ~
15461 \SpecialChar ~
15462 \SpecialChar ~
15463 \SpecialChar ~
15464 \SpecialChar ~
15465 \SpecialChar ~
15466 \SpecialChar ~
15467 \SpecialChar ~
15468 \SpecialChar ~
15469 \SpecialChar ~
15470 \SpecialChar ~
15471 \SpecialChar ~
15472 \SpecialChar ~
15473 \SpecialChar ~
15474 \SpecialChar ~
15475 \SpecialChar ~
15476 \SpecialChar ~
15477 switch (i) {
15478 \newline
15479 \SpecialChar ~
15480 \SpecialChar ~
15481 \SpecialChar ~
15482 case 4: ...\SpecialChar ~
15483 \SpecialChar ~
15484 \SpecialChar ~
15485 \SpecialChar ~
15486 \SpecialChar ~
15487 \SpecialChar ~
15488 \SpecialChar ~
15489 \SpecialChar ~
15490 \SpecialChar ~
15491 \SpecialChar ~
15492 \SpecialChar ~
15493 \SpecialChar ~
15494 \SpecialChar ~
15495 \SpecialChar ~
15496 \SpecialChar ~
15497 \SpecialChar ~
15498 \SpecialChar ~
15499 \SpecialChar ~
15500 \SpecialChar ~
15501 \SpecialChar ~
15502 \SpecialChar ~
15503 \SpecialChar ~
15504 \SpecialChar ~
15505 \SpecialChar ~
15506 \SpecialChar ~
15507 \SpecialChar ~
15508 case 0: ...
15509
15510 \newline
15511 \SpecialChar ~
15512 \SpecialChar ~
15513 \SpecialChar ~
15514 case 5: ...\SpecialChar ~
15515 \SpecialChar ~
15516 \SpecialChar ~
15517 \SpecialChar ~
15518 \SpecialChar ~
15519 \SpecialChar ~
15520 \SpecialChar ~
15521 \SpecialChar ~
15522 \SpecialChar ~
15523 \SpecialChar ~
15524 \SpecialChar ~
15525 \SpecialChar ~
15526 \SpecialChar ~
15527 \SpecialChar ~
15528 \SpecialChar ~
15529 \SpecialChar ~
15530 \SpecialChar ~
15531 \SpecialChar ~
15532 \SpecialChar ~
15533 \SpecialChar ~
15534 \SpecialChar ~
15535 \SpecialChar ~
15536 \SpecialChar ~
15537 \SpecialChar ~
15538 \SpecialChar ~
15539 \SpecialChar ~
15540 case 1: ...
15541
15542 \newline
15543 \SpecialChar ~
15544 \SpecialChar ~
15545 \SpecialChar ~
15546 case 3: ...\SpecialChar ~
15547 \SpecialChar ~
15548 \SpecialChar ~
15549 \SpecialChar ~
15550 \SpecialChar ~
15551 \SpecialChar ~
15552 \SpecialChar ~
15553 \SpecialChar ~
15554 \SpecialChar ~
15555 \SpecialChar ~
15556 \SpecialChar ~
15557 \SpecialChar ~
15558 \SpecialChar ~
15559 \SpecialChar ~
15560 \SpecialChar ~
15561 \SpecialChar ~
15562 \SpecialChar ~
15563 \SpecialChar ~
15564 \SpecialChar ~
15565 \SpecialChar ~
15566 \SpecialChar ~
15567 \SpecialChar ~
15568 \SpecialChar ~
15569 \SpecialChar ~
15570 \SpecialChar ~
15571 \SpecialChar ~
15572 case 2: ...
15573
15574 \newline
15575 \SpecialChar ~
15576 \SpecialChar ~
15577 \SpecialChar ~
15578 case 6: ...\SpecialChar ~
15579 \SpecialChar ~
15580 \SpecialChar ~
15581 \SpecialChar ~
15582 \SpecialChar ~
15583 \SpecialChar ~
15584 \SpecialChar ~
15585 \SpecialChar ~
15586 \SpecialChar ~
15587 \SpecialChar ~
15588 \SpecialChar ~
15589 \SpecialChar ~
15590 \SpecialChar ~
15591 \SpecialChar ~
15592 \SpecialChar ~
15593 \SpecialChar ~
15594 \SpecialChar ~
15595 \SpecialChar ~
15596 \SpecialChar ~
15597 \SpecialChar ~
15598 \SpecialChar ~
15599 \SpecialChar ~
15600 \SpecialChar ~
15601 \SpecialChar ~
15602 \SpecialChar ~
15603 \SpecialChar ~
15604 case 3: ...
15605
15606 \newline
15607 }\SpecialChar ~
15608 \SpecialChar ~
15609 \SpecialChar ~
15610 \SpecialChar ~
15611 \SpecialChar ~
15612 \SpecialChar ~
15613 \SpecialChar ~
15614 \SpecialChar ~
15615 \SpecialChar ~
15616 \SpecialChar ~
15617 \SpecialChar ~
15618 \SpecialChar ~
15619 \SpecialChar ~
15620 \SpecialChar ~
15621 \SpecialChar ~
15622 \SpecialChar ~
15623 \SpecialChar ~
15624 \SpecialChar ~
15625 \SpecialChar ~
15626 \SpecialChar ~
15627 \SpecialChar ~
15628 \SpecialChar ~
15629 \SpecialChar ~
15630 \SpecialChar ~
15631 \SpecialChar ~
15632 \SpecialChar ~
15633 \SpecialChar ~
15634 \SpecialChar ~
15635 \SpecialChar ~
15636 \SpecialChar ~
15637 \SpecialChar ~
15638 \SpecialChar ~
15639 \SpecialChar ~
15640 \SpecialChar ~
15641 \SpecialChar ~
15642 \SpecialChar ~
15643 }
15644 \layout Standard
15645
15646 Both the above switch statements will be implemented using a jump-table.
15647  The example to the right side is slightly more efficient as the check for
15648  the lower boundary of the jump-table is not needed.
15649 \end_deeper
15650 \layout Itemize
15651
15652 The number of case labels is at least three, since it takes two conditional
15653  statements to handle the boundary conditions.
15654 \layout Itemize
15655
15656 The number of case labels is less than 84, since each label takes 3 bytes
15657  and a jump-table can be utmost 256 bytes long.
15658 \layout Standard
15659
15660 Switch statements which have gaps in the numeric sequence or those that
15661  have more that 84 case labels can be split into more than one switch statement
15662  for efficient code generation, e.g.:
15663 \layout Verse
15664
15665
15666 \family typewriter
15667 switch (i) {
15668 \newline
15669 \SpecialChar ~
15670 \SpecialChar ~
15671 case 1: ...
15672
15673 \newline
15674 \SpecialChar ~
15675 \SpecialChar ~
15676 case 2: ...
15677
15678 \newline
15679 \SpecialChar ~
15680 \SpecialChar ~
15681 case 3: ...
15682
15683 \newline
15684 \SpecialChar ~
15685 \SpecialChar ~
15686 case 4: ...
15687
15688 \newline
15689 \SpecialChar ~
15690 \SpecialChar ~
15691 case 9: ...
15692
15693 \newline
15694 \SpecialChar ~
15695 \SpecialChar ~
15696 case 10: ...
15697
15698 \newline
15699 \SpecialChar ~
15700 \SpecialChar ~
15701 case 11: ...
15702
15703 \newline
15704 \SpecialChar ~
15705 \SpecialChar ~
15706 case 12: ...
15707
15708 \newline
15709 }
15710 \layout Standard
15711
15712 If the above switch statement is broken down into two switch statements
15713 \layout Verse
15714
15715
15716 \family typewriter
15717 switch (i) {
15718 \newline
15719 \SpecialChar ~
15720 \SpecialChar ~
15721 case 1: ...
15722
15723 \newline
15724 \SpecialChar ~
15725 \SpecialChar ~
15726 case 2: ...
15727
15728 \newline
15729 \SpecialChar ~
15730 \SpecialChar ~
15731 case 3: ...
15732
15733 \newline
15734 \SpecialChar ~
15735 \SpecialChar ~
15736 case 4: ...
15737
15738 \newline
15739 }
15740 \layout Standard
15741
15742 and
15743 \layout Verse
15744
15745
15746 \family typewriter
15747 switch (i) {
15748 \newline
15749 \SpecialChar ~
15750 \SpecialChar ~
15751 case 9:\SpecialChar ~
15752 \SpecialChar ~
15753 ...
15754
15755 \newline
15756 \SpecialChar ~
15757 \SpecialChar ~
15758 case 10:\SpecialChar ~
15759 ...
15760
15761 \newline
15762 \SpecialChar ~
15763 \SpecialChar ~
15764 case 11:\SpecialChar ~
15765 ...
15766
15767 \newline
15768 \SpecialChar ~
15769 \SpecialChar ~
15770 case 12:\SpecialChar ~
15771 ...
15772
15773 \newline
15774 }
15775 \layout Standard
15776
15777 then both the switch statements will be implemented using jump-tables whereas
15778  the unmodified switch statement will not be.
15779  You might also consider dummy cases 0 and 5 to 8 in this example.
15780
15781 \newline
15782 The pragma NOJTBOUND
15783 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
15784
15785 \end_inset
15786
15787  can be used to turn off checking the
15788 \emph on
15789 j
15790 \emph default
15791 ump
15792 \emph on
15793 t
15794 \emph default
15795 able
15796 \emph on
15797 bound
15798 \emph default
15799 aries.
15800  It has no effect if a default label is supplied.
15801  Use of this pragma is dangerous: if the switch argument is not matched
15802  by a case statement the processor will happily jump into Nirvana.
15803 \layout Subsubsection
15804
15805 Bit-shifting Operations
15806 \begin_inset LatexCommand \index{Bit shifting}
15807
15808 \end_inset
15809
15810 .
15811 \layout Standard
15812
15813 Bit shifting is one of the most frequently used operation in embedded programmin
15814 g.
15815  SDCC tries to implement bit-shift operations in the most efficient way
15816  possible, e.g.:
15817 \layout Verse
15818
15819
15820 \family typewriter
15821 unsigned char i;
15822 \newline
15823 ...
15824
15825 \newline
15826 i >>= 4;
15827 \newline
15828 ...
15829 \layout Standard
15830
15831 generates the following code:
15832 \layout Verse
15833
15834
15835 \family typewriter
15836 mov\SpecialChar ~
15837  a,_i
15838 \newline
15839 swap a
15840 \newline
15841 anl\SpecialChar ~
15842  a,#0x0f
15843 \newline
15844 mov\SpecialChar ~
15845  _i,a
15846 \layout Standard
15847
15848 In general SDCC will never setup a loop if the shift count is known.
15849  Another example:
15850 \layout Verse
15851
15852
15853 \family typewriter
15854 unsigned int i;
15855 \newline
15856 ...
15857
15858 \newline
15859 i >>= 9;
15860 \newline
15861 ...
15862 \layout Standard
15863
15864 will generate:
15865 \layout Verse
15866
15867
15868 \family typewriter
15869 mov\SpecialChar ~
15870 \SpecialChar ~
15871 a,(_i + 1)
15872 \newline
15873 mov\SpecialChar ~
15874 \SpecialChar ~
15875 (_i + 1),#0x00
15876 \newline
15877 clr\SpecialChar ~
15878 \SpecialChar ~
15879 c
15880 \newline
15881 rrc\SpecialChar ~
15882 \SpecialChar ~
15883 a
15884 \newline
15885 mov\SpecialChar ~
15886 \SpecialChar ~
15887 _i,a
15888 \layout Standard
15889
15890 Note that SDCC stores numbers in little-endian
15891 \begin_inset Foot
15892 collapsed false
15893
15894 \layout Standard
15895
15896 Usually 8-bit processors don't care much about endianness.
15897  This is not the case for the standard 8051 which only has an instruction
15898  to increment its
15899 \emph on
15900 dptr
15901 \emph default
15902
15903 \begin_inset LatexCommand \index{DPTR}
15904
15905 \end_inset
15906
15907 -datapointer
15908 \emph on
15909
15910 \emph default
15911 so little-endian is the more efficient byte order.
15912 \end_inset
15913
15914
15915 \begin_inset LatexCommand \index{little-endian}
15916
15917 \end_inset
15918
15919
15920 \begin_inset LatexCommand \index{Endianness}
15921
15922 \end_inset
15923
15924  format (i.e.
15925  lowest order first).
15926 \layout Subsubsection
15927
15928 Bit-rotation
15929 \begin_inset LatexCommand \index{Bit rotation}
15930
15931 \end_inset
15932
15933
15934 \layout Standard
15935
15936 A special case of the bit-shift operation is bit rotation, SDCC recognizes
15937  the following expression to be a left bit-rotation:
15938 \layout Verse
15939
15940
15941 \family typewriter
15942 unsigned char i;
15943 \newline
15944 ...
15945
15946 \newline
15947 i = ((i << 1) | (i >> 7));
15948 \family default
15949
15950 \newline
15951
15952 \family typewriter
15953 ...
15954 \layout Standard
15955
15956 will generate the following code:
15957 \layout Verse
15958
15959
15960 \family typewriter
15961 mov\SpecialChar ~
15962 \SpecialChar ~
15963 a,_i
15964 \newline
15965 rl\SpecialChar ~
15966 \SpecialChar ~
15967 \SpecialChar ~
15968 a
15969 \newline
15970 mov\SpecialChar ~
15971 \SpecialChar ~
15972 _i,a
15973 \layout Standard
15974
15975 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
15976 ns of this case will also be recognized as bit-rotation, i.e.:
15977 \layout Verse
15978
15979
15980 \family typewriter
15981 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
15982 \layout Subsubsection
15983
15984 Highest Order Bit
15985 \begin_inset LatexCommand \index{Highest Order Bit}
15986
15987 \end_inset
15988
15989
15990 \layout Standard
15991
15992 It is frequently required to obtain the highest order bit of an integral
15993  type (long, int, short or char types).
15994  SDCC recognizes the following expression to yield the highest order bit
15995  and generates optimized code for it, e.g.:
15996 \layout Verse
15997
15998
15999 \family typewriter
16000 unsigned int gint;
16001 \newline
16002
16003 \newline
16004 foo () {
16005 \newline
16006 \SpecialChar ~
16007 \SpecialChar ~
16008 unsigned char hob;
16009 \newline
16010 \SpecialChar ~
16011 \SpecialChar ~
16012 ...
16013
16014 \newline
16015 \SpecialChar ~
16016 \SpecialChar ~
16017 hob = (gint >> 15) & 1;
16018 \newline
16019 \SpecialChar ~
16020 \SpecialChar ~
16021 ..
16022
16023 \newline
16024 }
16025 \layout Standard
16026
16027 will generate the following code:
16028 \layout Verse
16029
16030
16031 \family typewriter
16032 \SpecialChar ~
16033 \SpecialChar ~
16034 \SpecialChar ~
16035 \SpecialChar ~
16036 \SpecialChar ~
16037 \SpecialChar ~
16038 \SpecialChar ~
16039 \SpecialChar ~
16040 \SpecialChar ~
16041 \SpecialChar ~
16042 \SpecialChar ~
16043 \SpecialChar ~
16044 \SpecialChar ~
16045 \SpecialChar ~
16046 \SpecialChar ~
16047 \SpecialChar ~
16048 \SpecialChar ~
16049 \SpecialChar ~
16050 \SpecialChar ~
16051 \SpecialChar ~
16052 \SpecialChar ~
16053 \SpecialChar ~
16054 \SpecialChar ~
16055 \SpecialChar ~
16056 \SpecialChar ~
16057  61 ;\SpecialChar ~
16058  hob.c 7
16059 \newline
16060 000A E5*01\SpecialChar ~
16061 \SpecialChar ~
16062 \SpecialChar ~
16063 \SpecialChar ~
16064 \SpecialChar ~
16065 \SpecialChar ~
16066 \SpecialChar ~
16067 \SpecialChar ~
16068 \SpecialChar ~
16069 \SpecialChar ~
16070 \SpecialChar ~
16071 \SpecialChar ~
16072 \SpecialChar ~
16073 \SpecialChar ~
16074 \SpecialChar ~
16075  62\SpecialChar ~
16076 \SpecialChar ~
16077 \SpecialChar ~
16078 \SpecialChar ~
16079 \SpecialChar ~
16080 \SpecialChar ~
16081 \SpecialChar ~
16082 \SpecialChar ~
16083  mov\SpecialChar ~
16084 \SpecialChar ~
16085  a,(_gint + 1)
16086 \newline
16087 000C 23\SpecialChar ~
16088 \SpecialChar ~
16089 \SpecialChar ~
16090 \SpecialChar ~
16091 \SpecialChar ~
16092 \SpecialChar ~
16093 \SpecialChar ~
16094 \SpecialChar ~
16095 \SpecialChar ~
16096 \SpecialChar ~
16097 \SpecialChar ~
16098 \SpecialChar ~
16099 \SpecialChar ~
16100 \SpecialChar ~
16101 \SpecialChar ~
16102 \SpecialChar ~
16103 \SpecialChar ~
16104 \SpecialChar ~
16105  63\SpecialChar ~
16106 \SpecialChar ~
16107 \SpecialChar ~
16108 \SpecialChar ~
16109 \SpecialChar ~
16110 \SpecialChar ~
16111 \SpecialChar ~
16112 \SpecialChar ~
16113  rl\SpecialChar ~
16114 \SpecialChar ~
16115 \SpecialChar ~
16116  a
16117 \newline
16118 000D 54 01\SpecialChar ~
16119 \SpecialChar ~
16120 \SpecialChar ~
16121 \SpecialChar ~
16122 \SpecialChar ~
16123 \SpecialChar ~
16124 \SpecialChar ~
16125 \SpecialChar ~
16126 \SpecialChar ~
16127 \SpecialChar ~
16128 \SpecialChar ~
16129 \SpecialChar ~
16130 \SpecialChar ~
16131 \SpecialChar ~
16132 \SpecialChar ~
16133  64\SpecialChar ~
16134 \SpecialChar ~
16135 \SpecialChar ~
16136 \SpecialChar ~
16137 \SpecialChar ~
16138 \SpecialChar ~
16139 \SpecialChar ~
16140 \SpecialChar ~
16141  anl\SpecialChar ~
16142 \SpecialChar ~
16143  a,#0x01
16144 \newline
16145 000F F5*02\SpecialChar ~
16146 \SpecialChar ~
16147 \SpecialChar ~
16148 \SpecialChar ~
16149 \SpecialChar ~
16150 \SpecialChar ~
16151 \SpecialChar ~
16152 \SpecialChar ~
16153 \SpecialChar ~
16154 \SpecialChar ~
16155 \SpecialChar ~
16156 \SpecialChar ~
16157 \SpecialChar ~
16158 \SpecialChar ~
16159 \SpecialChar ~
16160  65\SpecialChar ~
16161 \SpecialChar ~
16162 \SpecialChar ~
16163 \SpecialChar ~
16164 \SpecialChar ~
16165 \SpecialChar ~
16166 \SpecialChar ~
16167 \SpecialChar ~
16168  mov\SpecialChar ~
16169 \SpecialChar ~
16170  _foo_hob_1_1,a
16171 \layout Standard
16172
16173 Variations of this case however will
16174 \emph on
16175 not
16176 \emph default
16177  be recognized.
16178  It is a standard C expression, so I heartily recommend this be the only
16179  way to get the highest order bit, (it is portable).
16180  Of course it will be recognized even if it is embedded in other expressions,
16181  e.g.:
16182 \layout Verse
16183
16184
16185 \family typewriter
16186 xyz = gint + ((gint >> 15) & 1);
16187 \layout Standard
16188
16189 will still be recognized.
16190 \layout Subsubsection
16191
16192 Peephole Optimizer
16193 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
16194
16195 \end_inset
16196
16197
16198 \begin_inset LatexCommand \index{Peephole optimizer}
16199
16200 \end_inset
16201
16202
16203 \layout Standard
16204
16205 The compiler uses a rule based, pattern matching and re-writing mechanism
16206  for peep-hole optimization.
16207  It is inspired by
16208 \emph on
16209 copt
16210 \emph default
16211  a peep-hole optimizer by Christopher W.
16212  Fraser (cwfraser@microsoft.com).
16213  A default set of rules are compiled into the compiler, additional rules
16214  may be added with the
16215 \emph on
16216 -
16217 \begin_inset ERT
16218 status Collapsed
16219
16220 \layout Standard
16221
16222 \backslash
16223 /
16224 \end_inset
16225
16226 -peep-file
16227 \begin_inset LatexCommand \index{-\/-peep-file}
16228
16229 \end_inset
16230
16231  <filename>
16232 \emph default
16233  option.
16234  The rule language is best illustrated with examples.
16235 \layout Verse
16236
16237
16238 \family typewriter
16239 replace {
16240 \newline
16241 \SpecialChar ~
16242 \SpecialChar ~
16243 mov %1,a
16244 \newline
16245 \SpecialChar ~
16246 \SpecialChar ~
16247 mov a,%1
16248 \newline
16249 } by {
16250 \newline
16251 \SpecialChar ~
16252 \SpecialChar ~
16253 mov %1,a
16254 \newline
16255 }
16256 \layout Standard
16257
16258 The above rule will change the following assembly
16259 \begin_inset LatexCommand \index{Assembler routines}
16260
16261 \end_inset
16262
16263  sequence:
16264 \layout Verse
16265
16266
16267 \family typewriter
16268 mov r1,a
16269 \newline
16270 mov a,r1
16271 \layout Standard
16272
16273 to
16274 \layout Verse
16275
16276
16277 \family typewriter
16278 mov r1,a
16279 \layout Standard
16280
16281 Note: All occurrences of a
16282 \emph on
16283 %n
16284 \emph default
16285  (pattern variable) must denote the same string.
16286  With the above rule, the assembly sequence:
16287 \layout Verse
16288
16289
16290 \family typewriter
16291 mov r1,a
16292 \newline
16293 mov a,r2
16294 \layout Standard
16295
16296 will remain unmodified.
16297 \newline
16298
16299 \newline
16300 Other special case optimizations may be added by the user (via
16301 \emph on
16302 -
16303 \begin_inset ERT
16304 status Collapsed
16305
16306 \layout Standard
16307
16308 \backslash
16309 /
16310 \end_inset
16311
16312 -peep-file option
16313 \emph default
16314 ).
16315  E.g.
16316  some variants of the 8051 MCU allow only
16317 \family typewriter
16318 ajmp
16319 \family default
16320  and
16321 \family typewriter
16322 acall
16323 \family default
16324 .
16325  The following two rules will change all
16326 \family typewriter
16327 ljmp
16328 \family default
16329  and
16330 \family typewriter
16331 lcall
16332 \family default
16333  to
16334 \family typewriter
16335 ajmp
16336 \family default
16337  and
16338 \family typewriter
16339 acall
16340 \layout Verse
16341
16342
16343 \family typewriter
16344 replace { lcall %1 } by { acall %1 }
16345 \newline
16346 replace { ljmp %1 } by { ajmp %1 }
16347 \layout Standard
16348
16349 The
16350 \emph on
16351 inline-assembler code
16352 \emph default
16353  is also passed through the peep hole optimizer, thus the peephole optimizer
16354  can also be used as an assembly level macro expander.
16355  The rules themselves are MCU dependent whereas the rule language infra-structur
16356 e is MCU independent.
16357  Peephole optimization rules for other MCU can be easily programmed using
16358  the rule language.
16359 \newline
16360
16361 \newline
16362 The syntax for a rule is as follows:
16363 \layout Verse
16364
16365
16366 \family typewriter
16367 rule := replace [ restart ] '{' <assembly sequence> '
16368 \backslash
16369 n'
16370 \newline
16371 \SpecialChar ~
16372  \SpecialChar ~
16373  \SpecialChar ~
16374  \SpecialChar ~
16375  \SpecialChar ~
16376  \SpecialChar ~
16377  \SpecialChar ~
16378  \SpecialChar ~
16379  \SpecialChar ~
16380  \SpecialChar ~
16381  \SpecialChar ~
16382  \SpecialChar ~
16383  \SpecialChar ~
16384  \SpecialChar ~
16385  '}' by '{' '
16386 \backslash
16387 n'
16388 \newline
16389 \SpecialChar ~
16390  \SpecialChar ~
16391  \SpecialChar ~
16392  \SpecialChar ~
16393  \SpecialChar ~
16394  \SpecialChar ~
16395  \SpecialChar ~
16396  \SpecialChar ~
16397  \SpecialChar ~
16398  \SpecialChar ~
16399  \SpecialChar ~
16400  \SpecialChar ~
16401  \SpecialChar ~
16402  \SpecialChar ~
16403  \SpecialChar ~
16404  \SpecialChar ~
16405  <assembly sequence> '
16406 \backslash
16407 n'
16408 \newline
16409 \SpecialChar ~
16410  \SpecialChar ~
16411  \SpecialChar ~
16412  \SpecialChar ~
16413  \SpecialChar ~
16414  \SpecialChar ~
16415  \SpecialChar ~
16416  \SpecialChar ~
16417  \SpecialChar ~
16418  \SpecialChar ~
16419  \SpecialChar ~
16420  \SpecialChar ~
16421  \SpecialChar ~
16422  \SpecialChar ~
16423  '}' [if <functionName> ] '
16424 \backslash
16425 n'
16426 \layout Standard
16427
16428 <assembly sequence> := assembly instruction (each instruction including
16429  labels must be on a separate line).
16430 \newline
16431
16432 \newline
16433 The optimizer will apply to the rules one by one from the top in the sequence
16434  of their appearance, it will terminate when all rules are exhausted.
16435  If the 'restart' option is specified, then the optimizer will start matching
16436  the rules again from the top, this option for a rule is expensive (performance)
16437 , it is intended to be used in situations where a transformation will trigger
16438  the same rule again.
16439  An example of this (not a good one, it has side effects) is the following
16440  rule:
16441 \layout Verse
16442
16443
16444 \family typewriter
16445 replace restart {
16446 \newline
16447 \SpecialChar ~
16448 \SpecialChar ~
16449 pop %1
16450 \newline
16451 \SpecialChar ~
16452 \SpecialChar ~
16453 push %1 } by {
16454 \newline
16455 \SpecialChar ~
16456 \SpecialChar ~
16457 ; nop
16458 \newline
16459 }
16460 \layout Standard
16461
16462 Note that the replace pattern cannot be a blank, but can be a comment line.
16463  Without the 'restart' option only the inner most 'pop' 'push' pair would
16464  be eliminated, i.e.:
16465 \layout Verse
16466
16467
16468 \family typewriter
16469 pop ar1
16470 \newline
16471 pop ar2
16472 \newline
16473 push ar2
16474 \newline
16475 push ar1
16476 \layout Standard
16477
16478 would result in:
16479 \layout Verse
16480
16481
16482 \family typewriter
16483 pop ar1
16484 \newline
16485 ; nop
16486 \newline
16487 push ar1
16488 \layout Standard
16489
16490
16491 \emph on
16492 with
16493 \emph default
16494  the restart option the rule will be applied again to the resulting code
16495  and then all the pop-push pairs will be eliminated to yield:
16496 \layout Verse
16497
16498
16499 \family typewriter
16500 ; nop
16501 \newline
16502 ; nop
16503 \layout Standard
16504
16505 A conditional function can be attached to a rule.
16506  Attaching rules are somewhat more involved, let me illustrate this with
16507  an example.
16508 \layout Verse
16509
16510
16511 \family typewriter
16512 replace {
16513 \newline
16514 \SpecialChar ~
16515  \SpecialChar ~
16516  \SpecialChar ~
16517 ljmp %5
16518 \newline
16519 %2:
16520 \newline
16521 } by {
16522 \newline
16523 \SpecialChar ~
16524  \SpecialChar ~
16525  \SpecialChar ~
16526 sjmp %5
16527 \newline
16528 %2:
16529 \newline
16530 } if labelInRange
16531 \layout Standard
16532
16533 The optimizer does a look-up of a function name table defined in function
16534
16535 \emph on
16536 callFuncByName
16537 \emph default
16538  in the source file SDCCpeeph.c, with the name
16539 \emph on
16540 labelInRange
16541 \emph default
16542 .
16543  If it finds a corresponding entry the function is called.
16544  Note there can be no parameters specified for these functions, in this
16545  case the use of
16546 \emph on
16547 %5
16548 \emph default
16549  is crucial, since the function
16550 \emph on
16551 labelInRange
16552 \emph default
16553  expects to find the label in that particular variable (the hash table containin
16554 g the variable bindings is passed as a parameter).
16555  If you want to code more such functions, take a close look at the function
16556  labelInRange and the calling mechanism in source file SDCCpeeph.c.
16557  Currently implemented are
16558 \emph on
16559 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
16560  24bitMode, portIsDS390, 24bitModeAndPortDS390
16561 \emph default
16562 and
16563 \emph on
16564  notVolatile
16565 \emph default
16566 .
16567 \layout Standard
16568
16569 I know this whole thing is a little kludgey, but maybe some day we will
16570  have some better means.
16571  If you are looking at this file, you will see the default rules that are
16572  compiled into the compiler, you can add your own rules in the default set
16573  there if you get tired of specifying the -
16574 \begin_inset ERT
16575 status Collapsed
16576
16577 \layout Standard
16578
16579 \backslash
16580 /
16581 \end_inset
16582
16583 -peep-file option.
16584 \layout Subsection
16585
16586 Library Routines
16587 \emph on
16588
16589 \layout Standard
16590
16591
16592 \emph on
16593 <pending: this is messy and incomplete>
16594 \emph default
16595
16596 \layout Enumerate
16597
16598 Compiler support routines (_gptrget, _mulint etc)
16599 \layout Enumerate
16600
16601 Stdclib functions (puts, printf, strcat etc)
16602 \layout Enumerate
16603
16604 Math functions (sin, pow, sqrt etc)
16605 \layout Standard
16606
16607 Libraries
16608 \begin_inset LatexCommand \index{Libraries}
16609
16610 \end_inset
16611
16612  included in SDCC should have a license at least as liberal as the GNU Lesser
16613  General Public License
16614 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
16615
16616 \end_inset
16617
16618
16619 \emph on
16620 LGPL
16621 \emph default
16622 .
16623 \layout Comment
16624
16625 license statements for the libraries are missing.
16626  sdcc/device/lib/ser_ir.c
16627 \layout Comment
16628
16629 or _decdptr f.e.
16630  come with a GPL (as opposed to LGPL) License - this will not be liberal
16631  enough for many embedded programmers.
16632 \layout Standard
16633
16634 If you have ported some library or want to share experience about some code
16635  which f.e.
16636  falls into any of these categories Busses (I
16637 \begin_inset Formula $^{\textrm{2}}$
16638 \end_inset
16639
16640 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
16641  cards, eeprom, flash...), En-/Decryption, remote debugging, Keyboard, LCD,
16642  RTC, FPGA, PID then the sdcc-user mailing list
16643 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
16644
16645 \end_inset
16646
16647 \SpecialChar ~
16648 would certainly like to hear about it.
16649  Programmers coding for embedded systems are not especially famous for being
16650  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
16651 e these references are very valuable.
16652 \layout Subsection
16653
16654 External Stack
16655 \begin_inset LatexCommand \label{sub:External-Stack}
16656
16657 \end_inset
16658
16659
16660 \begin_inset LatexCommand \index{stack}
16661
16662 \end_inset
16663
16664
16665 \begin_inset LatexCommand \index{External stack}
16666
16667 \end_inset
16668
16669
16670 \layout Standard
16671
16672 The external stack (-
16673 \begin_inset ERT
16674 status Collapsed
16675
16676 \layout Standard
16677
16678 \backslash
16679 /
16680 \end_inset
16681
16682 -xstack option
16683 \begin_inset LatexCommand \index{-\/-xstack}
16684
16685 \end_inset
16686
16687 ) is located at the start of the external ram segment, and is 256 bytes
16688  in size.
16689  When -
16690 \begin_inset ERT
16691 status Collapsed
16692
16693 \layout Standard
16694
16695 \backslash
16696 /
16697 \end_inset
16698
16699 -xstack option is used to compile the program, the parameters and local
16700  variables of all reentrant functions are allocated in this area.
16701  This option is provided for programs with large stack space requirements.
16702  When used with the -
16703 \begin_inset ERT
16704 status Collapsed
16705
16706 \layout Standard
16707
16708 \backslash
16709 /
16710 \end_inset
16711
16712 -stack-auto
16713 \begin_inset LatexCommand \index{-\/-stack-auto}
16714
16715 \end_inset
16716
16717  option, all parameters and local variables are allocated on the external
16718  stack (note support libraries will need to be recompiled with the same
16719  options).
16720 \layout Standard
16721
16722 The compiler outputs the higher order address byte of the external ram segment
16723  into PORT P2, therefore when using the External Stack option, this port
16724  MAY NOT be used by the application program.
16725 \layout Subsection
16726
16727 ANSI-Compliance
16728 \begin_inset LatexCommand \index{ANSI-compliance}
16729
16730 \end_inset
16731
16732
16733 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
16734
16735 \end_inset
16736
16737
16738 \layout Standard
16739
16740 Deviations from the compliance:
16741 \layout Itemize
16742
16743 functions are not always reentrant.
16744 \layout Itemize
16745
16746 structures cannot be assigned values directly, cannot be passed as function
16747  parameters or assigned to each other and cannot be a return value from
16748  a function, e.g.:
16749 \begin_deeper
16750 \layout Verse
16751
16752
16753 \family typewriter
16754 struct s { ...
16755  };
16756 \newline
16757 struct s s1, s2;
16758 \newline
16759 foo()
16760 \newline
16761 {
16762 \newline
16763 \SpecialChar ~
16764 \SpecialChar ~
16765 \SpecialChar ~
16766 \SpecialChar ~
16767 ...
16768
16769 \newline
16770 \SpecialChar ~
16771 \SpecialChar ~
16772 \SpecialChar ~
16773 \SpecialChar ~
16774 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
16775 \newline
16776 \SpecialChar ~
16777 \SpecialChar ~
16778 \SpecialChar ~
16779 \SpecialChar ~
16780 ...
16781
16782 \newline
16783 }
16784 \newline
16785 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
16786  */
16787 \newline
16788 {
16789 \newline
16790 \SpecialChar ~
16791 \SpecialChar ~
16792 \SpecialChar ~
16793 \SpecialChar ~
16794 struct s rets;
16795 \newline
16796 \SpecialChar ~
16797 \SpecialChar ~
16798 \SpecialChar ~
16799 \SpecialChar ~
16800 ...
16801
16802 \newline
16803 \SpecialChar ~
16804 \SpecialChar ~
16805 \SpecialChar ~
16806 \SpecialChar ~
16807 return rets;/* is invalid in SDCC although allowed in ANSI */
16808 \newline
16809 }
16810 \end_deeper
16811 \layout Itemize
16812
16813 'long long
16814 \begin_inset LatexCommand \index{long long (not supported)}
16815
16816 \end_inset
16817
16818 ' (64 bit integers
16819 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
16820
16821 \end_inset
16822
16823 ) not supported.
16824 \layout Itemize
16825
16826 'double
16827 \begin_inset LatexCommand \index{double (not supported)}
16828
16829 \end_inset
16830
16831 ' precision floating point
16832 \begin_inset LatexCommand \index{Floating point support}
16833
16834 \end_inset
16835
16836 not supported.
16837 \layout Itemize
16838
16839 No support for setjmp and longjmp (for now).
16840 \layout Itemize
16841
16842 Old K&R style
16843 \begin_inset LatexCommand \index{K\&R style}
16844
16845 \end_inset
16846
16847  function declarations are NOT allowed.
16848 \begin_deeper
16849 \layout Verse
16850
16851
16852 \family typewriter
16853 foo(i,j) /* this old style of function declarations */
16854 \newline
16855 int i,j; /* are valid in ANSI but not valid in SDCC */
16856 \newline
16857 {
16858 \newline
16859 \SpecialChar ~
16860 \SpecialChar ~
16861 \SpecialChar ~
16862 \SpecialChar ~
16863 ...
16864
16865 \newline
16866 }
16867 \end_deeper
16868 \layout Itemize
16869
16870 functions declared as pointers
16871 \begin_inset LatexCommand \index{Pointers}
16872
16873 \end_inset
16874
16875
16876 \begin_inset LatexCommand \index{function pointers}
16877
16878 \end_inset
16879
16880  must be dereferenced during the call.
16881 \begin_deeper
16882 \layout Verse
16883
16884
16885 \family typewriter
16886 int (*foo)();
16887 \newline
16888 ...
16889
16890 \newline
16891 /* has to be called like this */
16892 \newline
16893 (*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
16894 \end_deeper
16895 \layout Subsection
16896
16897 Cyclomatic Complexity
16898 \begin_inset LatexCommand \index{Cyclomatic complexity}
16899
16900 \end_inset
16901
16902
16903 \layout Standard
16904
16905 Cyclomatic complexity of a function is defined as the number of independent
16906  paths the program can take during execution of the function.
16907  This is an important number since it defines the number test cases you
16908  have to generate to validate the function.
16909  The accepted industry standard for complexity number is 10, if the cyclomatic
16910  complexity reported by SDCC exceeds 10 you should think about simplification
16911  of the function logic.
16912  Note that the complexity level is not related to the number of lines of
16913  code in a function.
16914  Large functions can have low complexity, and small functions can have large
16915  complexity levels.
16916
16917 \newline
16918
16919 \newline
16920 SDCC uses the following formula to compute the complexity:
16921 \newline
16922
16923 \layout Standard
16924
16925 complexity = (number of edges in control flow graph) - (number of nodes
16926  in control flow graph) + 2;
16927 \newline
16928
16929 \newline
16930 Having said that the industry standard is 10, you should be aware that in
16931  some cases it be may unavoidable to have a complexity level of less than
16932  10.
16933  For example if you have switch statement with more than 10 case labels,
16934  each case label adds one to the complexity level.
16935  The complexity level is by no means an absolute measure of the algorithmic
16936  complexity of the function, it does however provide a good starting point
16937  for which functions you might look at for further optimization.
16938 \layout Subsection
16939
16940 Other Processors
16941 \layout Subsubsection
16942
16943 MCS51 variants
16944 \begin_inset LatexCommand \label{sub:MCS51-variants}
16945
16946 \end_inset
16947
16948
16949 \begin_inset LatexCommand \index{MCS51 variants}
16950
16951 \end_inset
16952
16953
16954 \layout Standard
16955
16956 MCS51 processors are available from many vendors and come in many different
16957  flavours.
16958  While they might differ considerably in respect to Special Function Registers
16959  the core MCS51 is usually not modified or is kept compatible.
16960
16961 \layout Subsubsection*
16962
16963 pdata access by SFR
16964 \layout Standard
16965
16966 With the upcome of devices with internal xdata and flash memory devices
16967  using port P2 as dedicated I/O port is becoming more popular.
16968  Switching the high byte for pdata
16969 \begin_inset LatexCommand \index{pdata}
16970
16971 \end_inset
16972
16973  access which was formerly done by port P2 is then achieved by a Special
16974  Function Register.
16975  In well-established MCS51 tradition the address of this
16976 \emph on
16977 sfr
16978 \emph default
16979  is where the chip designers decided to put it.
16980  As pdata addressing is used in the startup code for the initialization
16981  of xdata variables a separate startup code should be used as described
16982  in section
16983 \begin_inset LatexCommand \ref{sub:Startup-Code}
16984
16985 \end_inset
16986
16987 .
16988 \layout Subsubsection*
16989
16990 Other Features available by SFR
16991 \layout Standard
16992
16993 Some MCS51 variants offer features like Double DPTR
16994 \begin_inset LatexCommand \index{DPTR}
16995
16996 \end_inset
16997
16998 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
16999  These are currently not used for the MCS51 port.
17000  If you absolutely need them you can fall back to inline assembly or submit
17001  a patch to SDCC.
17002 \layout Subsubsection
17003
17004 The Z80 and gbz80 port
17005 \layout Standard
17006
17007 SDCC can target both the Zilog
17008 \begin_inset LatexCommand \index{Z80}
17009
17010 \end_inset
17011
17012  and the Nintendo Gameboy's Z80-like gbz80
17013 \begin_inset LatexCommand \index{GameBoy Z80}
17014
17015 \end_inset
17016
17017 .
17018  The Z80 port is passed through the same
17019 \emph on
17020 regressions tests
17021 \begin_inset LatexCommand \index{Regression test}
17022
17023 \end_inset
17024
17025
17026 \emph default
17027  as MCS51 and DS390 ports, so floating point support, support for long variables
17028  and bitfield support is fine.
17029 \layout Standard
17030
17031 As always, the code is the authoritative reference - see z80/ralloc.c and
17032  z80/gen.c.
17033  The stack frame is similar to that generated by the IAR Z80 compiler.
17034  IX is used as the base pointer, HL is used as a temporary register, and
17035  BC and DE are available for holding variables.
17036  IY is currently unused.
17037  Return values are stored in HL.
17038  One bad side effect of using IX as the base pointer is that a functions
17039  stack frame is limited to 127 bytes - this will be fixed in a later version.
17040 \layout Subsection
17041
17042 Retargetting for other MCUs.
17043 \layout Standard
17044
17045 The issues for retargetting the compiler are far too numerous to be covered
17046  by this document.
17047  What follows is a brief description of each of the seven phases of the
17048  compiler and its MCU dependency.
17049 \layout Itemize
17050
17051 Parsing the source and building the annotated parse tree.
17052  This phase is largely MCU independent (except for the language extensions).
17053  Syntax & semantic checks are also done in this phase, along with some initial
17054  optimizations like back patching labels and the pattern matching optimizations
17055  like bit-rotation etc.
17056 \layout Itemize
17057
17058 The second phase involves generating an intermediate code which can be easy
17059  manipulated during the later phases.
17060  This phase is entirely MCU independent.
17061  The intermediate code generation assumes the target machine has unlimited
17062  number of registers, and designates them with the name iTemp.
17063  The compiler can be made to dump a human readable form of the code generated
17064  by using the -
17065 \begin_inset ERT
17066 status Collapsed
17067
17068 \layout Standard
17069
17070 \backslash
17071 /
17072 \end_inset
17073
17074 -dumpraw option.
17075 \layout Itemize
17076
17077 This phase does the bulk of the standard optimizations and is also MCU independe
17078 nt.
17079  This phase can be broken down into several sub-phases:
17080 \newline
17081
17082 \newline
17083 Break down intermediate code (iCode) into basic blocks.
17084 \newline
17085 Do control flow & data flow analysis on the basic blocks.
17086 \newline
17087 Do local common subexpression elimination, then global subexpression elimination
17088 \newline
17089 Dead code elimination
17090 \newline
17091 Loop optimizations
17092 \newline
17093 If loop optimizations caused any changes then do 'global subexpression eliminati
17094 on' and 'dead code elimination' again.
17095 \layout Itemize
17096
17097 This phase determines the live-ranges; by live range I mean those iTemp
17098  variables defined by the compiler that still survive after all the optimization
17099 s.
17100  Live range analysis
17101 \begin_inset LatexCommand \index{Live range analysis}
17102
17103 \end_inset
17104
17105  is essential for register allocation, since these computation determines
17106  which of these iTemps will be assigned to registers, and for how long.
17107 \layout Itemize
17108
17109 Phase five is register allocation.
17110  There are two parts to this process.
17111 \newline
17112
17113 \newline
17114 The first part I call 'register packing' (for lack of a better term).
17115  In this case several MCU specific expression folding is done to reduce
17116  register pressure.
17117 \newline
17118
17119 \newline
17120 The second part is more MCU independent and deals with allocating registers
17121  to the remaining live ranges.
17122  A lot of MCU specific code does creep into this phase because of the limited
17123  number of index registers available in the 8051.
17124 \layout Itemize
17125
17126 The Code generation phase is (unhappily), entirely MCU dependent and very
17127  little (if any at all) of this code can be reused for other MCU.
17128  However the scheme for allocating a homogenized assembler operand for each
17129  iCode operand may be reused.
17130 \layout Itemize
17131
17132 As mentioned in the optimization section the peep-hole optimizer is rule
17133  based system, which can reprogrammed for other MCUs.
17134 \layout Section
17135 \pagebreak_top
17136 Compiler internals
17137 \begin_inset LatexCommand \index{Compiler internals}
17138
17139 \end_inset
17140
17141
17142 \layout Subsection
17143
17144 The anatomy of the compiler
17145 \begin_inset LatexCommand \label{sub:The-anatomy-of}
17146
17147 \end_inset
17148
17149
17150 \layout Standard
17151
17152
17153 \shape italic
17154 This is an excerpt from an article published in Circuit Cellar Magazine
17155  in august 2000.
17156  It's a little outdated (the compiler is much more efficient now and user/develo
17157 per friendly), but pretty well exposes the guts of it all.
17158 \shape default
17159
17160 \newline
17161
17162 \newline
17163 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
17164  It is fairly easy to retarget for other 8-bit MCU.
17165  Here we take a look at some of the internals of the compiler.
17166
17167 \layout Paragraph*
17168
17169 Parsing
17170 \begin_inset LatexCommand \index{Parsing}
17171
17172 \end_inset
17173
17174
17175 \layout Standard
17176
17177 Parsing the input source file and creating an AST (Annotated Syntax Tree
17178 \begin_inset LatexCommand \index{Annotated syntax tree}
17179
17180 \end_inset
17181
17182 ).
17183  This phase also involves propagating types (annotating each node of the
17184  parse tree with type information) and semantic analysis.
17185  There are some MCU specific parsing rules.
17186  For example the storage classes, the extended storage classes are MCU specific
17187  while there may be a xdata storage class for 8051 there is no such storage
17188  class for z80 or Atmel AVR.
17189  SDCC allows MCU specific storage class extensions, i.e.
17190  xdata will be treated as a storage class specifier when parsing 8051 C
17191  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
17192  C code.
17193 \layout Paragraph*
17194
17195 Generating iCode
17196 \begin_inset LatexCommand \index{iCode}
17197
17198 \end_inset
17199
17200
17201 \layout Standard
17202
17203 Intermediate code generation.
17204  In this phase the AST is broken down into three-operand form (iCode).
17205  These three operand forms are represented as doubly linked lists.
17206  ICode is the term given to the intermediate form generated by the compiler.
17207  ICode example section shows some examples of iCode generated for some simple
17208  C source functions.
17209 \layout Paragraph*
17210
17211 Optimizations
17212 \begin_inset LatexCommand \index{Optimizations}
17213
17214 \end_inset
17215
17216 .
17217 \layout Standard
17218
17219 Bulk of the target independent optimizations is performed in this phase.
17220  The optimizations include constant propagation, common sub-expression eliminati
17221 on, loop invariant code movement, strength reduction of loop induction variables
17222  and dead-code elimination.
17223 \layout Paragraph*
17224
17225 Live range analysis
17226 \begin_inset LatexCommand \index{Live range analysis}
17227
17228 \end_inset
17229
17230
17231 \layout Standard
17232
17233 During intermediate code generation phase, the compiler assumes the target
17234  machine has infinite number of registers and generates a lot of temporary
17235  variables.
17236  The live range computation determines the lifetime of each of these compiler-ge
17237 nerated temporaries.
17238  A picture speaks a thousand words.
17239  ICode example sections show the live range annotations for each of the
17240  operand.
17241  It is important to note here, each iCode is assigned a number in the order
17242  of its execution in the function.
17243  The live ranges are computed in terms of these numbers.
17244  The from number is the number of the iCode which first defines the operand
17245  and the to number signifies the iCode which uses this operand last.
17246 \layout Paragraph*
17247
17248 Register Allocation
17249 \begin_inset LatexCommand \index{Register allocation}
17250
17251 \end_inset
17252
17253
17254 \layout Standard
17255
17256 The register allocation determines the type and number of registers needed
17257  by each operand.
17258  In most MCUs only a few registers can be used for indirect addressing.
17259  In case of 8051 for example the registers R0 & R1 can be used to indirectly
17260  address the internal ram and DPTR to indirectly address the external ram.
17261  The compiler will try to allocate the appropriate register to pointer variables
17262  if it can.
17263  ICode example section shows the operands annotated with the registers assigned
17264  to them.
17265  The compiler will try to keep operands in registers as much as possible;
17266  there are several schemes the compiler uses to do achieve this.
17267  When the compiler runs out of registers the compiler will check to see
17268  if there are any live operands which is not used or defined in the current
17269  basic block being processed, if there are any found then it will push that
17270  operand and use the registers in this block, the operand will then be popped
17271  at the end of the basic block.
17272
17273 \layout Standard
17274
17275 There are other MCU specific considerations in this phase.
17276  Some MCUs have an accumulator; very short-lived operands could be assigned
17277  to the accumulator instead of general-purpose register.
17278 \layout Paragraph*
17279
17280 Code generation
17281 \layout Standard
17282
17283 Figure II gives a table of iCode operations supported by the compiler.
17284  The code generation involves translating these operations into corresponding
17285  assembly code for the processor.
17286  This sounds overly simple but that is the essence of code generation.
17287  Some of the iCode operations are generated on a MCU specific manner for
17288  example, the z80 port does not use registers to pass parameters so the
17289  SEND and RECV iCode operations will not be generated, and it also does
17290  not support JUMPTABLES.
17291
17292 \newline
17293
17294 \series bold
17295 \shape italic
17296 \color red
17297 <Where is Figure II ?>
17298 \layout Paragraph*
17299
17300 ICode Example
17301 \begin_inset LatexCommand \index{iCode}
17302
17303 \end_inset
17304
17305
17306 \layout Standard
17307
17308 This section shows some details of iCode.
17309  The example C code does not do anything useful; it is used as an example
17310  to illustrate the intermediate code generated by the compiler.
17311 \layout Verse
17312
17313
17314 \family typewriter
17315 1.\SpecialChar ~
17316 xdata int * p;
17317 \newline
17318 2.\SpecialChar ~
17319 int gint;
17320 \newline
17321 3.\SpecialChar ~
17322 /* This function does nothing useful.
17323  It is used
17324 \newline
17325 4.\SpecialChar ~
17326 \SpecialChar ~
17327 \SpecialChar ~
17328 \SpecialChar ~
17329 for the purpose of explaining iCode */
17330 \newline
17331 5.\SpecialChar ~
17332 short function (data int *x)
17333 \newline
17334 6.\SpecialChar ~
17335 {
17336 \newline
17337 7.\SpecialChar ~
17338 \SpecialChar ~
17339 \SpecialChar ~
17340 short i=10; /* dead initialization eliminated */
17341 \newline
17342 8.\SpecialChar ~
17343 \SpecialChar ~
17344 \SpecialChar ~
17345 short sum=10; /* dead initialization eliminated */
17346 \newline
17347 9.\SpecialChar ~
17348 \SpecialChar ~
17349 \SpecialChar ~
17350 short mul;
17351 \newline
17352 10.\SpecialChar ~
17353 \SpecialChar ~
17354 int j ;
17355 \newline
17356 11.\SpecialChar ~
17357 \SpecialChar ~
17358 while (*x) *x++ = *p++;
17359 \newline
17360 12.\SpecialChar ~
17361 \SpecialChar ~
17362 \SpecialChar ~
17363 \SpecialChar ~
17364 sum = 0 ;
17365 \newline
17366 13.\SpecialChar ~
17367 \SpecialChar ~
17368 mul = 0;
17369 \newline
17370 14.\SpecialChar ~
17371 \SpecialChar ~
17372 /* compiler detects i,j to be induction variables */
17373 \newline
17374 15.\SpecialChar ~
17375 \SpecialChar ~
17376 for (i = 0, j = 10 ; i < 10 ; i++, j
17377 \family default
17378 -
17379 \begin_inset ERT
17380 status Collapsed
17381
17382 \layout Standard
17383
17384 \backslash
17385 /
17386 \end_inset
17387
17388 -
17389 \family typewriter
17390 ) {
17391 \newline
17392 16.\SpecialChar ~
17393 \SpecialChar ~
17394 \SpecialChar ~
17395 \SpecialChar ~
17396 sum += i;
17397 \newline
17398 17.\SpecialChar ~
17399 \SpecialChar ~
17400 \SpecialChar ~
17401 \SpecialChar ~
17402 mul += i * 3; /* this multiplication remains */
17403 \newline
17404 18.\SpecialChar ~
17405 \SpecialChar ~
17406 \SpecialChar ~
17407 \SpecialChar ~
17408 gint += j * 3;/* this multiplication changed to addition */
17409 \newline
17410 19.\SpecialChar ~
17411 \SpecialChar ~
17412 }
17413 \newline
17414 20.\SpecialChar ~
17415 \SpecialChar ~
17416 return sum+mul;
17417 \newline
17418 21.\SpecialChar ~
17419 }
17420 \layout Standard
17421
17422 In addition to the operands each iCode contains information about the filename
17423  and line it corresponds to in the source file.
17424  The first field in the listing should be interpreted as follows:
17425 \newline
17426
17427 \shape italic
17428 \size footnotesize
17429 Filename(linenumber: iCode Execution sequence number : ICode hash table
17430  key : loop depth of the iCode).
17431 \shape default
17432 \size default
17433
17434 \newline
17435 Then follows the human readable form of the ICode operation.
17436  Each operand of this triplet form can be of three basic types a) compiler
17437  generated temporary b) user defined variable c) a constant value.
17438  Note that local variables and parameters are replaced by compiler generated
17439  temporaries.
17440  Live ranges
17441 \begin_inset LatexCommand \index{Live range analysis}
17442
17443 \end_inset
17444
17445  are computed only for temporaries (i.e.
17446  live ranges are not computed for global variables).
17447  Registers
17448 \begin_inset LatexCommand \index{Register allocation}
17449
17450 \end_inset
17451
17452  are allocated for temporaries only.
17453  Operands are formatted in the following manner:
17454 \newline
17455
17456 \shape italic
17457 \size footnotesize
17458 Operand Name [lr live-from : live-to ] { type information } [ registers
17459  allocated ].
17460 \shape default
17461 \size default
17462
17463 \newline
17464 As mentioned earlier the live ranges are computed in terms of the execution
17465  sequence number of the iCodes, for example
17466 \newline
17467 the iTemp0 is live from (i.e.
17468  first defined in iCode with execution sequence number 3, and is last used
17469  in the iCode with sequence number 5).
17470  For induction variables such as iTemp21 the live range computation extends
17471  the lifetime from the start to the end of the loop.
17472 \newline
17473 The register allocator used the live range information to allocate registers,
17474  the same registers may be used for different temporaries if their live
17475  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
17476  iTemp17 since their live ranges do not overlap.
17477  In addition the allocator also takes into consideration the type and usage
17478  of a temporary, for example itemp6 is a pointer to near space and is used
17479  as to fetch data from (i.e.
17480  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
17481  Some short lived temporaries are allocated to special registers which have
17482  meaning to the code generator e.g.
17483  iTemp13 is allocated to a pseudo register CC which tells the back end that
17484  the temporary is used only for a conditional jump the code generation makes
17485  use of this information to optimize a compare and jump ICode.
17486 \newline
17487 There are several loop optimizations
17488 \begin_inset LatexCommand \index{Loop optimization}
17489
17490 \end_inset
17491
17492  performed by the compiler.
17493  It can detect induction variables iTemp21(i) and iTemp23(j).
17494  Also note the compiler does selective strength reduction
17495 \begin_inset LatexCommand \index{Strength reduction}
17496
17497 \end_inset
17498
17499 , i.e.
17500  the multiplication of an induction variable in line 18 (gint = j * 3) is
17501  changed to addition, a new temporary iTemp17 is allocated and assigned
17502  a initial value, a constant 3 is then added for each iteration of the loop.
17503  The compiler does not change the multiplication
17504 \begin_inset LatexCommand \index{Multiplication}
17505
17506 \end_inset
17507
17508  in line 17 however since the processor does support an 8 * 8 bit multiplication.
17509 \newline
17510 Note the dead code elimination
17511 \begin_inset LatexCommand \index{Dead-code elimination}
17512
17513 \end_inset
17514
17515  optimization eliminated the dead assignments in line 7 & 8 to I and sum
17516  respectively.
17517 \newline
17518
17519 \layout Standard
17520
17521
17522 \size footnotesize
17523 Sample.c (5:1:0:0) _entry($9) :
17524 \layout Standard
17525
17526
17527 \size footnotesize
17528 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
17529 \layout Standard
17530
17531
17532 \size footnotesize
17533 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
17534 \layout Standard
17535
17536
17537 \size footnotesize
17538 Sample.c(11:4:53:0) preHeaderLbl0($11) :
17539 \layout Standard
17540
17541
17542 \size footnotesize
17543 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
17544  * int}[r2]
17545 \layout Standard
17546
17547
17548 \size footnotesize
17549 Sample.c(11:6:5:1) _whilecontinue_0($1) :
17550 \layout Standard
17551
17552
17553 \size footnotesize
17554 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
17555  int}[r0]]
17556 \layout Standard
17557
17558
17559 \size footnotesize
17560 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
17561 \layout Standard
17562
17563
17564 \size footnotesize
17565 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
17566  * int}
17567 \layout Standard
17568
17569
17570 \size footnotesize
17571 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
17572  {short}
17573 \layout Standard
17574
17575
17576 \size footnotesize
17577 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
17578  * int}[DPTR]]
17579 \layout Standard
17580
17581
17582 \size footnotesize
17583 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
17584 }[r2 r3]
17585 \layout Standard
17586
17587
17588 \size footnotesize
17589 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
17590  * int}[r0] + 0x2 {short}
17591 \layout Standard
17592
17593
17594 \size footnotesize
17595 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
17596 \layout Standard
17597
17598
17599 \size footnotesize
17600 Sample.c(11:17:21:0)_whilebreak_0($3) :
17601 \layout Standard
17602
17603
17604 \size footnotesize
17605 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
17606 \layout Standard
17607
17608
17609 \size footnotesize
17610 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
17611 \layout Standard
17612
17613
17614 \size footnotesize
17615 Sample.c(15:20:54:0)preHeaderLbl1($13) :
17616 \layout Standard
17617
17618
17619 \size footnotesize
17620 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
17621 \layout Standard
17622
17623
17624 \size footnotesize
17625 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
17626 \layout Standard
17627
17628
17629 \size footnotesize
17630 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
17631 \layout Standard
17632
17633
17634 \size footnotesize
17635 Sample.c(15:24:26:1)_forcond_0($4) :
17636 \layout Standard
17637
17638
17639 \size footnotesize
17640 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
17641  < 0xa {short}
17642 \layout Standard
17643
17644
17645 \size footnotesize
17646 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
17647 \layout Standard
17648
17649
17650 \size footnotesize
17651 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
17652  + ITemp21 [lr21:38]{short}[r4]
17653 \layout Standard
17654
17655
17656 \size footnotesize
17657 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
17658  * 0x3 {short}
17659 \layout Standard
17660
17661
17662 \size footnotesize
17663 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
17664  + iTemp15 [lr29:30]{short}[r1]
17665 \layout Standard
17666
17667
17668 \size footnotesize
17669 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
17670  r0]- 0x3 {short}
17671 \layout Standard
17672
17673
17674 \size footnotesize
17675 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
17676 int}[r7 r0]
17677 \layout Standard
17678
17679
17680 \size footnotesize
17681 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
17682  + 0x1 {short}
17683 \layout Standard
17684
17685
17686 \size footnotesize
17687 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
17688  r6]- 0x1 {short}
17689 \layout Standard
17690
17691
17692 \size footnotesize
17693 Sample.c(19:38:47:1) goto _forcond_0($4)
17694 \layout Standard
17695
17696
17697 \size footnotesize
17698 Sample.c(19:39:48:0)_forbreak_0($7) :
17699 \layout Standard
17700
17701
17702 \size footnotesize
17703 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
17704  + ITemp11 [lr19:40]{short}[r3]
17705 \layout Standard
17706
17707
17708 \size footnotesize
17709 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
17710 \layout Standard
17711
17712
17713 \size footnotesize
17714 Sample.c(20:42:51:0)_return($8) :
17715 \layout Standard
17716
17717
17718 \size footnotesize
17719 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
17720 \size default
17721
17722 \newline
17723
17724 \newline
17725 Finally the code generated for this function:
17726 \newline
17727
17728 \layout Standard
17729
17730
17731 \size footnotesize
17732 .area DSEG (DATA)
17733 \layout Standard
17734
17735
17736 \size footnotesize
17737 _p::
17738 \layout Standard
17739
17740
17741 \size footnotesize
17742 \SpecialChar ~
17743 \SpecialChar ~
17744 .ds 2
17745 \layout Standard
17746
17747
17748 \size footnotesize
17749 _gint::
17750 \layout Standard
17751
17752
17753 \size footnotesize
17754 \SpecialChar ~
17755 \SpecialChar ~
17756 .ds 2
17757 \layout Standard
17758
17759
17760 \size footnotesize
17761 ; sample.c 5
17762 \layout Standard
17763
17764
17765 \size footnotesize
17766 ; ----------------------------------------------
17767 \layout Standard
17768
17769
17770 \size footnotesize
17771 ; function function
17772 \layout Standard
17773
17774
17775 \size footnotesize
17776 ; ----------------------------------------------
17777 \layout Standard
17778
17779
17780 \size footnotesize
17781 _function:
17782 \layout Standard
17783
17784
17785 \size footnotesize
17786 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
17787 \layout Standard
17788
17789
17790 \size footnotesize
17791 \SpecialChar ~
17792 \SpecialChar ~
17793 mov r2,dpl
17794 \layout Standard
17795
17796
17797 \size footnotesize
17798 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
17799 \layout Standard
17800
17801
17802 \size footnotesize
17803 \SpecialChar ~
17804 \SpecialChar ~
17805 mov ar0,r2
17806 \layout Standard
17807
17808
17809 \size footnotesize
17810 ;_whilecontinue_0($1) :
17811 \layout Standard
17812
17813
17814 \size footnotesize
17815 00101$:
17816 \layout Standard
17817
17818
17819 \size footnotesize
17820 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
17821 \layout Standard
17822
17823
17824 \size footnotesize
17825 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
17826 \layout Standard
17827
17828
17829 \size footnotesize
17830 \SpecialChar ~
17831 \SpecialChar ~
17832 mov ar2,@r0
17833 \layout Standard
17834
17835
17836 \size footnotesize
17837 \SpecialChar ~
17838 \SpecialChar ~
17839 inc r0
17840 \layout Standard
17841
17842
17843 \size footnotesize
17844 \SpecialChar ~
17845 \SpecialChar ~
17846 mov ar3,@r0
17847 \layout Standard
17848
17849
17850 \size footnotesize
17851 \SpecialChar ~
17852 \SpecialChar ~
17853 dec r0
17854 \layout Standard
17855
17856
17857 \size footnotesize
17858 \SpecialChar ~
17859 \SpecialChar ~
17860 mov a,r2
17861 \layout Standard
17862
17863
17864 \size footnotesize
17865 \SpecialChar ~
17866 \SpecialChar ~
17867 orl a,r3
17868 \layout Standard
17869
17870
17871 \size footnotesize
17872 \SpecialChar ~
17873 \SpecialChar ~
17874 jz 00103$
17875 \layout Standard
17876
17877
17878 \size footnotesize
17879 00114$:
17880 \layout Standard
17881
17882
17883 \size footnotesize
17884 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
17885 \layout Standard
17886
17887
17888 \size footnotesize
17889 \SpecialChar ~
17890 \SpecialChar ~
17891 mov dpl,_p
17892 \layout Standard
17893
17894
17895 \size footnotesize
17896 \SpecialChar ~
17897 \SpecialChar ~
17898 mov dph,(_p + 1)
17899 \layout Standard
17900
17901
17902 \size footnotesize
17903 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
17904 \layout Standard
17905
17906
17907 \size footnotesize
17908 \SpecialChar ~
17909 \SpecialChar ~
17910 mov a,#0x02
17911 \layout Standard
17912
17913
17914 \size footnotesize
17915 \SpecialChar ~
17916 \SpecialChar ~
17917 add a,_p
17918 \layout Standard
17919
17920
17921 \size footnotesize
17922 \SpecialChar ~
17923 \SpecialChar ~
17924 mov _p,a
17925 \layout Standard
17926
17927
17928 \size footnotesize
17929 \SpecialChar ~
17930 \SpecialChar ~
17931 clr a
17932 \layout Standard
17933
17934
17935 \size footnotesize
17936 \SpecialChar ~
17937 \SpecialChar ~
17938 addc a,(_p + 1)
17939 \layout Standard
17940
17941
17942 \size footnotesize
17943 \SpecialChar ~
17944 \SpecialChar ~
17945 mov (_p + 1),a
17946 \layout Standard
17947
17948
17949 \size footnotesize
17950 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
17951 \layout Standard
17952
17953
17954 \size footnotesize
17955 \SpecialChar ~
17956 \SpecialChar ~
17957 movx a,@dptr
17958 \layout Standard
17959
17960
17961 \size footnotesize
17962 \SpecialChar ~
17963 \SpecialChar ~
17964 mov r2,a
17965 \layout Standard
17966
17967
17968 \size footnotesize
17969 \SpecialChar ~
17970 \SpecialChar ~
17971 inc dptr
17972 \layout Standard
17973
17974
17975 \size footnotesize
17976 \SpecialChar ~
17977 \SpecialChar ~
17978 movx a,@dptr
17979 \layout Standard
17980
17981
17982 \size footnotesize
17983 \SpecialChar ~
17984 \SpecialChar ~
17985 mov r3,a
17986 \layout Standard
17987
17988
17989 \size footnotesize
17990 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
17991 \layout Standard
17992
17993
17994 \size footnotesize
17995 \SpecialChar ~
17996 \SpecialChar ~
17997 mov @r0,ar2
17998 \layout Standard
17999
18000
18001 \size footnotesize
18002 \SpecialChar ~
18003 \SpecialChar ~
18004 inc r0
18005 \layout Standard
18006
18007
18008 \size footnotesize
18009 \SpecialChar ~
18010 \SpecialChar ~
18011 mov @r0,ar3
18012 \layout Standard
18013
18014
18015 \size footnotesize
18016 ; iTemp6 [lr5:16]{_near * int}[r0] =
18017 \layout Standard
18018
18019
18020 \size footnotesize
18021 ; iTemp6 [lr5:16]{_near * int}[r0] +
18022 \layout Standard
18023
18024
18025 \size footnotesize
18026 ; 0x2 {short}
18027 \layout Standard
18028
18029
18030 \size footnotesize
18031 \SpecialChar ~
18032 \SpecialChar ~
18033 inc r0
18034 \layout Standard
18035
18036
18037 \size footnotesize
18038 ; goto _whilecontinue_0($1)
18039 \layout Standard
18040
18041
18042 \size footnotesize
18043 \SpecialChar ~
18044 \SpecialChar ~
18045 sjmp 00101$
18046 \layout Standard
18047
18048
18049 \size footnotesize
18050 ; _whilebreak_0($3) :
18051 \layout Standard
18052
18053
18054 \size footnotesize
18055 00103$:
18056 \layout Standard
18057
18058
18059 \size footnotesize
18060 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
18061 \layout Standard
18062
18063
18064 \size footnotesize
18065 \SpecialChar ~
18066 \SpecialChar ~
18067 mov r2,#0x00
18068 \layout Standard
18069
18070
18071 \size footnotesize
18072 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
18073 \layout Standard
18074
18075
18076 \size footnotesize
18077 \SpecialChar ~
18078 \SpecialChar ~
18079 mov r3,#0x00
18080 \layout Standard
18081
18082
18083 \size footnotesize
18084 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
18085 \layout Standard
18086
18087
18088 \size footnotesize
18089 \SpecialChar ~
18090 \SpecialChar ~
18091 mov r4,#0x00
18092 \layout Standard
18093
18094
18095 \size footnotesize
18096 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
18097 \layout Standard
18098
18099
18100 \size footnotesize
18101 \SpecialChar ~
18102 \SpecialChar ~
18103 mov r5,#0x0A
18104 \layout Standard
18105
18106
18107 \size footnotesize
18108 \SpecialChar ~
18109 \SpecialChar ~
18110 mov r6,#0x00
18111 \layout Standard
18112
18113
18114 \size footnotesize
18115 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
18116 \layout Standard
18117
18118
18119 \size footnotesize
18120 \SpecialChar ~
18121 \SpecialChar ~
18122 mov r7,#0x1E
18123 \layout Standard
18124
18125
18126 \size footnotesize
18127 \SpecialChar ~
18128 \SpecialChar ~
18129 mov r0,#0x00
18130 \layout Standard
18131
18132
18133 \size footnotesize
18134 ; _forcond_0($4) :
18135 \layout Standard
18136
18137
18138 \size footnotesize
18139 00104$:
18140 \layout Standard
18141
18142
18143 \size footnotesize
18144 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
18145 \layout Standard
18146
18147
18148 \size footnotesize
18149 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
18150 \layout Standard
18151
18152
18153 \size footnotesize
18154 \SpecialChar ~
18155 \SpecialChar ~
18156 clr c
18157 \layout Standard
18158
18159
18160 \size footnotesize
18161 \SpecialChar ~
18162 \SpecialChar ~
18163 mov a,r4
18164 \layout Standard
18165
18166
18167 \size footnotesize
18168 \SpecialChar ~
18169 \SpecialChar ~
18170 xrl a,#0x80
18171 \layout Standard
18172
18173
18174 \size footnotesize
18175 \SpecialChar ~
18176 \SpecialChar ~
18177 subb a,#0x8a
18178 \layout Standard
18179
18180
18181 \size footnotesize
18182 \SpecialChar ~
18183 \SpecialChar ~
18184 jnc 00107$
18185 \layout Standard
18186
18187
18188 \size footnotesize
18189 00115$:
18190 \layout Standard
18191
18192
18193 \size footnotesize
18194 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
18195 \layout Standard
18196
18197
18198 \size footnotesize
18199 ; iTemp21 [lr21:38]{short}[r4]
18200 \layout Standard
18201
18202
18203 \size footnotesize
18204 \SpecialChar ~
18205 \SpecialChar ~
18206 mov a,r4
18207 \layout Standard
18208
18209
18210 \size footnotesize
18211 \SpecialChar ~
18212 \SpecialChar ~
18213 add a,r2
18214 \layout Standard
18215
18216
18217 \size footnotesize
18218 \SpecialChar ~
18219 \SpecialChar ~
18220 mov r2,a
18221 \layout Standard
18222
18223
18224 \size footnotesize
18225 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
18226 \layout Standard
18227
18228
18229 \size footnotesize
18230 \SpecialChar ~
18231 \SpecialChar ~
18232 mov b,#0x03
18233 \layout Standard
18234
18235
18236 \size footnotesize
18237 \SpecialChar ~
18238 \SpecialChar ~
18239 mov a,r4
18240 \layout Standard
18241
18242
18243 \size footnotesize
18244 \SpecialChar ~
18245 \SpecialChar ~
18246 mul ab
18247 \layout Standard
18248
18249
18250 \size footnotesize
18251 \SpecialChar ~
18252 \SpecialChar ~
18253 mov r1,a
18254 \layout Standard
18255
18256
18257 \size footnotesize
18258 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
18259 \layout Standard
18260
18261
18262 \size footnotesize
18263 ; iTemp15 [lr29:30]{short}[r1]
18264 \layout Standard
18265
18266
18267 \size footnotesize
18268 \SpecialChar ~
18269 \SpecialChar ~
18270 add a,r3
18271 \layout Standard
18272
18273
18274 \size footnotesize
18275 \SpecialChar ~
18276 \SpecialChar ~
18277 mov r3,a
18278 \layout Standard
18279
18280
18281 \size footnotesize
18282 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
18283 \layout Standard
18284
18285
18286 \size footnotesize
18287 \SpecialChar ~
18288 \SpecialChar ~
18289 mov a,r7
18290 \layout Standard
18291
18292
18293 \size footnotesize
18294 \SpecialChar ~
18295 \SpecialChar ~
18296 add a,#0xfd
18297 \layout Standard
18298
18299
18300 \size footnotesize
18301 \SpecialChar ~
18302 \SpecialChar ~
18303 mov r7,a
18304 \layout Standard
18305
18306
18307 \size footnotesize
18308 \SpecialChar ~
18309 \SpecialChar ~
18310 mov a,r0
18311 \layout Standard
18312
18313
18314 \size footnotesize
18315 \SpecialChar ~
18316 \SpecialChar ~
18317 addc a,#0xff
18318 \layout Standard
18319
18320
18321 \size footnotesize
18322 \SpecialChar ~
18323 \SpecialChar ~
18324 mov r0,a
18325 \layout Standard
18326
18327
18328 \size footnotesize
18329 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
18330 \layout Standard
18331
18332
18333 \size footnotesize
18334 \SpecialChar ~
18335 \SpecialChar ~
18336 mov a,r7
18337 \layout Standard
18338
18339
18340 \size footnotesize
18341 \SpecialChar ~
18342 \SpecialChar ~
18343 add a,_gint
18344 \layout Standard
18345
18346
18347 \size footnotesize
18348 \SpecialChar ~
18349 \SpecialChar ~
18350 mov _gint,a
18351 \layout Standard
18352
18353
18354 \size footnotesize
18355 \SpecialChar ~
18356 \SpecialChar ~
18357 mov a,r0
18358 \layout Standard
18359
18360
18361 \size footnotesize
18362 \SpecialChar ~
18363 \SpecialChar ~
18364 addc a,(_gint + 1)
18365 \layout Standard
18366
18367
18368 \size footnotesize
18369 \SpecialChar ~
18370 \SpecialChar ~
18371 mov (_gint + 1),a
18372 \layout Standard
18373
18374
18375 \size footnotesize
18376 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
18377 \layout Standard
18378
18379
18380 \size footnotesize
18381 \SpecialChar ~
18382 \SpecialChar ~
18383 inc r4
18384 \layout Standard
18385
18386
18387 \size footnotesize
18388 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
18389 \layout Standard
18390
18391
18392 \size footnotesize
18393 \SpecialChar ~
18394 \SpecialChar ~
18395 dec r5
18396 \layout Standard
18397
18398
18399 \size footnotesize
18400 \SpecialChar ~
18401 \SpecialChar ~
18402 cjne r5,#0xff,00104$
18403 \layout Standard
18404
18405
18406 \size footnotesize
18407 \SpecialChar ~
18408 \SpecialChar ~
18409 dec r6
18410 \layout Standard
18411
18412
18413 \size footnotesize
18414 ; goto _forcond_0($4)
18415 \layout Standard
18416
18417
18418 \size footnotesize
18419 \SpecialChar ~
18420 \SpecialChar ~
18421 sjmp 00104$
18422 \layout Standard
18423
18424
18425 \size footnotesize
18426 ; _forbreak_0($7) :
18427 \layout Standard
18428
18429
18430 \size footnotesize
18431 00107$:
18432 \layout Standard
18433
18434
18435 \size footnotesize
18436 ; ret iTemp24 [lr40:41]{short}
18437 \layout Standard
18438
18439
18440 \size footnotesize
18441 \SpecialChar ~
18442 \SpecialChar ~
18443 mov a,r3
18444 \layout Standard
18445
18446
18447 \size footnotesize
18448 \SpecialChar ~
18449 \SpecialChar ~
18450 add a,r2
18451 \layout Standard
18452
18453
18454 \size footnotesize
18455 \SpecialChar ~
18456 \SpecialChar ~
18457 mov dpl,a
18458 \layout Standard
18459
18460
18461 \size footnotesize
18462 ; _return($8) :
18463 \layout Standard
18464
18465
18466 \size footnotesize
18467 00108$:
18468 \layout Standard
18469
18470
18471 \size footnotesize
18472 \SpecialChar ~
18473 \SpecialChar ~
18474 ret
18475 \newline
18476
18477 \layout Subsection
18478
18479 A few words about basic block successors, predecessors and dominators
18480 \layout Standard
18481
18482 Successors are basic blocks
18483 \begin_inset LatexCommand \index{Basic blocks}
18484
18485 \end_inset
18486
18487  that might execute after this basic block.
18488 \newline
18489 Predecessors are basic blocks that might execute before reaching this basic
18490  block.
18491 \newline
18492 Dominators are basic blocks that WILL execute before reaching this basic
18493  block.
18494 \newline
18495
18496 \layout Standard
18497
18498 [basic block 1]
18499 \layout Standard
18500
18501 if (something)
18502 \layout Standard
18503
18504 \SpecialChar ~
18505 \SpecialChar ~
18506 \SpecialChar ~
18507 \SpecialChar ~
18508 [basic block 2]
18509 \layout Standard
18510
18511 else
18512 \layout Standard
18513
18514 \SpecialChar ~
18515 \SpecialChar ~
18516 \SpecialChar ~
18517 \SpecialChar ~
18518 [basic block 3]
18519 \layout Standard
18520
18521 [basic block 4]
18522 \newline
18523
18524 \layout Standard
18525
18526 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
18527 \layout Standard
18528
18529 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
18530 \layout Standard
18531
18532 c) domVect of [BB4] = BB1 ...
18533  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
18534  was executed.
18535 \layout Section
18536
18537 Acknowledgments
18538 \layout Standard
18539
18540
18541 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
18542
18543 \end_inset
18544
18545
18546 \newline
18547
18548 \newline
18549
18550 \emph on
18551 Thanks to all the other volunteer developers who have helped with coding,
18552  testing, web-page creation, distribution sets, etc.
18553  You know who you are :-)
18554 \emph default
18555
18556 \newline
18557
18558 \layout Standard
18559
18560 This document was initially written by Sandeep Dutta
18561 \layout Standard
18562
18563 All product names mentioned herein may be trademarks
18564 \begin_inset LatexCommand \index{Trademarks}
18565
18566 \end_inset
18567
18568  of their respective companies.
18569
18570 \layout Section
18571
18572 Alphabetical index
18573 \layout Standard
18574
18575 To avoid confusion, the installation and building options for SDCC itself
18576  (chapter 2) are not part of the index.
18577 \layout Standard
18578
18579
18580 \begin_inset LatexCommand \printindex{}
18581
18582 \end_inset
18583
18584
18585 \the_end