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

   1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 221
   3 \textclass book
   4 \begin_preamble
   5
   6 \usepackage[
   7   pdftitle={SDCC Compiler User Guide},
   8   pdfauthor={SDCC development team},
   9   pdfsubject={installation, user manual},
  10   pdfkeywords={8032, 8051, ansi, c, compiler, CPU, DS390,
  11                embedded, GPL, HC08, manual, mcs51, PIC, Z80},
  12   colorlinks=true,
  13   linkcolor=blue] {hyperref}
  14 %
  15 \sloppy
  16 \tolerance=500
  17 \emergencystretch=30pt
  18 %
  19 \date{}
  20 \end_preamble
  21 \language english
  22 \inputencoding default
  23 \fontscheme pslatex
  24 \graphics default
  25 \paperfontsize default
  26 \spacing single
  27 \papersize letterpaper
  28 \paperpackage a4
  29 \use_geometry 1
  30 \use_amsmath 0
  31 \use_natbib 0
  32 \use_numerical_citations 0
  33 \paperorientation portrait
  34 \leftmargin 30mm
  35 \topmargin 20mm
  36 \rightmargin 25mm
  37 \bottommargin 20mm
  38 \secnumdepth 3
  39 \tocdepth 3
  40 \paragraph_separation indent
  41 \defskip medskip
  42 \quotes_language swedish
  43 \quotes_times 2
  44 \papercolumns 1
  45 \papersides 1
  46 \paperpagestyle fancy
  47
  48 \layout Comment
  49
  50 Please note: double dashed longoptions (e.g.
  51  --version) are written this way: -
  52 \begin_inset ERT
  53 status Collapsed
  54
  55 \layout Standard
  56
  57 \backslash
  58 /
  59 \end_inset
  60
  61 -
  62 \layout Comment
  63
  64 Two resp.
  65  three consecutive dashes simply result in a long resp.
  66  extra long dash.
  67 \layout Comment
  68
  69 Architecture specific stuff (like memory models, code examples) should maybe
  70  later go
  71 \layout Comment
  72
  73 into seperate sections/chapters/appendices (it is hard to document PIC or
  74  Z80 in
  75 \layout Comment
  76
  77 a 8051 centered document) - for now simply add.
  78 \layout Title
  79
  80 SDCC Compiler User Guide
  81 \layout Date
  82
  83
  84 \size normal
  85 SDCC 2.4.2
  86 \size footnotesize
  87
  88 \newline
  89 $Date$
  90 \newline
  91 $Revision$
  92 \layout Comment
  93
  94 The above strings enclosed in $ are automatically updated by cvs
  95 \layout Standard
  96
  97
  98 \begin_inset LatexCommand \tableofcontents{}
  99
 100 \end_inset
 101
 102
 103 \layout Chapter
 104
 105 Introduction
 106 \layout Section
 107
 108 About SDCC
 109 \layout Standard
 110
 111
 112 \series bold
 113 SDCC
 114 \series default
 115  (
 116 \emph on
 117 S
 118 \emph default
 119 mall
 120 \emph on
 121 D
 122 \emph default
 123 evice
 124 \emph on
 125 C
 126 \emph default
 127
 128 \emph on
 129 C
 130 \emph default
 131 ompiler) is a Freeware, retargettable, optimizing ANSI-C compiler by
 132 \series bold
 133 Sandeep Dutta
 134 \series default
 135  designed for 8 bit Microprocessors.
 136  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 137  8051, 8052
 138 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
 139
 140 \end_inset
 141
 142 , etc.), Dallas DS80C390 variants, Motorola HC08 and Zilog Z80 based MCUs.
 143  It can be retargetted for other microprocessors, support for Microchip
 144  PIC, Atmel AVR is under development.
 145  The entire source code for the compiler is distributed under GPL.
 146  SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
 147  SDCC has extensive language extensions suitable for utilizing various microcont
 148 rollers and underlying hardware effectively.
 149
 150 \newline
 151
 152 \newline
 153 In addition to the MCU specific optimizations SDCC also does a host of standard
 154  optimizations like:
 155 \layout Itemize
 156
 157 global sub expression elimination,
 158 \layout Itemize
 159
 160 loop optimizations (loop invariant, strength reduction of induction variables
 161  and loop reversing),
 162 \layout Itemize
 163
 164 constant folding & propagation,
 165 \layout Itemize
 166
 167 copy propagation,
 168 \layout Itemize
 169
 170 dead code elimination
 171 \layout Itemize
 172
 173 jump tables for
 174 \emph on
 175 switch
 176 \emph default
 177  statements.
 178 \layout Standard
 179
 180 For the back-end SDCC uses a global register allocation scheme which should
 181  be well suited for other 8 bit MCUs.
 182
 183 \newline
 184
 185 \newline
 186 The peep hole optimizer uses a rule based substitution mechanism which is
 187  MCU independent.
 188
 189 \newline
 190
 191 \newline
 192 Supported data-types are:
 193 \layout Itemize
 194
 195 char (8 bits, 1 byte),
 196 \layout Itemize
 197
 198 short and int (16 bits, 2 bytes),
 199 \layout Itemize
 200
 201 long (32 bit, 4 bytes)
 202 \layout Itemize
 203
 204 float (4 byte IEEE).
 205
 206 \layout Standard
 207
 208 The compiler also allows
 209 \emph on
 210 inline assembler code
 211 \emph default
 212  to be embedded anywhere in a function.
 213  In addition, routines developed in assembly can also be called.
 214 \newline
 215
 216 \newline
 217 SDCC also provides an option (-
 218 \begin_inset ERT
 219 status Collapsed
 220
 221 \layout Standard
 222
 223 \backslash
 224 /
 225 \end_inset
 226
 227 -cyclomatic) to report the relative complexity of a function.
 228  These functions can then be further optimized, or hand coded in assembly
 229  if needed.
 230
 231 \newline
 232
 233 \newline
 234 SDCC also comes with a companion source level debugger SDCDB, the debugger
 235  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 236
 237 \newline
 238
 239 \newline
 240 The latest version can be downloaded from
 241 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 242
 243 \end_inset
 244
 245 .
 246
 247 \series bold
 248
 249 \series default
 250 \emph on
 251 Please note: the compiler will probably always be some steps ahead of this
 252  documentation
 253 \series bold
 254 \emph default
 255
 256 \begin_inset LatexCommand \index{Status of documentation}
 257
 258 \end_inset
 259
 260
 261 \begin_inset Foot
 262 collapsed false
 263
 264 \layout Standard
 265
 266 Obviously this has pros and cons
 267 \end_inset
 268
 269 .
 270 \layout Section
 271
 272 Open Source
 273 \layout Standard
 274
 275 All packages used in this compiler system are
 276 \emph on
 277 opensource
 278 \emph default
 279  and
 280 \emph on
 281 freeware
 282 \emph default
 283 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 284  etc) is distributed with the package.
 285  This documentation is maintained using a freeware word processor (LyX).
 286 \newline
 287 This program is free software; you can redistribute it and/or modify it
 288  under the terms of the GNU General Public License
 289 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 290
 291 \end_inset
 292
 293  as published by the Free Software Foundation; either version 2, or (at
 294  your option) any later version.
 295  This program is distributed in the hope that it will be useful, but WITHOUT
 296  ANY WARRANTY; without even the implied warranty
 297 \begin_inset LatexCommand \index{warranty}
 298
 299 \end_inset
 300
 301  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 302  See the GNU General Public License for more details.
 303  You should have received a copy of the GNU General Public License along
 304  with this program; if not, write to the Free Software Foundation, 59 Temple
 305  Place - Suite 330, Boston, MA 02111-1307, USA.
 306  In other words, you are welcome to use, share and improve this program.
 307  You are forbidden to forbid anyone else to use, share and improve what
 308  you give them.
 309  Help stamp out software-hoarding!
 310 \layout Section
 311
 312 Typographic conventions
 313 \begin_inset LatexCommand \index{Typographic conventions}
 314
 315 \end_inset
 316
 317
 318 \layout Standard
 319
 320 Throughout this manual, we will use the following convention.
 321  Commands you have to type in are printed in
 322 \family sans
 323 \series bold
 324 "sans serif"
 325 \series default
 326 .
 327
 328 \family default
 329  Code samples are printed in
 330 \family typewriter
 331 typewriter font.
 332
 333 \family default
 334  Interesting items and new terms are printed in
 335 \emph on
 336 italic.
 337 \layout Section
 338
 339 Compatibility with previous versions
 340 \layout Standard
 341
 342 This version has numerous bug fixes compared with the previous version.
 343  But we also introduced some incompatibilities with older versions.
 344  Not just for the fun of it, but to make the compiler more stable, efficient
 345  and ANSI compliant
 346 \begin_inset LatexCommand \index{ANSI-compliance}
 347
 348 \end_inset
 349
 350  (see section
 351 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 352
 353 \end_inset
 354
 355  for ANSI-Compliance).
 356
 357 \newline
 358
 359 \layout Itemize
 360
 361 short is now equivalent to int (16 bits), it used to be equivalent to char
 362  (8 bits) which is not ANSI compliant
 363 \layout Itemize
 364
 365 the default directory for gcc-builds where include, library and documentation
 366  files are stored is now in /usr/local/share
 367 \layout Itemize
 368
 369 char type parameters to vararg functions are casted to int unless explicitly
 370  casted, e.g.:
 371 \newline
 372
 373 \family typewriter
 374 \SpecialChar ~
 375 \SpecialChar ~
 376 char a=3;
 377 \newline
 378 \SpecialChar ~
 379 \SpecialChar ~
 380 printf ("%d %c
 381 \backslash
 382 n", a, (char)a);
 383 \family default
 384
 385 \newline
 386  will push a as an int and as a char resp.
 387 \layout Itemize
 388
 389 option -
 390 \begin_inset ERT
 391 status Collapsed
 392
 393 \layout Standard
 394
 395 \backslash
 396 /
 397 \end_inset
 398
 399 -regextend has been removed
 400 \layout Itemize
 401
 402 option -
 403 \begin_inset ERT
 404 status Collapsed
 405
 406 \layout Standard
 407
 408 \backslash
 409 /
 410 \end_inset
 411
 412 -noregparms has been removed
 413 \layout Itemize
 414
 415 option -
 416 \begin_inset ERT
 417 status Collapsed
 418
 419 \layout Standard
 420
 421 \backslash
 422 /
 423 \end_inset
 424
 425 -stack-after-data has been removed
 426 \layout Standard
 427
 428
 429 \emph on
 430 <pending: more incompatibilities?>
 431 \layout Section
 432
 433 System Requirements
 434 \layout Standard
 435
 436 What do you need before you start installation of SDCC? A computer, and
 437  a desire to compute.
 438  The preferred method of installation is to compile SDCC from source using
 439  GNU gcc and make.
 440  For Windows some pre-compiled binary distributions are available for your
 441  convenience.
 442  You should have some experience with command line tools and compiler use.
 443 \layout Section
 444
 445 Other Resources
 446 \layout Standard
 447
 448 The SDCC home page at
 449 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 450
 451 \end_inset
 452
 453  is a great place to find distribution sets.
 454  You can also find links to the user mailing lists that offer help or discuss
 455  SDCC with other SDCC users.
 456  Web links to other SDCC related sites can also be found here.
 457  This document can be found in the DOC directory of the source package as
 458  a text or HTML file.
 459  A pdf version of this document is available at
 460 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 461
 462 \end_inset
 463
 464 .
 465  Some of the other tools (simulator and assembler) included with SDCC contain
 466  their own documentation and can be found in the source distribution.
 467  If you want the latest unreleased software, the complete source package
 468  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 469 \layout Section
 470
 471 Wishes for the future
 472 \layout Standard
 473
 474 There are (and always will be) some things that could be done.
 475  Here are some I can think of:
 476 \newline
 477
 478 \layout Standard
 479
 480
 481 \family typewriter
 482 char KernelFunction3(char p) at 0x340;
 483 \newline
 484
 485 \layout Standard
 486
 487
 488 \family typewriter
 489 code banking
 490 \begin_inset LatexCommand \index{code banking (not supported)}
 491
 492 \end_inset
 493
 494  support for mcs51
 495 \newline
 496
 497 \newline
 498
 499 \family default
 500 If you can think of some more, please see the section
 501 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 502
 503 \end_inset
 504
 505  about filing feature requests
 506 \begin_inset LatexCommand \index{Requesting features}
 507
 508 \end_inset
 509
 510
 511 \begin_inset LatexCommand \index{Feature request}
 512
 513 \end_inset
 514
 515 .
 516 \newline
 517
 518 \layout Chapter
 519
 520 Installing SDCC
 521 \begin_inset LatexCommand \index{Installation}
 522
 523 \end_inset
 524
 525
 526 \layout Standard
 527
 528 For most users it is sufficient to skip to either section
 529 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 530
 531 \end_inset
 532
 533  or section
 534 \begin_inset LatexCommand \ref{sub:Windows-Install}
 535
 536 \end_inset
 537
 538 .
 539  More detailled instructions follow below.
 540 \layout Section
 541
 542 Configure Options
 543 \begin_inset LatexCommand \index{Options SDCC configuration}
 544
 545 \end_inset
 546
 547
 548 \layout Standard
 549
 550 The install paths, search paths and other options are defined when running
 551  'configure'.
 552  The defaults can be overridden by:
 553 \layout List
 554 \labelwidthstring 00.00.0000
 555
 556 -
 557 \begin_inset ERT
 558 status Collapsed
 559
 560 \layout Standard
 561
 562 \backslash
 563 /
 564 \end_inset
 565
 566 -prefix see table below
 567 \layout List
 568 \labelwidthstring 00.00.0000
 569
 570 -
 571 \begin_inset ERT
 572 status Collapsed
 573
 574 \layout Standard
 575
 576 \backslash
 577 /
 578 \end_inset
 579
 580 -exec_prefix see table below
 581 \layout List
 582 \labelwidthstring 00.00.0000
 583
 584 -
 585 \begin_inset ERT
 586 status Collapsed
 587
 588 \layout Standard
 589
 590 \backslash
 591 /
 592 \end_inset
 593
 594 -bindir see table below
 595 \layout List
 596 \labelwidthstring 00.00.0000
 597
 598 -
 599 \begin_inset ERT
 600 status Collapsed
 601
 602 \layout Standard
 603
 604 \backslash
 605 /
 606 \end_inset
 607
 608 -datadir see table below
 609 \layout List
 610 \labelwidthstring 00.00.0000
 611
 612 docdir environment variable, see table below
 613 \layout List
 614 \labelwidthstring 00.00.0000
 615
 616 include_dir_suffix environment variable, see table below
 617 \layout List
 618 \labelwidthstring 00.00.0000
 619
 620 lib_dir_suffix environment variable, see table below
 621 \layout List
 622 \labelwidthstring 00.00.0000
 623
 624 sdccconf_h_dir_separator environment variable, either / or
 625 \backslash
 626
 627 \backslash
 628  makes sense here.
 629  This character will only be used in sdccconf.h; don't forget it's a C-header,
 630  therefore a double-backslash is needed there.
 631 \layout List
 632 \labelwidthstring 00.00.0000
 633
 634 -
 635 \begin_inset ERT
 636 status Collapsed
 637
 638 \layout Standard
 639
 640 \backslash
 641 /
 642 \end_inset
 643
 644 -disable-mcs51-port Excludes the Intel mcs51 port
 645 \layout List
 646 \labelwidthstring 00.00.0000
 647
 648 -
 649 \begin_inset ERT
 650 status Collapsed
 651
 652 \layout Standard
 653
 654 \backslash
 655 /
 656 \end_inset
 657
 658 -disable-gbz80-port Excludes the Gameboy gbz80 port
 659 \layout List
 660 \labelwidthstring 00.00.0000
 661
 662 -
 663 \begin_inset ERT
 664 status Collapsed
 665
 666 \layout Standard
 667
 668 \backslash
 669 /
 670 \end_inset
 671
 672 -disable-z80-port Excludes the z80 port
 673 \layout List
 674 \labelwidthstring 00.00.0000
 675
 676 -
 677 \begin_inset ERT
 678 status Collapsed
 679
 680 \layout Standard
 681
 682 \backslash
 683 /
 684 \end_inset
 685
 686 -disable-avr-port Excludes the AVR port
 687 \layout List
 688 \labelwidthstring 00.00.0000
 689
 690 -
 691 \begin_inset ERT
 692 status Collapsed
 693
 694 \layout Standard
 695
 696 \backslash
 697 /
 698 \end_inset
 699
 700 -disable-ds390-port Excludes the DS390 port
 701 \layout List
 702 \labelwidthstring 00.00.0000
 703
 704 -
 705 \begin_inset ERT
 706 status Collapsed
 707
 708 \layout Standard
 709
 710 \backslash
 711 /
 712 \end_inset
 713
 714 -disable-hc08-port Excludes the HC08 port
 715 \layout List
 716 \labelwidthstring 00.00.0000
 717
 718 -
 719 \begin_inset ERT
 720 status Collapsed
 721
 722 \layout Standard
 723
 724 \backslash
 725 /
 726 \end_inset
 727
 728 -disable-pic-port Excludes the PIC port
 729 \layout List
 730 \labelwidthstring 00.00.0000
 731
 732 -
 733 \begin_inset ERT
 734 status Collapsed
 735
 736 \layout Standard
 737
 738 \backslash
 739 /
 740 \end_inset
 741
 742 -disable-xa51-port Excludes the XA51 port
 743 \layout List
 744 \labelwidthstring 00.00.0000
 745
 746 -
 747 \begin_inset ERT
 748 status Collapsed
 749
 750 \layout Standard
 751
 752 \backslash
 753 /
 754 \end_inset
 755
 756 -disable-ucsim Disables configuring and building of ucsim
 757 \layout List
 758 \labelwidthstring 00.00.0000
 759
 760 -
 761 \begin_inset ERT
 762 status Collapsed
 763
 764 \layout Standard
 765
 766 \backslash
 767 /
 768 \end_inset
 769
 770 -disable-device-lib-build Disables automatically building device libraries
 771 \layout List
 772 \labelwidthstring 00.00.0000
 773
 774 -
 775 \begin_inset ERT
 776 status Collapsed
 777
 778 \layout Standard
 779
 780 \backslash
 781 /
 782 \end_inset
 783
 784 -disable-packihx Disables building packihx
 785 \layout List
 786 \labelwidthstring 00.00.0000
 787
 788 -
 789 \begin_inset ERT
 790 status Collapsed
 791
 792 \layout Standard
 793
 794 \backslash
 795 /
 796 \end_inset
 797
 798 -enable-libgc Use the Bohem memory allocator.
 799  Lower runtime footprint.
 800 \layout Standard
 801
 802 Furthermore the environment variables CC, CFLAGS, ...
 803  the tools and their arguments can be influenced.
 804  Please see `configure -
 805 \begin_inset ERT
 806 status Collapsed
 807
 808 \layout Standard
 809
 810 \backslash
 811 /
 812 \end_inset
 813
 814 -help` and the man/info pages of `configure` for details.
 815 \newline
 816
 817 \newline
 818 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 819  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 820 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 821  At the moment it's not possible to change the default settings (it was
 822  simply never required).
 823 \newline
 824
 825 \newline
 826 These configure options are compiled into the binaries, and can only be
 827  changed by rerunning 'configure' and recompiling SDCC.
 828  The configure options are written in
 829 \emph on
 830 italics
 831 \emph default
 832  to distinguish them from run time environment variables (see section search
 833  paths).
 834 \newline
 835
 836 \newline
 837 The settings for
 838 \begin_inset Quotes sld
 839 \end_inset
 840
 841 Win32 builds
 842 \begin_inset Quotes srd
 843 \end_inset
 844
 845  are used by the SDCC team to build the official Win32 binaries.
 846  The SDCC team uses Mingw32 to build the official Windows binaries, because
 847  it's
 848 \layout Enumerate
 849
 850 open source,
 851 \layout Enumerate
 852
 853 a gcc compiler and last but not least
 854 \layout Enumerate
 855
 856 the binaries can be built by cross compiling on Sourceforge's compile farm.
 857 \layout Standard
 858
 859 See the examples, how to pass the Win32 settings to 'configure'.
 860  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 861  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 862  for Win32.
 863 \newline
 864
 865 \newline
 866 These defaults are:
 867 \newline
 868
 869 \layout Standard
 870 \align center
 871
 872 \begin_inset  Tabular
 873 <lyxtabular version="3" rows="8" columns="3">
 874 <features>
 875 <column alignment="block" valignment="top" leftline="true" width="0in">
 876 <column alignment="block" valignment="top" leftline="true" width="0in">
 877 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 878 <row topline="true" bottomline="true">
 879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 880 \begin_inset Text
 881
 882 \layout Standard
 883
 884 Variable
 885 \end_inset
 886 </cell>
 887 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 888 \begin_inset Text
 889
 890 \layout Standard
 891
 892 default
 893 \end_inset
 894 </cell>
 895 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 896 \begin_inset Text
 897
 898 \layout Standard
 899
 900 Win32 builds
 901 \end_inset
 902 </cell>
 903 </row>
 904 <row topline="true">
 905 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 906 \begin_inset Text
 907
 908 \layout Standard
 909
 910
 911 \emph on
 912 PREFIX
 913 \end_inset
 914 </cell>
 915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 916 \begin_inset Text
 917
 918 \layout Standard
 919
 920 /usr/local
 921 \end_inset
 922 </cell>
 923 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 924 \begin_inset Text
 925
 926 \layout Standard
 927
 928
 929 \backslash
 930 sdcc
 931 \end_inset
 932 </cell>
 933 </row>
 934 <row topline="true">
 935 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 936 \begin_inset Text
 937
 938 \layout Standard
 939
 940
 941 \emph on
 942 EXEC_PREFIX
 943 \end_inset
 944 </cell>
 945 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 946 \begin_inset Text
 947
 948 \layout Standard
 949
 950
 951 \emph on
 952 $PREFIX
 953 \end_inset
 954 </cell>
 955 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 956 \begin_inset Text
 957
 958 \layout Standard
 959
 960
 961 \emph on
 962 $PREFIX
 963 \end_inset
 964 </cell>
 965 </row>
 966 <row topline="true">
 967 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 968 \begin_inset Text
 969
 970 \layout Standard
 971
 972
 973 \emph on
 974 BINDIR
 975 \end_inset
 976 </cell>
 977 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 978 \begin_inset Text
 979
 980 \layout Standard
 981
 982
 983 \emph on
 984 $EXECPREFIX
 985 \emph default
 986 /bin
 987 \end_inset
 988 </cell>
 989 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 990 \begin_inset Text
 991
 992 \layout Standard
 993
 994
 995 \emph on
 996 $EXECPREFIX
 997 \emph default
 998
 999 \backslash
1000 bin
1001 \end_inset
1002 </cell>
1003 </row>
1004 <row topline="true">
1005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1006 \begin_inset Text
1007
1008 \layout Standard
1009
1010
1011 \emph on
1012 DATADIR
1013 \end_inset
1014 </cell>
1015 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1016 \begin_inset Text
1017
1018 \layout Standard
1019
1020
1021 \emph on
1022 $PREFIX
1023 \emph default
1024 /share
1025 \end_inset
1026 </cell>
1027 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1028 \begin_inset Text
1029
1030 \layout Standard
1031
1032
1033 \emph on
1034 $PREFIX
1035 \end_inset
1036 </cell>
1037 </row>
1038 <row topline="true">
1039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1040 \begin_inset Text
1041
1042 \layout Standard
1043
1044
1045 \emph on
1046 DOCDIR
1047 \end_inset
1048 </cell>
1049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1050 \begin_inset Text
1051
1052 \layout Standard
1053
1054
1055 \emph on
1056 $DATADIR
1057 \emph default
1058 /sdcc/doc
1059 \end_inset
1060 </cell>
1061 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1062 \begin_inset Text
1063
1064 \layout Standard
1065
1066
1067 \emph on
1068 $DATADIR
1069 \emph default
1070
1071 \backslash
1072 doc
1073 \end_inset
1074 </cell>
1075 </row>
1076 <row topline="true">
1077 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1078 \begin_inset Text
1079
1080 \layout Standard
1081
1082
1083 \emph on
1084 INCLUDE_DIR_SUFFIX
1085 \end_inset
1086 </cell>
1087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1088 \begin_inset Text
1089
1090 \layout Standard
1091
1092 sdcc/include
1093 \end_inset
1094 </cell>
1095 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1096 \begin_inset Text
1097
1098 \layout Standard
1099
1100 include
1101 \end_inset
1102 </cell>
1103 </row>
1104 <row topline="true" bottomline="true">
1105 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1106 \begin_inset Text
1107
1108 \layout Standard
1109
1110
1111 \emph on
1112 LIB_DIR_SUFFIX
1113 \end_inset
1114 </cell>
1115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1116 \begin_inset Text
1117
1118 \layout Standard
1119
1120 sdcc/lib
1121 \end_inset
1122 </cell>
1123 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1124 \begin_inset Text
1125
1126 \layout Standard
1127
1128 lib
1129 \end_inset
1130 </cell>
1131 </row>
1132 </lyxtabular>
1133
1134 \end_inset
1135
1136
1137 \newline
1138
1139 \layout Standard
1140 \noindent
1141 'configure' also computes relative paths.
1142  This is needed for full relocatability of a binary package and to complete
1143  search paths (see section search paths below):
1144 \newline
1145
1146 \layout Standard
1147 \align center
1148
1149 \begin_inset  Tabular
1150 <lyxtabular version="3" rows="4" columns="3">
1151 <features>
1152 <column alignment="block" valignment="top" leftline="true" width="0in">
1153 <column alignment="block" valignment="top" leftline="true" width="0in">
1154 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1155 <row topline="true" bottomline="true">
1156 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1157 \begin_inset Text
1158
1159 \layout Standard
1160
1161 Variable (computed)
1162 \end_inset
1163 </cell>
1164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1165 \begin_inset Text
1166
1167 \layout Standard
1168
1169 default
1170 \end_inset
1171 </cell>
1172 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1173 \begin_inset Text
1174
1175 \layout Standard
1176
1177 Win32 builds
1178 \end_inset
1179 </cell>
1180 </row>
1181 <row topline="true" bottomline="true">
1182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1183 \begin_inset Text
1184
1185 \layout Standard
1186
1187
1188 \emph on
1189 BIN2DATA_DIR
1190 \end_inset
1191 </cell>
1192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1193 \begin_inset Text
1194
1195 \layout Standard
1196
1197 ../share
1198 \end_inset
1199 </cell>
1200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1201 \begin_inset Text
1202
1203 \layout Standard
1204
1205 ..
1206 \end_inset
1207 </cell>
1208 </row>
1209 <row bottomline="true">
1210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1211 \begin_inset Text
1212
1213 \layout Standard
1214
1215
1216 \emph on
1217 PREFIX2BIN_DIR
1218 \end_inset
1219 </cell>
1220 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1221 \begin_inset Text
1222
1223 \layout Standard
1224
1225 bin
1226 \end_inset
1227 </cell>
1228 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1229 \begin_inset Text
1230
1231 \layout Standard
1232
1233 bin
1234 \end_inset
1235 </cell>
1236 </row>
1237 <row bottomline="true">
1238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1239 \begin_inset Text
1240
1241 \layout Standard
1242
1243
1244 \emph on
1245 PREFIX2DATA_DIR
1246 \end_inset
1247 </cell>
1248 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1249 \begin_inset Text
1250
1251 \layout Standard
1252
1253 share/sdcc
1254 \end_inset
1255 </cell>
1256 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1257 \begin_inset Text
1258
1259 \layout Standard
1260
1261 \end_inset
1262 </cell>
1263 </row>
1264 </lyxtabular>
1265
1266 \end_inset
1267
1268
1269 \newline
1270
1271 \layout Standard
1272 \noindent
1273 Examples:
1274 \layout LyX-Code
1275
1276 ./configure
1277 \newline
1278 ./configure -
1279 \begin_inset ERT
1280 status Collapsed
1281
1282 \layout Standard
1283
1284 \backslash
1285 /
1286 \end_inset
1287
1288 -prefix=
1289 \begin_inset Quotes srd
1290 \end_inset
1291
1292 /usr/bin
1293 \begin_inset Quotes srd
1294 \end_inset
1295
1296  -
1297 \begin_inset ERT
1298 status Collapsed
1299
1300 \layout Standard
1301
1302 \backslash
1303 /
1304 \end_inset
1305
1306 -datadir=
1307 \begin_inset Quotes srd
1308 \end_inset
1309
1310 /usr/share
1311 \begin_inset Quotes srd
1312 \end_inset
1313
1314
1315 \newline
1316 ./configure -
1317 \begin_inset ERT
1318 status Collapsed
1319
1320 \layout Standard
1321
1322 \backslash
1323 /
1324 \end_inset
1325
1326 -disable-avr-port -
1327 \begin_inset ERT
1328 status Collapsed
1329
1330 \layout Standard
1331
1332 \backslash
1333 /
1334 \end_inset
1335
1336 -disable-xa51-port
1337 \layout Standard
1338
1339 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1340 32'):
1341 \layout LyX-Code
1342
1343 ./configure
1344 \backslash
1345
1346 \newline
1347 CC=
1348 \begin_inset Quotes srd
1349 \end_inset
1350
1351 i586-mingw32msvc-gcc
1352 \begin_inset Quotes srd
1353 \end_inset
1354
1355  CXX=
1356 \begin_inset Quotes srd
1357 \end_inset
1358
1359 i586-mingw32msvc-g++
1360 \begin_inset Quotes srd
1361 \end_inset
1362
1363
1364 \backslash
1365
1366 \newline
1367 RANLIB=
1368 \begin_inset Quotes srd
1369 \end_inset
1370
1371 i586-mingw32msvc-ranlib
1372 \begin_inset Quotes srd
1373 \end_inset
1374
1375
1376 \backslash
1377
1378 \newline
1379 STRIP=
1380 \begin_inset Quotes srd
1381 \end_inset
1382
1383 i586-mingw32msvc-strip
1384 \begin_inset Quotes srd
1385 \end_inset
1386
1387
1388 \backslash
1389
1390 \newline
1391 -
1392 \begin_inset ERT
1393 status Collapsed
1394
1395 \layout Standard
1396
1397 \backslash
1398 /
1399 \end_inset
1400
1401 -prefix=
1402 \begin_inset Quotes srd
1403 \end_inset
1404
1405 /sdcc
1406 \begin_inset Quotes srd
1407 \end_inset
1408
1409
1410 \backslash
1411
1412 \newline
1413 -
1414 \begin_inset ERT
1415 status Collapsed
1416
1417 \layout Standard
1418
1419 \backslash
1420 /
1421 \end_inset
1422
1423 -datadir=
1424 \begin_inset Quotes srd
1425 \end_inset
1426
1427 /sdcc
1428 \begin_inset Quotes srd
1429 \end_inset
1430
1431
1432 \backslash
1433
1434 \newline
1435 docdir=
1436 \begin_inset Quotes srd
1437 \end_inset
1438
1439 /sdcc/doc
1440 \begin_inset Quotes srd
1441 \end_inset
1442
1443
1444 \backslash
1445
1446 \newline
1447 include_dir_suffix=
1448 \begin_inset Quotes srd
1449 \end_inset
1450
1451 include
1452 \begin_inset Quotes srd
1453 \end_inset
1454
1455
1456 \backslash
1457
1458 \newline
1459 lib_dir_suffix=
1460 \begin_inset Quotes srd
1461 \end_inset
1462
1463 lib
1464 \begin_inset Quotes srd
1465 \end_inset
1466
1467
1468 \backslash
1469
1470 \newline
1471 sdccconf_h_dir_separator=
1472 \begin_inset Quotes srd
1473 \end_inset
1474
1475
1476 \backslash
1477
1478 \backslash
1479
1480 \backslash
1481
1482 \backslash
1483
1484 \begin_inset Quotes srd
1485 \end_inset
1486
1487
1488 \backslash
1489
1490 \newline
1491 -
1492 \begin_inset ERT
1493 status Collapsed
1494
1495 \layout Standard
1496
1497 \backslash
1498 /
1499 \end_inset
1500
1501 -disable-device-lib-build
1502 \backslash
1503
1504 \newline
1505 -
1506 \begin_inset ERT
1507 status Collapsed
1508
1509 \layout Standard
1510
1511 \backslash
1512 /
1513 \end_inset
1514
1515 -disable-ucsim
1516 \backslash
1517
1518 \newline
1519 -
1520 \begin_inset ERT
1521 status Collapsed
1522
1523 \layout Standard
1524
1525 \backslash
1526 /
1527 \end_inset
1528
1529 -host=i586-mingw32msvc -
1530 \begin_inset ERT
1531 status Collapsed
1532
1533 \layout Standard
1534
1535 \backslash
1536 /
1537 \end_inset
1538
1539 -build=unknown-unknown-linux-gnu
1540 \layout Standard
1541
1542 To
1543 \begin_inset Quotes sld
1544 \end_inset
1545
1546 cross
1547 \begin_inset Quotes srd
1548 \end_inset
1549
1550 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1551 ):
1552 \layout LyX-Code
1553
1554 ./configure -C
1555 \backslash
1556
1557 \newline
1558 CFLAGS=
1559 \begin_inset Quotes srd
1560 \end_inset
1561
1562 -mno-cygwin -O2
1563 \begin_inset Quotes srd
1564 \end_inset
1565
1566
1567 \backslash
1568
1569 \newline
1570 LDFLAGS=
1571 \begin_inset Quotes srd
1572 \end_inset
1573
1574 -mno-cygwin
1575 \begin_inset Quotes srd
1576 \end_inset
1577
1578
1579 \backslash
1580
1581 \newline
1582 -
1583 \begin_inset ERT
1584 status Collapsed
1585
1586 \layout Standard
1587
1588 \backslash
1589 /
1590 \end_inset
1591
1592 -prefix=
1593 \begin_inset Quotes srd
1594 \end_inset
1595
1596 /sdcc
1597 \begin_inset Quotes srd
1598 \end_inset
1599
1600
1601 \backslash
1602
1603 \newline
1604 -
1605 \begin_inset ERT
1606 status Collapsed
1607
1608 \layout Standard
1609
1610 \backslash
1611 /
1612 \end_inset
1613
1614 -datadir=
1615 \begin_inset Quotes srd
1616 \end_inset
1617
1618 /sdcc
1619 \begin_inset Quotes srd
1620 \end_inset
1621
1622
1623 \backslash
1624
1625 \newline
1626 docdir=
1627 \begin_inset Quotes srd
1628 \end_inset
1629
1630 /sdcc/doc
1631 \begin_inset Quotes srd
1632 \end_inset
1633
1634
1635 \backslash
1636
1637 \newline
1638 include_dir_suffix=
1639 \begin_inset Quotes srd
1640 \end_inset
1641
1642 include
1643 \begin_inset Quotes srd
1644 \end_inset
1645
1646
1647 \backslash
1648
1649 \newline
1650 lib_dir_suffix=
1651 \begin_inset Quotes srd
1652 \end_inset
1653
1654 lib
1655 \begin_inset Quotes srd
1656 \end_inset
1657
1658
1659 \backslash
1660
1661 \newline
1662 sdccconf_h_dir_separator=
1663 \begin_inset Quotes srd
1664 \end_inset
1665
1666
1667 \backslash
1668
1669 \backslash
1670
1671 \backslash
1672
1673 \backslash
1674
1675 \begin_inset Quotes srd
1676 \end_inset
1677
1678
1679 \backslash
1680
1681 \newline
1682 -
1683 \begin_inset ERT
1684 status Collapsed
1685
1686 \layout Standard
1687
1688 \backslash
1689 /
1690 \end_inset
1691
1692 -disable-ucsim
1693 \layout Standard
1694
1695 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1696  The option '-
1697 \begin_inset ERT
1698 status Collapsed
1699
1700 \layout Standard
1701
1702 \backslash
1703 /
1704 \end_inset
1705
1706 -C' turns on caching, which gives a little bit extra speed.
1707  However if options are changed, it can be necessary to delete the config.cache
1708  file.
1709 \layout Section
1710
1711 Install paths
1712 \begin_inset LatexCommand \label{sub:Install-paths}
1713
1714 \end_inset
1715
1716
1717 \begin_inset LatexCommand \index{Install paths}
1718
1719 \end_inset
1720
1721
1722 \layout Standard
1723 \added_space_top medskip \align center
1724
1725 \begin_inset  Tabular
1726 <lyxtabular version="3" rows="5" columns="4">
1727 <features>
1728 <column alignment="center" valignment="top" leftline="true" width="0">
1729 <column alignment="center" valignment="top" leftline="true" width="0">
1730 <column alignment="center" valignment="top" leftline="true" width="0">
1731 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1732 <row topline="true" bottomline="true">
1733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1734 \begin_inset Text
1735
1736 \layout Standard
1737
1738
1739 \series bold
1740 Description
1741 \end_inset
1742 </cell>
1743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1744 \begin_inset Text
1745
1746 \layout Standard
1747
1748
1749 \series bold
1750 Path
1751 \end_inset
1752 </cell>
1753 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1754 \begin_inset Text
1755
1756 \layout Standard
1757
1758
1759 \series bold
1760 Default
1761 \end_inset
1762 </cell>
1763 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1764 \begin_inset Text
1765
1766 \layout Standard
1767
1768
1769 \series bold
1770 Win32 builds
1771 \end_inset
1772 </cell>
1773 </row>
1774 <row topline="true">
1775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1776 \begin_inset Text
1777
1778 \layout Standard
1779
1780 Binary files*
1781 \end_inset
1782 </cell>
1783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1784 \begin_inset Text
1785
1786 \layout Standard
1787
1788
1789 \emph on
1790 $EXEC_PREFIX
1791 \end_inset
1792 </cell>
1793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1794 \begin_inset Text
1795
1796 \layout Standard
1797
1798 /usr/local/bin
1799 \end_inset
1800 </cell>
1801 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1802 \begin_inset Text
1803
1804 \layout Standard
1805
1806
1807 \backslash
1808 sdcc
1809 \backslash
1810 bin
1811 \end_inset
1812 </cell>
1813 </row>
1814 <row topline="true">
1815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1816 \begin_inset Text
1817
1818 \layout Standard
1819
1820 Include files
1821 \end_inset
1822 </cell>
1823 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1824 \begin_inset Text
1825
1826 \layout Standard
1827
1828
1829 \emph on
1830 $DATADIR/ $INCLUDE_DIR_SUFFIX
1831 \end_inset
1832 </cell>
1833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1834 \begin_inset Text
1835
1836 \layout Standard
1837
1838 /usr/local/share/sdcc/include
1839 \end_inset
1840 </cell>
1841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1842 \begin_inset Text
1843
1844 \layout Standard
1845
1846
1847 \backslash
1848 sdcc
1849 \backslash
1850 include
1851 \end_inset
1852 </cell>
1853 </row>
1854 <row topline="true">
1855 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1856 \begin_inset Text
1857
1858 \layout Standard
1859
1860 Library file**
1861 \end_inset
1862 </cell>
1863 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1864 \begin_inset Text
1865
1866 \layout Standard
1867
1868
1869 \emph on
1870 $DATADIR/$LIB_DIR_SUFFIX
1871 \end_inset
1872 </cell>
1873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1874 \begin_inset Text
1875
1876 \layout Standard
1877
1878 /usr/local/share/sdcc/lib
1879 \end_inset
1880 </cell>
1881 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1882 \begin_inset Text
1883
1884 \layout Standard
1885
1886
1887 \backslash
1888 sdcc
1889 \backslash
1890 lib
1891 \end_inset
1892 </cell>
1893 </row>
1894 <row topline="true" bottomline="true">
1895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1896 \begin_inset Text
1897
1898 \layout Standard
1899
1900 Documentation
1901 \end_inset
1902 </cell>
1903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1904 \begin_inset Text
1905
1906 \layout Standard
1907
1908
1909 \emph on
1910 $DOCDIR
1911 \end_inset
1912 </cell>
1913 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1914 \begin_inset Text
1915
1916 \layout Standard
1917
1918 /usr/local/share/sdcc/doc
1919 \end_inset
1920 </cell>
1921 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1922 \begin_inset Text
1923
1924 \layout Standard
1925
1926
1927 \backslash
1928 sdcc
1929 \backslash
1930 doc
1931 \end_inset
1932 </cell>
1933 </row>
1934 </lyxtabular>
1935
1936 \end_inset
1937
1938
1939 \layout Verse
1940
1941
1942 \size footnotesize
1943 *compiler, preprocessor, assembler, and linker
1944 \newline
1945 **the
1946 \shape italic
1947 model
1948 \shape default
1949  is auto-appended by the compiler, e.g.
1950  small, large, z80, ds390 etc
1951 \layout Standard
1952 \noindent
1953 The install paths can still be changed during `make install` with e.g.:
1954 \layout LyX-Code
1955
1956 make install prefix=$(HOME)/local/sdcc
1957 \layout Standard
1958
1959 Of course this doesn't change the search paths compiled into the binaries.
1960 \layout Section
1961
1962 Search Paths
1963 \begin_inset LatexCommand \label{sub:Search-Paths}
1964
1965 \end_inset
1966
1967
1968 \begin_inset LatexCommand \index{Search path}
1969
1970 \end_inset
1971
1972
1973 \layout Standard
1974
1975 Some search paths or parts of them are determined by configure variables
1976  (in
1977 \emph on
1978 italics
1979 \emph default
1980 , see section above).
1981  Further search paths are determined by environment variables during runtime.
1982
1983 \newline
1984 The paths searched when running the compiler are as follows (the first catch
1985  wins):
1986 \newline
1987
1988 \newline
1989 1.
1990  Binary files (preprocessor, assembler and linker)
1991 \newline
1992
1993 \layout Standard
1994 \align center
1995
1996 \begin_inset  Tabular
1997 <lyxtabular version="3" rows="4" columns="3">
1998 <features>
1999 <column alignment="block" valignment="top" leftline="true" width="0in">
2000 <column alignment="block" valignment="top" leftline="true" width="0in">
2001 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2002 <row topline="true" bottomline="true">
2003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2004 \begin_inset Text
2005
2006 \layout Standard
2007
2008 Search path
2009 \end_inset
2010 </cell>
2011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2012 \begin_inset Text
2013
2014 \layout Standard
2015
2016 default
2017 \end_inset
2018 </cell>
2019 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2020 \begin_inset Text
2021
2022 \layout Standard
2023
2024 Win32 builds
2025 \end_inset
2026 </cell>
2027 </row>
2028 <row topline="true">
2029 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2030 \begin_inset Text
2031
2032 \layout Standard
2033
2034 $SDCC_HOME/
2035 \emph on
2036 $PPREFIX2BIN_DIR
2037 \end_inset
2038 </cell>
2039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2040 \begin_inset Text
2041
2042 \layout Standard
2043
2044 $SDCC_HOME/bin
2045 \end_inset
2046 </cell>
2047 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2048 \begin_inset Text
2049
2050 \layout Standard
2051
2052 $SDCC_HOME
2053 \backslash
2054 bin
2055 \end_inset
2056 </cell>
2057 </row>
2058 <row topline="true">
2059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2060 \begin_inset Text
2061
2062 \layout Standard
2063
2064 Path of argv[0] (if available)
2065 \end_inset
2066 </cell>
2067 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2068 \begin_inset Text
2069
2070 \layout Standard
2071
2072 Path of argv[0]
2073 \end_inset
2074 </cell>
2075 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2076 \begin_inset Text
2077
2078 \layout Standard
2079
2080 Path of argv[0]
2081 \end_inset
2082 </cell>
2083 </row>
2084 <row topline="true" bottomline="true">
2085 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2086 \begin_inset Text
2087
2088 \layout Standard
2089
2090 $PATH
2091 \end_inset
2092 </cell>
2093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2094 \begin_inset Text
2095
2096 \layout Standard
2097
2098 $PATH
2099 \end_inset
2100 </cell>
2101 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2102 \begin_inset Text
2103
2104 \layout Standard
2105
2106 $PATH
2107 \end_inset
2108 </cell>
2109 </row>
2110 </lyxtabular>
2111
2112 \end_inset
2113
2114
2115 \newline
2116
2117 \layout Standard
2118 \noindent
2119 2.
2120  Include files
2121 \newline
2122
2123 \layout Standard
2124 \align center
2125
2126 \begin_inset  Tabular
2127 <lyxtabular version="3" rows="6" columns="3">
2128 <features>
2129 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2130 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2131 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2132 <row topline="true" bottomline="true">
2133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2134 \begin_inset Text
2135
2136 \layout Standard
2137
2138 Search path
2139 \end_inset
2140 </cell>
2141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2142 \begin_inset Text
2143
2144 \layout Standard
2145
2146 default
2147 \end_inset
2148 </cell>
2149 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2150 \begin_inset Text
2151
2152 \layout Standard
2153
2154 Win32 builds
2155 \end_inset
2156 </cell>
2157 </row>
2158 <row topline="true">
2159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2160 \begin_inset Text
2161
2162 \layout Standard
2163
2164 -
2165 \begin_inset ERT
2166 status Collapsed
2167
2168 \layout Standard
2169
2170 \backslash
2171 /
2172 \end_inset
2173
2174 -I dir
2175 \end_inset
2176 </cell>
2177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2178 \begin_inset Text
2179
2180 \layout Standard
2181
2182 -
2183 \begin_inset ERT
2184 status Collapsed
2185
2186 \layout Standard
2187
2188 \backslash
2189 /
2190 \end_inset
2191
2192 -I dir
2193 \end_inset
2194 </cell>
2195 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2196 \begin_inset Text
2197
2198 \layout Standard
2199
2200 -
2201 \begin_inset ERT
2202 status Collapsed
2203
2204 \layout Standard
2205
2206 \backslash
2207 /
2208 \end_inset
2209
2210 -I dir
2211 \end_inset
2212 </cell>
2213 </row>
2214 <row topline="true">
2215 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2216 \begin_inset Text
2217
2218 \layout Standard
2219
2220 $SDCC_INCLUDE
2221 \end_inset
2222 </cell>
2223 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2224 \begin_inset Text
2225
2226 \layout Standard
2227
2228 $SDCC_INCLUDE
2229 \end_inset
2230 </cell>
2231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2232 \begin_inset Text
2233
2234 \layout Standard
2235
2236 $SDCC_INCLUDE
2237 \end_inset
2238 </cell>
2239 </row>
2240 <row topline="true">
2241 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2242 \begin_inset Text
2243
2244 \layout Standard
2245
2246 $SDCC_HOME/
2247 \newline
2248
2249 \emph on
2250 $PREFIX2DATA_DIR/
2251 \newline
2252 $INCLUDE_DIR_SUFFIX
2253 \end_inset
2254 </cell>
2255 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2256 \begin_inset Text
2257
2258 \layout Standard
2259
2260 $SDCC_ HOME/
2261 \newline
2262 share/sdcc/
2263 \newline
2264 include
2265 \end_inset
2266 </cell>
2267 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2268 \begin_inset Text
2269
2270 \layout Standard
2271
2272 $SDCC_HOME
2273 \backslash
2274 include
2275 \end_inset
2276 </cell>
2277 </row>
2278 <row topline="true">
2279 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2280 \begin_inset Text
2281
2282 \layout Standard
2283
2284 path(argv[0])/
2285 \newline
2286
2287 \emph on
2288 $BIN2DATADIR/
2289 \emph default
2290
2291 \newline
2292
2293 \emph on
2294 $INCLUDE_DIR_SUFFIX
2295 \end_inset
2296 </cell>
2297 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2298 \begin_inset Text
2299
2300 \layout Standard
2301
2302 path(argv[0])/
2303 \newline
2304 ../sdcc/include
2305 \newline
2306 \SpecialChar ~
2307 \SpecialChar ~
2308 \SpecialChar ~
2309 \SpecialChar ~
2310 \SpecialChar ~
2311 \SpecialChar ~
2312 \SpecialChar ~
2313 \SpecialChar ~
2314 \SpecialChar ~
2315 \SpecialChar ~
2316 \SpecialChar ~
2317 \SpecialChar ~
2318 \SpecialChar ~
2319 \SpecialChar ~
2320 \SpecialChar ~
2321 \SpecialChar ~
2322 \SpecialChar ~
2323 \SpecialChar ~
2324 \SpecialChar ~
2325 \SpecialChar ~
2326 \SpecialChar ~
2327 \SpecialChar ~
2328 \SpecialChar ~
2329 \SpecialChar ~
2330 \SpecialChar ~
2331 \SpecialChar ~
2332 \SpecialChar ~
2333 \SpecialChar ~
2334 \SpecialChar ~
2335 \SpecialChar ~
2336 \SpecialChar ~
2337 \SpecialChar ~
2338 \SpecialChar ~
2339 \SpecialChar ~
2340 \SpecialChar ~
2341 \SpecialChar ~
2342 \SpecialChar ~
2343 \SpecialChar ~
2344
2345 \end_inset
2346 </cell>
2347 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2348 \begin_inset Text
2349
2350 \layout Standard
2351
2352 path(argv[0])
2353 \backslash
2354 ..
2355 \backslash
2356 include
2357 \end_inset
2358 </cell>
2359 </row>
2360 <row topline="true" bottomline="true">
2361 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2362 \begin_inset Text
2363
2364 \layout Standard
2365
2366
2367 \emph on
2368 $DATADIR/
2369 \emph default
2370
2371 \newline
2372
2373 \emph on
2374 $INCLUDE_DIR_SUFFIX
2375 \end_inset
2376 </cell>
2377 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2378 \begin_inset Text
2379
2380 \layout Standard
2381
2382 /usr/local/share/sdcc/
2383 \newline
2384 include
2385 \end_inset
2386 </cell>
2387 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2388 \begin_inset Text
2389
2390 \layout Standard
2391
2392 (not on Win32)
2393 \end_inset
2394 </cell>
2395 </row>
2396 </lyxtabular>
2397
2398 \end_inset
2399
2400
2401 \newline
2402
2403 \layout Standard
2404 \noindent
2405 The option -
2406 \begin_inset ERT
2407 status Collapsed
2408
2409 \layout Standard
2410
2411 \backslash
2412 /
2413 \end_inset
2414
2415 -nostdinc disables the last two search paths.
2416 \newline
2417
2418 \newline
2419 3.
2420  Library files
2421 \newline
2422
2423 \layout Standard
2424
2425 With the exception of
2426 \begin_inset Quotes sld
2427 \end_inset
2428
2429 -
2430 \begin_inset ERT
2431 status Collapsed
2432
2433 \layout Standard
2434
2435 \backslash
2436 /
2437 \end_inset
2438
2439 -L dir
2440 \begin_inset Quotes srd
2441 \end_inset
2442
2443  the
2444 \shape italic
2445 model
2446 \shape default
2447  is auto-appended by the compiler (e.g.
2448  small, large, z80, ds390 etc.).
2449
2450 \newline
2451
2452 \layout Standard
2453 \align center
2454
2455 \begin_inset  Tabular
2456 <lyxtabular version="3" rows="6" columns="3">
2457 <features>
2458 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2459 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2460 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2461 <row topline="true" bottomline="true">
2462 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2463 \begin_inset Text
2464
2465 \layout Standard
2466
2467 Search path
2468 \end_inset
2469 </cell>
2470 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2471 \begin_inset Text
2472
2473 \layout Standard
2474
2475 default
2476 \end_inset
2477 </cell>
2478 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2479 \begin_inset Text
2480
2481 \layout Standard
2482
2483 Win32 builds
2484 \end_inset
2485 </cell>
2486 </row>
2487 <row topline="true">
2488 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2489 \begin_inset Text
2490
2491 \layout Standard
2492
2493 -
2494 \begin_inset ERT
2495 status Collapsed
2496
2497 \layout Standard
2498
2499 \backslash
2500 /
2501 \end_inset
2502
2503 -L dir
2504 \end_inset
2505 </cell>
2506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2507 \begin_inset Text
2508
2509 \layout Standard
2510
2511 -
2512 \begin_inset ERT
2513 status Collapsed
2514
2515 \layout Standard
2516
2517 \backslash
2518 /
2519 \end_inset
2520
2521 -L dir
2522 \end_inset
2523 </cell>
2524 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2525 \begin_inset Text
2526
2527 \layout Standard
2528
2529 -
2530 \begin_inset ERT
2531 status Collapsed
2532
2533 \layout Standard
2534
2535 \backslash
2536 /
2537 \end_inset
2538
2539 -L dir
2540 \end_inset
2541 </cell>
2542 </row>
2543 <row topline="true">
2544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2545 \begin_inset Text
2546
2547 \layout Standard
2548
2549 $SDCC_LIB/
2550 \newline
2551
2552 \emph on
2553 <model>
2554 \end_inset
2555 </cell>
2556 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2557 \begin_inset Text
2558
2559 \layout Standard
2560
2561 $SDCC_LIB/
2562 \newline
2563
2564 \emph on
2565 <model>
2566 \end_inset
2567 </cell>
2568 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2569 \begin_inset Text
2570
2571 \layout Standard
2572
2573 $SDCC_LIB
2574 \backslash
2575
2576 \newline
2577
2578 \emph on
2579 <model>
2580 \end_inset
2581 </cell>
2582 </row>
2583 <row topline="true">
2584 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2585 \begin_inset Text
2586
2587 \layout Standard
2588
2589 $SDCC_HOME/
2590 \newline
2591
2592 \emph on
2593 $PREFIX2DATA_DIR/
2594 \newline
2595 $LIB_DIR_SUFFIX/<model>
2596 \end_inset
2597 </cell>
2598 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2599 \begin_inset Text
2600
2601 \layout Standard
2602
2603 $SDCC_HOME/
2604 \newline
2605 share/sdcc/
2606 \newline
2607 lib/
2608 \emph on
2609 <model>
2610 \end_inset
2611 </cell>
2612 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2613 \begin_inset Text
2614
2615 \layout Standard
2616
2617 $SDCC_HOME
2618 \backslash
2619 lib
2620 \backslash
2621
2622 \emph on
2623
2624 \newline
2625 <model>
2626 \end_inset
2627 </cell>
2628 </row>
2629 <row topline="true">
2630 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2631 \begin_inset Text
2632
2633 \layout Standard
2634
2635 path(argv[0])/
2636 \newline
2637
2638 \emph on
2639 $BIN2DATADIR/
2640 \emph default
2641
2642 \newline
2643
2644 \emph on
2645 $LIB_DIR_SUFFIX/<model>
2646 \end_inset
2647 </cell>
2648 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2649 \begin_inset Text
2650
2651 \layout Standard
2652
2653 path(argv[0])/
2654 \newline
2655 ../sdcc/lib/
2656 \emph on
2657 <model>
2658 \newline
2659 \SpecialChar ~
2660 \SpecialChar ~
2661 \SpecialChar ~
2662 \SpecialChar ~
2663 \SpecialChar ~
2664 \SpecialChar ~
2665 \SpecialChar ~
2666 \SpecialChar ~
2667 \SpecialChar ~
2668 \SpecialChar ~
2669 \SpecialChar ~
2670 \SpecialChar ~
2671 \SpecialChar ~
2672 \SpecialChar ~
2673 \SpecialChar ~
2674 \SpecialChar ~
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
2699 \end_inset
2700 </cell>
2701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2702 \begin_inset Text
2703
2704 \layout Standard
2705
2706 path(argv[0])
2707 \backslash
2708
2709 \newline
2710 ..
2711 \backslash
2712 lib
2713 \backslash
2714
2715 \emph on
2716 <model>
2717 \newline
2718 \SpecialChar ~
2719 \SpecialChar ~
2720 \SpecialChar ~
2721 \SpecialChar ~
2722 \SpecialChar ~
2723 \SpecialChar ~
2724 \SpecialChar ~
2725 \SpecialChar ~
2726 \SpecialChar ~
2727 \SpecialChar ~
2728 \SpecialChar ~
2729 \SpecialChar ~
2730 \SpecialChar ~
2731 \SpecialChar ~
2732 \SpecialChar ~
2733 \SpecialChar ~
2734 \SpecialChar ~
2735 \SpecialChar ~
2736 \SpecialChar ~
2737 \SpecialChar ~
2738 \SpecialChar ~
2739 \SpecialChar ~
2740 \SpecialChar ~
2741 \SpecialChar ~
2742 \SpecialChar ~
2743 \SpecialChar ~
2744 \SpecialChar ~
2745 \SpecialChar ~
2746 \SpecialChar ~
2747 \SpecialChar ~
2748 \SpecialChar ~
2749 \SpecialChar ~
2750 \SpecialChar ~
2751 \SpecialChar ~
2752 \SpecialChar ~
2753
2754 \end_inset
2755 </cell>
2756 </row>
2757 <row topline="true" bottomline="true">
2758 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2759 \begin_inset Text
2760
2761 \layout Standard
2762
2763
2764 \emph on
2765 $DATADIR/
2766 \newline
2767 $LIB_DIR_SUFFIX/<model>
2768 \end_inset
2769 </cell>
2770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2771 \begin_inset Text
2772
2773 \layout Standard
2774
2775 /usr/local/share/sdcc/
2776 \newline
2777 lib/
2778 \emph on
2779 <model>
2780 \end_inset
2781 </cell>
2782 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2783 \begin_inset Text
2784
2785 \layout Standard
2786
2787 (not on Win32)
2788 \end_inset
2789 </cell>
2790 </row>
2791 </lyxtabular>
2792
2793 \end_inset
2794
2795
2796 \newline
2797
2798 \layout Comment
2799
2800 Don't delete any of the stray spaces in the table above without checking
2801  the HTML output (last line)!
2802 \layout Standard
2803
2804 \SpecialChar ~
2805
2806 \newline
2807 The option -
2808 \begin_inset ERT
2809 status Collapsed
2810
2811 \layout Standard
2812
2813 \backslash
2814 /
2815 \end_inset
2816
2817 -nostdlib disables the last two search paths.
2818 \layout Section
2819
2820 Building SDCC
2821 \begin_inset LatexCommand \index{Building SDCC}
2822
2823 \end_inset
2824
2825
2826 \layout Subsection
2827
2828 Building SDCC on Linux
2829 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2830
2831 \end_inset
2832
2833
2834 \layout Enumerate
2835
2836
2837 \series medium
2838 Download the source package
2839 \series default
2840  either from the SDCC CVS repository or from the nightly snapshots
2841 \series medium
2842 , it will be named something like sdcc
2843 \series default
2844 .src
2845 \series medium
2846 .t
2847 \series default
2848 ar.
2849 \series medium
2850 gz
2851 \series default
2852
2853 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2854
2855 \end_inset
2856
2857 .
2858 \layout Enumerate
2859
2860
2861 \series medium
2862 Bring up a command line terminal, such as xterm.
2863 \layout Enumerate
2864
2865
2866 \series medium
2867 Unpack the file using a command like:
2868 \family sans
2869 \series bold
2870 "tar -xvzf sdcc.src.tar.gz
2871 \family default
2872 \series default
2873 "
2874 \series medium
2875 , this will create a sub-directory called sdcc with all of the sources.
2876 \layout Enumerate
2877
2878 Change directory into the main SDCC directory, for example type:
2879 \family sans
2880 \series bold
2881 "cd sdcc
2882 \series default
2883 ".
2884 \layout Enumerate
2885
2886
2887 \series medium
2888 Type
2889 \family sans
2890 \series bold
2891 "./configure
2892 \family default
2893 \series default
2894 ".
2895  This configures the package for compilation on your system.
2896 \layout Enumerate
2897
2898
2899 \series medium
2900 Type
2901 \family sans
2902 \series bold
2903 "make
2904 \family default
2905 \series default
2906 "
2907 \series medium
2908 .
2909
2910 \series default
2911  All of the source packages will compile, this can take a while.
2912 \layout Enumerate
2913
2914
2915 \series medium
2916 Type
2917 \family sans
2918 \series bold
2919 "make install"
2920 \family default
2921 \series default
2922  as root
2923 \series medium
2924 .
2925
2926 \series default
2927  This copies the binary executables, the include files, the libraries and
2928  the documentation to the install directories.
2929  Proceed with section
2930 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
2931
2932 \end_inset
2933
2934 .
2935 \layout Subsection
2936
2937 Building SDCC on OSX 2.x
2938 \layout Standard
2939
2940 Follow the instruction for Linux.
2941 \newline
2942
2943 \newline
2944 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
2945 )) fails to compile SDCC.
2946  Fortunately there's also gcc 2.9.x installed, which works fine.
2947  This compiler can be selected by running 'configure' with:
2948 \layout LyX-Code
2949
2950 ./configure CC=gcc2 CXX=g++2
2951 \layout Subsection
2952
2953 Cross compiling SDCC on Linux for Windows
2954 \layout Standard
2955
2956 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
2957  See section 'Configure Options'.
2958 \layout Subsection
2959
2960 Building SDCC on Windows
2961 \layout Standard
2962
2963 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
2964  built on Windows.
2965  They use Unix-sockets, which are not available on Win32.
2966 \layout Subsection
2967
2968 Building SDCC using Cygwin and Mingw32
2969 \layout Standard
2970
2971 For building and installing a Cygwin executable follow the instructions
2972  for Linux.
2973 \newline
2974
2975 \newline
2976 On Cygwin a
2977 \begin_inset Quotes sld
2978 \end_inset
2979
2980 native
2981 \begin_inset Quotes srd
2982 \end_inset
2983
2984  Win32-binary can be built, which will not need the Cygwin-DLL.
2985  For the necessary 'configure' options see section 'configure options' or
2986  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
2987 \newline
2988
2989 \newline
2990 In order to install Cygwin on Windows download setup.exe from
2991 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
2992
2993 \end_inset
2994
2995 .
2996  Run it, set the
2997 \begin_inset Quotes sld
2998 \end_inset
2999
3000 default text file type
3001 \begin_inset Quotes srd
3002 \end_inset
3003
3004  to
3005 \begin_inset Quotes sld
3006 \end_inset
3007
3008 unix
3009 \begin_inset Quotes srd
3010 \end_inset
3011
3012  and download/install at least the following packages.
3013  Some packages are selected by default, others will be automatically selected
3014  because of dependencies with the manually selected packages.
3015  Never deselect these packages!
3016 \layout Itemize
3017
3018 flex
3019 \layout Itemize
3020
3021 bison
3022 \layout Itemize
3023
3024 gcc ; version 3.x is fine, no need to use the old 2.9x
3025 \layout Itemize
3026
3027 binutils ; selected with gcc
3028 \layout Itemize
3029
3030 make
3031 \layout Itemize
3032
3033 rxvt ; a nice console, which makes life much easier under windoze (see below)
3034 \layout Itemize
3035
3036 man ; not really needed for building SDCC, but you'll miss it sooner or
3037  later
3038 \layout Itemize
3039
3040 less ; not really needed for building SDCC, but you'll miss it sooner or
3041  later
3042 \layout Itemize
3043
3044 cvs ; only if you use CVS access
3045 \layout Standard
3046
3047 If you want to develop something you'll need:
3048 \layout Itemize
3049
3050 python ; for the regression tests
3051 \layout Itemize
3052
3053 gdb ; the gnu debugger, together with the nice GUI
3054 \begin_inset Quotes sld
3055 \end_inset
3056
3057 insight
3058 \begin_inset Quotes srd
3059 \end_inset
3060
3061
3062 \layout Itemize
3063
3064 openssh ; to access the CF or commit changes
3065 \layout Itemize
3066
3067 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3068  use autoconf-stable!
3069 \layout Standard
3070
3071 rxvt is a nice console with history.
3072  Replace in your cygwin.bat the line
3073 \layout LyX-Code
3074
3075 bash -
3076 \begin_inset ERT
3077 status Collapsed
3078
3079 \layout Standard
3080
3081 \backslash
3082 /
3083 \end_inset
3084
3085 -login -i
3086 \layout Standard
3087
3088 with (one line):
3089 \layout LyX-Code
3090
3091 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3092 \layout LyX-Code
3093
3094      -bg black -fg white -geometry 100x65 -e bash -
3095 \begin_inset ERT
3096 status Collapsed
3097
3098 \layout Standard
3099
3100 \backslash
3101 /
3102 \end_inset
3103
3104 -login
3105 \layout Standard
3106
3107 Text selected with the mouse is automatically copied to the clipboard, pasting
3108  works with shift-insert.
3109 \newline
3110
3111 \newline
3112 The other good tip is to make sure you have no //c/-style paths anywhere,
3113  use /cygdrive/c/ instead.
3114  Using // invokes a network lookup which is very slow.
3115  If you think
3116 \begin_inset Quotes sld
3117 \end_inset
3118
3119 cygdrive
3120 \begin_inset Quotes srd
3121 \end_inset
3122
3123  is too long, you can change it with e.g.
3124 \layout LyX-Code
3125
3126 mount -s -u -c /mnt
3127 \layout Standard
3128
3129 SDCC sources use the unix line ending LF.
3130  Life is much easier, if you store the source tree on a drive which is mounted
3131  in binary mode.
3132  And use an editor which can handle LF-only line endings.
3133  Make sure not to commit files with windows line endings.
3134  The tabulator spacing
3135 \begin_inset LatexCommand \index{tabulator spacing (8)}
3136
3137 \end_inset
3138
3139  used in the project is 8.
3140 \layout Subsection
3141
3142 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3143 \layout Standard
3144
3145
3146 \series medium
3147 Download the source package
3148 \series default
3149  either from the SDCC CVS repository or from the
3150 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3151
3152 \end_inset
3153
3154
3155 \series medium
3156 , it will be named something like sdcc
3157 \series default
3158 .src
3159 \series medium
3160 .tgz.
3161
3162 \series default
3163  SDCC is distributed with all the projects, workspaces, and files you need
3164  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3165  doesn't build under MSVC).
3166  The workspace name is 'sdcc.dsw'.
3167  Please note that as it is now, all the executables are created in a folder
3168  called sdcc
3169 \backslash
3170 bin_vc.
3171  Once built you need to copy the executables from sdcc
3172 \backslash
3173 bin_vc to sdcc
3174 \backslash
3175 bin before running SDCC.
3176
3177 \newline
3178
3179 \newline
3180 WARNING: Visual studio is very picky with line terminations; it expects
3181  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3182  If you are getting a message such as "This makefile was not generated by
3183  Developer Studio etc.
3184  etc.
3185 \begin_inset Quotes srd
3186 \end_inset
3187
3188  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3189  need to convert the Unix style line endings to DOS style line endings.
3190  To do so you can use the
3191 \begin_inset Quotes sld
3192 \end_inset
3193
3194 unix2dos
3195 \begin_inset Quotes srd
3196 \end_inset
3197
3198  utility freely available on the internet.
3199  Doug Hawkins reported in the sdcc-user list that this works:
3200 \newline
3201
3202 \newline
3203 C:
3204 \backslash
3205 Programming
3206 \backslash
3207 SDCC> unix2dos sdcc.dsw
3208 \newline
3209 C:
3210 \backslash
3211 Programming
3212 \backslash
3213 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3214 \newline
3215
3216 \newline
3217 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3218  flex.exe, and gawk.exe.
3219  One good place to get them is
3220 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3221
3222 \end_inset
3223
3224
3225 \newline
3226
3227 \newline
3228 Download the file UnxUtils
3229 \begin_inset LatexCommand \index{UnxUtils}
3230
3231 \end_inset
3232
3233 .zip.
3234  Now you have to install the utilities and setup MSVC so it can locate the
3235  required programs.
3236  Here there are two alternatives (choose one!):
3237 \layout Enumerate
3238
3239 The easy way:
3240 \newline
3241
3242 \newline
3243 a) Extract UnxUtils.zip to your C:
3244 \backslash
3245  hard disk PRESERVING the original paths, otherwise bison won't work.
3246  (If you are using WinZip make certain that 'Use folder names' is selected)
3247 \newline
3248
3249 \newline
3250 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3251  in 'Show directories for:' select 'Executable files', and in the directories
3252  window add a new path: 'C:
3253 \backslash
3254 user
3255 \backslash
3256 local
3257 \backslash
3258 wbin', click ok.
3259 \newline
3260
3261 \newline
3262 (As a side effect, you get a bunch of Unix utilities that could be useful,
3263  such as diff and patch.)
3264 \layout Enumerate
3265
3266 A more compact way:
3267 \newline
3268
3269 \newline
3270 This one avoids extracting a bunch of files you may not use, but requires
3271  some extra work:
3272 \newline
3273
3274 \newline
3275 a) Create a directory were to put the tools needed, or use a directory already
3276  present.
3277  Say for example 'C:
3278 \backslash
3279 util'.
3280 \newline
3281
3282 \newline
3283 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3284  to such directory WITHOUT preserving the original paths.
3285  (If you are using WinZip make certain that 'Use folder names' is not selected)
3286 \newline
3287
3288 \newline
3289 c) Rename bison.exe to '_bison.exe'.
3290 \newline
3291
3292 \newline
3293 d) Create a batch file 'bison.bat' in 'C:
3294 \backslash
3295 util
3296 \backslash
3297 ' and add these lines:
3298 \newline
3299 \SpecialChar ~
3300 \SpecialChar ~
3301 set BISON_SIMPLE=C:
3302 \backslash
3303 util
3304 \backslash
3305 bison.simple
3306 \newline
3307 \SpecialChar ~
3308 \SpecialChar ~
3309 set BISON_HAIRY=C:
3310 \backslash
3311 util
3312 \backslash
3313 bison.hairy
3314 \newline
3315 \SpecialChar ~
3316 \SpecialChar ~
3317 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3318 \newline
3319
3320 \newline
3321 Steps 'c' and 'd' are needed because bison requires by default that the
3322  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3323  '/usr/local/share/' I think.
3324  So it is necessary to tell bison where those files are located if they
3325  are not in such directory.
3326  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3327 \newline
3328
3329 \newline
3330 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3331  in 'Show directories for:' select 'Executable files', and in the directories
3332  window add a new path: 'c:
3333 \backslash
3334 util', click ok.
3335  Note that you can use any other path instead of 'c:
3336 \backslash
3337 util', even the path where the Visual C++ tools are, probably: 'C:
3338 \backslash
3339 Program Files
3340 \backslash
3341 Microsoft Visual Studio
3342 \backslash
3343 Common
3344 \backslash
3345 Tools'.
3346  So you don't have to execute step 'e' :)
3347 \layout Standard
3348
3349 That is it.
3350  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3351  the executables from sdcc
3352 \backslash
3353 bin_vc to sdcc
3354 \backslash
3355 bin, and you can compile using SDCC.
3356 \layout Subsection
3357
3358 Building SDCC Using Borland
3359 \layout Enumerate
3360
3361 From the sdcc directory, run the command "make -f Makefile.bcc".
3362  This should regenerate all the .exe files in the bin directory except for
3363  sdcdb.exe (which currently doesn't build under Borland C++).
3364 \layout Enumerate
3365
3366 If you modify any source files and need to rebuild, be aware that the dependenci
3367 es may not be correctly calculated.
3368  The safest option is to delete all .obj files and run the build again.
3369  From a Cygwin BASH prompt, this can easily be done with the command (be
3370  sure you are in the sdcc directory):
3371 \newline
3372
3373 \newline
3374
3375 \family sans
3376 \series bold
3377 find .
3378
3379 \backslash
3380 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3381 \backslash
3382 ) -print -exec rm {}
3383 \backslash
3384 ;
3385 \family default
3386 \series default
3387
3388 \newline
3389
3390 \newline
3391 or on Windows NT/2000/XP from the command prompt with the command:
3392 \newline
3393
3394 \family sans
3395 \series bold
3396
3397 \newline
3398 del /s *.obj *.lib *.rul
3399 \family default
3400 \series default
3401  from the sdcc directory.
3402 \layout Subsection
3403
3404 Windows Install Using a Binary Package
3405 \begin_inset LatexCommand \label{sub:Windows-Install}
3406
3407 \end_inset
3408
3409
3410 \layout Enumerate
3411
3412 Download the binary package from
3413 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3414
3415 \end_inset
3416
3417  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3418  This should unpack to a group of sub-directories.
3419  An example directory structure after unpacking the mingw32 package is:
3420  c:
3421 \backslash
3422 sdcc
3423 \backslash
3424 bin for the executables, c:
3425 \backslash
3426 sdcc
3427 \backslash
3428 include and c:
3429 \backslash
3430 sdcc
3431 \backslash
3432 lib for the include and libraries.
3433 \layout Enumerate
3434
3435 Adjust your environment variable PATH to include the location of the bin
3436  directory or start sdcc using the full path.
3437 \layout Section
3438
3439 Building the Documentation
3440 \layout Standard
3441
3442 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3443  as changing into the doc directory and typing
3444 \family sans
3445 \series bold
3446
3447 \begin_inset Quotes srd
3448 \end_inset
3449
3450 make
3451 \begin_inset Quotes srd
3452 \end_inset
3453
3454
3455 \family default
3456 \series default
3457  there.
3458  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3459 x).
3460  Using LyX
3461 \begin_inset LatexCommand \url{www.lyx.org}
3462
3463 \end_inset
3464
3465  as editor this is straightforward.
3466  Prebuilt documentation in html and pdf format is available from
3467 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3468
3469 \end_inset
3470
3471 .
3472 \layout Section
3473
3474 Reading the Documentation
3475 \layout Standard
3476
3477 Currently reading the document in pdf format is recommended, as for unknown
3478  reason the hyperlinks are working there whereas in the html version they
3479  are not
3480 \begin_inset Foot
3481 collapsed false
3482
3483 \layout Standard
3484
3485 If you should know why please drop us a note
3486 \end_inset
3487
3488 .
3489  You'll find the pdf version at
3490 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
3491
3492 \end_inset
3493
3494 .
3495 \newline
3496 This documentation is in some aspects different from a commercial documentation:
3497
3498 \layout Itemize
3499
3500 It tries to document SDCC for several processor architectures in one document
3501  (commercially these probably would be separate documents/products).
3502  This document
3503 \begin_inset LatexCommand \index{Status of documentation}
3504
3505 \end_inset
3506
3507  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3508 on about f.e.
3509  Z80, PIC14, PIC16 and HC08.
3510 \layout Itemize
3511
3512 There are many references pointing away from this documentation.
3513  Don't let this distract you.
3514  If there f.e.
3515  was a reference like
3516 \begin_inset LatexCommand \url{www.opencores.org}
3517
3518 \end_inset
3519
3520  together with a statement
3521 \begin_inset Quotes sld
3522 \end_inset
3523
3524 some processors which are targetted by SDCC can be implemented in a
3525 \emph on
3526 f
3527 \emph default
3528 ield
3529 \emph on
3530 p
3531 \emph default
3532 rogrammable
3533 \emph on
3534 g
3535 \emph default
3536 ate
3537 \emph on
3538 a
3539 \emph default
3540 rray
3541 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3542
3543 \end_inset
3544
3545
3546 \begin_inset Quotes srd
3547 \end_inset
3548
3549  we expect you to have a quick look there and come back.
3550  If you read this you are on the right track.
3551 \layout Itemize
3552
3553 Some sections attribute more space to problems, restrictions and warnings
3554  than to the solution.
3555 \layout Itemize
3556
3557 The installation section and the section about the debugger is intimidating.
3558 \layout Itemize
3559
3560 There are still lots of typos and there are more different writing styles
3561  than pictures.
3562 \layout Section
3563
3564 Testing the SDCC Compiler
3565 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3566
3567 \end_inset
3568
3569
3570 \layout Standard
3571
3572 The first thing you should do after installing your SDCC compiler is to
3573  see if it runs.
3574  Type
3575 \family sans
3576 \series bold
3577 "sdcc -
3578 \begin_inset ERT
3579 status Collapsed
3580
3581 \layout Standard
3582
3583 \backslash
3584 /
3585 \end_inset
3586
3587 -version"
3588 \begin_inset LatexCommand \index{version}
3589
3590 \end_inset
3591
3592
3593 \family default
3594 \series default
3595  at the prompt, and the program should run and tell you the version.
3596  If it doesn't run, or gives a message about not finding sdcc program, then
3597  you need to check over your installation.
3598  Make sure that the sdcc bin directory is in your executable search path
3599  defined by the PATH environment setting (
3600 \series medium
3601 see
3602 \series default
3603 section
3604 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3605
3606 \end_inset
3607
3608 \SpecialChar ~
3609
3610 \series medium
3611 Install trouble-shooting for suggestions
3612 \series default
3613 ).
3614  Make sure that the sdcc program is in the bin folder, if not perhaps something
3615  did not install correctly.
3616 \newline
3617
3618 \newline
3619
3620 \series medium
3621 SDCC
3622 \series default
3623 is commonly installed as described in section
3624 \begin_inset Quotes sld
3625 \end_inset
3626
3627 Install and search paths
3628 \begin_inset Quotes srd
3629 \end_inset
3630
3631 .
3632 \newline
3633
3634 \newline
3635
3636 \series medium
3637 Make sure the compiler works on a very simple example.
3638  Type in the following test.c program using your favorite
3639 \series default
3640 ASCII
3641 \series medium
3642 editor:
3643 \layout Verse
3644
3645
3646 \family typewriter
3647 char test;
3648 \newline
3649
3650 \newline
3651 void main(void) {
3652 \newline
3653 \SpecialChar ~
3654 \SpecialChar ~
3655 \SpecialChar ~
3656 \SpecialChar ~
3657 test=0;
3658 \newline
3659 }
3660 \layout Standard
3661
3662
3663 \series medium
3664 Compile this using the following command:
3665 \family sans
3666 \series bold
3667 "sdcc -c test.c".
3668
3669 \family default
3670 \series default
3671
3672 \series medium
3673 If all goes well, the compiler will generate a test.asm and test.rel file.
3674  Congratulations, you've just compiled your first program with SDCC.
3675  We used the -c option to tell SDCC not to link the generated code, just
3676  to keep things simple for this step.
3677 \series default
3678
3679 \newline
3680
3681 \newline
3682
3683 \series medium
3684 The next step is to try it with the linker.
3685  Type in
3686 \family sans
3687 \series bold
3688 "sdcc test.c
3689 \family default
3690 \series default
3691 "
3692 \series medium
3693 .
3694  If all goes well the compiler will link with the libraries and produce
3695  a test.ihx output file.
3696  If this step fails
3697 \series default
3698
3699 \series medium
3700 (no test.ihx, and the linker generates warnings), then the problem is most
3701  likely that
3702 \series default
3703 SDCC
3704 \series medium
3705  cannot find the
3706 \series default
3707 /
3708 \series medium
3709 usr/local/share/sdcc/lib directory
3710 \series default
3711
3712 \series medium
3713 (see
3714 \series default
3715 section
3716 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3717
3718 \end_inset
3719
3720 \SpecialChar ~
3721
3722 \series medium
3723 Install trouble-shooting for suggestions).
3724 \series default
3725
3726 \newline
3727
3728 \newline
3729
3730 \series medium
3731 The final test is to ensure
3732 \series default
3733 SDCC
3734 \series medium
3735  can use the
3736 \series default
3737 standard
3738 \series medium
3739  header files and libraries.
3740  Edit test.c and change it to the following:
3741 \layout Verse
3742
3743
3744 \family typewriter
3745 #include <string.h>
3746 \newline
3747
3748 \newline
3749 char str1[10];
3750 \newline
3751
3752 \newline
3753 void main(void) {
3754 \newline
3755 \SpecialChar ~
3756 \SpecialChar ~
3757 strcpy(str1, "testing");
3758 \newline
3759 }
3760 \layout Standard
3761
3762
3763 \series medium
3764 Compile this by typing
3765 \family sans
3766 \series bold
3767 "sdcc test.c"
3768 \family default
3769 \series medium
3770 .
3771  This should generate a test.ihx output file, and it should give no warnings
3772  such as not finding the string.h file.
3773  If it cannot find the string.h file, then the problem is that
3774 \series default
3775 SDCC
3776 \series medium
3777  cannot find the /usr/local/share/sdcc/include directory
3778 \series default
3779
3780 \series medium
3781 (see the
3782 \series default
3783 section
3784 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3785
3786 \end_inset
3787
3788 \SpecialChar ~
3789
3790 \series medium
3791 Install trouble-shooting section for suggestions).
3792
3793 \series default
3794  Use option
3795 \series bold
3796 -
3797 \begin_inset ERT
3798 status Collapsed
3799
3800 \layout Standard
3801
3802 \backslash
3803 /
3804 \end_inset
3805
3806 -print-search-dirs
3807 \series default
3808
3809 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3810
3811 \end_inset
3812
3813  to find exactly where SDCC is looking for the include and lib files.
3814 \layout Section
3815
3816 Install Trouble-shooting
3817 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3818
3819 \end_inset
3820
3821
3822 \begin_inset LatexCommand \index{Install trouble-shooting}
3823
3824 \end_inset
3825
3826
3827 \layout Subsection
3828
3829 If SDCC does not build correctly
3830 \layout Standard
3831
3832 A thing to try is starting from scratch by unpacking the .tgz source package
3833  again in an empty directory.
3834  Configure it like:
3835 \newline
3836
3837 \newline
3838
3839 \family sans
3840 \series bold
3841 ./configure 2>&1 | tee configure.log
3842 \family default
3843 \series default
3844
3845 \newline
3846
3847 \newline
3848 and build it like:
3849 \newline
3850
3851 \newline
3852
3853 \family sans
3854 \series bold
3855 make 2>&1 | tee make.log
3856 \family default
3857 \series default
3858
3859 \newline
3860
3861 \newline
3862 If anything goes wrong, you can review the log files to locate the problem.
3863  Or a relevant part of this can be attached to an email that could be helpful
3864  when requesting help from the mailing list.
3865 \layout Subsection
3866
3867 What the
3868 \begin_inset Quotes sld
3869 \end_inset
3870
3871 ./configure
3872 \begin_inset Quotes srd
3873 \end_inset
3874
3875  does
3876 \layout Standard
3877
3878 The
3879 \begin_inset Quotes sld
3880 \end_inset
3881
3882 ./configure
3883 \begin_inset Quotes srd
3884 \end_inset
3885
3886  command is a script that analyzes your system and performs some configuration
3887  to ensure the source package compiles on your system.
3888  It will take a few minutes to run, and will compile a few tests to determine
3889  what compiler features are installed.
3890 \layout Subsection
3891
3892 What the
3893 \begin_inset Quotes sld
3894 \end_inset
3895
3896 make
3897 \begin_inset Quotes srd
3898 \end_inset
3899
3900  does
3901 \layout Standard
3902
3903 This runs the GNU make tool, which automatically compiles all the source
3904  packages into the final installed binary executables.
3905 \layout Subsection
3906
3907 What the
3908 \begin_inset Quotes sld
3909 \end_inset
3910
3911 make install
3912 \begin_inset Quotes erd
3913 \end_inset
3914
3915  command does.
3916 \layout Standard
3917
3918 This will install the compiler, other executables libraries and include
3919  files into the appropriate directories.
3920  See sections
3921 \begin_inset LatexCommand \ref{sub:Install-paths}
3922
3923 \end_inset
3924
3925 ,\SpecialChar ~
3926
3927 \begin_inset LatexCommand \ref{sub:Search-Paths}
3928
3929 \end_inset
3930
3931 \SpecialChar ~
3932 about install and search paths.
3933 \newline
3934 On most systems you will need super-user privileges to do this.
3935 \layout Section
3936
3937 Components of SDCC
3938 \layout Standard
3939
3940 SDCC is not just a compiler, but a collection of tools by various developers.
3941  These include linkers, assemblers, simulators and other components.
3942  Here is a summary of some of the components.
3943  Note that the included simulator and assembler have separate documentation
3944  which you can find in the source package in their respective directories.
3945  As SDCC grows to include support for other processors, other packages from
3946  various developers are included and may have their own sets of documentation.
3947 \newline
3948
3949 \newline
3950 You might want to look at the files which are installed in <installdir>.
3951  At the time of this writing, we find the following programs for gcc-builds:
3952 \newline
3953
3954 \newline
3955 In <installdir>/bin:
3956 \layout Itemize
3957
3958 sdcc - The compiler.
3959 \layout Itemize
3960
3961 sdcpp - The C preprocessor.
3962 \layout Itemize
3963
3964 asx8051 - The assembler for 8051 type processors.
3965 \layout Itemize
3966
3967 as-z80
3968 \series bold
3969 ,
3970 \series default
3971 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
3972 \layout Itemize
3973
3974 aslink -The linker for 8051 type processors.
3975 \layout Itemize
3976
3977 link-z80
3978 \series bold
3979 ,
3980 \series default
3981 link-gbz80 - The Z80 and GameBoy Z80 linkers.
3982 \layout Itemize
3983
3984 s51 - The ucSim 8051 simulator.
3985 \layout Itemize
3986
3987 sdcdb - The source debugger.
3988 \layout Itemize
3989
3990 packihx - A tool to pack (compress) Intel hex files.
3991 \layout Standard
3992
3993 In <installdir>/share/sdcc/include
3994 \layout Itemize
3995
3996 the include files
3997 \layout Standard
3998
3999 In <installdir>/share/sdcc/lib
4000 \layout Itemize
4001
4002 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4003  relocatables.
4004 \layout Standard
4005
4006 In <installdir>/share/sdcc/doc
4007 \layout Itemize
4008
4009 the documentation
4010 \layout Standard
4011
4012 As development for other processors proceeds, this list will expand to include
4013  executables to support processors like AVR, PIC, etc.
4014 \layout Subsection
4015
4016 sdcc - The Compiler
4017 \layout Standard
4018
4019 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4020  the assembler and linkage editor.
4021 \layout Subsection
4022
4023 sdcpp - The C-Preprocessor
4024 \layout Standard
4025
4026 The preprocessor
4027 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4028
4029 \end_inset
4030
4031  is a modified version of the GNU preprocessor.
4032  The C preprocessor is used to pull in #include sources, process #ifdef
4033  statements, #defines and so on.
4034 \layout Subsection
4035
4036 as
4037 \emph on
4038 xxxx
4039 \emph default
4040 , aslink, link-
4041 \emph on
4042 xxx
4043 \emph default
4044  - The Assemblers and Linkage Editors
4045 \layout Standard
4046
4047 This is retargettable assembler & linkage editor, it was developed by Alan
4048  Baldwin.
4049  John Hartman created the version for 8051, and I (Sandeep) have made some
4050  enhancements and bug fixes for it to work properly with SDCC.
4051 \layout Subsection
4052
4053 s51 - The Simulator
4054 \layout Standard
4055
4056 S51
4057 \begin_inset LatexCommand \index{s51}
4058
4059 \end_inset
4060
4061  is a freeware, opensource simulator developed by Daniel Drotos (
4062 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
4063
4064 \end_inset
4065
4066 ).
4067  The simulator is built as part of the build process.
4068  For more information visit Daniel's web site at:
4069 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4070
4071 \end_inset
4072
4073 .
4074  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4075  XA51 family.
4076 \layout Subsection
4077
4078 sdcdb - Source Level Debugger
4079 \layout Standard
4080
4081 Sdcdb
4082 \begin_inset LatexCommand \index{sdcdb (debugger)}
4083
4084 \end_inset
4085
4086  is the companion source level debugger.
4087  More about sdcdb in section
4088 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4089
4090 \end_inset
4091
4092 .
4093  The current version of the debugger uses Daniel's Simulator S51
4094 \begin_inset LatexCommand \index{s51}
4095
4096 \end_inset
4097
4098 , but can be easily changed to use other simulators.
4099
4100 \layout Chapter
4101
4102 Using SDCC
4103 \layout Section
4104
4105 Compiling
4106 \layout Subsection
4107
4108 Single Source File Projects
4109 \layout Standard
4110
4111 For single source file 8051 projects the process is very simple.
4112  Compile your programs with the following command
4113 \family sans
4114 \series bold
4115 "sdcc sourcefile.c".
4116
4117 \family default
4118 \series default
4119  This will compile, assemble and link your source file.
4120  Output files are as follows:
4121 \layout Itemize
4122
4123 sourcefile.asm
4124 \begin_inset LatexCommand \index{<file>.asm}
4125
4126 \end_inset
4127
4128  - Assembler source
4129 \begin_inset LatexCommand \index{Assembler source}
4130
4131 \end_inset
4132
4133  file created by the compiler
4134 \layout Itemize
4135
4136 sourcefile.lst
4137 \begin_inset LatexCommand \index{<file>.lst}
4138
4139 \end_inset
4140
4141  - Assembler listing
4142 \begin_inset LatexCommand \index{Assembler listing}
4143
4144 \end_inset
4145
4146  file created by the Assembler
4147 \layout Itemize
4148
4149 sourcefile.rst
4150 \begin_inset LatexCommand \index{<file>.rst}
4151
4152 \end_inset
4153
4154  - Assembler listing
4155 \begin_inset LatexCommand \index{Assembler listing}
4156
4157 \end_inset
4158
4159  file updated with linkedit information, created by linkage editor
4160 \layout Itemize
4161
4162 sourcefile.sym
4163 \begin_inset LatexCommand \index{<file>.sym}
4164
4165 \end_inset
4166
4167  - symbol listing
4168 \begin_inset LatexCommand \index{Symbol listing}
4169
4170 \end_inset
4171
4172  for the sourcefile, created by the assembler
4173 \layout Itemize
4174
4175 sourcefile.rel
4176 \begin_inset LatexCommand \index{<file>.rel}
4177
4178 \end_inset
4179
4180  or sourcefile.o
4181 \begin_inset LatexCommand \index{<file>.o}
4182
4183 \end_inset
4184
4185  - Object file
4186 \begin_inset LatexCommand \index{Object file}
4187
4188 \end_inset
4189
4190  created by the assembler, input to Linkage editor
4191 \layout Itemize
4192
4193 sourcefile.map
4194 \begin_inset LatexCommand \index{<file>.map}
4195
4196 \end_inset
4197
4198  - The memory map
4199 \begin_inset LatexCommand \index{Memory map}
4200
4201 \end_inset
4202
4203  for the load module, created by the Linker
4204 \layout Itemize
4205
4206 sourcefile.mem
4207 \begin_inset LatexCommand \index{<file>.mem}
4208
4209 \end_inset
4210
4211  - A file with a summary of the memory usage
4212 \layout Itemize
4213
4214 sourcefile.ihx
4215 \begin_inset LatexCommand \index{<file>.ihx}
4216
4217 \end_inset
4218
4219  - The load module in Intel hex format
4220 \begin_inset LatexCommand \index{Intel hex format}
4221
4222 \end_inset
4223
4224  (you can select the Motorola S19 format
4225 \begin_inset LatexCommand \index{Motorola S19 format}
4226
4227 \end_inset
4228
4229  with -
4230 \begin_inset ERT
4231 status Collapsed
4232
4233 \layout Standard
4234
4235 \backslash
4236 /
4237 \end_inset
4238
4239 -out-fmt-s19
4240 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4241
4242 \end_inset
4243
4244 .
4245  If you need another format you might want to use
4246 \family sans
4247 \shape italic
4248 objdump
4249 \family default
4250 \shape default
4251
4252 \begin_inset LatexCommand \index{objdump (tool)}
4253
4254 \end_inset
4255
4256  or
4257 \family sans
4258 \shape italic
4259  srecord
4260 \family default
4261 \shape default
4262
4263 \begin_inset LatexCommand \index{srecord (tool)}
4264
4265 \end_inset
4266
4267 ).
4268  Both formats are documented in the documentation of srecord
4269 \begin_inset LatexCommand \index{srecord (tool)}
4270
4271 \end_inset
4272
4273
4274 \layout Itemize
4275
4276 sourcefile.adb
4277 \begin_inset LatexCommand \index{<file>.adb}
4278
4279 \end_inset
4280
4281  - An intermediate file containing debug information needed to create the
4282  .cdb file (with -
4283 \begin_inset ERT
4284 status Open
4285
4286 \layout Standard
4287
4288 \backslash
4289 /
4290 \end_inset
4291
4292 -debug
4293 \begin_inset LatexCommand \index{-\/-debug}
4294
4295 \end_inset
4296
4297 )
4298 \layout Itemize
4299
4300 sourcefile.cdb
4301 \begin_inset LatexCommand \index{<file>.cdb}
4302
4303 \end_inset
4304
4305  - An optional file (with -
4306 \begin_inset ERT
4307 status Collapsed
4308
4309 \layout Standard
4310
4311 \backslash
4312 /
4313 \end_inset
4314
4315 -debug) containing debug information.
4316  The format is documented in cdbfileformat.pdf.
4317 \layout Itemize
4318
4319 sourcefile.
4320  - (no extension)
4321 \begin_inset LatexCommand \index{<file> (no extension)}
4322
4323 \end_inset
4324
4325  An optional AOMF or AOMF51
4326 \begin_inset LatexCommand \index{AOMF, AOMF51}
4327
4328 \end_inset
4329
4330  file containing debug information (generated with option -
4331 \begin_inset ERT
4332 status Collapsed
4333
4334 \layout Standard
4335
4336 \backslash
4337 /
4338 \end_inset
4339
4340 -debug).
4341  The (Intel)
4342 \emph on
4343  a
4344 \emph default
4345 bsolute
4346 \emph on
4347 o
4348 \emph default
4349 bject
4350 \emph on
4351 m
4352 \emph default
4353 odule
4354 \emph on
4355 f
4356 \emph default
4357 ormat is commonly used by third party tools (debuggers
4358 \begin_inset LatexCommand \index{Debugger}
4359
4360 \end_inset
4361
4362 , simulators, emulators)
4363 \layout Itemize
4364
4365 sourcefile.dump*
4366 \begin_inset LatexCommand \index{<file>.dump*}
4367
4368 \end_inset
4369
4370  - Dump file to debug the compiler it self (generated with option -
4371 \begin_inset ERT
4372 status Collapsed
4373
4374 \layout Standard
4375
4376 \backslash
4377 /
4378 \end_inset
4379
4380 -dumpall) (see section
4381 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4382
4383 \end_inset
4384
4385 \SpecialChar ~
4386  and section
4387 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4388
4389 \end_inset
4390
4391 \SpecialChar ~
4392
4393 \begin_inset Quotes sld
4394 \end_inset
4395
4396 Anatomy of the compiler
4397 \begin_inset Quotes srd
4398 \end_inset
4399
4400 ).
4401 \layout Subsection
4402
4403 Projects with Multiple Source Files
4404 \layout Standard
4405
4406 SDCC can compile only ONE file at a time.
4407  Let us for example assume that you have a project containing the following
4408  files:
4409 \newline
4410
4411 \newline
4412 foo1.c (contains some functions)
4413 \newline
4414 foo2.c (contains some more functions)
4415 \newline
4416 foomain.c (contains more functions and the function main)
4417 \newline
4418
4419 \size footnotesize
4420
4421 \newline
4422
4423 \size default
4424 The first two files will need to be compiled separately with the commands:
4425 \size footnotesize
4426
4427 \size default
4428
4429 \newline
4430
4431 \newline
4432
4433 \family sans
4434 \series bold
4435 sdcc\SpecialChar ~
4436 -c\SpecialChar ~
4437 foo1.c
4438 \family default
4439 \series default
4440 \size footnotesize
4441
4442 \newline
4443
4444 \family sans
4445 \series bold
4446 \size default
4447 sdcc\SpecialChar ~
4448 -c\SpecialChar ~
4449 foo2.c
4450 \family default
4451 \series default
4452
4453 \newline
4454
4455 \newline
4456 Then compile the source file containing the
4457 \emph on
4458 main()
4459 \emph default
4460  function and link
4461 \begin_inset LatexCommand \index{Linker}
4462
4463 \end_inset
4464
4465  the files together with the following command:
4466 \newline
4467
4468 \newline
4469
4470 \family sans
4471 \series bold
4472 sdcc\SpecialChar ~
4473 foomain.c\SpecialChar ~
4474 foo1.rel\SpecialChar ~
4475 foo2.rel
4476 \family default
4477 \series default
4478
4479 \begin_inset LatexCommand \index{<file>.rel}
4480
4481 \end_inset
4482
4483
4484 \newline
4485
4486 \newline
4487 Alternatively,
4488 \emph on
4489 foomain.c
4490 \emph default
4491 can be separately compiled as well:
4492 \family sans
4493 \series bold
4494
4495 \newline
4496
4497 \newline
4498 sdcc\SpecialChar ~
4499 -c\SpecialChar ~
4500 foomain.c
4501 \newline
4502 sdcc foomain.rel foo1.rel foo2.rel
4503 \newline
4504
4505 \newline
4506
4507 \family default
4508 \series default
4509 The file containing the
4510 \emph on
4511 main()
4512 \emph default
4513  function
4514 \emph on
4515
4516 \emph default
4517 \noun on
4518 must
4519 \noun default
4520  be the
4521 \noun on
4522 first
4523 \noun default
4524  file specified in the command line, since the linkage editor processes
4525  file in the order they are presented to it.
4526  The linker is invoked from SDCC using a script file with extension .lnk
4527 \begin_inset LatexCommand \index{<file>.lnk}
4528
4529 \end_inset
4530
4531 .
4532  You can view this file to troubleshoot linking problems such as those arising
4533  from missing libraries.
4534 \layout Subsection
4535
4536 Projects with Additional Libraries
4537 \begin_inset LatexCommand \index{Libraries}
4538
4539 \end_inset
4540
4541
4542 \layout Standard
4543
4544 Some reusable routines may be compiled into a library, see the documentation
4545  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4546  for how to create a
4547 \emph on
4548 .lib
4549 \begin_inset LatexCommand \index{<file>.lib}
4550
4551 \end_inset
4552
4553
4554 \emph default
4555  library file.
4556  Libraries created in this manner can be included in the command line.
4557  Make sure you include the -L <library-path> option to tell the linker where
4558  to look for these files if they are not in the current directory.
4559  Here is an example, assuming you have the source file
4560 \emph on
4561 foomain.c
4562 \emph default
4563  and a library
4564 \emph on
4565  foolib.lib
4566 \emph default
4567  in the directory
4568 \emph on
4569 mylib
4570 \emph default
4571  (if that is not the same as your current project):
4572 \newline
4573
4574 \newline
4575
4576 \family sans
4577 \series bold
4578 sdcc foomain.c foolib.lib -L mylib
4579 \newline
4580
4581 \newline
4582
4583 \family default
4584 \series default
4585 Note here that
4586 \emph on
4587  mylib
4588 \emph default
4589  must be an absolute path name.
4590 \newline
4591
4592 \newline
4593 The most efficient way to use libraries is to keep separate modules in separate
4594  source files.
4595  The lib file now should name all the modules.rel
4596 \begin_inset LatexCommand \index{<file>.rel}
4597
4598 \end_inset
4599
4600  files.
4601  For an example see the standard library file
4602 \emph on
4603 libsdcc.lib
4604 \emph default
4605  in the directory <installdir>/share/lib/small.
4606 \layout Subsection
4607
4608 Using sdcclib to Create and Manage Libraries
4609 \begin_inset LatexCommand \index{sdcclib}
4610
4611 \end_inset
4612
4613
4614 \layout Standard
4615
4616 Alternatively, instead of having a .rel file for each entry on the library
4617  file as described in the preceding section, sdcclib can be used to embed
4618  all the modules belonging to such library in the library file itself.
4619  This results in a larger library file, but it greatly reduces the number
4620  of disk files accessed by the linker.
4621   Additionally, the packed library file contains an index of all include
4622  modules and symbols that significantly speeds up the linking process.
4623  To display a list of options supported by sdcclib type:
4624 \newline
4625
4626 \layout Standard
4627
4628
4629 \family sans
4630 \series bold
4631 sdcclib -?
4632 \begin_inset LatexCommand \index{sdcclib}
4633
4634 \end_inset
4635
4636
4637 \newline
4638
4639 \newline
4640
4641 \family default
4642 \series default
4643 To create a new library file, start by compiling all the required modules.
4644  For example:
4645 \newline
4646
4647 \layout Standard
4648
4649
4650 \family sans
4651 \series bold
4652 sdcc -c _divsint.c
4653 \layout Standard
4654
4655
4656 \family sans
4657 \series bold
4658 sdcc -c _divuint.c
4659 \layout Standard
4660
4661
4662 \family sans
4663 \series bold
4664 sdcc -c _modsint.c
4665 \layout Standard
4666
4667
4668 \family sans
4669 \series bold
4670 sdcc -c _moduint.c
4671 \layout Standard
4672
4673
4674 \family sans
4675 \series bold
4676 sdcc -c _mulint.c
4677 \newline
4678
4679 \layout Standard
4680
4681 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4682  and _mulint.rel.
4683  The next step is to add the .rel files to the library file:
4684 \newline
4685
4686 \layout Standard
4687
4688
4689 \family sans
4690 \series bold
4691 sdcclib libint.lib _divsint.rel
4692 \family default
4693
4694 \begin_inset LatexCommand \index{sdcclib}
4695
4696 \end_inset
4697
4698
4699 \layout Standard
4700
4701
4702 \family sans
4703 \series bold
4704 sdcclib libint.lib _divuint.rel
4705 \layout Standard
4706
4707
4708 \family sans
4709 \series bold
4710 sdcclib libint.lib _modsint.rel
4711 \layout Standard
4712
4713
4714 \family sans
4715 \series bold
4716 sdcclib libint.lib _moduint.rel
4717 \layout Standard
4718
4719
4720 \family sans
4721 \series bold
4722 sdcclib libint.lib _mulint.rel
4723 \series default
4724
4725 \newline
4726
4727 \layout Standard
4728
4729 If the file already exists in the library, it will be replaced.
4730  To see what modules and symbols are included in the library, options -s
4731  and -m are available.
4732  For example:
4733 \newline
4734
4735 \newline
4736
4737 \family sans
4738 \series bold
4739 sdcclib -s libint.lib
4740 \family default
4741
4742 \begin_inset LatexCommand \index{sdcclib}
4743
4744 \end_inset
4745
4746
4747 \newline
4748
4749 \family typewriter
4750 \series default
4751 _divsint.rel:
4752 \layout Standard
4753
4754
4755 \family typewriter
4756 __divsint_a_1_1
4757 \layout Standard
4758
4759
4760 \family typewriter
4761 __divsint_PARM_2
4762 \layout Standard
4763
4764
4765 \family typewriter
4766 __divsint
4767 \newline
4768 _divuint.rel:
4769 \layout Standard
4770
4771
4772 \family typewriter
4773 __divuint_a_1_1
4774 \layout Standard
4775
4776
4777 \family typewriter
4778 __divuint_PARM_2
4779 \layout Standard
4780
4781
4782 \family typewriter
4783 __divuint_reste_1_1
4784 \layout Standard
4785
4786
4787 \family typewriter
4788 __divuint_count_1_1
4789 \layout Standard
4790
4791
4792 \family typewriter
4793 __divuint
4794 \newline
4795 _modsint.rel:
4796 \layout Standard
4797
4798
4799 \family typewriter
4800 __modsint_a_1_1
4801 \layout Standard
4802
4803
4804 \family typewriter
4805 __modsint_PARM_2
4806 \layout Standard
4807
4808
4809 \family typewriter
4810 __modsint
4811 \newline
4812 _moduint.rel:
4813 \layout Standard
4814
4815
4816 \family typewriter
4817 __moduint_a_1_1
4818 \layout Standard
4819
4820
4821 \family typewriter
4822 __moduint_PARM_2
4823 \layout Standard
4824
4825
4826 \family typewriter
4827 __moduint_count_1_1
4828 \layout Standard
4829
4830
4831 \family typewriter
4832 __moduint
4833 \newline
4834 _mulint.rel:
4835 \layout Standard
4836
4837
4838 \family typewriter
4839 __mulint_PARM_2
4840 \layout Standard
4841
4842
4843 \family typewriter
4844 __mulint
4845 \family default
4846 \series bold
4847
4848 \newline
4849
4850 \layout Standard
4851
4852 If the source files are compiled using -
4853 \begin_inset ERT
4854 status Open
4855
4856 \layout Standard
4857
4858 \backslash
4859 /
4860 \end_inset
4861
4862 -debug
4863 \begin_inset LatexCommand \index{-\/-debug}
4864
4865 \end_inset
4866
4867 , the corresponding debug information file .adb will be include in the library
4868  file as well.
4869  The library files created with sdcclib are plain text files, so they can
4870  be viewed with a text editor.
4871  It is not recomended to modify a library file created with sdcclib using
4872  a text editor, as there are file indexes numbers located accross the file
4873  used by the linker to quickly locate the required module to link.
4874  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
4875  it can be safely deleted, since all the information required for linking
4876  is embedded in the library file itself.
4877  Library files created using sdcclib are used as described in the preceding
4878  sections.
4879 \layout Section
4880
4881 Command Line Options
4882 \begin_inset LatexCommand \index{Command Line Options}
4883
4884 \end_inset
4885
4886
4887 \layout Subsection
4888
4889 Processor Selection Options
4890 \begin_inset LatexCommand \index{Options processor selection}
4891
4892 \end_inset
4893
4894
4895 \begin_inset LatexCommand \index{Processor selection options}
4896
4897 \end_inset
4898
4899
4900 \layout List
4901 \labelwidthstring 00.00.0000
4902
4903
4904 \series bold
4905 -mmcs51
4906 \begin_inset LatexCommand \index{-mmcs51}
4907
4908 \end_inset
4909
4910
4911 \series default
4912  Generate code for the Intel MCS51
4913 \begin_inset LatexCommand \index{MCS51}
4914
4915 \end_inset
4916
4917  family of processors.
4918  This is the default processor target.
4919 \layout List
4920 \labelwidthstring 00.00.0000
4921
4922
4923 \series bold
4924 -mds390
4925 \begin_inset LatexCommand \index{-mds390}
4926
4927 \end_inset
4928
4929
4930 \series default
4931  Generate code for the Dallas DS80C390
4932 \begin_inset LatexCommand \index{DS80C390}
4933
4934 \end_inset
4935
4936  processor.
4937 \layout List
4938 \labelwidthstring 00.00.0000
4939
4940
4941 \series bold
4942 -mds400
4943 \begin_inset LatexCommand \index{-mds400}
4944
4945 \end_inset
4946
4947
4948 \series default
4949  Generate code for the Dallas DS80C400
4950 \begin_inset LatexCommand \index{DS80C400}
4951
4952 \end_inset
4953
4954  processor.
4955 \layout List
4956 \labelwidthstring 00.00.0000
4957
4958
4959 \series bold
4960 -mhc08
4961 \begin_inset LatexCommand \index{-mhc08}
4962
4963 \end_inset
4964
4965
4966 \series default
4967  Generate code for the Motorola HC08
4968 \begin_inset LatexCommand \index{HC08}
4969
4970 \end_inset
4971
4972  family of processors (added Oct 2003).
4973 \layout List
4974 \labelwidthstring 00.00.0000
4975
4976
4977 \series bold
4978 -mz80
4979 \begin_inset LatexCommand \index{-mz80}
4980
4981 \end_inset
4982
4983
4984 \series default
4985  Generate code for the Zilog Z80
4986 \begin_inset LatexCommand \index{Z80}
4987
4988 \end_inset
4989
4990  family of processors.
4991 \layout List
4992 \labelwidthstring 00.00.0000
4993
4994
4995 \series bold
4996 -mgbz80
4997 \begin_inset LatexCommand \index{-mgbz80}
4998
4999 \end_inset
5000
5001
5002 \series default
5003  Generate code for the GameBoy Z80
5004 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5005
5006 \end_inset
5007
5008  processor (Not actively maintained).
5009 \layout List
5010 \labelwidthstring 00.00.0000
5011
5012
5013 \series bold
5014 -mavr
5015 \begin_inset LatexCommand \index{-mavr}
5016
5017 \end_inset
5018
5019
5020 \series default
5021  Generate code for the Atmel AVR
5022 \begin_inset LatexCommand \index{AVR}
5023
5024 \end_inset
5025
5026  processor (In development, not complete).
5027  AVR users should probably have a look at avr-gcc
5028 \begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
5029
5030 \end_inset
5031
5032  or winavr
5033 \begin_inset LatexCommand \url{http://winavr.sourceforge.net}
5034
5035 \end_inset
5036
5037 .
5038 \layout Comment
5039
5040 I think it is fair to direct users there for now.
5041  Open source is also about avoiding unnecessary work .
5042  But I didn't find the 'official' link.
5043 \layout List
5044 \labelwidthstring 00.00.0000
5045
5046
5047 \series bold
5048 -mpic14
5049 \begin_inset LatexCommand \index{-mpic14}
5050
5051 \end_inset
5052
5053
5054 \series default
5055  Generate code for the Microchip PIC 14
5056 \begin_inset LatexCommand \index{PIC14}
5057
5058 \end_inset
5059
5060 -bit processors (p16f84 and variants.
5061  In development, not complete).
5062 \layout Comment
5063
5064 p16f627 p16f628 p16f84 p16f873 p16f877?
5065 \layout List
5066 \labelwidthstring 00.00.0000
5067
5068
5069 \series bold
5070 -mpic16
5071 \begin_inset LatexCommand \index{-mpic16}
5072
5073 \end_inset
5074
5075
5076 \series default
5077  Generate code for the Microchip PIC 16
5078 \begin_inset LatexCommand \index{PIC16}
5079
5080 \end_inset
5081
5082 -bit processors (p18f452 and variants.
5083  In development, not complete).
5084 \layout List
5085 \labelwidthstring 00.00.0000
5086
5087
5088 \series bold
5089 -mtlcs900h
5090 \series default
5091  Generate code for the Toshiba TLCS-900H
5092 \begin_inset LatexCommand \index{TLCS-900H}
5093
5094 \end_inset
5095
5096  processor (Not maintained, not complete).
5097 \layout List
5098 \labelwidthstring 00.00.0000
5099
5100
5101 \series bold
5102 -mxa51
5103 \begin_inset LatexCommand \index{-mxa51}
5104
5105 \end_inset
5106
5107
5108 \series default
5109  Generate code for the Phillips XA51
5110 \begin_inset LatexCommand \index{XA51}
5111
5112 \end_inset
5113
5114  processor (Not maintained, not complete).
5115 \layout Subsection
5116
5117 Preprocessor Options
5118 \begin_inset LatexCommand \index{Options preprocessor}
5119
5120 \end_inset
5121
5122
5123 \begin_inset LatexCommand \index{Preprocessor options}
5124
5125 \end_inset
5126
5127
5128 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5129
5130 \end_inset
5131
5132
5133 \layout List
5134 \labelwidthstring 00.00.0000
5135
5136
5137 \series bold
5138 -I<path>
5139 \begin_inset LatexCommand \index{-I<path>}
5140
5141 \end_inset
5142
5143
5144 \series default
5145  The additional location where the pre processor will look for <..h> or
5146 \begin_inset Quotes eld
5147 \end_inset
5148
5149 ..h
5150 \begin_inset Quotes erd
5151 \end_inset
5152
5153  files.
5154 \layout List
5155 \labelwidthstring 00.00.0000
5156
5157
5158 \series bold
5159 -D<macro[=value]>
5160 \begin_inset LatexCommand \index{-D<macro[=value]>}
5161
5162 \end_inset
5163
5164
5165 \series default
5166  Command line definition of macros.
5167  Passed to the preprocessor.
5168 \layout List
5169 \labelwidthstring 00.00.0000
5170
5171
5172 \series bold
5173 -M
5174 \begin_inset LatexCommand \index{-M}
5175
5176 \end_inset
5177
5178
5179 \series default
5180  Tell the preprocessor to output a rule suitable for make describing the
5181  dependencies of each object file.
5182  For each source file, the preprocessor outputs one make-rule whose target
5183  is the object file name for that source file and whose dependencies are
5184  all the files `#include'd in it.
5185  This rule may be a single line or may be continued with `
5186 \backslash
5187 '-newline if it is long.
5188  The list of rules is printed on standard output instead of the preprocessed
5189  C program.
5190  `-M' implies `-E
5191 \begin_inset LatexCommand \index{-E}
5192
5193 \end_inset
5194
5195 '.
5196 \layout List
5197 \labelwidthstring 00.00.0000
5198
5199
5200 \series bold
5201 -C
5202 \begin_inset LatexCommand \index{-C}
5203
5204 \end_inset
5205
5206
5207 \series default
5208  Tell the preprocessor not to discard comments.
5209  Used with the `-E' option.
5210 \layout List
5211 \labelwidthstring 00.00.0000
5212
5213
5214 \series bold
5215 -MM
5216 \begin_inset LatexCommand \index{-MM}
5217
5218 \end_inset
5219
5220
5221 \size large
5222 \bar under
5223
5224 \series default
5225 \size default
5226 \bar default
5227 Like `-M' but the output mentions only the user header files included with
5228  `#include
5229 \begin_inset Quotes eld
5230 \end_inset
5231
5232 file"'.
5233  System header files included with `#include <file>' are omitted.
5234 \layout List
5235 \labelwidthstring 00.00.0000
5236
5237
5238 \series bold
5239 -Aquestion(answer)
5240 \begin_inset LatexCommand \index{-Aquestion(answer)}
5241
5242 \end_inset
5243
5244
5245 \series default
5246  Assert the answer answer for question, in case it is tested with a preprocessor
5247  conditional such as `#if #question(answer)'.
5248  `-A-' disables the standard assertions that normally describe the target
5249  machine.
5250 \layout List
5251 \labelwidthstring 00.00.0000
5252
5253
5254 \series bold
5255 -Umacro
5256 \begin_inset LatexCommand \index{-Umacro}
5257
5258 \end_inset
5259
5260
5261 \series default
5262  Undefine macro macro.
5263  `-U' options are evaluated after all `-D' options, but before any `-include'
5264  and `-imacros' options.
5265 \layout List
5266 \labelwidthstring 00.00.0000
5267
5268
5269 \series bold
5270 -dM
5271 \begin_inset LatexCommand \index{-dM}
5272
5273 \end_inset
5274
5275
5276 \series default
5277  Tell the preprocessor to output only a list of the macro definitions that
5278  are in effect at the end of preprocessing.
5279  Used with the `-E' option.
5280 \layout List
5281 \labelwidthstring 00.00.0000
5282
5283
5284 \series bold
5285 -dD
5286 \begin_inset LatexCommand \index{-dD}
5287
5288 \end_inset
5289
5290
5291 \series default
5292  Tell the preprocessor to pass all macro definitions into the output, in
5293  their proper sequence in the rest of the output.
5294 \layout List
5295 \labelwidthstring 00.00.0000
5296
5297
5298 \series bold
5299 -dN
5300 \begin_inset LatexCommand \index{-dN}
5301
5302 \end_inset
5303
5304
5305 \size large
5306 \bar under
5307
5308 \series default
5309 \size default
5310 \bar default
5311 Like `-dD' except that the macro arguments and contents are omitted.
5312  Only `#define name' is included in the output.
5313 \layout List
5314 \labelwidthstring 00.00.0000
5315
5316
5317 \series bold
5318 -Wp\SpecialChar ~
5319 preprocessorOption[,preprocessorOption]
5320 \series default
5321
5322 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5323
5324 \end_inset
5325
5326 ...
5327  Pass the preprocessorOption to the preprocessor
5328 \family typewriter
5329 sdcpp
5330 \family default
5331
5332 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5333
5334 \end_inset
5335
5336 .
5337  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5338  Collection (gcc), if you need more dedicated options please refer to the
5339  documentation at
5340 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5341
5342 \end_inset
5343
5344 .
5345 \layout Subsection
5346
5347 Linker Options
5348 \begin_inset LatexCommand \index{Options linker}
5349
5350 \end_inset
5351
5352
5353 \begin_inset LatexCommand \index{Linker options}
5354
5355 \end_inset
5356
5357
5358 \layout List
5359 \labelwidthstring 00.00.0000
5360
5361
5362 \series bold
5363 -L\SpecialChar ~
5364 -
5365 \series default
5366
5367 \begin_inset ERT
5368 status Collapsed
5369
5370 \layout Standard
5371
5372 \backslash
5373 /
5374 \end_inset
5375
5376
5377 \series bold
5378 -lib-path
5379 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5380
5381 \end_inset
5382
5383
5384 \begin_inset LatexCommand \index{-L -\/-lib-path}
5385
5386 \end_inset
5387
5388
5389 \series default
5390 \SpecialChar ~
5391 <absolute path to additional libraries> This option is passed to the linkage
5392  editor's additional libraries
5393 \begin_inset LatexCommand \index{Libraries}
5394
5395 \end_inset
5396
5397  search path.
5398  The path name must be absolute.
5399  Additional library files may be specified in the command line.
5400  See section Compiling programs for more details.
5401 \layout List
5402 \labelwidthstring 00.00.0000
5403
5404
5405 \series bold
5406 -
5407 \begin_inset ERT
5408 status Collapsed
5409
5410 \layout Standard
5411
5412 \backslash
5413 /
5414 \end_inset
5415
5416 -xram-loc
5417 \series default
5418
5419 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5420
5421 \end_inset
5422
5423 \SpecialChar ~
5424 <Value> The start location of the external ram
5425 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5426
5427 \end_inset
5428
5429 , default value is 0.
5430  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5431 \begin_inset ERT
5432 status Collapsed
5433
5434 \layout Standard
5435
5436 \backslash
5437 /
5438 \end_inset
5439
5440 -xram-loc 0x8000 or -
5441 \begin_inset ERT
5442 status Collapsed
5443
5444 \layout Standard
5445
5446 \backslash
5447 /
5448 \end_inset
5449
5450 -xram-loc 32768.
5451 \layout List
5452 \labelwidthstring 00.00.0000
5453
5454
5455 \series bold
5456 -
5457 \begin_inset ERT
5458 status Collapsed
5459
5460 \layout Standard
5461
5462 \backslash
5463 /
5464 \end_inset
5465
5466 -code-loc
5467 \series default
5468
5469 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5470
5471 \end_inset
5472
5473 \SpecialChar ~
5474 <Value> The start location of the code
5475 \begin_inset LatexCommand \index{code}
5476
5477 \end_inset
5478
5479  segment, default value 0.
5480  Note when this option is used the interrupt vector table is also relocated
5481  to the given address.
5482  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5483 \begin_inset ERT
5484 status Collapsed
5485
5486 \layout Standard
5487
5488 \backslash
5489 /
5490 \end_inset
5491
5492 -code-loc 0x8000 or -
5493 \begin_inset ERT
5494 status Collapsed
5495
5496 \layout Standard
5497
5498 \backslash
5499 /
5500 \end_inset
5501
5502 -code-loc 32768.
5503 \layout List
5504 \labelwidthstring 00.00.0000
5505
5506
5507 \series bold
5508 -
5509 \begin_inset ERT
5510 status Collapsed
5511
5512 \layout Standard
5513
5514 \backslash
5515 /
5516 \end_inset
5517
5518 -stack-loc
5519 \series default
5520
5521 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5522
5523 \end_inset
5524
5525 \SpecialChar ~
5526 <Value> By default the stack
5527 \begin_inset LatexCommand \index{stack}
5528
5529 \end_inset
5530
5531  is placed after the data segment.
5532  Using this option the stack can be placed anywhere in the internal memory
5533  space of the 8051.
5534  The value entered can be in Hexadecimal or Decimal format, e.g.
5535  -
5536 \begin_inset ERT
5537 status Collapsed
5538
5539 \layout Standard
5540
5541 \backslash
5542 /
5543 \end_inset
5544
5545 -stack-loc 0x20 or -
5546 \begin_inset ERT
5547 status Collapsed
5548
5549 \layout Standard
5550
5551 \backslash
5552 /
5553 \end_inset
5554
5555 -stack-loc 32.
5556  Since the sp register is incremented before a push or call, the initial
5557  sp will be set to one byte prior the provided value.
5558  The provided value should not overlap any other memory areas such as used
5559  register banks or the data segment and with enough space for the current
5560  application.
5561 \layout List
5562 \labelwidthstring 00.00.0000
5563
5564
5565 \series bold
5566 -
5567 \begin_inset ERT
5568 status Collapsed
5569
5570 \layout Standard
5571
5572 \backslash
5573 /
5574 \end_inset
5575
5576 -data-loc
5577 \series default
5578
5579 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5580
5581 \end_inset
5582
5583 \SpecialChar ~
5584 <Value> The start location of the internal ram data
5585 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5586
5587 \end_inset
5588
5589  segment.
5590  The value entered can be in Hexadecimal or Decimal format, eg.
5591  -
5592 \begin_inset ERT
5593 status Collapsed
5594
5595 \layout Standard
5596
5597 \backslash
5598 /
5599 \end_inset
5600
5601 -data-loc 0x20 or -
5602 \begin_inset ERT
5603 status Collapsed
5604
5605 \layout Standard
5606
5607 \backslash
5608 /
5609 \end_inset
5610
5611 -data-loc 32.
5612  (By default, the start location of the internal ram data segment  is set
5613  as low as possible in memory, taking into account the used register banks
5614  and the bit segment at address 0x20.
5615  For example if register banks 0 and 1 are used without bit variables, the
5616  data segment will be set, if -
5617 \begin_inset ERT
5618 status Collapsed
5619
5620 \layout Standard
5621
5622 \backslash
5623 /
5624 \end_inset
5625
5626 -data-loc is not used, to location 0x10.)
5627 \layout List
5628 \labelwidthstring 00.00.0000
5629
5630
5631 \series bold
5632 -
5633 \begin_inset ERT
5634 status Collapsed
5635
5636 \layout Standard
5637
5638 \backslash
5639 /
5640 \end_inset
5641
5642 -idata-loc
5643 \series default
5644
5645 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5646
5647 \end_inset
5648
5649 \SpecialChar ~
5650 <Value> The start location of the indirectly addressable internal ram
5651 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5652
5653 \end_inset
5654
5655  of the 8051, default value is 0x80.
5656  The value entered can be in Hexadecimal or Decimal format, eg.
5657  -
5658 \begin_inset ERT
5659 status Collapsed
5660
5661 \layout Standard
5662
5663 \backslash
5664 /
5665 \end_inset
5666
5667 -idata-loc 0x88 or -
5668 \begin_inset ERT
5669 status Collapsed
5670
5671 \layout Standard
5672
5673 \backslash
5674 /
5675 \end_inset
5676
5677 -idata-loc 136.
5678 \layout List
5679 \labelwidthstring 00.00.0000
5680
5681
5682 \series bold
5683 -
5684 \begin_inset ERT
5685 status Collapsed
5686
5687 \layout Standard
5688
5689 \backslash
5690 /
5691 \end_inset
5692
5693 -bit-loc
5694 \series default
5695 \SpecialChar ~
5696 <Value> The start location of the bit
5697 \begin_inset LatexCommand \index{bit}
5698
5699 \end_inset
5700
5701  addressable internal ram of the 8051.
5702  This is
5703 \emph on
5704 not
5705 \emph default
5706  implemented yet.
5707  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5708 -bBSEG=<Value>.
5709 \layout List
5710 \labelwidthstring 00.00.0000
5711
5712
5713 \series bold
5714 -
5715 \begin_inset ERT
5716 status Collapsed
5717
5718 \layout Standard
5719
5720 \backslash
5721 /
5722 \end_inset
5723
5724 -out-fmt-ihx
5725 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5726
5727 \end_inset
5728
5729
5730 \bar under
5731
5732 \series default
5733 \bar default
5734 The linker output (final object code) is in Intel Hex format.
5735 \begin_inset LatexCommand \index{Intel hex format}
5736
5737 \end_inset
5738
5739  This is the default option.
5740  The format itself is documented in the documentation of srecord
5741 \begin_inset LatexCommand \index{srecord (tool)}
5742
5743 \end_inset
5744
5745 .
5746 \layout List
5747 \labelwidthstring 00.00.0000
5748
5749
5750 \series bold
5751 -
5752 \begin_inset ERT
5753 status Collapsed
5754
5755 \layout Standard
5756
5757 \backslash
5758 /
5759 \end_inset
5760
5761 -out-fmt-s19
5762 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5763
5764 \end_inset
5765
5766
5767 \bar under
5768
5769 \series default
5770 \bar default
5771 The linker output (final object code) is in Motorola S19 format
5772 \begin_inset LatexCommand \index{Motorola S19 format}
5773
5774 \end_inset
5775
5776 .
5777  The format itself is documented in the documentation of srecord.
5778 \layout List
5779 \labelwidthstring 00.00.0000
5780
5781
5782 \series bold
5783 -Wl\SpecialChar ~
5784 linkOption[,linkOption]
5785 \series default
5786
5787 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5788
5789 \end_inset
5790
5791 ...
5792  Pass the linkOption to the linker.
5793  See file sdcc/as/doc/asxhtm.html for more on linker options.
5794 \layout Subsection
5795
5796 MCS51 Options
5797 \begin_inset LatexCommand \index{Options MCS51}
5798
5799 \end_inset
5800
5801
5802 \begin_inset LatexCommand \index{MCS51 options}
5803
5804 \end_inset
5805
5806
5807 \layout List
5808 \labelwidthstring 00.00.0000
5809
5810
5811 \series bold
5812 -
5813 \begin_inset ERT
5814 status Collapsed
5815
5816 \layout Standard
5817
5818 \backslash
5819 /
5820 \end_inset
5821
5822 -model-small
5823 \begin_inset LatexCommand \index{-\/-model-small}
5824
5825 \end_inset
5826
5827
5828 \series default
5829 \size large
5830 \emph on
5831
5832 \size default
5833 \emph default
5834 Generate code for Small Model programs, see section Memory Models for more
5835  details.
5836  This is the default model.
5837 \layout List
5838 \labelwidthstring 00.00.0000
5839
5840
5841 \series bold
5842 -
5843 \begin_inset ERT
5844 status Collapsed
5845
5846 \layout Standard
5847
5848 \backslash
5849 /
5850 \end_inset
5851
5852 -model-large
5853 \begin_inset LatexCommand \index{-\/-model-large}
5854
5855 \end_inset
5856
5857
5858 \series default
5859  Generate code for Large model programs, see section Memory Models for more
5860  details.
5861  If this option is used all source files in the project have to be compiled
5862  with this option.
5863 \layout List
5864 \labelwidthstring 00.00.0000
5865
5866
5867 \series bold
5868 -
5869 \begin_inset ERT
5870 status Collapsed
5871
5872 \layout Standard
5873
5874 \backslash
5875 /
5876 \end_inset
5877
5878 -xstack
5879 \begin_inset LatexCommand \index{-\/-xstack}
5880
5881 \end_inset
5882
5883
5884 \series default
5885  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
5886  variables and passing parameters.
5887  See section
5888 \begin_inset LatexCommand \ref{sub:External-Stack}
5889
5890 \end_inset
5891
5892 \SpecialChar ~
5893  External Stack for more details.
5894 \layout List
5895 \labelwidthstring 00.00.0000
5896
5897
5898 \series bold
5899 -
5900 \begin_inset ERT
5901 status Collapsed
5902
5903 \layout Standard
5904
5905 \backslash
5906 /
5907 \end_inset
5908
5909 -iram-size
5910 \series default
5911 \SpecialChar ~
5912 <Value>
5913 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
5914
5915 \end_inset
5916
5917  Causes the linker to check if the internal ram usage is within limits of
5918  the given value.
5919 \layout List
5920 \labelwidthstring 00.00.0000
5921
5922
5923 \series bold
5924 -
5925 \begin_inset ERT
5926 status Collapsed
5927
5928 \layout Standard
5929
5930 \backslash
5931 /
5932 \end_inset
5933
5934 -xram-size
5935 \series default
5936 \SpecialChar ~
5937 <Value>
5938 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
5939
5940 \end_inset
5941
5942  Causes the linker to check if the external ram usage is within limits of
5943  the given value.
5944 \layout List
5945 \labelwidthstring 00.00.0000
5946
5947
5948 \series bold
5949 -
5950 \begin_inset ERT
5951 status Collapsed
5952
5953 \layout Standard
5954
5955 \backslash
5956 /
5957 \end_inset
5958
5959 -code-size
5960 \series default
5961 \SpecialChar ~
5962 <Value>
5963 \begin_inset LatexCommand \index{-\/-code-size <Value>}
5964
5965 \end_inset
5966
5967  Causes the linker to check if the code memory usage is within limits of
5968  the given value.
5969 \layout List
5970 \labelwidthstring 00.00.0000
5971
5972
5973 \series bold
5974 -
5975 \begin_inset ERT
5976 status Collapsed
5977
5978 \layout Standard
5979
5980 \backslash
5981 /
5982 \end_inset
5983
5984 -stack-size
5985 \series default
5986 \SpecialChar ~
5987 <Value>
5988 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
5989
5990 \end_inset
5991
5992  Causes the linker to check if there is at minimum <Value> bytes for stack.
5993 \layout List
5994 \labelwidthstring 00.00.0000
5995
5996
5997 \series bold
5998 -
5999 \begin_inset ERT
6000 status Collapsed
6001
6002 \layout Standard
6003
6004 \backslash
6005 /
6006 \end_inset
6007
6008 -pack-iram
6009 \series default
6010 \SpecialChar ~
6011
6012 \begin_inset LatexCommand \index{-\/-pack-iram}
6013
6014 \end_inset
6015
6016  Causes the linker use unused register banks for data variables or stack.
6017 \layout Subsection
6018
6019 DS390 / DS400 Options
6020 \begin_inset LatexCommand \index{Options DS390}
6021
6022 \end_inset
6023
6024
6025 \begin_inset LatexCommand \index{DS390 options}
6026
6027 \end_inset
6028
6029
6030 \layout List
6031 \labelwidthstring 00.00.0000
6032
6033
6034 \series bold
6035 -
6036 \begin_inset ERT
6037 status Collapsed
6038
6039 \layout Standard
6040
6041 \backslash
6042 /
6043 \end_inset
6044
6045 -model-flat24
6046 \series default
6047
6048 \begin_inset LatexCommand \index{-\/-model-flat24}
6049
6050 \end_inset
6051
6052
6053 \size large
6054 \emph on
6055
6056 \size default
6057 \emph default
6058 Generate 24-bit flat mode code.
6059  This is the one and only that the ds390 code generator supports right now
6060  and is default when using
6061 \emph on
6062 -mds390
6063 \emph default
6064 .
6065  See section Memory Models for more details.
6066 \layout List
6067 \labelwidthstring 00.00.0000
6068
6069
6070 \series bold
6071 -
6072 \begin_inset ERT
6073 status Collapsed
6074
6075 \layout Standard
6076
6077 \backslash
6078 /
6079 \end_inset
6080
6081 -protect-sp-update
6082 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6083
6084 \end_inset
6085
6086
6087 \series default
6088  disable interrupts during ESP:SP updates.
6089 \layout List
6090 \labelwidthstring 00.00.0000
6091
6092
6093 \series bold
6094 -
6095 \begin_inset ERT
6096 status Collapsed
6097
6098 \layout Standard
6099
6100 \backslash
6101 /
6102 \end_inset
6103
6104 -stack-10bit
6105 \series default
6106
6107 \begin_inset LatexCommand \index{-\/-stack-10bit}
6108
6109 \end_inset
6110
6111  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6112  This is the one and only that the ds390 code generator supports right now
6113  and is default when using
6114 \emph on
6115 -mds390
6116 \emph default
6117 .
6118  In this mode, the stack is located in the lower 1K of the internal RAM,
6119  which is mapped to 0x400000.
6120  Note that the support is incomplete, since it still uses a single byte
6121  as the stack pointer.
6122  This means that only the lower 256 bytes of the potential 1K stack space
6123  will actually be used.
6124  However, this does allow you to reclaim the precious 256 bytes of low RAM
6125  for use for the DATA and IDATA segments.
6126  The compiler will not generate any code to put the processor into 10 bit
6127  stack mode.
6128  It is important to ensure that the processor is in this mode before calling
6129  any re-entrant functions compiled with this option.
6130  In principle, this should work with the
6131 \emph on
6132 -
6133 \begin_inset ERT
6134 status Collapsed
6135
6136 \layout Standard
6137
6138 \backslash
6139 /
6140 \end_inset
6141
6142 -stack-auto
6143 \begin_inset LatexCommand \index{-\/-stack-auto}
6144
6145 \end_inset
6146
6147
6148 \emph default
6149  option, but that has not been tested.
6150  It is incompatible with the
6151 \emph on
6152 -
6153 \begin_inset ERT
6154 status Collapsed
6155
6156 \layout Standard
6157
6158 \backslash
6159 /
6160 \end_inset
6161
6162 -xstack
6163 \begin_inset LatexCommand \index{-\/-xstack}
6164
6165 \end_inset
6166
6167
6168 \emph default
6169  option.
6170  It also only makes sense if the processor is in 24 bit contiguous addressing
6171  mode (see the
6172 \emph on
6173 -
6174 \begin_inset ERT
6175 status Collapsed
6176
6177 \layout Standard
6178
6179 \backslash
6180 /
6181 \end_inset
6182
6183 -model-flat24 option
6184 \emph default
6185 ).
6186 \layout List
6187 \labelwidthstring 00.00.0000
6188
6189
6190 \series bold
6191 -
6192 \begin_inset ERT
6193 status Collapsed
6194
6195 \layout Standard
6196
6197 \backslash
6198 /
6199 \end_inset
6200
6201 -stack-probe
6202 \begin_inset LatexCommand \index{-\/-stack-probe}
6203
6204 \end_inset
6205
6206
6207 \series default
6208  insert call to function __stack_probe at each function prologue.
6209 \layout List
6210 \labelwidthstring 00.00.0000
6211
6212
6213 \series bold
6214 -
6215 \begin_inset ERT
6216 status Collapsed
6217
6218 \layout Standard
6219
6220 \backslash
6221 /
6222 \end_inset
6223
6224 -tini-libid
6225 \begin_inset LatexCommand \index{-\/-tini-libid}
6226
6227 \end_inset
6228
6229
6230 \series default
6231  <nnnn> LibraryID used in -mTININative.
6232
6233 \layout List
6234 \labelwidthstring 00.00.0000
6235
6236
6237 \series bold
6238 -
6239 \begin_inset ERT
6240 status Collapsed
6241
6242 \layout Standard
6243
6244 \backslash
6245 /
6246 \end_inset
6247
6248 -use-accelerator
6249 \begin_inset LatexCommand \index{-\/-use-accelerator}
6250
6251 \end_inset
6252
6253
6254 \series default
6255  generate code for DS390 Arithmetic Accelerator.
6256
6257 \layout Subsection
6258
6259 Z80 Options
6260 \begin_inset LatexCommand \index{Options Z80}
6261
6262 \end_inset
6263
6264
6265 \begin_inset LatexCommand \index{Z80 options}
6266
6267 \end_inset
6268
6269
6270 \layout List
6271 \labelwidthstring 00.00.0000
6272
6273
6274 \series bold
6275 -
6276 \begin_inset ERT
6277 status Collapsed
6278
6279 \layout Standard
6280
6281 \backslash
6282 /
6283 \end_inset
6284
6285 -callee-saves-bc
6286 \series default
6287
6288 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6289
6290 \end_inset
6291
6292
6293 \size large
6294 \emph on
6295
6296 \size default
6297 \emph default
6298 Force a called function to always save BC.
6299 \layout List
6300 \labelwidthstring 00.00.0000
6301
6302
6303 \series bold
6304 -
6305 \begin_inset ERT
6306 status Collapsed
6307
6308 \layout Standard
6309
6310 \backslash
6311 /
6312 \end_inset
6313
6314 -no-std-crt0
6315 \series default
6316
6317 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6318
6319 \end_inset
6320
6321  When linking, skip the standard crt0.o object file.
6322  You must provide your own crt0.o for your system when linking.
6323
6324 \layout Subsection
6325
6326 Optimization Options
6327 \begin_inset LatexCommand \index{Options optimization}
6328
6329 \end_inset
6330
6331
6332 \begin_inset LatexCommand \index{Optimization options}
6333
6334 \end_inset
6335
6336
6337 \layout List
6338 \labelwidthstring 00.00.0000
6339
6340
6341 \series bold
6342 -
6343 \begin_inset ERT
6344 status Collapsed
6345
6346 \layout Standard
6347
6348 \backslash
6349 /
6350 \end_inset
6351
6352 -nogcse
6353 \begin_inset LatexCommand \index{-\/-nogcse}
6354
6355 \end_inset
6356
6357
6358 \series default
6359  Will not do global subexpression elimination, this option may be used when
6360  the compiler creates undesirably large stack/data spaces to store compiler
6361  temporaries.
6362  A warning message will be generated when this happens and the compiler
6363  will indicate the number of extra bytes it allocated.
6364  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6365 nogcse
6366 \begin_inset LatexCommand \index{\#pragma nogcse}
6367
6368 \end_inset
6369
6370  can be used to turn off global subexpression elimination
6371 \begin_inset LatexCommand \index{Subexpression elimination}
6372
6373 \end_inset
6374
6375  for a given function only.
6376 \layout List
6377 \labelwidthstring 00.00.0000
6378
6379
6380 \series bold
6381 -
6382 \begin_inset ERT
6383 status Collapsed
6384
6385 \layout Standard
6386
6387 \backslash
6388 /
6389 \end_inset
6390
6391 -noinvariant
6392 \begin_inset LatexCommand \index{-\/-noinvariant}
6393
6394 \end_inset
6395
6396
6397 \series default
6398  Will not do loop invariant optimizations, this may be turned off for reasons
6399  explained for the previous option.
6400  For more details of loop optimizations performed see Loop Invariants in
6401  section
6402 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6403
6404 \end_inset
6405
6406 .
6407  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6408 noinvariant
6409 \begin_inset LatexCommand \index{\#pragma noinvariant}
6410
6411 \end_inset
6412
6413  can be used to turn off invariant optimizations for a given function only.
6414 \layout List
6415 \labelwidthstring 00.00.0000
6416
6417
6418 \series bold
6419 -
6420 \begin_inset ERT
6421 status Collapsed
6422
6423 \layout Standard
6424
6425 \backslash
6426 /
6427 \end_inset
6428
6429 -noinduction
6430 \begin_inset LatexCommand \index{-\/-noinduction}
6431
6432 \end_inset
6433
6434
6435 \series default
6436  Will not do loop induction optimizations, see section strength reduction
6437  for more details.
6438  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6439 noinduction
6440 \begin_inset LatexCommand \index{\#pragma noinduction}
6441
6442 \end_inset
6443
6444  can be used to turn off induction optimizations for a given function only.
6445 \layout List
6446 \labelwidthstring 00.00.0000
6447
6448
6449 \series bold
6450 -
6451 \begin_inset ERT
6452 status Collapsed
6453
6454 \layout Standard
6455
6456 \backslash
6457 /
6458 \end_inset
6459
6460 -nojtbound
6461 \begin_inset LatexCommand \index{-\/-nojtbound}
6462
6463 \end_inset
6464
6465
6466 \size large
6467 \bar under
6468
6469 \series default
6470 \size default
6471 \bar default
6472  Will not generate boundary condition check when switch statements
6473 \begin_inset LatexCommand \index{switch statement}
6474
6475 \end_inset
6476
6477  are implemented using jump-tables.
6478  See section
6479 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6480
6481 \end_inset
6482
6483 \SpecialChar ~
6484 Switch Statements for more details.
6485  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6486 nojtbound
6487 \begin_inset LatexCommand \index{\#pragma nojtbound}
6488
6489 \end_inset
6490
6491  can be used to turn off boundary checking for jump tables for a given function
6492  only.
6493 \layout List
6494 \labelwidthstring 00.00.0000
6495
6496
6497 \series bold
6498 -
6499 \begin_inset ERT
6500 status Collapsed
6501
6502 \layout Standard
6503
6504 \backslash
6505 /
6506 \end_inset
6507
6508 -noloopreverse
6509 \begin_inset LatexCommand \index{-\/-noloopreverse}
6510
6511 \end_inset
6512
6513
6514 \series default
6515 \size large
6516
6517 \size default
6518 Will not do loop reversal
6519 \begin_inset LatexCommand \index{Loop reversing}
6520
6521 \end_inset
6522
6523 optimization.
6524 \layout List
6525 \labelwidthstring 00.00.0000
6526
6527 -
6528 \begin_inset ERT
6529 status Collapsed
6530
6531 \layout Standard
6532
6533 \backslash
6534 /
6535 \end_inset
6536
6537 -
6538 \series bold
6539 nolabelopt
6540 \series default
6541
6542 \begin_inset LatexCommand \index{-\/-nolabelopt }
6543
6544 \end_inset
6545
6546 Will not optimize labels (makes the dumpfiles more readable).
6547 \layout List
6548 \labelwidthstring 00.00.0000
6549
6550
6551 \series bold
6552 -
6553 \begin_inset ERT
6554 status Collapsed
6555
6556 \layout Standard
6557
6558 \backslash
6559 /
6560 \end_inset
6561
6562 -no-xinit-opt
6563 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6564
6565 \end_inset
6566
6567
6568 \series default
6569  Will not memcpy initialized data from code space into xdata space.
6570  This saves a few bytes in code space if you don't have initialized data.
6571 \layout List
6572 \labelwidthstring 00.00.0000
6573
6574
6575 \series bold
6576 -
6577 \begin_inset ERT
6578 status Collapsed
6579
6580 \layout Standard
6581
6582 \backslash
6583 /
6584 \end_inset
6585
6586 -nooverlay
6587 \begin_inset LatexCommand \index{-\/-nooverlay}
6588
6589 \end_inset
6590
6591
6592 \series default
6593   The compiler will not overlay parameters and local variables of any function,
6594  see section Parameters and local variables for more details.
6595 \layout List
6596 \labelwidthstring 00.00.0000
6597
6598
6599 \series bold
6600 -
6601 \begin_inset ERT
6602 status Collapsed
6603
6604 \layout Standard
6605
6606 \backslash
6607 /
6608 \end_inset
6609
6610 -no-peep
6611 \begin_inset LatexCommand \index{-\/-no-peep}
6612
6613 \end_inset
6614
6615
6616 \series default
6617  Disable peep-hole optimization.
6618 \layout List
6619 \labelwidthstring 00.00.0000
6620
6621
6622 \series bold
6623 -
6624 \begin_inset ERT
6625 status Collapsed
6626
6627 \layout Standard
6628
6629 \backslash
6630 /
6631 \end_inset
6632
6633 -peep-file
6634 \series default
6635
6636 \begin_inset LatexCommand \index{-\/-peep-file}
6637
6638 \end_inset
6639
6640 \SpecialChar ~
6641 <filename> This option can be used to use additional rules to be used by
6642  the peep hole optimizer.
6643  See section
6644 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6645
6646 \end_inset
6647
6648 \SpecialChar ~
6649 Peep Hole optimizations for details on how to write these rules.
6650 \layout List
6651 \labelwidthstring 00.00.0000
6652
6653
6654 \series bold
6655 -
6656 \begin_inset ERT
6657 status Collapsed
6658
6659 \layout Standard
6660
6661 \backslash
6662 /
6663 \end_inset
6664
6665 -peep-asm
6666 \begin_inset LatexCommand \index{-\/-peep-asm}
6667
6668 \end_inset
6669
6670
6671 \series default
6672   Pass the inline assembler code through the peep hole optimizer.
6673  This can cause unexpected changes to inline assembler code, please go through
6674  the peephole optimizer
6675 \begin_inset LatexCommand \index{Peephole optimizer}
6676
6677 \end_inset
6678
6679  rules defined in the source file tree '<target>/peeph.def' before using
6680  this option.
6681 \layout Subsection
6682
6683 Other Options
6684 \begin_inset LatexCommand \index{Options other}
6685
6686 \end_inset
6687
6688
6689 \layout List
6690 \labelwidthstring 00.00.0000
6691
6692
6693 \series bold
6694 -c\SpecialChar ~
6695 -
6696 \begin_inset ERT
6697 status Collapsed
6698
6699 \layout Standard
6700
6701 \backslash
6702 /
6703 \end_inset
6704
6705 -compile-only
6706 \begin_inset LatexCommand \index{-\/-compile-only}
6707
6708 \end_inset
6709
6710
6711 \begin_inset LatexCommand \index{-c -\/-compile-only}
6712
6713 \end_inset
6714
6715
6716 \series default
6717  will compile and assemble the source, but will not call the linkage editor.
6718 \layout List
6719 \labelwidthstring 00.00.0000
6720
6721
6722 \series bold
6723 -
6724 \series default
6725
6726 \begin_inset ERT
6727 status Collapsed
6728
6729 \layout Standard
6730
6731 \backslash
6732 /
6733 \end_inset
6734
6735
6736 \series bold
6737 -c1mode
6738 \begin_inset LatexCommand \index{-\/-c1mode}
6739
6740 \end_inset
6741
6742
6743 \series default
6744  reads the preprocessed source from standard input and compiles it.
6745  The file name for the assembler output must be specified using the -o option.
6746 \layout List
6747 \labelwidthstring 00.00.0000
6748
6749
6750 \series bold
6751 -E
6752 \begin_inset LatexCommand \index{-E}
6753
6754 \end_inset
6755
6756
6757 \series default
6758  Run only the C preprocessor.
6759  Preprocess all the C source files specified and output the results to standard
6760  output.
6761 \layout List
6762 \labelwidthstring 00.00.0000
6763
6764
6765 \series bold
6766 -o\SpecialChar ~
6767 <path/file>
6768 \begin_inset LatexCommand \index{-o <path/file>}
6769
6770 \end_inset
6771
6772
6773 \series default
6774 The output path resp.
6775  file where everything will be placed.
6776  If the parameter is a path, it must have a trailing slash (or backslash
6777  for the Windows binaries) to be recognized as a path.
6778
6779 \layout List
6780 \labelwidthstring 00.00.0000
6781
6782
6783 \series bold
6784 -
6785 \begin_inset ERT
6786 status Collapsed
6787
6788 \layout Standard
6789
6790 \backslash
6791 /
6792 \end_inset
6793
6794 -stack-auto
6795 \begin_inset LatexCommand \index{-\/-stack-auto}
6796
6797 \end_inset
6798
6799
6800 \series default
6801 \size large
6802 \emph on
6803
6804 \size default
6805 \emph default
6806 All functions in the source file will be compiled as
6807 \emph on
6808 reentrant
6809 \emph default
6810
6811 \begin_inset LatexCommand \index{reentrant}
6812
6813 \end_inset
6814
6815 , i.e.
6816  the parameters and local variables will be allocated on the stack
6817 \begin_inset LatexCommand \index{stack}
6818
6819 \end_inset
6820
6821 .
6822  See section
6823 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
6824
6825 \end_inset
6826
6827  Parameters and Local Variables for more details.
6828  If this option is used all source files in the project should be compiled
6829  with this option.
6830
6831 \layout List
6832 \labelwidthstring 00.00.0000
6833
6834
6835 \series bold
6836 -
6837 \begin_inset ERT
6838 status Collapsed
6839
6840 \layout Standard
6841
6842 \backslash
6843 /
6844 \end_inset
6845
6846 -callee-saves
6847 \begin_inset LatexCommand \index{-\/-callee-saves}
6848
6849 \end_inset
6850
6851  function1[,function2][,function3]....
6852
6853 \series default
6854  The compiler by default uses a caller saves convention for register saving
6855  across function calls, however this can cause unnecessary register pushing
6856  & popping when calling small functions from larger functions.
6857  This option can be used to switch the register saving convention for the
6858  function names specified.
6859  The compiler will not save registers when calling these functions, no extra
6860  code will be generated at the entry & exit (function prologue
6861 \series bold
6862
6863 \begin_inset LatexCommand \index{function prologue}
6864
6865 \end_inset
6866
6867
6868 \series default
6869  & epilogue
6870 \series bold
6871
6872 \begin_inset LatexCommand \index{function epilogue}
6873
6874 \end_inset
6875
6876
6877 \series default
6878 ) for these functions to save & restore the registers used by these functions,
6879  this can SUBSTANTIALLY reduce code & improve run time performance of the
6880  generated code.
6881  In the future the compiler (with inter procedural analysis) will be able
6882  to determine the appropriate scheme to use for each function call.
6883  DO NOT use this option for built-in functions such as _mulint..., if this
6884  option is used for a library function the appropriate library function
6885  needs to be recompiled with the same option.
6886  If the project consists of multiple source files then all the source file
6887  should be compiled with the same -
6888 \begin_inset ERT
6889 status Collapsed
6890
6891 \layout Standard
6892
6893 \backslash
6894 /
6895 \end_inset
6896
6897 -callee-saves option string.
6898  Also see #pragma\SpecialChar ~
6899 callee_saves
6900 \begin_inset LatexCommand \index{\#pragma callee\_saves}
6901
6902 \end_inset
6903
6904 .
6905 \layout List
6906 \labelwidthstring 00.00.0000
6907
6908
6909 \series bold
6910 -
6911 \begin_inset ERT
6912 status Open
6913
6914 \layout Standard
6915
6916 \backslash
6917 /
6918 \end_inset
6919
6920 -debug
6921 \begin_inset LatexCommand \index{-\/-debug}
6922
6923 \end_inset
6924
6925
6926 \bar under
6927
6928 \series default
6929 \bar default
6930 When this option is used the compiler will generate debug information.
6931  The debug information collected in a file with .cdb extension can be used
6932  with the SDCDB.
6933  For more information see documentation for SDCDB.
6934  Another file with no extension contains debug information in AOMF or AOMF51
6935 \begin_inset LatexCommand \index{AOMF, AOMF51}
6936
6937 \end_inset
6938
6939  format which is commonly used by third party tools.
6940 \layout List
6941 \labelwidthstring 00.00.0000
6942
6943
6944 \series bold
6945 -S
6946 \begin_inset LatexCommand \index{-S}
6947
6948 \end_inset
6949
6950
6951 \size large
6952 \bar under
6953
6954 \series default
6955 \size default
6956 \bar default
6957 Stop after the stage of compilation proper; do not assemble.
6958  The output is an assembler code file for the input file specified.
6959 \layout List
6960 \labelwidthstring 00.00.0000
6961
6962
6963 \series bold
6964 -
6965 \begin_inset ERT
6966 status Collapsed
6967
6968 \layout Standard
6969
6970 \backslash
6971 /
6972 \end_inset
6973
6974 -int-long-reent
6975 \begin_inset LatexCommand \index{-\/-int-long-reent}
6976
6977 \end_inset
6978
6979
6980 \series default
6981  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
6982  Note by default these libraries are compiled as non-reentrant.
6983  See section Installation for more details.
6984 \layout List
6985 \labelwidthstring 00.00.0000
6986
6987
6988 \series bold
6989 -
6990 \begin_inset ERT
6991 status Collapsed
6992
6993 \layout Standard
6994
6995 \backslash
6996 /
6997 \end_inset
6998
6999 -cyclomatic
7000 \begin_inset LatexCommand \index{-\/-cyclomatic}
7001
7002 \end_inset
7003
7004
7005 \bar under
7006
7007 \series default
7008 \bar default
7009 This option will cause the compiler to generate an information message for
7010  each function in the source file.
7011  The message contains some
7012 \emph on
7013 important
7014 \emph default
7015  information about the function.
7016  The number of edges and nodes the compiler detected in the control flow
7017  graph of the function, and most importantly the
7018 \emph on
7019 cyclomatic complexity
7020 \begin_inset LatexCommand \index{Cyclomatic complexity}
7021
7022 \end_inset
7023
7024
7025 \emph default
7026  see section on Cyclomatic Complexity for more details.
7027 \layout List
7028 \labelwidthstring 00.00.0000
7029
7030
7031 \series bold
7032 -
7033 \begin_inset ERT
7034 status Collapsed
7035
7036 \layout Standard
7037
7038 \backslash
7039 /
7040 \end_inset
7041
7042 -float-reent
7043 \begin_inset LatexCommand \index{-\/-float-reent}
7044
7045 \end_inset
7046
7047
7048 \series default
7049  Floating point library is compiled as reentrant
7050 \begin_inset LatexCommand \index{reentrant}
7051
7052 \end_inset
7053
7054 .
7055  See section Installation for more details.
7056 \layout List
7057 \labelwidthstring 00.00.0000
7058
7059
7060 \series bold
7061 -
7062 \begin_inset ERT
7063 status Collapsed
7064
7065 \layout Standard
7066
7067 \backslash
7068 /
7069 \end_inset
7070
7071 -main-return
7072 \begin_inset LatexCommand \index{-\/-main-return}
7073
7074 \end_inset
7075
7076
7077 \series default
7078  This option can be used if the code generated is called by a monitor program
7079  or if the main routine includes an endless loop.
7080  This option might result in slightly smaller code and save two bytes of
7081  stack space.
7082  The return from the 'main'
7083 \begin_inset LatexCommand \index{main return}
7084
7085 \end_inset
7086
7087  function will return to the function calling main.
7088  The default setting is to lock up i.e.
7089  generate a '
7090 \family typewriter
7091 sjmp .
7092 \family default
7093 '.
7094 \layout List
7095 \labelwidthstring 00.00.0000
7096
7097
7098 \series bold
7099 -
7100 \begin_inset ERT
7101 status Collapsed
7102
7103 \layout Standard
7104
7105 \backslash
7106 /
7107 \end_inset
7108
7109 -nostdincl
7110 \begin_inset LatexCommand \index{-\/-nostdincl}
7111
7112 \end_inset
7113
7114
7115 \series default
7116  This will prevent the compiler from passing on the default include path
7117  to the preprocessor.
7118 \layout List
7119 \labelwidthstring 00.00.0000
7120
7121
7122 \series bold
7123 -
7124 \begin_inset ERT
7125 status Collapsed
7126
7127 \layout Standard
7128
7129 \backslash
7130 /
7131 \end_inset
7132
7133 -nostdlib
7134 \begin_inset LatexCommand \index{-\/-nostdlib}
7135
7136 \end_inset
7137
7138
7139 \series default
7140  This will prevent the compiler from passing on the default library
7141 \begin_inset LatexCommand \index{Libraries}
7142
7143 \end_inset
7144
7145  path to the linker.
7146 \layout List
7147 \labelwidthstring 00.00.0000
7148
7149
7150 \series bold
7151 -
7152 \begin_inset ERT
7153 status Collapsed
7154
7155 \layout Standard
7156
7157 \backslash
7158 /
7159 \end_inset
7160
7161 -verbose
7162 \begin_inset LatexCommand \index{-\/-verbose}
7163
7164 \end_inset
7165
7166
7167 \series default
7168  Shows the various actions the compiler is performing.
7169 \layout List
7170 \labelwidthstring 00.00.0000
7171
7172
7173 \series bold
7174 -V
7175 \begin_inset LatexCommand \index{-V}
7176
7177 \end_inset
7178
7179
7180 \series default
7181  Shows the actual commands the compiler is executing.
7182 \layout List
7183 \labelwidthstring 00.00.0000
7184
7185
7186 \series bold
7187 -
7188 \begin_inset ERT
7189 status Collapsed
7190
7191 \layout Standard
7192
7193 \backslash
7194 /
7195 \end_inset
7196
7197 -no-c-code-in-asm
7198 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7199
7200 \end_inset
7201
7202
7203 \series default
7204  Hides your ugly and inefficient c-code from the asm file, so you can always
7205  blame the compiler :)
7206 \layout List
7207 \labelwidthstring 00.00.0000
7208
7209
7210 \series bold
7211 -
7212 \begin_inset ERT
7213 status Collapsed
7214
7215 \layout Standard
7216
7217 \backslash
7218 /
7219 \end_inset
7220
7221 -no-peep-comments
7222 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7223
7224 \end_inset
7225
7226
7227 \series default
7228  Will not include peep-hole comments in the generated files.
7229 \layout List
7230 \labelwidthstring 00.00.0000
7231
7232
7233 \series bold
7234 -
7235 \begin_inset ERT
7236 status Collapsed
7237
7238 \layout Standard
7239
7240 \backslash
7241 /
7242 \end_inset
7243
7244 -i-code-in-asm
7245 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7246
7247 \end_inset
7248
7249
7250 \series default
7251  Include i-codes in the asm file.
7252  Sounds like noise but is most helpful for debugging the compiler itself.
7253 \layout List
7254 \labelwidthstring 00.00.0000
7255
7256
7257 \series bold
7258 -
7259 \begin_inset ERT
7260 status Collapsed
7261
7262 \layout Standard
7263
7264 \backslash
7265 /
7266 \end_inset
7267
7268 -less-pedantic
7269 \begin_inset LatexCommand \index{-\/-less-pedantic}
7270
7271 \end_inset
7272
7273
7274 \series default
7275  Disable some of the more pedantic warnings
7276 \begin_inset LatexCommand \index{Warnings}
7277
7278 \end_inset
7279
7280  (jwk burps: please be more specific here, please!).
7281  If you want rather more than less warnings you should consider using a
7282  separate tool dedicated to syntax checking like splint
7283 \begin_inset LatexCommand \url{www.splint.org}
7284
7285 \end_inset
7286
7287 .
7288 \layout List
7289 \labelwidthstring 00.00.0000
7290
7291
7292 \series bold
7293 -
7294 \begin_inset ERT
7295 status Collapsed
7296
7297 \layout Standard
7298
7299 \backslash
7300 /
7301 \end_inset
7302
7303 -print-search-dirs
7304 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7305
7306 \end_inset
7307
7308
7309 \series default
7310  Display the directories in the compiler's search path
7311 \layout List
7312 \labelwidthstring 00.00.0000
7313
7314
7315 \series bold
7316 -
7317 \begin_inset ERT
7318 status Collapsed
7319
7320 \layout Standard
7321
7322 \backslash
7323 /
7324 \end_inset
7325
7326 -vc
7327 \begin_inset LatexCommand \index{-\/-vc}
7328
7329 \end_inset
7330
7331
7332 \series default
7333  Display errors and warnings using MSVC style, so you can use SDCC with
7334  visual studio.
7335 \layout List
7336 \labelwidthstring 00.00.0000
7337
7338
7339 \series bold
7340 -
7341 \begin_inset ERT
7342 status Collapsed
7343
7344 \layout Standard
7345
7346 \backslash
7347 /
7348 \end_inset
7349
7350 -use-stdout
7351 \begin_inset LatexCommand \index{-\/-use-stdout}
7352
7353 \end_inset
7354
7355
7356 \series default
7357  Send errors and warnings to stdout instead of stderr.
7358 \layout List
7359 \labelwidthstring 00.00.0000
7360
7361
7362 \series bold
7363 -Wa\SpecialChar ~
7364 asmOption[,asmOption]
7365 \series default
7366
7367 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7368
7369 \end_inset
7370
7371 ...
7372  Pass the asmOption to the assembler
7373 \begin_inset LatexCommand \index{Options assembler}
7374
7375 \end_inset
7376
7377
7378 \begin_inset LatexCommand \index{Assembler options}
7379
7380 \end_inset
7381
7382 .
7383  See file sdcc/as/doc/asxhtm.html for assembler options.
7384 \layout Subsection
7385
7386 Intermediate Dump Options
7387 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7388
7389 \end_inset
7390
7391
7392 \begin_inset LatexCommand \index{Options intermediate dump}
7393
7394 \end_inset
7395
7396
7397 \begin_inset LatexCommand \index{Intermediate dump options}
7398
7399 \end_inset
7400
7401
7402 \layout Standard
7403
7404 The following options are provided for the purpose of retargetting and debugging
7405  the compiler.
7406  These provided a means to dump the intermediate code (iCode
7407 \begin_inset LatexCommand \index{iCode}
7408
7409 \end_inset
7410
7411 ) generated by the compiler in human readable form at various stages of
7412  the compilation process.
7413  More on iCodes see chapter
7414 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7415
7416 \end_inset
7417
7418
7419 \begin_inset Quotes srd
7420 \end_inset
7421
7422 The anatomy of the compiler
7423 \begin_inset Quotes srd
7424 \end_inset
7425
7426 .
7427 \layout List
7428 \labelwidthstring 00.00.0000
7429
7430
7431 \series bold
7432 -
7433 \begin_inset ERT
7434 status Collapsed
7435
7436 \layout Standard
7437
7438 \backslash
7439 /
7440 \end_inset
7441
7442 -dumpraw
7443 \begin_inset LatexCommand \index{-\/-dumpraw}
7444
7445 \end_inset
7446
7447
7448 \series default
7449  This option will cause the compiler to dump the intermediate code into
7450  a file of named
7451 \emph on
7452 <source filename>.dumpraw
7453 \emph default
7454  just after the intermediate code has been generated for a function, i.e.
7455  before any optimizations are done.
7456  The basic blocks
7457 \begin_inset LatexCommand \index{Basic blocks}
7458
7459 \end_inset
7460
7461  at this stage ordered in the depth first number, so they may not be in
7462  sequence of execution.
7463 \layout List
7464 \labelwidthstring 00.00.0000
7465
7466
7467 \series bold
7468 -
7469 \begin_inset ERT
7470 status Collapsed
7471
7472 \layout Standard
7473
7474 \backslash
7475 /
7476 \end_inset
7477
7478 -dumpgcse
7479 \begin_inset LatexCommand \index{-\/-dumpgcse}
7480
7481 \end_inset
7482
7483
7484 \series default
7485  Will create a dump of iCode's, after global subexpression elimination
7486 \begin_inset LatexCommand \index{Global subexpression elimination}
7487
7488 \end_inset
7489
7490 , into a file named
7491 \emph on
7492 <source filename>.dumpgcse.
7493 \layout List
7494 \labelwidthstring 00.00.0000
7495
7496
7497 \series bold
7498 -
7499 \begin_inset ERT
7500 status Collapsed
7501
7502 \layout Standard
7503
7504 \backslash
7505 /
7506 \end_inset
7507
7508 -dumpdeadcode
7509 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
7510
7511 \end_inset
7512
7513
7514 \series default
7515  Will create a dump of iCode's, after deadcode elimination
7516 \begin_inset LatexCommand \index{Dead-code elimination}
7517
7518 \end_inset
7519
7520 , into a file named
7521 \emph on
7522 <source filename>.dumpdeadcode.
7523 \layout List
7524 \labelwidthstring 00.00.0000
7525
7526
7527 \series bold
7528 -
7529 \begin_inset ERT
7530 status Collapsed
7531
7532 \layout Standard
7533
7534 \backslash
7535 /
7536 \end_inset
7537
7538 -dumploop
7539 \begin_inset LatexCommand \index{-\/-dumploop}
7540
7541 \end_inset
7542
7543
7544 \series default
7545 \size large
7546
7547 \size default
7548 Will create a dump of iCode's, after loop optimizations
7549 \begin_inset LatexCommand \index{Loop optimization}
7550
7551 \end_inset
7552
7553 , into a file named
7554 \emph on
7555 <source filename>.dumploop.
7556 \layout List
7557 \labelwidthstring 00.00.0000
7558
7559
7560 \series bold
7561 -
7562 \begin_inset ERT
7563 status Collapsed
7564
7565 \layout Standard
7566
7567 \backslash
7568 /
7569 \end_inset
7570
7571 -dumprange
7572 \begin_inset LatexCommand \index{-\/-dumprange}
7573
7574 \end_inset
7575
7576
7577 \series default
7578 \size large
7579
7580 \size default
7581 Will create a dump of iCode's, after live range analysis
7582 \begin_inset LatexCommand \index{Live range analysis}
7583
7584 \end_inset
7585
7586 , into a file named
7587 \emph on
7588 <source filename>.dumprange.
7589 \layout List
7590 \labelwidthstring 00.00.0000
7591
7592
7593 \series bold
7594 -
7595 \begin_inset ERT
7596 status Collapsed
7597
7598 \layout Standard
7599
7600 \backslash
7601 /
7602 \end_inset
7603
7604 -dumlrange
7605 \begin_inset LatexCommand \index{-\/-dumlrange}
7606
7607 \end_inset
7608
7609
7610 \series default
7611  Will dump the life ranges
7612 \begin_inset LatexCommand \index{Live range analysis}
7613
7614 \end_inset
7615
7616  for all symbols.
7617 \layout List
7618 \labelwidthstring 00.00.0000
7619
7620
7621 \series bold
7622 -
7623 \begin_inset ERT
7624 status Collapsed
7625
7626 \layout Standard
7627
7628 \backslash
7629 /
7630 \end_inset
7631
7632 -dumpregassign
7633 \begin_inset LatexCommand \index{-\/-dumpregassign}
7634
7635 \end_inset
7636
7637
7638 \bar under
7639
7640 \series default
7641 \bar default
7642 Will create a dump of iCode's, after register assignment
7643 \begin_inset LatexCommand \index{Register assignment}
7644
7645 \end_inset
7646
7647 , into a file named
7648 \emph on
7649 <source filename>.dumprassgn.
7650 \layout List
7651 \labelwidthstring 00.00.0000
7652
7653
7654 \series bold
7655 -
7656 \begin_inset ERT
7657 status Collapsed
7658
7659 \layout Standard
7660
7661 \backslash
7662 /
7663 \end_inset
7664
7665 -dumplrange
7666 \begin_inset LatexCommand \index{-\/-dumplrange}
7667
7668 \end_inset
7669
7670
7671 \series default
7672  Will create a dump of the live ranges of iTemp's
7673 \layout List
7674 \labelwidthstring 00.00.0000
7675
7676
7677 \series bold
7678 -
7679 \begin_inset ERT
7680 status Collapsed
7681
7682 \layout Standard
7683
7684 \backslash
7685 /
7686 \end_inset
7687
7688 -dumpall
7689 \begin_inset LatexCommand \index{-\/-dumpall}
7690
7691 \end_inset
7692
7693
7694 \size large
7695 \bar under
7696
7697 \series default
7698 \size default
7699 \bar default
7700 Will cause all the above mentioned dumps to be created.
7701 \layout Subsection
7702
7703 Redirecting output on Windows Shells
7704 \layout Standard
7705
7706 By default SDCC writes it's error messages to
7707 \begin_inset Quotes sld
7708 \end_inset
7709
7710 standard error
7711 \begin_inset Quotes srd
7712 \end_inset
7713
7714 .
7715  To force all messages to
7716 \begin_inset Quotes sld
7717 \end_inset
7718
7719 standard output
7720 \begin_inset Quotes srd
7721 \end_inset
7722
7723  use
7724 \series bold
7725 -
7726 \series default
7727 \emph on
7728
7729 \begin_inset ERT
7730 status Collapsed
7731
7732 \layout Standard
7733
7734 \backslash
7735 /
7736 \end_inset
7737
7738
7739 \series bold
7740 \emph default
7741 -
7742 \series default
7743 use-stdout
7744 \begin_inset LatexCommand \index{-\/-use-stdout}
7745
7746 \end_inset
7747
7748 .
7749  Additionally, if you happen to have visual studio installed in your windows
7750  machine, you can use it to compile your sources using a custom build and
7751  the SDCC -
7752 \emph on
7753
7754 \begin_inset ERT
7755 status Collapsed
7756
7757 \layout Standard
7758
7759 \backslash
7760 /
7761 \end_inset
7762
7763
7764 \emph default
7765 -vc
7766 \begin_inset LatexCommand \index{-\/-vc}
7767
7768 \end_inset
7769
7770  option.
7771  Something like this should work:
7772 \newline
7773
7774 \newline
7775
7776 \series bold
7777 c:
7778 \backslash
7779 sdcc
7780 \backslash
7781 bin
7782 \backslash
7783 sdcc.exe -
7784 \series default
7785 \emph on
7786
7787 \begin_inset ERT
7788 status Collapsed
7789
7790 \layout Standard
7791
7792 \backslash
7793 /
7794 \end_inset
7795
7796
7797 \series bold
7798 \emph default
7799 -vc -
7800 \series default
7801 \emph on
7802
7803 \begin_inset ERT
7804 status Collapsed
7805
7806 \layout Standard
7807
7808 \backslash
7809 /
7810 \end_inset
7811
7812
7813 \series bold
7814 \emph default
7815 -model-large -c $(InputPath)
7816 \layout Section
7817
7818 Environment variables
7819 \begin_inset LatexCommand \index{Environment variables}
7820
7821 \end_inset
7822
7823
7824 \layout Standard
7825
7826 SDCC recognizes the following environment variables:
7827 \layout List
7828 \labelwidthstring 00.00.0000
7829
7830
7831 \series bold
7832 SDCC_LEAVE_SIGNALS
7833 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
7834
7835 \end_inset
7836
7837
7838 \series default
7839  SDCC installs a signal handler
7840 \begin_inset LatexCommand \index{signal handler}
7841
7842 \end_inset
7843
7844  to be able to delete temporary files after an user break (^C) or an exception.
7845  If this environment variable is set, SDCC won't install the signal handler
7846  in order to be able to debug SDCC.
7847 \layout List
7848 \labelwidthstring 00.00.0000
7849
7850
7851 \series bold
7852 TMP,\SpecialChar ~
7853 TEMP,\SpecialChar ~
7854 TMPDIR
7855 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
7856
7857 \end_inset
7858
7859
7860 \series default
7861  Path, where temporary files will be created.
7862  The order of the variables is the search order.
7863  In a standard *nix environment these variables are not set, and there's
7864  no need to set them.
7865  On Windows it's recommended to set one of them.
7866 \layout List
7867 \labelwidthstring 00.00.0000
7868
7869
7870 \series bold
7871 SDCC_HOME
7872 \begin_inset LatexCommand \index{SDCC\_HOME}
7873
7874 \end_inset
7875
7876
7877 \series default
7878  Path, see section
7879 \begin_inset LatexCommand \ref{sub:Install-paths}
7880
7881 \end_inset
7882
7883 \SpecialChar ~
7884
7885 \begin_inset Quotes sld
7886 \end_inset
7887
7888  Install Paths
7889 \begin_inset Quotes srd
7890 \end_inset
7891
7892 .
7893 \layout List
7894 \labelwidthstring 00.00.0000
7895
7896
7897 \series bold
7898 SDCC_INCLUDE
7899 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
7900
7901 \end_inset
7902
7903
7904 \series default
7905  Path, see section
7906 \begin_inset LatexCommand \ref{sub:Search-Paths}
7907
7908 \end_inset
7909
7910 \SpecialChar ~
7911
7912 \begin_inset Quotes sld
7913 \end_inset
7914
7915 Search Paths
7916 \begin_inset Quotes srd
7917 \end_inset
7918
7919 .
7920 \layout List
7921 \labelwidthstring 00.00.0000
7922
7923
7924 \series bold
7925 SDCC_LIB
7926 \begin_inset LatexCommand \index{SDCC\_LIB}
7927
7928 \end_inset
7929
7930
7931 \series default
7932  Path, see section
7933 \begin_inset LatexCommand \ref{sub:Search-Paths}
7934
7935 \end_inset
7936
7937 \SpecialChar ~
7938
7939 \begin_inset Quotes sld
7940 \end_inset
7941
7942 Search Paths
7943 \begin_inset Quotes srd
7944 \end_inset
7945
7946 ..
7947 \layout Standard
7948
7949 There are some more environment variables recognized by SDCC, but these
7950  are solely used for debugging purposes.
7951  They can change or disappear very quickly, and will never be documented.
7952 \layout Section
7953
7954 Storage Class Language Extensions
7955 \layout Subsection
7956
7957 MCS51/DS390 Storage Class
7958 \begin_inset LatexCommand \index{Storage class}
7959
7960 \end_inset
7961
7962  Language Extensions
7963 \layout Standard
7964
7965 In addition to the ANSI storage classes SDCC allows the following MCS51
7966  specific storage classes:
7967 \layout Subsubsection
7968
7969 data
7970 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
7971
7972 \end_inset
7973
7974  / near
7975 \begin_inset LatexCommand \index{near (storage class)}
7976
7977 \end_inset
7978
7979
7980 \layout Standard
7981
7982 This is the
7983 \series bold
7984 default
7985 \series default
7986  storage class for the Small Memory model (
7987 \emph on
7988 data
7989 \emph default
7990  and
7991 \emph on
7992 near
7993 \emph default
7994  can be used synonymously).
7995  Variables declared with this storage class will be allocated in the directly
7996  addressable portion of the internal RAM of a 8051, e.g.:
7997 \layout Verse
7998
7999
8000 \family typewriter
8001 data unsigned char test_data;
8002 \layout Standard
8003
8004 Writing 0x01 to this variable generates the assembly code:
8005 \layout Verse
8006
8007
8008 \family typewriter
8009 75*00 01\SpecialChar ~
8010 \SpecialChar ~
8011 \SpecialChar ~
8012 mov\SpecialChar ~
8013 \SpecialChar ~
8014 _test_data,#0x01
8015 \layout Subsubsection
8016
8017 xdata
8018 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8019
8020 \end_inset
8021
8022  / far
8023 \begin_inset LatexCommand \index{far (storage class)}
8024
8025 \end_inset
8026
8027
8028 \layout Standard
8029
8030 Variables declared with this storage class will be placed in the external
8031  RAM.
8032  This is the
8033 \series bold
8034 default
8035 \series default
8036  storage class for the Large Memory model, e.g.:
8037 \layout Verse
8038
8039
8040 \family typewriter
8041 xdata unsigned char test_xdata;
8042 \layout Standard
8043
8044 Writing 0x01 to this variable generates the assembly code:
8045 \layout Verse
8046
8047
8048 \family typewriter
8049 90s00r00\SpecialChar ~
8050 \SpecialChar ~
8051 \SpecialChar ~
8052 mov\SpecialChar ~
8053 \SpecialChar ~
8054 dptr,#_test_xdata
8055 \newline
8056 74\SpecialChar ~
8057 01\SpecialChar ~
8058 \SpecialChar ~
8059 \SpecialChar ~
8060 \SpecialChar ~
8061 \SpecialChar ~
8062 \SpecialChar ~
8063 mov\SpecialChar ~
8064 \SpecialChar ~
8065 a,#0x01
8066 \newline
8067 F0\SpecialChar ~
8068 \SpecialChar ~
8069 \SpecialChar ~
8070 \SpecialChar ~
8071 \SpecialChar ~
8072 \SpecialChar ~
8073 \SpecialChar ~
8074 \SpecialChar ~
8075 \SpecialChar ~
8076 movx\SpecialChar ~
8077 @dptr,a
8078 \layout Subsubsection
8079
8080 idata
8081 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8082
8083 \end_inset
8084
8085
8086 \layout Standard
8087
8088 Variables declared with this storage class will be allocated into the indirectly
8089  addressable portion of the internal ram of a 8051, e.g.:
8090 \layout Verse
8091
8092
8093 \family typewriter
8094 idata unsigned char test_idata;
8095 \layout Standard
8096
8097 Writing 0x01 to this variable generates the assembly code:
8098 \layout Verse
8099
8100
8101 \family typewriter
8102 78r00\SpecialChar ~
8103 \SpecialChar ~
8104 \SpecialChar ~
8105 \SpecialChar ~
8106 \SpecialChar ~
8107 \SpecialChar ~
8108 \SpecialChar ~
8109 mov\SpecialChar ~
8110 \SpecialChar ~
8111 r0,#_test_idata
8112 \newline
8113 76\SpecialChar ~
8114 01\SpecialChar ~
8115 \SpecialChar ~
8116 \SpecialChar ~
8117 \SpecialChar ~
8118 \SpecialChar ~
8119 \SpecialChar ~
8120 \SpecialChar ~
8121 mov\SpecialChar ~
8122 \SpecialChar ~
8123 @r0,#0x01
8124 \layout Standard
8125
8126 Please note, the first 128 byte of idata physically access the same RAM
8127  as the data memory.
8128  The original 8051 had 128 byte idata memory, nowadays most devices have
8129  256 byte idata memory.
8130  The stack
8131 \begin_inset LatexCommand \index{stack}
8132
8133 \end_inset
8134
8135  is located in idata memory.
8136 \layout Subsubsection
8137
8138 pdata
8139 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8140
8141 \end_inset
8142
8143
8144 \layout Standard
8145
8146 Paged xdata access is currently not as straightforward as using the other
8147  addressing modes of a 8051.
8148  The following example writes 0x01 to the address pointed to.
8149  Please note, pdata access physically accesses xdata memory.
8150  The high byte of the address is determined by port P2
8151 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8152
8153 \end_inset
8154
8155 (or in case of some 8051 variants by a separate Special Function Register,
8156  see section
8157 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8158
8159 \end_inset
8160
8161 ).
8162 \layout Verse
8163
8164
8165 \family typewriter
8166 pdata unsigned char *test_pdata_ptr;
8167 \newline
8168
8169 \newline
8170 void main()
8171 \newline
8172 {
8173 \newline
8174 \SpecialChar ~
8175 \SpecialChar ~
8176 \SpecialChar ~
8177 \SpecialChar ~
8178 test_pdata_ptr = (pdata *)0xfe;
8179 \newline
8180 \SpecialChar ~
8181 \SpecialChar ~
8182 \SpecialChar ~
8183 \SpecialChar ~
8184 *test_pdata_ptr = 1;
8185 \newline
8186 }
8187 \layout Standard
8188
8189 Generates the assembly code:
8190 \layout Verse
8191
8192
8193 \family typewriter
8194 75*01 FE\SpecialChar ~
8195 \SpecialChar ~
8196 \SpecialChar ~
8197 mov\SpecialChar ~
8198  _test_pdata_ptr,#0xFE
8199 \newline
8200 78 FE\SpecialChar ~
8201 \SpecialChar ~
8202 \SpecialChar ~
8203 \SpecialChar ~
8204 \SpecialChar ~
8205 \SpecialChar ~
8206 mov\SpecialChar ~
8207  r0,#0xFE
8208 \newline
8209 74 01\SpecialChar ~
8210 \SpecialChar ~
8211 \SpecialChar ~
8212 \SpecialChar ~
8213 \SpecialChar ~
8214 \SpecialChar ~
8215 mov\SpecialChar ~
8216  a,#0x01
8217 \newline
8218 F2\SpecialChar ~
8219 \SpecialChar ~
8220 \SpecialChar ~
8221 \SpecialChar ~
8222 \SpecialChar ~
8223 \SpecialChar ~
8224 \SpecialChar ~
8225 \SpecialChar ~
8226 \SpecialChar ~
8227 movx @r0,a
8228 \layout Standard
8229
8230 Be extremely carefull if you use pdata together with the -
8231 \begin_inset ERT
8232 status Collapsed
8233
8234 \layout Standard
8235
8236 \backslash
8237 /
8238 \end_inset
8239
8240 -xstack
8241 \begin_inset LatexCommand \index{-\/-xstack}
8242
8243 \end_inset
8244
8245  option.
8246 \layout Subsubsection
8247
8248 code
8249 \begin_inset LatexCommand \index{code}
8250
8251 \end_inset
8252
8253
8254 \layout Standard
8255
8256 'Variables' declared with this storage class will be placed in the code
8257  memory:
8258 \layout Verse
8259
8260
8261 \family typewriter
8262 code unsigned char test_code;
8263 \layout Standard
8264
8265 Read access to this variable generates the assembly code:
8266 \layout Verse
8267
8268
8269 \family typewriter
8270 90s00r6F\SpecialChar ~
8271 \SpecialChar ~
8272 \SpecialChar ~
8273 mov dptr,#_test_code
8274 \newline
8275 E4\SpecialChar ~
8276 \SpecialChar ~
8277 \SpecialChar ~
8278 \SpecialChar ~
8279 \SpecialChar ~
8280 \SpecialChar ~
8281 \SpecialChar ~
8282 \SpecialChar ~
8283 \SpecialChar ~
8284 clr a
8285 \newline
8286 93\SpecialChar ~
8287 \SpecialChar ~
8288 \SpecialChar ~
8289 \SpecialChar ~
8290 \SpecialChar ~
8291 \SpecialChar ~
8292 \SpecialChar ~
8293 \SpecialChar ~
8294 \SpecialChar ~
8295 movc a,@a+dptr
8296 \layout Standard
8297
8298
8299 \family typewriter
8300 char
8301 \family default
8302  indexed arrays of characters in code memory can be accessed efficiently:
8303 \layout Verse
8304
8305
8306 \family typewriter
8307 code char test_array[] = {'c','h','e','a','p'};
8308 \layout Standard
8309
8310 Read access to this array using an 8-bit unsigned index generates the assembly
8311  code:
8312 \layout Verse
8313
8314
8315 \family typewriter
8316 E5*00\SpecialChar ~
8317 \SpecialChar ~
8318 \SpecialChar ~
8319 \SpecialChar ~
8320 \SpecialChar ~
8321 \SpecialChar ~
8322 mov a,_index
8323 \layout Verse
8324
8325
8326 \family typewriter
8327 90s00r41\SpecialChar ~
8328 \SpecialChar ~
8329 \SpecialChar ~
8330 mov dptr,#_test_array
8331 \layout Verse
8332
8333
8334 \family typewriter
8335 93\SpecialChar ~
8336 \SpecialChar ~
8337 \SpecialChar ~
8338 \SpecialChar ~
8339 \SpecialChar ~
8340 \SpecialChar ~
8341 \SpecialChar ~
8342 \SpecialChar ~
8343 \SpecialChar ~
8344 movc a,@a+dptr
8345 \layout Subsubsection
8346
8347 bit
8348 \begin_inset LatexCommand \index{bit}
8349
8350 \end_inset
8351
8352
8353 \layout Standard
8354
8355 This is a data-type and a storage class specifier.
8356  When a variable is declared as a bit, it is allocated into the bit addressable
8357  memory of 8051, e.g.:
8358 \layout Verse
8359
8360
8361 \family typewriter
8362 bit test_bit;
8363 \layout Standard
8364
8365 Writing 1 to this variable generates the assembly code:
8366 \layout Verse
8367
8368
8369 \family typewriter
8370 D2*00\SpecialChar ~
8371 \SpecialChar ~
8372 \SpecialChar ~
8373 \SpecialChar ~
8374 \SpecialChar ~
8375 \SpecialChar ~
8376 \SpecialChar ~
8377 setb\SpecialChar ~
8378 _test_bit
8379 \layout Standard
8380
8381 The bit addressable memory consists of 128 bits which are located from 0x20
8382  to 0x2f in data memory.
8383
8384 \newline
8385 Apart from this 8051 specific storage class most architectures support ANSI-C
8386  bitfields
8387 \begin_inset LatexCommand \index{bitfields}
8388
8389 \end_inset
8390
8391
8392 \begin_inset Foot
8393 collapsed false
8394
8395 \layout Standard
8396
8397 Not really meant as examples, but nevertheless showing what bitfields are
8398  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8399 \end_inset
8400
8401 .
8402  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
8403  signed modifier are implemented as unsigned.
8404 \layout Subsubsection
8405
8406 sfr
8407 \begin_inset LatexCommand \index{sfr}
8408
8409 \end_inset
8410
8411  / sbit
8412 \begin_inset LatexCommand \index{sbit}
8413
8414 \end_inset
8415
8416
8417 \layout Standard
8418
8419 Like the bit keyword,
8420 \emph on
8421 sfr / sbit
8422 \emph default
8423 signifies both a data-type and storage class, they are used to describe
8424  the
8425 \emph on
8426 s
8427 \emph default
8428 pecial
8429 \emph on
8430 f
8431 \emph default
8432 unction
8433 \emph on
8434 r
8435 \emph default
8436 egisters and
8437 \emph on
8438 s
8439 \emph default
8440 pecial
8441 \emph on
8442 bit
8443 \emph default
8444  variables of a 8051, eg:
8445 \layout Verse
8446
8447
8448 \family typewriter
8449 sfr at
8450 \begin_inset LatexCommand \index{at}
8451
8452 \end_inset
8453
8454  0x80 P0;\SpecialChar ~
8455  /* special function register P0 at location 0x80 */
8456 \newline
8457 sbit at 0xd7 CY; /* CY (Carry Flag
8458 \begin_inset LatexCommand \index{Flags}
8459
8460 \end_inset
8461
8462
8463 \begin_inset LatexCommand \index{Carry flag}
8464
8465 \end_inset
8466
8467 ) */
8468 \layout Standard
8469
8470 Special function registers which are located on an address dividable by
8471  8 are bit-addressable, an
8472 \emph on
8473  sbit
8474 \emph default
8475  addresses a specific bit within these sfr.
8476 \layout Subsubsection
8477
8478 Pointers
8479 \begin_inset LatexCommand \index{Pointer}
8480
8481 \end_inset
8482
8483  to MCS51/DS390 specific memory spaces
8484 \layout Standard
8485
8486 SDCC allows (via language extensions) pointers to explicitly point to any
8487  of the memory spaces
8488 \begin_inset LatexCommand \index{Memory model}
8489
8490 \end_inset
8491
8492  of the 8051.
8493  In addition to the explicit pointers, the compiler uses (by default) generic
8494  pointers which can be used to point to any of the memory spaces.
8495 \newline
8496
8497 \newline
8498 Pointer declaration examples:
8499 \layout Verse
8500
8501
8502 \family typewriter
8503 /* pointer physically in internal ram pointing to object in external ram
8504  */
8505 \newline
8506 xdata unsigned char * data p;
8507 \newline
8508
8509 \newline
8510 /* pointer physically in external ram pointing to object in internal ram
8511  */
8512 \newline
8513 data unsigned char * xdata p;
8514 \newline
8515
8516 \newline
8517 /* pointer physically in code rom pointing to data in xdata space */
8518 \newline
8519 xdata unsigned char * code p;
8520 \newline
8521
8522 \newline
8523 /* pointer physically in code space pointing to data in code space */
8524 \newline
8525 code unsigned char * code p;
8526 \newline
8527
8528 \newline
8529 /* the following is a generic pointer physically located in xdata space
8530  */
8531 \newline
8532 char * xdata p;
8533 \layout Standard
8534
8535 Well you get the idea.
8536
8537 \newline
8538
8539 \newline
8540 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
8541 \emph on
8542 generic
8543 \emph default
8544  pointers.
8545
8546 \size small
8547
8548 \newline
8549
8550 \newline
8551
8552 \size default
8553 The highest order byte of the
8554 \emph on
8555 generic
8556 \emph default
8557  pointers contains the data space information.
8558  Assembler support routines are called whenever data is stored or retrieved
8559  using
8560 \emph on
8561 generic
8562 \emph default
8563  pointers.
8564  These are useful for developing reusable library
8565 \begin_inset LatexCommand \index{Libraries}
8566
8567 \end_inset
8568
8569  routines.
8570  Explicitly specifying the pointer type will generate the most efficient
8571  code.
8572 \layout Subsubsection
8573
8574 Notes on MCS51 memory
8575 \begin_inset LatexCommand \index{MCS51 memory}
8576
8577 \end_inset
8578
8579  layout
8580 \layout Standard
8581
8582 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
8583  RAM memory which is structured as follows:
8584 \newline
8585
8586 \newline
8587 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
8588
8589 \newline
8590 - Bytes 20-2F - 16 bytes to hold 128 bit
8591 \begin_inset LatexCommand \index{bit}
8592
8593 \end_inset
8594
8595  variables and,
8596 \newline
8597 - Bytes 30-7F - 80 bytes for general purpose use.
8598 \newline
8599
8600 \layout Standard
8601
8602 Additionally some members of the MCS51 family may have up to 128 bytes of
8603  additional, indirectly addressable, internal RAM memory (
8604 \emph on
8605 idata
8606 \emph default
8607
8608 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8609
8610 \end_inset
8611
8612 ).
8613  Furthermore, some chips may have some built in external memory (
8614 \emph on
8615 xdata
8616 \emph default
8617
8618 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8619
8620 \end_inset
8621
8622 ) which should not be confused with the internal, directly addressable RAM
8623  memory (
8624 \emph on
8625 data
8626 \emph default
8627
8628 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8629
8630 \end_inset
8631
8632 ).
8633  Sometimes this built in
8634 \emph on
8635 xdata
8636 \emph default
8637  memory has to be activated before using it (you can probably find this
8638  information on the datasheet of the microcontroller your are using, see
8639  also section
8640 \begin_inset LatexCommand \ref{sub:Startup-Code}
8641
8642 \end_inset
8643
8644 \SpecialChar ~
8645 Startup-Code).
8646 \layout Standard
8647
8648 Normally SDCC will only use the first bank
8649 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
8650
8651 \end_inset
8652
8653  of registers (register bank 0), but it is possible to specify that other
8654  banks of registers should be used in interrupt
8655 \begin_inset LatexCommand \index{interrupt}
8656
8657 \end_inset
8658
8659  routines.
8660  By default, the compiler will place the stack after the last byte of allocated
8661  memory for variables.
8662  For example, if the first 2 banks of registers are used, and only four
8663  bytes are used for
8664 \emph on
8665 data
8666 \emph default
8667  variables, it will position the base of the internal stack at address 20
8668  (0x14).
8669  This implies that as the stack
8670 \begin_inset LatexCommand \index{stack}
8671
8672 \end_inset
8673
8674  grows, it will use up the remaining register banks, and the 16 bytes used
8675  by the 128 bit variables, and 80 bytes for general purpose use.
8676  If any bit variables are used, the data variables will be placed after
8677  the byte holding the last bit variable.
8678  For example, if register banks 0 and 1 are used, and there are 9 bit variables
8679  (two bytes used),
8680 \emph on
8681 data
8682 \emph default
8683  variables will be placed starting at address 0x22.
8684  You can also use -
8685 \begin_inset ERT
8686 status Collapsed
8687
8688 \layout Standard
8689
8690 \backslash
8691 /
8692 \end_inset
8693
8694 -data-loc
8695 \begin_inset LatexCommand \index{-\/-data-loc<Value>}
8696
8697 \end_inset
8698
8699  to specify the start address of the
8700 \emph on
8701 data
8702 \emph default
8703  and -
8704 \begin_inset ERT
8705 status Collapsed
8706
8707 \layout Standard
8708
8709 \backslash
8710 /
8711 \end_inset
8712
8713 -iram-size to specify the size of the total internal RAM (
8714 \emph on
8715 data
8716 \emph default
8717 +
8718 \emph on
8719 idata
8720 \emph default
8721 ).
8722
8723 \layout Standard
8724
8725 By default the 8051 linker will place the stack after the last byte of data
8726  variables.
8727  Option -
8728 \begin_inset ERT
8729 status Collapsed
8730
8731 \layout Standard
8732
8733 \backslash
8734 /
8735 \end_inset
8736
8737 -stack-loc
8738 \begin_inset LatexCommand \index{-\/-stack-loc<Value>}
8739
8740 \end_inset
8741
8742  allows you to specify the start of the stack, i.e.
8743  you could start it after any data in the general purpose area.
8744  If your microcontroller has additional indirectly addressable internal
8745  RAM (
8746 \emph on
8747 idata
8748 \emph default
8749 ) you can place the stack on it.
8750  You may also need to use -
8751 \begin_inset ERT
8752 status Collapsed
8753
8754 \layout Standard
8755
8756 \backslash
8757 /
8758 \end_inset
8759
8760 -xdata-loc
8761 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
8762
8763 \end_inset
8764
8765  to set the start address of the external RAM (
8766 \emph on
8767 xdata
8768 \emph default
8769 ) and -
8770 \begin_inset ERT
8771 status Collapsed
8772
8773 \layout Standard
8774
8775 \backslash
8776 /
8777 \end_inset
8778
8779 -xram-size
8780 \begin_inset LatexCommand \index{-\/-data-loc}
8781
8782 \end_inset
8783
8784  to specify its size.
8785  Same goes for the code memory, using -
8786 \begin_inset ERT
8787 status Collapsed
8788
8789 \layout Standard
8790
8791 \backslash
8792 /
8793 \end_inset
8794
8795 -code-loc
8796 \begin_inset LatexCommand \index{-\/-data-loc}
8797
8798 \end_inset
8799
8800  and -
8801 \begin_inset ERT
8802 status Collapsed
8803
8804 \layout Standard
8805
8806 \backslash
8807 /
8808 \end_inset
8809
8810 -code-size
8811 \begin_inset LatexCommand \index{-\/-data-loc}
8812
8813 \end_inset
8814
8815 .
8816  If in doubt, don't specify any options and see if the resulting memory
8817  layout is appropriate, then you can adjust it.
8818 \layout Standard
8819
8820 The linker generates two files with memory allocation information.
8821  The first, with extension .map
8822 \begin_inset LatexCommand \index{<file>.map}
8823
8824 \end_inset
8825
8826  shows all the variables and segments.
8827  The second with extension .mem
8828 \begin_inset LatexCommand \index{<file>.mem}
8829
8830 \end_inset
8831
8832  shows the final memory layout.
8833  The linker will complain either if memory segments overlap, there is not
8834  enough memory, or there is not enough space for stack.
8835  If you get any linking warnings and/or errors related to stack or segments
8836  allocation, take a look at either the .map or .mem files to find out what
8837  the problem is.
8838  The .mem file may even suggest a solution to the problem.
8839 \layout Subsection
8840
8841 Z80/Z180 Storage Class
8842 \begin_inset LatexCommand \index{Storage class}
8843
8844 \end_inset
8845
8846  Language Extensions
8847 \layout Subsubsection
8848
8849 sfr
8850 \begin_inset LatexCommand \index{sfr}
8851
8852 \end_inset
8853
8854  (in/out to 8-bit addresses)
8855 \layout Standard
8856
8857 The Z80
8858 \begin_inset LatexCommand \index{Z80}
8859
8860 \end_inset
8861
8862  family has separate address spaces for memory and
8863 \emph on
8864 i
8865 \emph default
8866 nput/
8867 \emph on
8868 o
8869 \emph default
8870 utput memory.
8871  I/O memory
8872 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
8873
8874 \end_inset
8875
8876  is accessed with special instructions, e.g.:
8877 \layout Verse
8878
8879
8880 \family typewriter
8881 sfr at 0x78 IoPort;\SpecialChar ~
8882 \SpecialChar ~
8883 /* define a var in I/O space at 78h called IoPort */
8884
8885 \layout Standard
8886
8887 Writing 0x01 to this variable generates the assembly code:
8888 \layout Verse
8889
8890
8891 \family typewriter
8892 3E 01\SpecialChar ~
8893 \SpecialChar ~
8894 \SpecialChar ~
8895 \SpecialChar ~
8896 \SpecialChar ~
8897 \SpecialChar ~
8898 ld a,#0x01
8899 \newline
8900 D3 78\SpecialChar ~
8901 \SpecialChar ~
8902 \SpecialChar ~
8903 \SpecialChar ~
8904 \SpecialChar ~
8905 \SpecialChar ~
8906 out (_IoPort),a
8907 \layout Subsubsection
8908
8909 banked sfr
8910 \begin_inset LatexCommand \index{sfr}
8911
8912 \end_inset
8913
8914  (in/out to 16-bit addresses)
8915 \layout Standard
8916
8917 The keyword
8918 \emph on
8919 banked
8920 \emph default
8921  is used to support 16 bit addresses in I/O memory e.g.:
8922 \layout Verse
8923
8924
8925 \family typewriter
8926 sfr banked at
8927 \begin_inset LatexCommand \index{at}
8928
8929 \end_inset
8930
8931  0x123 IoPort;
8932 \layout Standard
8933
8934 Writing 0x01 to this variable generates the assembly code:
8935 \layout Verse
8936
8937
8938 \family typewriter
8939 01 23 01\SpecialChar ~
8940 \SpecialChar ~
8941 \SpecialChar ~
8942 ld bc,#_IoPort
8943 \newline
8944 3E 01\SpecialChar ~
8945 \SpecialChar ~
8946 \SpecialChar ~
8947 \SpecialChar ~
8948 \SpecialChar ~
8949 \SpecialChar ~
8950 ld a,#0x01
8951 \newline
8952 ED 79\SpecialChar ~
8953 \SpecialChar ~
8954 \SpecialChar ~
8955 \SpecialChar ~
8956 \SpecialChar ~
8957 \SpecialChar ~
8958 out (c),a
8959 \layout Subsubsection
8960
8961 sfr
8962 \begin_inset LatexCommand \index{sfr}
8963
8964 \end_inset
8965
8966  (in0/out0 to 8 bit addresses on Z180
8967 \begin_inset LatexCommand \index{Z180}
8968
8969 \end_inset
8970
8971 /HD64180
8972 \begin_inset LatexCommand \index{HD64180}
8973
8974 \end_inset
8975
8976 )
8977 \layout Standard
8978
8979 The compiler option -
8980 \begin_inset ERT
8981 status Collapsed
8982
8983 \layout Standard
8984
8985 \backslash
8986 /
8987 \end_inset
8988
8989 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
8990 portmode
8991 \begin_inset LatexCommand \index{\#pragma portmode}
8992
8993 \end_inset
8994
8995 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
8996 ns
8997 \family typewriter
8998 in0/out0
8999 \family default
9000  instead of
9001 \family typewriter
9002 in/out
9003 \family default
9004 .
9005  If you include the file z180.h this will be set automatically.
9006 \layout Subsection
9007
9008 HC08 Storage Class
9009 \begin_inset LatexCommand \index{Storage class}
9010
9011 \end_inset
9012
9013  Language Extensions
9014 \layout Subsubsection
9015
9016 data
9017 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9018
9019 \end_inset
9020
9021
9022 \layout Standard
9023
9024 The data storage class declares a variable that resides in the first 256
9025  bytes of memory (the direct page).
9026  The HC08 is most efficient at accessing variables (especially pointers)
9027  stored here.
9028 \layout Subsubsection
9029
9030 xdata
9031 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9032
9033 \end_inset
9034
9035
9036 \layout Standard
9037
9038 The xdata storage class declares a variable that can reside anywhere in
9039  memory.
9040  This is the default if no storage class is specified.
9041
9042 \layout Section
9043
9044 Absolute Addressing
9045 \begin_inset LatexCommand \index{Absolute addressing}
9046
9047 \end_inset
9048
9049
9050 \layout Standard
9051
9052 Data items can be assigned an absolute address with the
9053 \emph on
9054 at
9055 \begin_inset LatexCommand \index{at}
9056
9057 \end_inset
9058
9059  <address>
9060 \emph default
9061  keyword, in addition to a storage class, e.g.:
9062 \layout Verse
9063
9064
9065 \family typewriter
9066 xdata
9067 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9068
9069 \end_inset
9070
9071  at
9072 \begin_inset LatexCommand \index{at}
9073
9074 \end_inset
9075
9076  0x7ffe unsigned int chksum;
9077 \layout Standard
9078
9079 In the above example the variable chksum will located at 0x7ffe and 0x7fff
9080  of the external ram.
9081  The compiler does
9082 \emph on
9083 not
9084 \emph default
9085  reserve any space for variables declared in this way (they are implemented
9086  with an equate in the assembler).
9087  Thus it is left to the programmer to make sure there are no overlaps with
9088  other variables that are declared without the absolute address.
9089  The assembler listing file (.lst
9090 \begin_inset LatexCommand \index{<file>.lst}
9091
9092 \end_inset
9093
9094 ) and the linker output files (.rst
9095 \begin_inset LatexCommand \index{<file>.rst}
9096
9097 \end_inset
9098
9099 ) and (.map
9100 \begin_inset LatexCommand \index{<file>.map}
9101
9102 \end_inset
9103
9104 ) are good places to look for such overlaps.
9105  Variables with an absolute address are
9106 \emph on
9107 not
9108 \emph default
9109  initialized
9110 \begin_inset LatexCommand \index{Variable initialization}
9111
9112 \end_inset
9113
9114 .
9115 \layout Standard
9116
9117 In case of memory mapped I/O devices the keyword
9118 \emph on
9119 volatile
9120 \emph default
9121  have to be used to tell the compiler that accesses might not be optimized
9122  away:
9123 \layout Verse
9124
9125
9126 \family typewriter
9127 volatile
9128 \begin_inset LatexCommand \index{volatile}
9129
9130 \end_inset
9131
9132  xdata
9133 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9134
9135 \end_inset
9136
9137  at
9138 \begin_inset LatexCommand \index{at}
9139
9140 \end_inset
9141
9142  0x8000 unsigned char PORTA_8255;
9143 \layout Standard
9144
9145 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9146 r) array
9147 \family typewriter
9148 \size footnotesize
9149
9150 \begin_inset LatexCommand \index{Aligned array}
9151
9152 \end_inset
9153
9154
9155 \family default
9156 \size default
9157  starts at a block (256 byte) boundary
9158 \begin_inset LatexCommand \index{block boundary}
9159
9160 \end_inset
9161
9162  (section
9163 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9164
9165 \end_inset
9166
9167  has an example).
9168 \newline
9169 Absolute addresses can be specified for variables in all storage classes,
9170  e.g.:
9171 \layout Verse
9172
9173
9174 \family typewriter
9175 bit
9176 \begin_inset LatexCommand \index{bit}
9177
9178 \end_inset
9179
9180  at
9181 \begin_inset LatexCommand \index{at}
9182
9183 \end_inset
9184
9185  0x02 bvar;
9186 \layout Standard
9187
9188 The above example will allocate the variable at offset 0x02 in the bit-addressab
9189 le space.
9190  There is no real advantage to assigning absolute addresses to variables
9191  in this manner, unless you want strict control over all the variables allocated.
9192  One possible use would be to write hardware portable code.
9193  For example, if you have a routine that uses one or more of the microcontroller
9194  I/O pins, and such pins are different for two different hardwares, you
9195  can declare the I/O pins in your routine using:
9196 \layout Verse
9197
9198
9199 \family typewriter
9200 extern volatile bit SDI;
9201 \newline
9202 extern volatile bit SCLK;
9203 \newline
9204 extern volatile bit CPOL;
9205 \newline
9206
9207 \newline
9208 void DS1306_put(unsigned char value)
9209 \newline
9210 {
9211 \newline
9212 \SpecialChar ~
9213 \SpecialChar ~
9214 \SpecialChar ~
9215 \SpecialChar ~
9216 unsigned char mask=0x80;
9217 \newline
9218
9219 \newline
9220 \SpecialChar ~
9221 \SpecialChar ~
9222 \SpecialChar ~
9223 \SpecialChar ~
9224 while(mask)
9225 \newline
9226 \SpecialChar ~
9227 \SpecialChar ~
9228 \SpecialChar ~
9229 \SpecialChar ~
9230 {
9231 \newline
9232 \SpecialChar ~
9233 \SpecialChar ~
9234 \SpecialChar ~
9235 \SpecialChar ~
9236 \SpecialChar ~
9237 \SpecialChar ~
9238 \SpecialChar ~
9239 \SpecialChar ~
9240 SDI=(value & mask)?1:0;
9241 \newline
9242 \SpecialChar ~
9243 \SpecialChar ~
9244 \SpecialChar ~
9245 \SpecialChar ~
9246 \SpecialChar ~
9247 \SpecialChar ~
9248 \SpecialChar ~
9249 \SpecialChar ~
9250 SCLK=!CPOL;
9251 \newline
9252 \SpecialChar ~
9253 \SpecialChar ~
9254 \SpecialChar ~
9255 \SpecialChar ~
9256 \SpecialChar ~
9257 \SpecialChar ~
9258 \SpecialChar ~
9259 \SpecialChar ~
9260 SCLK=CPOL;
9261 \newline
9262 \SpecialChar ~
9263 \SpecialChar ~
9264 \SpecialChar ~
9265 \SpecialChar ~
9266 \SpecialChar ~
9267 \SpecialChar ~
9268 \SpecialChar ~
9269 \SpecialChar ~
9270 mask/=2;
9271 \newline
9272 \SpecialChar ~
9273 \SpecialChar ~
9274 \SpecialChar ~
9275 \SpecialChar ~
9276 }
9277 \newline
9278 }
9279 \layout Standard
9280
9281 Then, someplace in the code for the first hardware you would use
9282 \layout Verse
9283
9284
9285 \family typewriter
9286 bit at 0x80 SDI;\SpecialChar ~
9287 \SpecialChar ~
9288 \SpecialChar ~
9289 \SpecialChar ~
9290 /* I/O port 0, bit 0 */
9291 \newline
9292 bit at 0x81 SCLK;\SpecialChar ~
9293 \SpecialChar ~
9294 \SpecialChar ~
9295 /* I/O port 0, bit 1 */
9296 \newline
9297 bit CPOL;\SpecialChar ~
9298 \SpecialChar ~
9299 \SpecialChar ~
9300 \SpecialChar ~
9301 \SpecialChar ~
9302 \SpecialChar ~
9303 \SpecialChar ~
9304 \SpecialChar ~
9305 \SpecialChar ~
9306 \SpecialChar ~
9307 \SpecialChar ~
9308 /* This is a variable, let the linker allocate this one */
9309 \layout Standard
9310
9311 Similarly, for the second hardware you would use
9312 \layout Verse
9313
9314
9315 \family typewriter
9316 bit at 0x83 SDI;\SpecialChar ~
9317 \SpecialChar ~
9318 \SpecialChar ~
9319 \SpecialChar ~
9320 /* I/O port 0, bit 3 */
9321 \newline
9322 bit at 0x91 SCLK;\SpecialChar ~
9323 \SpecialChar ~
9324 \SpecialChar ~
9325 /* I/O port 1, bit 1 */
9326 \newline
9327 bit
9328 \begin_inset LatexCommand \index{bit}
9329
9330 \end_inset
9331
9332  CPOL;\SpecialChar ~
9333 \SpecialChar ~
9334 \SpecialChar ~
9335 \SpecialChar ~
9336 \SpecialChar ~
9337 \SpecialChar ~
9338 \SpecialChar ~
9339 \SpecialChar ~
9340 \SpecialChar ~
9341 \SpecialChar ~
9342 \SpecialChar ~
9343 /* This is a variable, let the linker allocate this one */
9344 \layout Standard
9345
9346 and you can use the same hardware dependent routine without changes, as
9347  for example in a library.
9348  This is somehow similar to sbit, but only one absolute address has to be
9349  specified in the whole project.
9350 \layout Section
9351
9352 Parameters
9353 \begin_inset LatexCommand \index{Parameters}
9354
9355 \end_inset
9356
9357
9358 \begin_inset LatexCommand \index{function parameter}
9359
9360 \end_inset
9361
9362  & Local Variables
9363 \begin_inset LatexCommand \index{local variables}
9364
9365 \end_inset
9366
9367
9368 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
9369
9370 \end_inset
9371
9372
9373 \layout Standard
9374
9375 Automatic (local) variables and parameters to functions can either be placed
9376  on the stack or in data-space.
9377  The default action of the compiler is to place these variables in the internal
9378  RAM (for small model) or external RAM (for large model).
9379  This in fact makes them similar to
9380 \emph on
9381 static
9382 \begin_inset LatexCommand \index{static}
9383
9384 \end_inset
9385
9386
9387 \emph default
9388  so by default functions are non-reentrant
9389 \begin_inset LatexCommand \index{reentrant}
9390
9391 \end_inset
9392
9393 .
9394
9395 \newline
9396
9397 \newline
9398 They can be placed on the stack
9399 \begin_inset LatexCommand \index{stack}
9400
9401 \end_inset
9402
9403  by using the
9404 \emph on
9405  -
9406 \begin_inset ERT
9407 status Collapsed
9408
9409 \layout Standard
9410
9411 \backslash
9412 /
9413 \end_inset
9414
9415 -stack-auto
9416 \begin_inset LatexCommand \index{-\/-stack-auto}
9417
9418 \end_inset
9419
9420
9421 \emph default
9422  option, by using
9423 \emph on
9424 #pragma\SpecialChar ~
9425 stackauto
9426 \emph default
9427
9428 \begin_inset LatexCommand \index{\#pragma stackauto}
9429
9430 \end_inset
9431
9432  or by using the
9433 \emph on
9434 reentrant
9435 \begin_inset LatexCommand \index{reentrant}
9436
9437 \end_inset
9438
9439
9440 \emph default
9441  keyword in the function declaration, e.g.:
9442 \layout Verse
9443
9444
9445 \family typewriter
9446 unsigned char foo(char i) reentrant
9447 \newline
9448 {
9449 \newline
9450 \SpecialChar ~
9451 \SpecialChar ~
9452 \SpecialChar ~
9453 \SpecialChar ~
9454 ...
9455
9456 \newline
9457 }
9458 \layout Standard
9459
9460 Since stack space on 8051 is limited, the
9461 \emph on
9462 reentrant
9463 \emph default
9464 keyword or the
9465 \emph on
9466  -
9467 \begin_inset ERT
9468 status Collapsed
9469
9470 \layout Standard
9471
9472 \backslash
9473 /
9474 \end_inset
9475
9476 -stack-auto
9477 \emph default
9478  option should be used sparingly.
9479  Note that the reentrant keyword just means that the parameters & local
9480  variables will be allocated to the stack, it
9481 \emph on
9482 does not
9483 \emph default
9484  mean that the function is register bank
9485 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9486
9487 \end_inset
9488
9489  independent.
9490 \newline
9491
9492 \newline
9493 Local variables
9494 \begin_inset LatexCommand \index{local variables}
9495
9496 \end_inset
9497
9498  can be assigned storage classes and absolute
9499 \begin_inset LatexCommand \index{Absolute addressing}
9500
9501 \end_inset
9502
9503  addresses, e.g.:
9504 \layout Verse
9505
9506
9507 \family typewriter
9508 unsigned char foo()
9509 \newline
9510 {
9511 \newline
9512 \SpecialChar ~
9513 \SpecialChar ~
9514 \SpecialChar ~
9515 \SpecialChar ~
9516 xdata unsigned char i;
9517 \newline
9518 \SpecialChar ~
9519 \SpecialChar ~
9520 \SpecialChar ~
9521 \SpecialChar ~
9522 bit bvar;
9523 \newline
9524 \SpecialChar ~
9525 \SpecialChar ~
9526 \SpecialChar ~
9527 \SpecialChar ~
9528 data at
9529 \begin_inset LatexCommand \index{at}
9530
9531 \end_inset
9532
9533  0x31 unsigned char j;
9534 \newline
9535 \SpecialChar ~
9536 \SpecialChar ~
9537 \SpecialChar ~
9538 \SpecialChar ~
9539 ...
9540
9541 \newline
9542 }
9543 \layout Standard
9544
9545 In the above example the variable
9546 \emph on
9547 i
9548 \emph default
9549  will be allocated in the external ram,
9550 \emph on
9551 bvar
9552 \emph default
9553  in bit addressable space and
9554 \emph on
9555  j
9556 \emph default
9557  in internal ram.
9558  When compiled with
9559 \emph on
9560 -
9561 \begin_inset ERT
9562 status Collapsed
9563
9564 \layout Standard
9565
9566 \backslash
9567 /
9568 \end_inset
9569
9570 -stack-auto
9571 \emph default
9572  or when a function is declared as
9573 \emph on
9574 reentrant
9575 \emph default
9576  this should only be done for static variables.
9577 \layout Standard
9578
9579 Parameters
9580 \begin_inset LatexCommand \index{function parameter}
9581
9582 \end_inset
9583
9584  however are not allowed any storage class
9585 \begin_inset LatexCommand \index{Storage class}
9586
9587 \end_inset
9588
9589 , (storage classes for parameters will be ignored), their allocation is
9590  governed by the memory model in use, and the reentrancy options.
9591 \layout Section
9592
9593 Overlaying
9594 \begin_inset LatexCommand \label{sub:Overlaying}
9595
9596 \end_inset
9597
9598
9599 \begin_inset LatexCommand \index{Overlaying}
9600
9601 \end_inset
9602
9603
9604 \layout Standard
9605
9606 For non-reentrant
9607 \begin_inset LatexCommand \index{reentrant}
9608
9609 \end_inset
9610
9611  functions SDCC will try to reduce internal ram space usage by overlaying
9612  parameters and local variables of a function (if possible).
9613  Parameters and local variables
9614 \begin_inset LatexCommand \index{local variables}
9615
9616 \end_inset
9617
9618  of a function will be allocated to an overlayable segment if the function
9619  has
9620 \emph on
9621 no other function calls and the function is non-reentrant and the memory
9622  model
9623 \begin_inset LatexCommand \index{Memory model}
9624
9625 \end_inset
9626
9627  is small.
9628
9629 \emph default
9630  If an explicit storage class
9631 \begin_inset LatexCommand \index{Storage class}
9632
9633 \end_inset
9634
9635  is specified for a local variable, it will NOT be overlayed.
9636 \layout Standard
9637
9638 Note that the compiler (not the linkage editor) makes the decision for overlayin
9639 g the data items.
9640  Functions that are called from an interrupt service routine should be preceded
9641  by a #pragma\SpecialChar ~
9642 nooverlay
9643 \begin_inset LatexCommand \index{\#pragma nooverlay}
9644
9645 \end_inset
9646
9647  if they are not reentrant.
9648 \layout Standard
9649
9650 Also note that the compiler does not do any processing of inline assembler
9651  code, so the compiler might incorrectly assign local variables and parameters
9652  of a function into the overlay segment if the inline assembler code calls
9653  other c-functions that might use the overlay.
9654  In that case the #pragma\SpecialChar ~
9655 nooverlay should be used.
9656 \layout Standard
9657
9658 Parameters and local variables of functions that contain 16 or 32 bit multiplica
9659 tion
9660 \begin_inset LatexCommand \index{Multiplication}
9661
9662 \end_inset
9663
9664  or division
9665 \begin_inset LatexCommand \index{Division}
9666
9667 \end_inset
9668
9669  will NOT be overlayed since these are implemented using external functions,
9670  e.g.:
9671 \layout Verse
9672
9673
9674 \family typewriter
9675 #pragma save
9676 \newline
9677 #pragma nooverlay
9678 \begin_inset LatexCommand \index{\#pragma nooverlay}
9679
9680 \end_inset
9681
9682
9683 \newline
9684 void set_error(unsigned char errcd)
9685 \newline
9686 {
9687 \newline
9688 \SpecialChar ~
9689 \SpecialChar ~
9690 \SpecialChar ~
9691 \SpecialChar ~
9692 P3 = errcd;
9693 \newline
9694 }
9695 \newline
9696 #pragma restore
9697 \newline
9698
9699 \newline
9700 void some_isr () interrupt
9701 \begin_inset LatexCommand \index{interrupt}
9702
9703 \end_inset
9704
9705  2
9706 \newline
9707 {
9708 \newline
9709 \SpecialChar ~
9710 \SpecialChar ~
9711 \SpecialChar ~
9712 \SpecialChar ~
9713 ...
9714 \newline
9715 \SpecialChar ~
9716 \SpecialChar ~
9717 \SpecialChar ~
9718 \SpecialChar ~
9719 set_error(10);
9720 \newline
9721 \SpecialChar ~
9722 \SpecialChar ~
9723 \SpecialChar ~
9724 \SpecialChar ~
9725 ...
9726
9727 \newline
9728 }
9729 \layout Standard
9730
9731 In the above example the parameter
9732 \emph on
9733 errcd
9734 \emph default
9735  for the function
9736 \emph on
9737 set_error
9738 \emph default
9739  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
9740 nooverlay was
9741  not present, this could cause unpredictable runtime behavior when called
9742  from an interrupt service routine.
9743  The #pragma\SpecialChar ~
9744 nooverlay ensures that the parameters and local variables for
9745  the function are NOT overlayed.
9746 \layout Section
9747
9748 Interrupt Service Routines
9749 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
9750
9751 \end_inset
9752
9753
9754 \layout Subsection
9755
9756 General Information
9757 \layout Standard
9758
9759 SDCC allows
9760 \emph on
9761 i
9762 \emph default
9763 nterrupt
9764 \emph on
9765 s
9766 \emph default
9767 ervice
9768 \emph on
9769 r
9770 \emph default
9771 outines to be coded in C, with some extended keywords.
9772 \layout Verse
9773
9774
9775 \family typewriter
9776 void timer_isr (void) interrupt 1 using 1
9777 \newline
9778 {
9779 \newline
9780 \SpecialChar ~
9781 \SpecialChar ~
9782 \SpecialChar ~
9783 \SpecialChar ~
9784 ...
9785
9786 \newline
9787 }
9788 \layout Standard
9789
9790 The optional number following the
9791 \emph on
9792 interrupt
9793 \begin_inset LatexCommand \index{interrupt}
9794
9795 \end_inset
9796
9797
9798 \emph default
9799  keyword is the interrupt number this routine will service.
9800  When present, the compiler will insert a call to this routine in the interrupt
9801  vector table for the interrupt number specified.
9802  If you have multiple source files in your project, interrupt service routines
9803  can be present in any of them, but a prototype of the isr MUST be present
9804  or included in the file that contains the function
9805 \emph on
9806 main
9807 \emph default
9808 .
9809  The
9810 \emph on
9811 using
9812 \emph default
9813  keyword can be used to tell the compiler to use the specified register
9814  bank (8051 specific) when generating code for this function.
9815
9816 \newline
9817
9818 \layout Standard
9819
9820 Interrupt service routines open the door for some very interesting bugs:
9821 \newline
9822 If an interrupt service routine changes variables which are accessed by
9823  other functions these variables have to be declared
9824 \emph on
9825 volatile
9826 \emph default
9827
9828 \begin_inset LatexCommand \index{volatile}
9829
9830 \end_inset
9831
9832 .
9833
9834 \layout Standard
9835
9836 If the access to these variables is not
9837 \emph on
9838 atomic
9839 \begin_inset LatexCommand \index{atomic access}
9840
9841 \end_inset
9842
9843
9844 \emph default
9845  (i.e.
9846  the processor needs more than one instruction for the access and could
9847  be interrupted while accessing the variable) the interrupt must be disabled
9848  during the access to avoid inconsistent data.
9849  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
9850  and should be protected by disabling interrupts.
9851  You're not automatically on the safe side if you use 8 bit variables though.
9852  We need an example here: f.e.
9853  on the 8051 the harmless looking
9854 \begin_inset Quotes srd
9855 \end_inset
9856
9857
9858 \family typewriter
9859 flags\SpecialChar ~
9860 |=\SpecialChar ~
9861 0x80;
9862 \family default
9863
9864 \begin_inset Quotes sld
9865 \end_inset
9866
9867  is not atomic if
9868 \family typewriter
9869 flags
9870 \family default
9871  resides in xdata.
9872  Setting
9873 \begin_inset Quotes srd
9874 \end_inset
9875
9876
9877 \family typewriter
9878 flags\SpecialChar ~
9879 |=\SpecialChar ~
9880 0x40;
9881 \family default
9882
9883 \begin_inset Quotes sld
9884 \end_inset
9885
9886  from within an interrupt routine might get lost if the interrupt occurs
9887  at the wrong time.
9888
9889 \begin_inset Quotes sld
9890 \end_inset
9891
9892
9893 \family typewriter
9894 counter\SpecialChar ~
9895 +=\SpecialChar ~
9896 8;
9897 \family default
9898
9899 \begin_inset Quotes srd
9900 \end_inset
9901
9902  is not atomic on the 8051 even if
9903 \family typewriter
9904 counter
9905 \family default
9906  is located in data memory.
9907  Bugs like these are hard to reproduce and can cause a lot of trouble.
9908
9909 \layout Standard
9910
9911 The return address and the registers used in the interrupt service routine
9912  are saved on the stack
9913 \begin_inset LatexCommand \index{stack}
9914
9915 \end_inset
9916
9917  so there must be sufficient stack space.
9918  If there isn't variables or registers (or even the return address itself)
9919  will be corrupted.
9920  This
9921 \emph on
9922 stack overflow
9923 \emph default
9924
9925 \begin_inset LatexCommand \index{stack overflow}
9926
9927 \end_inset
9928
9929  is most likely to happen if the interrupt occurs during the
9930 \begin_inset Quotes sld
9931 \end_inset
9932
9933 deepest
9934 \begin_inset Quotes srd
9935 \end_inset
9936
9937  subroutine when the stack is already in use for f.e.
9938  many return addresses.
9939 \layout Standard
9940
9941 A special note here, int (16 bit) and long (32 bit) integer division
9942 \begin_inset LatexCommand \index{Division}
9943
9944 \end_inset
9945
9946 , multiplication
9947 \begin_inset LatexCommand \index{Multiplication}
9948
9949 \end_inset
9950
9951  & modulus
9952 \begin_inset LatexCommand \index{Modulus}
9953
9954 \end_inset
9955
9956  and floating-point
9957 \begin_inset LatexCommand \index{Floating point support}
9958
9959 \end_inset
9960
9961  operations are implemented using external support routines developed in
9962  ANSI-C.
9963  If an interrupt service routine needs to do any of these operations then
9964  the support routines (as mentioned in a following section) will have to
9965  be recompiled using the
9966 \emph on
9967  -
9968 \begin_inset ERT
9969 status Collapsed
9970
9971 \layout Standard
9972
9973 \backslash
9974 /
9975 \end_inset
9976
9977 -stack-auto
9978 \begin_inset LatexCommand \index{-\/-stack-auto}
9979
9980 \end_inset
9981
9982
9983 \emph default
9984  option and the source file will need to be compiled using the
9985 \emph on
9986 -
9987 \begin_inset ERT
9988 status Collapsed
9989
9990 \layout Standard
9991
9992 \backslash
9993 /
9994 \end_inset
9995
9996 -int-long-reent
9997 \emph default
9998
9999 \begin_inset LatexCommand \index{-\/-int-long-reent}
10000
10001 \end_inset
10002
10003  compiler option.
10004 \layout Standard
10005
10006 Calling other functions from an interrupt service routine is not recommended,
10007  avoid it if possible.
10008  Note that when some function is called from an interrupt service routine
10009  it should be preceded by a #pragma\SpecialChar ~
10010 nooverlay
10011 \begin_inset LatexCommand \index{\#pragma nooverlay}
10012
10013 \end_inset
10014
10015  if it is not reentrant.
10016  Furthermore nonreentrant functions should not be called from the main program
10017  while the interrupt service routine might be active.
10018
10019 \newline
10020
10021 \newline
10022 Also see section
10023 \begin_inset LatexCommand \ref{sub:Overlaying}
10024
10025 \end_inset
10026
10027 \SpecialChar ~
10028 about Overlaying and section
10029 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10030
10031 \end_inset
10032
10033 \SpecialChar ~
10034 about Functions using private register banks.
10035 \layout Subsection
10036
10037 MCS51/DS390 Interrupt Service Routines
10038 \layout Standard
10039
10040 Interrupt numbers and the corresponding address & descriptions for the Standard
10041  8051/8052 are listed below.
10042  SDCC will automatically adjust the interrupt vector table to the maximum
10043  interrupt number specified.
10044 \newline
10045
10046 \layout Standard
10047 \align center
10048
10049 \begin_inset  Tabular
10050 <lyxtabular version="3" rows="7" columns="3">
10051 <features>
10052 <column alignment="center" valignment="top" leftline="true" width="0in">
10053 <column alignment="center" valignment="top" leftline="true" width="0in">
10054 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10055 <row topline="true" bottomline="true">
10056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10057 \begin_inset Text
10058
10059 \layout Standard
10060
10061 Interrupt #
10062 \end_inset
10063 </cell>
10064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10065 \begin_inset Text
10066
10067 \layout Standard
10068
10069 Description
10070 \end_inset
10071 </cell>
10072 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10073 \begin_inset Text
10074
10075 \layout Standard
10076
10077 Vector Address
10078 \end_inset
10079 </cell>
10080 </row>
10081 <row topline="true">
10082 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10083 \begin_inset Text
10084
10085 \layout Standard
10086
10087 0
10088 \end_inset
10089 </cell>
10090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10091 \begin_inset Text
10092
10093 \layout Standard
10094
10095 External 0
10096 \end_inset
10097 </cell>
10098 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10099 \begin_inset Text
10100
10101 \layout Standard
10102
10103 0x0003
10104 \end_inset
10105 </cell>
10106 </row>
10107 <row topline="true">
10108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10109 \begin_inset Text
10110
10111 \layout Standard
10112
10113 1
10114 \end_inset
10115 </cell>
10116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10117 \begin_inset Text
10118
10119 \layout Standard
10120
10121 Timer 0
10122 \end_inset
10123 </cell>
10124 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10125 \begin_inset Text
10126
10127 \layout Standard
10128
10129 0x000B
10130 \end_inset
10131 </cell>
10132 </row>
10133 <row topline="true">
10134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10135 \begin_inset Text
10136
10137 \layout Standard
10138
10139 2
10140 \end_inset
10141 </cell>
10142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10143 \begin_inset Text
10144
10145 \layout Standard
10146
10147 External 1
10148 \end_inset
10149 </cell>
10150 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10151 \begin_inset Text
10152
10153 \layout Standard
10154
10155 0x0013
10156 \end_inset
10157 </cell>
10158 </row>
10159 <row topline="true">
10160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10161 \begin_inset Text
10162
10163 \layout Standard
10164
10165 3
10166 \end_inset
10167 </cell>
10168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10169 \begin_inset Text
10170
10171 \layout Standard
10172
10173 Timer 1
10174 \end_inset
10175 </cell>
10176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10177 \begin_inset Text
10178
10179 \layout Standard
10180
10181 0x001B
10182 \end_inset
10183 </cell>
10184 </row>
10185 <row topline="true">
10186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10187 \begin_inset Text
10188
10189 \layout Standard
10190
10191 4
10192 \end_inset
10193 </cell>
10194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10195 \begin_inset Text
10196
10197 \layout Standard
10198
10199 Serial
10200 \end_inset
10201 </cell>
10202 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10203 \begin_inset Text
10204
10205 \layout Standard
10206
10207 0x0023
10208 \end_inset
10209 </cell>
10210 </row>
10211 <row topline="true" bottomline="true">
10212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10213 \begin_inset Text
10214
10215 \layout Standard
10216
10217 5
10218 \end_inset
10219 </cell>
10220 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10221 \begin_inset Text
10222
10223 \layout Standard
10224
10225 Timer 2 (8052)
10226 \end_inset
10227 </cell>
10228 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10229 \begin_inset Text
10230
10231 \layout Standard
10232
10233 0x002B
10234 \end_inset
10235 </cell>
10236 </row>
10237 </lyxtabular>
10238
10239 \end_inset
10240
10241
10242 \newline
10243
10244 \layout Standard
10245
10246 If the interrupt service routine is defined without
10247 \emph on
10248 using
10249 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10250
10251 \end_inset
10252
10253
10254 \emph default
10255  a register bank or with register bank 0 (
10256 \emph on
10257 using
10258 \emph default
10259  0), the compiler will save the registers used by itself on the stack upon
10260  entry and restore them at exit, however if such an interrupt service routine
10261  calls another function then the entire register bank will be saved on the
10262  stack.
10263  This scheme may be advantageous for small interrupt service routines which
10264  have low register usage.
10265 \layout Standard
10266
10267 If the interrupt service routine is defined to be using a specific register
10268  bank then only
10269 \emph on
10270 a, b, dptr
10271 \emph default
10272  & psw are saved and restored, if such an interrupt service routine calls
10273  another function (using another register bank) then the entire register
10274  bank of the called function will be saved on the stack.
10275  This scheme is recommended for larger interrupt service routines.
10276 \layout Subsection
10277
10278 HC08 Interrupt Service Routines
10279 \layout Standard
10280
10281 Since the number of interrupts available is chip specific and the interrupt
10282  vector table always ends at the last byte of memory, the interrupt numbers
10283  corresponds to the interrupt vectors in reverse order of address.
10284  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
10285  2 will use the interrupt vector at 0xfffa, and so on.
10286  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
10287  this way; instead see section
10288 \begin_inset LatexCommand \ref{sub:Startup-Code}
10289
10290 \end_inset
10291
10292  for details on customizing startup.
10293 \layout Section
10294
10295 Enabling and Disabling Interrupts
10296 \layout Subsection
10297
10298 Critical Functions and Critical Statements
10299 \layout Standard
10300
10301 A special keyword may be associated with a block or a function declaring
10302  it as
10303 \emph on
10304 critical
10305 \emph default
10306 .
10307  SDCC will generate code to disable all interrupts
10308 \begin_inset LatexCommand \index{interrupt}
10309
10310 \end_inset
10311
10312  upon entry to a critical function and restore the interrupt enable to the
10313  previous state before returning.
10314  Nesting critical functions will need one additional byte on the stack
10315 \begin_inset LatexCommand \index{stack}
10316
10317 \end_inset
10318
10319  for each call.
10320 \layout Verse
10321
10322
10323 \family typewriter
10324 int foo () critical
10325 \begin_inset LatexCommand \index{critical}
10326
10327 \end_inset
10328
10329
10330 \newline
10331 {
10332 \newline
10333 \SpecialChar ~
10334 \SpecialChar ~
10335 \SpecialChar ~
10336 \SpecialChar ~
10337 ...
10338
10339 \newline
10340 \SpecialChar ~
10341 \SpecialChar ~
10342 \SpecialChar ~
10343 \SpecialChar ~
10344 ...
10345
10346 \newline
10347 }
10348 \layout Standard
10349
10350 The critical attribute maybe used with other attributes like
10351 \emph on
10352 reentrant.
10353 \emph default
10354
10355 \newline
10356 The keyword
10357 \emph on
10358 critical
10359 \emph default
10360  may also be used to disable interrupts more locally:
10361 \layout Verse
10362
10363
10364 \family typewriter
10365 critical{ i++; }
10366 \layout Standard
10367
10368 More than one statement could have been included in the block.
10369 \layout Subsection
10370
10371 Enabling and Disabling Interrupts directly
10372 \layout Standard
10373
10374 Interrupts
10375 \begin_inset LatexCommand \index{interrupt}
10376
10377 \end_inset
10378
10379  can also be disabled and enabled directly (8051):
10380 \layout Verse
10381
10382
10383 \family typewriter
10384 EA = 0;\SpecialChar ~
10385 \SpecialChar ~
10386 \SpecialChar ~
10387 \SpecialChar ~
10388 \SpecialChar ~
10389 \SpecialChar ~
10390 \SpecialChar ~
10391 \SpecialChar ~
10392 \SpecialChar ~
10393 \SpecialChar ~
10394 \SpecialChar ~
10395 \SpecialChar ~
10396 or:\SpecialChar ~
10397 \SpecialChar ~
10398 \SpecialChar ~
10399 \SpecialChar ~
10400 \SpecialChar ~
10401 \SpecialChar ~
10402 \SpecialChar ~
10403 \SpecialChar ~
10404 \SpecialChar ~
10405 \SpecialChar ~
10406 \SpecialChar ~
10407 EA_SAVE = EA;
10408 \layout Verse
10409
10410
10411 \family typewriter
10412 ...\SpecialChar ~
10413 \SpecialChar ~
10414 \SpecialChar ~
10415 \SpecialChar ~
10416 \SpecialChar ~
10417 \SpecialChar ~
10418 \SpecialChar ~
10419 \SpecialChar ~
10420 \SpecialChar ~
10421 \SpecialChar ~
10422 \SpecialChar ~
10423 \SpecialChar ~
10424 \SpecialChar ~
10425 \SpecialChar ~
10426 \SpecialChar ~
10427 \SpecialChar ~
10428 \SpecialChar ~
10429 \SpecialChar ~
10430 \SpecialChar ~
10431 \SpecialChar ~
10432 \SpecialChar ~
10433 \SpecialChar ~
10434 \SpecialChar ~
10435 \SpecialChar ~
10436 \SpecialChar ~
10437 \SpecialChar ~
10438 \SpecialChar ~
10439 \SpecialChar ~
10440 \SpecialChar ~
10441 \SpecialChar ~
10442 EA = 0;
10443 \layout Verse
10444
10445
10446 \family typewriter
10447 EA = 1;\SpecialChar ~
10448 \SpecialChar ~
10449 \SpecialChar ~
10450 \SpecialChar ~
10451 \SpecialChar ~
10452 \SpecialChar ~
10453 \SpecialChar ~
10454 \SpecialChar ~
10455 \SpecialChar ~
10456 \SpecialChar ~
10457 \SpecialChar ~
10458 \SpecialChar ~
10459 \SpecialChar ~
10460 \SpecialChar ~
10461 \SpecialChar ~
10462 \SpecialChar ~
10463 \SpecialChar ~
10464 \SpecialChar ~
10465 \SpecialChar ~
10466 \SpecialChar ~
10467 \SpecialChar ~
10468 \SpecialChar ~
10469 \SpecialChar ~
10470 \SpecialChar ~
10471 \SpecialChar ~
10472 \SpecialChar ~
10473 ...
10474 \layout Verse
10475
10476
10477 \family typewriter
10478 \SpecialChar ~
10479 \SpecialChar ~
10480 \SpecialChar ~
10481 \SpecialChar ~
10482 \SpecialChar ~
10483 \SpecialChar ~
10484 \SpecialChar ~
10485 \SpecialChar ~
10486 \SpecialChar ~
10487 \SpecialChar ~
10488 \SpecialChar ~
10489 \SpecialChar ~
10490 \SpecialChar ~
10491 \SpecialChar ~
10492 \SpecialChar ~
10493 \SpecialChar ~
10494 \SpecialChar ~
10495 \SpecialChar ~
10496 \SpecialChar ~
10497 \SpecialChar ~
10498 \SpecialChar ~
10499 \SpecialChar ~
10500 \SpecialChar ~
10501 \SpecialChar ~
10502 \SpecialChar ~
10503 \SpecialChar ~
10504 \SpecialChar ~
10505 \SpecialChar ~
10506 \SpecialChar ~
10507 \SpecialChar ~
10508 \SpecialChar ~
10509 \SpecialChar ~
10510 \SpecialChar ~
10511 EA = EA_SAVE;
10512 \layout Standard
10513
10514 On other architectures which have seperate opcodes for enabling and disabling
10515  interrupts you might want to make use of defines with inline assembly
10516 \begin_inset LatexCommand \index{Assembler routines}
10517
10518 \end_inset
10519
10520  (HC08):
10521 \layout Verse
10522
10523
10524 \family typewriter
10525 #define CLI _asm
10526 \begin_inset LatexCommand \index{\_asm}
10527
10528 \end_inset
10529
10530 \SpecialChar ~
10531 \SpecialChar ~
10532 cli\SpecialChar ~
10533 \SpecialChar ~
10534 _endasm
10535 \begin_inset LatexCommand \index{\_endasm}
10536
10537 \end_inset
10538
10539 ;
10540 \layout Verse
10541
10542
10543 \family typewriter
10544 #define SEI _asm\SpecialChar ~
10545 \SpecialChar ~
10546 sei\SpecialChar ~
10547 \SpecialChar ~
10548 _endasm;
10549 \layout Verse
10550
10551
10552 \family typewriter
10553 ...
10554 \layout Standard
10555
10556 Note: it is sometimes sufficient to disable only a specific interrupt source
10557  like f.e.
10558  a timer or serial interrupt by manipulating an
10559 \emph on
10560 interrupt mask
10561 \begin_inset LatexCommand \index{interrupt mask}
10562
10563 \end_inset
10564
10565
10566 \emph default
10567  register.
10568
10569 \layout Standard
10570
10571 Usually the time during which interrupts are disabled should be kept as
10572  short as possible.
10573  This minimizes both
10574 \emph on
10575 interrupt latency
10576 \emph default
10577
10578 \begin_inset LatexCommand \index{interrupt latency}
10579
10580 \end_inset
10581
10582  (the time between the occurrence of the interrupt and the execution of
10583  the first code in the interrupt routine) and
10584 \emph on
10585 interrupt jitter
10586 \emph default
10587
10588 \begin_inset LatexCommand \index{interrupt jitter}
10589
10590 \end_inset
10591
10592  (the difference between the shortest and the longest interrupt latency).
10593  These really are something different, f.e.
10594  a serial interrupt has to be served before its buffer overruns so it cares
10595  for the maximum interrupt latency, whereas it does not care about jitter.
10596  On a loudspeaker driven via a digital to analog converter which is fed
10597  by an interrupt a latency of a few milliseconds might be tolerable, whereas
10598  a much smaller jitter will be very audible.
10599 \layout Standard
10600
10601 You can reenable interrupts within an interrupt routine and on some architecture
10602 s you can make use of two (or more) levels of
10603 \emph on
10604 interrupt priorities
10605 \emph default
10606
10607 \begin_inset LatexCommand \index{interrupt priority}
10608
10609 \end_inset
10610
10611 .
10612  On some architectures which don't support interrupt priorities these can
10613  be implemented by manipulating the interrupt mask and reenabling interrupts
10614  within the interrupt routine.
10615  Check there is sufficient space on the stack
10616 \begin_inset LatexCommand \index{stack}
10617
10618 \end_inset
10619
10620  and don't add complexity unless you have to.
10621
10622 \layout Section
10623
10624 Functions using private register banks
10625 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
10626
10627 \end_inset
10628
10629  (mcs51/ds390)
10630 \layout Standard
10631
10632 Some architectures have support for quickly changing register sets.
10633  SDCC supports this feature with the
10634 \emph on
10635 using
10636 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10637
10638 \end_inset
10639
10640
10641 \emph default
10642  attribute (which tells the compiler to use a register bank
10643 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10644
10645 \end_inset
10646
10647  other than the default bank zero).
10648  It should only be applied to
10649 \emph on
10650 interrupt
10651 \begin_inset LatexCommand \index{interrupt}
10652
10653 \end_inset
10654
10655
10656 \emph default
10657  functions (see footnote below).
10658  This will in most circumstances make the generated ISR code more efficient
10659  since it will not have to save registers on the stack.
10660 \layout Standard
10661
10662 The
10663 \emph on
10664 using
10665 \emph default
10666  attribute will have no effect on the generated code for a
10667 \emph on
10668 non-interrupt
10669 \emph default
10670  function (but may occasionally be useful anyway
10671 \begin_inset Foot
10672 collapsed false
10673
10674 \layout Standard
10675
10676 possible exception: if a function is called ONLY from 'interrupt' functions
10677  using a particular bank, it can be declared with the same 'using' attribute
10678  as the calling 'interrupt' functions.
10679  For instance, if you have several ISRs using bank one, and all of them
10680  call memcpy(), it might make sense to create a specialized version of memcpy()
10681  'using 1', since this would prevent the ISR from having to save bank zero
10682  to the stack on entry and switch to bank zero before calling the function
10683 \end_inset
10684
10685 ).
10686 \newline
10687
10688 \emph on
10689 (pending: I don't think this has been done yet)
10690 \layout Standard
10691
10692 An
10693 \emph on
10694 interrupt
10695 \emph default
10696  function using a non-zero bank will assume that it can trash that register
10697  bank, and will not save it.
10698  Since high-priority interrupts
10699 \begin_inset LatexCommand \index{interrupt priority}
10700
10701 \end_inset
10702
10703  can interrupt low-priority ones on the 8051 and friends, this means that
10704  if a high-priority ISR
10705 \emph on
10706 using
10707 \emph default
10708  a particular bank occurs while processing a low-priority ISR
10709 \emph on
10710 using
10711 \emph default
10712  the same bank, terrible and bad things can happen.
10713  To prevent this, no single register bank should be
10714 \emph on
10715 used
10716 \emph default
10717  by both a high priority and a low priority ISR.
10718  This is probably most easily done by having all high priority ISRs use
10719  one bank and all low priority ISRs use another.
10720  If you have an ISR which can change priority at runtime, you're on your
10721  own: I suggest using the default bank zero and taking the small performance
10722  hit.
10723 \layout Standard
10724
10725 It is most efficient if your ISR calls no other functions.
10726  If your ISR must call other functions, it is most efficient if those functions
10727  use the same bank as the ISR (see note 1 below); the next best is if the
10728  called functions use bank zero.
10729  It is very inefficient to call a function using a different, non-zero bank
10730  from an ISR.
10731
10732 \layout Section
10733
10734 Startup Code
10735 \begin_inset LatexCommand \label{sub:Startup-Code}
10736
10737 \end_inset
10738
10739
10740 \begin_inset LatexCommand \index{Startup code}
10741
10742 \end_inset
10743
10744
10745 \layout Subsection
10746
10747 MCS51/DS390 Startup Code
10748 \layout Standard
10749
10750 The compiler inserts a call to the C routine
10751 \emph on
10752 _sdcc_external_startup()
10753 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
10754
10755 \end_inset
10756
10757
10758 \series bold
10759 \emph default
10760
10761 \series default
10762 at the start of the CODE area.
10763  This routine is in the runtime library
10764 \begin_inset LatexCommand \index{Runtime library}
10765
10766 \end_inset
10767
10768 .
10769  By default this routine returns 0, if this routine returns a non-zero value,
10770  the static & global variable initialization will be skipped and the function
10771  main will be invoked.
10772  Otherwise static & global variables will be initialized before the function
10773  main is invoked.
10774  You could add a
10775 \emph on
10776 _sdcc_external_startup()
10777 \emph default
10778  routine to your program to override the default if you need to setup hardware
10779  or perform some other critical operation prior to static & global variable
10780  initialization.
10781  On some mcs51 variants xdata has to be explicitly enabled before it can
10782  be accessed, this is the place to do it.
10783  The startup code clears the complete 256 byte of idata memory, this might
10784  cause problems for 128 byte devices (endless loop reported for Chipcon
10785  CC1010).
10786 \layout Standard
10787
10788 See also the compiler option
10789 \emph on
10790 -
10791 \begin_inset ERT
10792 status Collapsed
10793
10794 \layout Standard
10795
10796 \backslash
10797 /
10798 \end_inset
10799
10800 -no-xinit
10801 \emph default
10802 -
10803 \emph on
10804 opt
10805 \emph default
10806
10807 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
10808
10809 \end_inset
10810
10811  and section
10812 \begin_inset LatexCommand \ref{sub:MCS51-variants}
10813
10814 \end_inset
10815
10816 \SpecialChar ~
10817 about MCS51-variants.
10818 \layout Subsection
10819
10820 HC08 Startup Code
10821 \layout Standard
10822
10823 The HC08 startup code follows the same scheme as the MCS51 startup code.
10824 \layout Subsection
10825
10826 Z80 Startup Code
10827 \layout Standard
10828
10829 On the Z80 the startup code is inserted by linking with crt0.o which is generated
10830  from sdcc/device/lib/z80/crt0.s.
10831  If you need a different startup code you can use the compiler option
10832 \emph on
10833 -
10834 \series bold
10835 \emph default
10836
10837 \begin_inset ERT
10838 status Collapsed
10839
10840 \layout Standard
10841
10842 \backslash
10843 /
10844 \end_inset
10845
10846
10847 \series default
10848 \emph on
10849 -no-std-crt0
10850 \emph default
10851
10852 \begin_inset LatexCommand \index{-\/-no-std-crt0}
10853
10854 \end_inset
10855
10856  and provide your own crt0.o.
10857
10858 \layout Section
10859
10860 Inline Assembler Code
10861 \begin_inset LatexCommand \index{Assembler routines}
10862
10863 \end_inset
10864
10865
10866 \layout Subsection
10867
10868 A Step by Step Introduction
10869 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
10870
10871 \end_inset
10872
10873
10874 \layout Standard
10875
10876 Starting from a small snippet of c-code this example shows for the MCS51
10877  how to use inline assembly, access variables, a function parameter and
10878  an array in xdata memory.
10879  The example uses an MCS51 here but is easily adapted for other architectures.
10880  This is a buffer routine which should be optimized:
10881 \layout Verse
10882
10883
10884 \family typewriter
10885 \size footnotesize
10886 unsigned char far
10887 \begin_inset LatexCommand \index{far (storage class)}
10888
10889 \end_inset
10890
10891  at
10892 \begin_inset LatexCommand \index{at}
10893
10894 \end_inset
10895
10896  0x7f00 buf[0x100];
10897 \begin_inset LatexCommand \index{Aligned array}
10898
10899 \end_inset
10900
10901
10902 \newline
10903 unsigned char head,tail;
10904 \newline
10905
10906 \newline
10907 void to_buffer( unsigned char c )
10908 \newline
10909 {
10910 \newline
10911 \SpecialChar ~
10912 \SpecialChar ~
10913 \SpecialChar ~
10914 \SpecialChar ~
10915 if( head != tail-1 )
10916 \newline
10917 \SpecialChar ~
10918 \SpecialChar ~
10919 \SpecialChar ~
10920 \SpecialChar ~
10921 \SpecialChar ~
10922 \SpecialChar ~
10923 \SpecialChar ~
10924 \SpecialChar ~
10925 buf[ head++ ] = c;\SpecialChar ~
10926 \SpecialChar ~
10927 \SpecialChar ~
10928 \SpecialChar ~
10929 /* access to a 256 byte aligned array */
10930 \newline
10931 }
10932 \layout Standard
10933
10934 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
10935  then a corresponding buffer.asm file is generated.
10936  We define a new function
10937 \family typewriter
10938 to_buffer_asm()
10939 \family default
10940  in file buffer.c in which we cut and paste the generated code, removing
10941  unwanted comments and some ':'.
10942  Then add
10943 \begin_inset Quotes sld
10944 \end_inset
10945
10946 _asm
10947 \begin_inset Quotes srd
10948 \end_inset
10949
10950  and
10951 \begin_inset Quotes sld
10952 \end_inset
10953
10954 _endasm;
10955 \begin_inset Quotes srd
10956 \end_inset
10957
10958  to the beginning and the end of the function body:
10959 \layout Verse
10960
10961
10962 \family typewriter
10963 \size footnotesize
10964 /* With a cut and paste from the .asm file, we have something to start with.
10965 \newline
10966 \SpecialChar ~
10967 \SpecialChar ~
10968 \SpecialChar ~
10969 The function is not yet OK! (registers aren't saved) */
10970 \newline
10971 void to_buffer_asm( unsigned char c )
10972 \newline
10973 {
10974 \newline
10975 \SpecialChar ~
10976 \SpecialChar ~
10977 \SpecialChar ~
10978 \SpecialChar ~
10979 _asm
10980 \begin_inset LatexCommand \index{\_asm}
10981
10982 \end_inset
10983
10984
10985 \newline
10986 \SpecialChar ~
10987 \SpecialChar ~
10988 \SpecialChar ~
10989 \SpecialChar ~
10990 mov\SpecialChar ~
10991 \SpecialChar ~
10992 r2,dpl
10993 \newline
10994 ;buffer.c if( head != tail-1 )
10995 \newline
10996 \SpecialChar ~
10997 \SpecialChar ~
10998 \SpecialChar ~
10999 \SpecialChar ~
11000 mov\SpecialChar ~
11001 \SpecialChar ~
11002 a,_tail
11003 \newline
11004 \SpecialChar ~
11005 \SpecialChar ~
11006 \SpecialChar ~
11007 \SpecialChar ~
11008 dec\SpecialChar ~
11009 \SpecialChar ~
11010 a
11011 \newline
11012 \SpecialChar ~
11013 \SpecialChar ~
11014 \SpecialChar ~
11015 \SpecialChar ~
11016 mov\SpecialChar ~
11017 \SpecialChar ~
11018 r3,a
11019 \newline
11020 \SpecialChar ~
11021 \SpecialChar ~
11022 \SpecialChar ~
11023 \SpecialChar ~
11024 mov\SpecialChar ~
11025 \SpecialChar ~
11026 a,_head
11027 \newline
11028 \SpecialChar ~
11029 \SpecialChar ~
11030 \SpecialChar ~
11031 \SpecialChar ~
11032 cjne a,ar3,00106$
11033 \newline
11034 \SpecialChar ~
11035 \SpecialChar ~
11036 \SpecialChar ~
11037 \SpecialChar ~
11038 ret
11039 \newline
11040 00106$:
11041 \newline
11042 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
11043 \begin_inset LatexCommand \index{Aligned array}
11044
11045 \end_inset
11046
11047
11048 \newline
11049 \SpecialChar ~
11050 \SpecialChar ~
11051 \SpecialChar ~
11052 \SpecialChar ~
11053 mov\SpecialChar ~
11054 \SpecialChar ~
11055 r3,_head
11056 \newline
11057 \SpecialChar ~
11058 \SpecialChar ~
11059 \SpecialChar ~
11060 \SpecialChar ~
11061 inc\SpecialChar ~
11062 \SpecialChar ~
11063 _head
11064 \newline
11065 \SpecialChar ~
11066 \SpecialChar ~
11067 \SpecialChar ~
11068 \SpecialChar ~
11069 mov\SpecialChar ~
11070 \SpecialChar ~
11071 dpl,r3
11072 \newline
11073 \SpecialChar ~
11074 \SpecialChar ~
11075 \SpecialChar ~
11076 \SpecialChar ~
11077 mov\SpecialChar ~
11078 \SpecialChar ~
11079 dph,#(_buf >> 8)
11080 \newline
11081 \SpecialChar ~
11082 \SpecialChar ~
11083 \SpecialChar ~
11084 \SpecialChar ~
11085 mov\SpecialChar ~
11086 \SpecialChar ~
11087 a,r2
11088 \newline
11089 \SpecialChar ~
11090 \SpecialChar ~
11091 \SpecialChar ~
11092 \SpecialChar ~
11093 movx @dptr,a
11094 \newline
11095 00103$:
11096 \newline
11097 \SpecialChar ~
11098 \SpecialChar ~
11099 \SpecialChar ~
11100 \SpecialChar ~
11101 ret
11102 \newline
11103 \SpecialChar ~
11104 \SpecialChar ~
11105 \SpecialChar ~
11106 \SpecialChar ~
11107 _endasm;
11108 \newline
11109 }
11110 \layout Standard
11111
11112 The new file buffer.c should compile with only one warning about the unreferenced
11113  function argument 'c'.
11114  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
11115  (1) and finally have:
11116 \layout Verse
11117
11118
11119 \family typewriter
11120 \size footnotesize
11121 unsigned char far at 0x7f00 buf[0x100];
11122 \newline
11123 unsigned char head,tail;
11124 \newline
11125 #define USE_ASSEMBLY (1)
11126 \newline
11127
11128 \newline
11129 #if !USE_ASSEMBLY
11130 \newline
11131
11132 \newline
11133 void to_buffer( unsigned char c )
11134 \newline
11135 {
11136 \newline
11137 \SpecialChar ~
11138 \SpecialChar ~
11139 \SpecialChar ~
11140 \SpecialChar ~
11141 if( head != tail-1 )
11142 \newline
11143 \SpecialChar ~
11144 \SpecialChar ~
11145 \SpecialChar ~
11146 \SpecialChar ~
11147 \SpecialChar ~
11148 \SpecialChar ~
11149 \SpecialChar ~
11150 \SpecialChar ~
11151 buf[ head++ ] = c;
11152 \newline
11153 }
11154 \newline
11155
11156 \newline
11157 #else
11158 \newline
11159
11160 \newline
11161 void to_buffer( unsigned char c )
11162 \newline
11163 {
11164 \newline
11165 \SpecialChar ~
11166 \SpecialChar ~
11167 \SpecialChar ~
11168 \SpecialChar ~
11169 c; // to avoid warning: unreferenced function argument
11170 \newline
11171 \SpecialChar ~
11172 \SpecialChar ~
11173 \SpecialChar ~
11174 \SpecialChar ~
11175 _asm
11176 \begin_inset LatexCommand \index{\_asm}
11177
11178 \end_inset
11179
11180
11181 \newline
11182 \SpecialChar ~
11183 \SpecialChar ~
11184 \SpecialChar ~
11185 \SpecialChar ~
11186 \SpecialChar ~
11187 \SpecialChar ~
11188 \SpecialChar ~
11189 \SpecialChar ~
11190 ; save used registers here.
11191
11192 \newline
11193 \SpecialChar ~
11194 \SpecialChar ~
11195 \SpecialChar ~
11196 \SpecialChar ~
11197 \SpecialChar ~
11198 \SpecialChar ~
11199 \SpecialChar ~
11200 \SpecialChar ~
11201 ; If we were still using r2,r3 we would have to push them here.
11202
11203 \newline
11204 ; if( head != tail-1 )
11205 \newline
11206 \SpecialChar ~
11207 \SpecialChar ~
11208 \SpecialChar ~
11209 \SpecialChar ~
11210 \SpecialChar ~
11211 \SpecialChar ~
11212 \SpecialChar ~
11213 \SpecialChar ~
11214 mov\SpecialChar ~
11215  a,_tail
11216 \newline
11217 \SpecialChar ~
11218 \SpecialChar ~
11219 \SpecialChar ~
11220 \SpecialChar ~
11221 \SpecialChar ~
11222 \SpecialChar ~
11223 \SpecialChar ~
11224 \SpecialChar ~
11225 dec\SpecialChar ~
11226  a
11227 \newline
11228 \SpecialChar ~
11229 \SpecialChar ~
11230 \SpecialChar ~
11231 \SpecialChar ~
11232 \SpecialChar ~
11233 \SpecialChar ~
11234 \SpecialChar ~
11235 \SpecialChar ~
11236 xrl\SpecialChar ~
11237  a,_head
11238 \newline
11239 \SpecialChar ~
11240 \SpecialChar ~
11241 \SpecialChar ~
11242 \SpecialChar ~
11243 \SpecialChar ~
11244 \SpecialChar ~
11245 \SpecialChar ~
11246 \SpecialChar ~
11247 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
11248 \newline
11249 \SpecialChar ~
11250 \SpecialChar ~
11251 \SpecialChar ~
11252 \SpecialChar ~
11253 \SpecialChar ~
11254 \SpecialChar ~
11255 \SpecialChar ~
11256 \SpecialChar ~
11257 jz\SpecialChar ~
11258 \SpecialChar ~
11259  t_b_end$
11260 \newline
11261 \SpecialChar ~
11262 \SpecialChar ~
11263 \SpecialChar ~
11264 \SpecialChar ~
11265 \SpecialChar ~
11266 \SpecialChar ~
11267 \SpecialChar ~
11268 \SpecialChar ~
11269 ;
11270 \newline
11271 ; buf[ head++ ] = c;
11272 \newline
11273 \SpecialChar ~
11274 \SpecialChar ~
11275 \SpecialChar ~
11276 \SpecialChar ~
11277 \SpecialChar ~
11278 \SpecialChar ~
11279 \SpecialChar ~
11280 \SpecialChar ~
11281 mov\SpecialChar ~
11282  a,dpl \SpecialChar ~
11283 \SpecialChar ~
11284 \SpecialChar ~
11285 \SpecialChar ~
11286 \SpecialChar ~
11287 \SpecialChar ~
11288 \SpecialChar ~
11289 ; dpl holds lower byte of function argument
11290 \newline
11291 \SpecialChar ~
11292 \SpecialChar ~
11293 \SpecialChar ~
11294 \SpecialChar ~
11295 \SpecialChar ~
11296 \SpecialChar ~
11297 \SpecialChar ~
11298 \SpecialChar ~
11299 mov\SpecialChar ~
11300  dpl,_head \SpecialChar ~
11301 \SpecialChar ~
11302 \SpecialChar ~
11303 ; buf is 0x100 byte aligned so head can be used directly
11304 \newline
11305 \SpecialChar ~
11306 \SpecialChar ~
11307 \SpecialChar ~
11308 \SpecialChar ~
11309 \SpecialChar ~
11310 \SpecialChar ~
11311 \SpecialChar ~
11312 \SpecialChar ~
11313 mov\SpecialChar ~
11314  dph,#(_buf>>8)
11315 \newline
11316 \SpecialChar ~
11317 \SpecialChar ~
11318 \SpecialChar ~
11319 \SpecialChar ~
11320 \SpecialChar ~
11321 \SpecialChar ~
11322 \SpecialChar ~
11323 \SpecialChar ~
11324 movx @dptr,a
11325 \newline
11326 \SpecialChar ~
11327 \SpecialChar ~
11328 \SpecialChar ~
11329 \SpecialChar ~
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 \SpecialChar ~
11334 inc \SpecialChar ~
11335 _head
11336 \newline
11337 \SpecialChar ~
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 \SpecialChar ~
11341 \SpecialChar ~
11342 \SpecialChar ~
11343 \SpecialChar ~
11344 \SpecialChar ~
11345 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
11346 \newline
11347 t_b_end$:
11348 \newline
11349 \SpecialChar ~
11350 \SpecialChar ~
11351 \SpecialChar ~
11352 \SpecialChar ~
11353 \SpecialChar ~
11354 \SpecialChar ~
11355 \SpecialChar ~
11356 \SpecialChar ~
11357 ; restore used registers here
11358 \newline
11359 \SpecialChar ~
11360 \SpecialChar ~
11361 \SpecialChar ~
11362 \SpecialChar ~
11363 _endasm;
11364 \newline
11365 }
11366 \newline
11367 #endif
11368 \layout Standard
11369
11370 The inline assembler code can contain any valid code understood by the assembler
11371 , this includes any assembler directives and comment lines
11372 \begin_inset Foot
11373 collapsed false
11374
11375 \layout Standard
11376
11377 The assembler does not like some characters like ':' or ''' in comments.
11378  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
11379 \end_inset
11380
11381 .
11382  The compiler does not do any validation of the code within the
11383 \family typewriter
11384 _asm
11385 \begin_inset LatexCommand \index{\_asm}
11386
11387 \end_inset
11388
11389  ...
11390  _endasm;
11391 \family default
11392  keyword pair.
11393  Specifically it will not know which registers are used and thus register
11394  pushing/popping
11395 \begin_inset LatexCommand \index{push/pop}
11396
11397 \end_inset
11398
11399  has to be done manually.
11400
11401 \layout Standard
11402
11403 It is recommended that each assembly instruction (including labels) be placed
11404  in a separate line (as the example shows).
11405  When the -
11406 \begin_inset ERT
11407 status Collapsed
11408
11409 \layout Standard
11410
11411 \backslash
11412 /
11413 \end_inset
11414
11415 -
11416 \emph on
11417 peep-asm
11418 \begin_inset LatexCommand \index{-\/-peep-asm}
11419
11420 \end_inset
11421
11422
11423 \emph default
11424  command line option is used, the inline assembler code will be passed through
11425  the peephole optimizer
11426 \begin_inset LatexCommand \index{Peephole optimizer}
11427
11428 \end_inset
11429
11430 .
11431  There are only a few (if any) cases where this option makes sense, it might
11432  cause some unexpected changes in the inline assembler code.
11433  Please go through the peephole optimizer rules defined in file
11434 \emph on
11435 SDCCpeeph.def
11436 \emph default
11437  before using this option.
11438 \layout Subsection
11439
11440 Naked Functions
11441 \begin_inset LatexCommand \label{sub:Naked-Functions}
11442
11443 \end_inset
11444
11445
11446 \begin_inset LatexCommand \index{Naked functions}
11447
11448 \end_inset
11449
11450
11451 \layout Standard
11452
11453 A special keyword may be associated with a function declaring it as
11454 \emph on
11455 _naked
11456 \begin_inset LatexCommand \index{\_naked}
11457
11458 \end_inset
11459
11460 .
11461
11462 \emph default
11463 The
11464 \emph on
11465 _naked
11466 \emph default
11467  function modifier attribute prevents the compiler from generating prologue
11468 \begin_inset LatexCommand \index{function prologue}
11469
11470 \end_inset
11471
11472  and epilogue
11473 \begin_inset LatexCommand \index{function epilogue}
11474
11475 \end_inset
11476
11477  code for that function.
11478  This means that the user is entirely responsible for such things as saving
11479  any registers that may need to be preserved, selecting the proper register
11480  bank, generating the
11481 \emph on
11482 return
11483 \emph default
11484  instruction at the end, etc.
11485  Practically, this means that the contents of the function must be written
11486  in inline assembler.
11487  This is particularly useful for interrupt functions, which can have a large
11488  (and often unnecessary) prologue/epilogue.
11489  For example, compare the code generated by these two functions:
11490 \layout Verse
11491
11492
11493 \family typewriter
11494 volatile
11495 \begin_inset LatexCommand \index{volatile}
11496
11497 \end_inset
11498
11499  data unsigned char counter;
11500 \newline
11501
11502 \newline
11503 void simpleInterrupt(void) interrupt
11504 \begin_inset LatexCommand \index{interrupt}
11505
11506 \end_inset
11507
11508  1
11509 \newline
11510 {
11511 \newline
11512 \SpecialChar ~
11513 \SpecialChar ~
11514 \SpecialChar ~
11515 \SpecialChar ~
11516 counter++;
11517 \newline
11518 }
11519 \newline
11520
11521 \newline
11522 void nakedInterrupt(void) interrupt 2 _naked
11523 \newline
11524 {
11525 \newline
11526 \SpecialChar ~
11527 \SpecialChar ~
11528 \SpecialChar ~
11529 \SpecialChar ~
11530 _asm
11531 \begin_inset LatexCommand \index{\_asm}
11532
11533 \end_inset
11534
11535
11536 \newline
11537 \SpecialChar ~
11538 \SpecialChar ~
11539 \SpecialChar ~
11540 \SpecialChar ~
11541 \SpecialChar ~
11542 \SpecialChar ~
11543 inc\SpecialChar ~
11544 \SpecialChar ~
11545 \SpecialChar ~
11546 \SpecialChar ~
11547 \SpecialChar ~
11548 _counter ; does not change flags, no need to save psw
11549 \newline
11550 \SpecialChar ~
11551 \SpecialChar ~
11552 \SpecialChar ~
11553 \SpecialChar ~
11554 \SpecialChar ~
11555 \SpecialChar ~
11556 reti\SpecialChar ~
11557 \SpecialChar ~
11558 \SpecialChar ~
11559 \SpecialChar ~
11560 ; MUST explicitly include ret or reti in _naked function.
11561 \newline
11562 \SpecialChar ~
11563 \SpecialChar ~
11564 \SpecialChar ~
11565 \SpecialChar ~
11566 _endasm
11567 \begin_inset LatexCommand \index{\_endasm}
11568
11569 \end_inset
11570
11571 ;
11572 \newline
11573 }
11574 \layout Standard
11575
11576 For an 8051 target, the generated simpleInterrupt looks like:
11577 \layout Verse
11578
11579
11580 \family typewriter
11581 _simpleInterrupt:
11582 \newline
11583 \SpecialChar ~
11584 \SpecialChar ~
11585 \SpecialChar ~
11586 \SpecialChar ~
11587 push\SpecialChar ~
11588 \SpecialChar ~
11589 \SpecialChar ~
11590 \SpecialChar ~
11591 acc
11592 \newline
11593 \SpecialChar ~
11594 \SpecialChar ~
11595 \SpecialChar ~
11596 \SpecialChar ~
11597 push\SpecialChar ~
11598 \SpecialChar ~
11599 \SpecialChar ~
11600 \SpecialChar ~
11601 b
11602 \newline
11603 \SpecialChar ~
11604 \SpecialChar ~
11605 \SpecialChar ~
11606 \SpecialChar ~
11607 push\SpecialChar ~
11608 \SpecialChar ~
11609 \SpecialChar ~
11610 \SpecialChar ~
11611 dpl
11612 \newline
11613 \SpecialChar ~
11614 \SpecialChar ~
11615 \SpecialChar ~
11616 \SpecialChar ~
11617 push\SpecialChar ~
11618 \SpecialChar ~
11619 \SpecialChar ~
11620 \SpecialChar ~
11621 dph
11622 \newline
11623 \SpecialChar ~
11624 \SpecialChar ~
11625 \SpecialChar ~
11626 \SpecialChar ~
11627 push\SpecialChar ~
11628 \SpecialChar ~
11629 \SpecialChar ~
11630 \SpecialChar ~
11631 psw
11632 \newline
11633 \SpecialChar ~
11634 \SpecialChar ~
11635 \SpecialChar ~
11636 \SpecialChar ~
11637 mov\SpecialChar ~
11638 \SpecialChar ~
11639 \SpecialChar ~
11640 \SpecialChar ~
11641 \SpecialChar ~
11642 psw,#0x00
11643 \newline
11644 \SpecialChar ~
11645 \SpecialChar ~
11646 \SpecialChar ~
11647 \SpecialChar ~
11648 inc\SpecialChar ~
11649 \SpecialChar ~
11650 \SpecialChar ~
11651 \SpecialChar ~
11652 \SpecialChar ~
11653 _counter
11654 \newline
11655 \SpecialChar ~
11656 \SpecialChar ~
11657 \SpecialChar ~
11658 \SpecialChar ~
11659 pop\SpecialChar ~
11660 \SpecialChar ~
11661 \SpecialChar ~
11662 \SpecialChar ~
11663 \SpecialChar ~
11664 psw
11665 \newline
11666 \SpecialChar ~
11667 \SpecialChar ~
11668 \SpecialChar ~
11669 \SpecialChar ~
11670 pop\SpecialChar ~
11671 \SpecialChar ~
11672 \SpecialChar ~
11673 \SpecialChar ~
11674 \SpecialChar ~
11675 dph
11676 \newline
11677 \SpecialChar ~
11678 \SpecialChar ~
11679 \SpecialChar ~
11680 \SpecialChar ~
11681 pop\SpecialChar ~
11682 \SpecialChar ~
11683 \SpecialChar ~
11684 \SpecialChar ~
11685 \SpecialChar ~
11686 dpl
11687 \newline
11688 \SpecialChar ~
11689 \SpecialChar ~
11690 \SpecialChar ~
11691 \SpecialChar ~
11692 pop\SpecialChar ~
11693 \SpecialChar ~
11694 \SpecialChar ~
11695 \SpecialChar ~
11696 \SpecialChar ~
11697 b
11698 \newline
11699 \SpecialChar ~
11700 \SpecialChar ~
11701 \SpecialChar ~
11702 \SpecialChar ~
11703 pop\SpecialChar ~
11704 \SpecialChar ~
11705 \SpecialChar ~
11706 \SpecialChar ~
11707 \SpecialChar ~
11708 acc
11709 \newline
11710 \SpecialChar ~
11711 \SpecialChar ~
11712 \SpecialChar ~
11713 \SpecialChar ~
11714 reti
11715 \layout Standard
11716
11717 whereas nakedInterrupt looks like:
11718 \layout Verse
11719
11720
11721 \family typewriter
11722 _nakedInterrupt:
11723 \newline
11724 \SpecialChar ~
11725 \SpecialChar ~
11726 \SpecialChar ~
11727 \SpecialChar ~
11728 inc\SpecialChar ~
11729 \SpecialChar ~
11730 \SpecialChar ~
11731 \SpecialChar ~
11732 _counter ; does not change flags, no need to save psw
11733 \newline
11734 \SpecialChar ~
11735 \SpecialChar ~
11736 \SpecialChar ~
11737 \SpecialChar ~
11738 reti\SpecialChar ~
11739 \SpecialChar ~
11740 \SpecialChar ~
11741 \SpecialChar ~
11742 \SpecialChar ~
11743 \SpecialChar ~
11744 \SpecialChar ~
11745 \SpecialChar ~
11746 \SpecialChar ~
11747 \SpecialChar ~
11748 \SpecialChar ~
11749 \SpecialChar ~
11750 ; MUST explicitly include ret or reti in _naked function
11751 \layout Standard
11752
11753 The related directive #pragma exclude
11754 \begin_inset LatexCommand \index{\#pragma exclude}
11755
11756 \end_inset
11757
11758  allows a more fine grained control over pushing & popping
11759 \begin_inset LatexCommand \index{push/pop}
11760
11761 \end_inset
11762
11763  the registers.
11764 \layout Standard
11765
11766 While there is nothing preventing you from writing C code inside a
11767 \family typewriter
11768 _naked
11769 \family default
11770  function, there are many ways to shoot yourself in the foot doing this,
11771  and it is recommended that you stick to inline assembler.
11772 \layout Subsection
11773
11774 Use of Labels within Inline Assembler
11775 \layout Standard
11776
11777 SDCC allows the use of in-line assembler with a few restrictions regarding
11778  labels.
11779  In older versions of the compiler all labels defined within inline assembler
11780  code
11781 \emph on
11782 had to be
11783 \emph default
11784  of the form
11785 \emph on
11786 nnnnn$
11787 \emph default
11788  where nnnn is a number less than 100 (which implies a limit of utmost 100
11789  inline assembler labels
11790 \emph on
11791 per function
11792 \emph default
11793 \noun on
11794 )
11795 \noun default
11796 .
11797
11798 \layout Verse
11799
11800
11801 \family typewriter
11802 _asm
11803 \begin_inset LatexCommand \index{\_asm}
11804
11805 \end_inset
11806
11807
11808 \newline
11809 \SpecialChar ~
11810 \SpecialChar ~
11811 \SpecialChar ~
11812 \SpecialChar ~
11813 mov\SpecialChar ~
11814 \SpecialChar ~
11815 \SpecialChar ~
11816 \SpecialChar ~
11817 \SpecialChar ~
11818 b,#10
11819 \newline
11820 00001$:
11821 \newline
11822 \SpecialChar ~
11823 \SpecialChar ~
11824 \SpecialChar ~
11825 \SpecialChar ~
11826 djnz\SpecialChar ~
11827 \SpecialChar ~
11828 \SpecialChar ~
11829 \SpecialChar ~
11830 b,00001$
11831 \newline
11832 _endasm
11833 \begin_inset LatexCommand \index{\_endasm}
11834
11835 \end_inset
11836
11837  ;
11838 \layout Standard
11839
11840 Inline assembler code cannot reference any C-Labels, however it can reference
11841  labels
11842 \begin_inset LatexCommand \index{Labels}
11843
11844 \end_inset
11845
11846  defined by the inline assembler, e.g.:
11847 \layout Verse
11848
11849
11850 \family typewriter
11851 foo() {
11852 \newline
11853 \SpecialChar ~
11854 \SpecialChar ~
11855 \SpecialChar ~
11856 \SpecialChar ~
11857 /* some c code */
11858 \newline
11859 \SpecialChar ~
11860 \SpecialChar ~
11861 \SpecialChar ~
11862 \SpecialChar ~
11863 _asm
11864 \newline
11865 \SpecialChar ~
11866 \SpecialChar ~
11867 \SpecialChar ~
11868 \SpecialChar ~
11869 \SpecialChar ~
11870 \SpecialChar ~
11871 ; some assembler code
11872 \newline
11873 \SpecialChar ~
11874 \SpecialChar ~
11875 \SpecialChar ~
11876 \SpecialChar ~
11877 \SpecialChar ~
11878 \SpecialChar ~
11879 ljmp $0003
11880 \newline
11881 \SpecialChar ~
11882 \SpecialChar ~
11883 \SpecialChar ~
11884 \SpecialChar ~
11885 _endasm;
11886 \newline
11887 \SpecialChar ~
11888 \SpecialChar ~
11889 \SpecialChar ~
11890 \SpecialChar ~
11891 /* some more c code */
11892 \newline
11893 clabel:\SpecialChar ~
11894 \SpecialChar ~
11895 /* inline assembler cannot reference this label */
11896 \newline
11897 \SpecialChar ~
11898 \SpecialChar ~
11899 \SpecialChar ~
11900 \SpecialChar ~
11901 _asm
11902 \newline
11903 \SpecialChar ~
11904 \SpecialChar ~
11905 \SpecialChar ~
11906 \SpecialChar ~
11907 $0003: ;label (can be referenced by inline assembler only)
11908 \newline
11909 \SpecialChar ~
11910 \SpecialChar ~
11911 \SpecialChar ~
11912 \SpecialChar ~
11913 _endasm ;
11914 \newline
11915 \SpecialChar ~
11916 \SpecialChar ~
11917 \SpecialChar ~
11918 \SpecialChar ~
11919 /* some more c code */
11920 \newline
11921 }
11922 \layout Standard
11923
11924 In other words inline assembly code can access labels defined in inline
11925  assembly within the scope of the function.
11926  The same goes the other way, i.e.
11927  labels defines in inline assembly can not be accessed by C statements.
11928 \layout Section
11929
11930 Interfacing with Assembler Code
11931 \begin_inset LatexCommand \index{Assembler routines}
11932
11933 \end_inset
11934
11935
11936 \layout Subsection
11937
11938 Global Registers used for Parameter Passing
11939 \begin_inset LatexCommand \index{Parameter passing}
11940
11941 \end_inset
11942
11943
11944 \layout Standard
11945
11946 The compiler always uses the global registers
11947 \emph on
11948 DPL, DPH
11949 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
11950
11951 \end_inset
11952
11953
11954 \begin_inset LatexCommand \index{DPTR}
11955
11956 \end_inset
11957
11958 , B
11959 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
11960
11961 \end_inset
11962
11963
11964 \emph default
11965 and
11966 \emph on
11967  ACC
11968 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
11969
11970 \end_inset
11971
11972
11973 \emph default
11974  to pass the first parameter to a routine.
11975  The second parameter onwards is either allocated on the stack (for reentrant
11976  routines or if -
11977 \begin_inset ERT
11978 status Collapsed
11979
11980 \layout Standard
11981
11982 \backslash
11983 /
11984 \end_inset
11985
11986 -stack-auto is used) or in data / xdata memory (depending on the memory
11987  model).
11988
11989 \layout Subsection
11990
11991 Assembler Routine (non-reentrant)
11992 \layout Standard
11993
11994 In the following example
11995 \begin_inset LatexCommand \index{reentrant}
11996
11997 \end_inset
11998
11999
12000 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
12001
12002 \end_inset
12003
12004  the function c_func calls an assembler routine asm_func, which takes two
12005  parameters
12006 \begin_inset LatexCommand \index{function parameter}
12007
12008 \end_inset
12009
12010 .
12011 \layout Verse
12012
12013
12014 \family typewriter
12015 extern int asm_func(unsigned char, unsigned char);
12016 \newline
12017
12018 \newline
12019 int c_func (unsigned char i, unsigned char j)
12020 \newline
12021 {
12022 \newline
12023 \SpecialChar ~
12024 \SpecialChar ~
12025 \SpecialChar ~
12026 \SpecialChar ~
12027 return asm_func(i,j);
12028 \newline
12029 }
12030 \newline
12031
12032 \newline
12033 int main()
12034 \newline
12035 {
12036 \newline
12037 \SpecialChar ~
12038 \SpecialChar ~
12039 \SpecialChar ~
12040 \SpecialChar ~
12041 return c_func(10,9);
12042 \newline
12043 }
12044 \layout Standard
12045
12046 The corresponding assembler function is:
12047 \layout Verse
12048
12049
12050 \family typewriter
12051 .globl _asm_func_PARM_2
12052 \newline
12053 \SpecialChar ~
12054 \SpecialChar ~
12055 \SpecialChar ~
12056 \SpecialChar ~
12057 \SpecialChar ~
12058 \SpecialChar ~
12059 \SpecialChar ~
12060 \SpecialChar ~
12061 .globl _asm_func
12062 \newline
12063 \SpecialChar ~
12064 \SpecialChar ~
12065 \SpecialChar ~
12066 \SpecialChar ~
12067 \SpecialChar ~
12068 \SpecialChar ~
12069 \SpecialChar ~
12070 \SpecialChar ~
12071 .area OSEG
12072 \newline
12073 _asm_func_PARM_2:
12074 \newline
12075 \SpecialChar ~
12076 \SpecialChar ~
12077 \SpecialChar ~
12078 \SpecialChar ~
12079 \SpecialChar ~
12080 \SpecialChar ~
12081 \SpecialChar ~
12082 \SpecialChar ~
12083 .ds    1
12084 \newline
12085 \SpecialChar ~
12086 \SpecialChar ~
12087 \SpecialChar ~
12088 \SpecialChar ~
12089 \SpecialChar ~
12090 \SpecialChar ~
12091 \SpecialChar ~
12092 \SpecialChar ~
12093 .area CSEG
12094 \newline
12095 _asm_func:
12096 \newline
12097 \SpecialChar ~
12098 \SpecialChar ~
12099 \SpecialChar ~
12100 \SpecialChar ~
12101 \SpecialChar ~
12102 \SpecialChar ~
12103 \SpecialChar ~
12104 \SpecialChar ~
12105 mov\SpecialChar ~
12106 \SpecialChar ~
12107 \SpecialChar ~
12108 \SpecialChar ~
12109 a,dpl
12110 \newline
12111 \SpecialChar ~
12112 \SpecialChar ~
12113 \SpecialChar ~
12114 \SpecialChar ~
12115 \SpecialChar ~
12116 \SpecialChar ~
12117 \SpecialChar ~
12118 \SpecialChar ~
12119 add\SpecialChar ~
12120 \SpecialChar ~
12121 \SpecialChar ~
12122 \SpecialChar ~
12123 a,_asm_func_PARM_2
12124 \newline
12125 \SpecialChar ~
12126 \SpecialChar ~
12127 \SpecialChar ~
12128 \SpecialChar ~
12129 \SpecialChar ~
12130 \SpecialChar ~
12131 \SpecialChar ~
12132 \SpecialChar ~
12133 mov\SpecialChar ~
12134 \SpecialChar ~
12135 \SpecialChar ~
12136 \SpecialChar ~
12137 dpl,a
12138 \newline
12139 \SpecialChar ~
12140 \SpecialChar ~
12141 \SpecialChar ~
12142 \SpecialChar ~
12143 \SpecialChar ~
12144 \SpecialChar ~
12145 \SpecialChar ~
12146 \SpecialChar ~
12147 mov\SpecialChar ~
12148 \SpecialChar ~
12149 \SpecialChar ~
12150 \SpecialChar ~
12151 dph
12152 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12153
12154 \end_inset
12155
12156 ,#0x00
12157 \newline
12158 \SpecialChar ~
12159 \SpecialChar ~
12160 \SpecialChar ~
12161 \SpecialChar ~
12162 \SpecialChar ~
12163 \SpecialChar ~
12164 \SpecialChar ~
12165 \SpecialChar ~
12166 ret
12167 \layout Standard
12168
12169 Note here that the return values
12170 \begin_inset LatexCommand \index{return value}
12171
12172 \end_inset
12173
12174  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
12175  two byte values.
12176  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
12177 b' & 'acc' for four byte values.
12178 \layout Standard
12179
12180 The parameter naming convention is _<function_name>_PARM_<n>, where n is
12181  the parameter number starting from 1, and counting from the left.
12182  The first parameter is passed in
12183 \begin_inset Quotes eld
12184 \end_inset
12185
12186 dpl
12187 \begin_inset Quotes erd
12188 \end_inset
12189
12190  for a one byte parameter,
12191 \begin_inset Quotes eld
12192 \end_inset
12193
12194 dptr
12195 \begin_inset Quotes erd
12196 \end_inset
12197
12198  for two bytes,
12199 \begin_inset Quotes eld
12200 \end_inset
12201
12202 b,dptr
12203 \begin_inset Quotes erd
12204 \end_inset
12205
12206  for three bytes and
12207 \begin_inset Quotes eld
12208 \end_inset
12209
12210 acc,b,dptr
12211 \begin_inset Quotes erd
12212 \end_inset
12213
12214  for a four bytes parameter.
12215  The variable name for the second parameter will be _<function_name>_PARM_2.
12216 \newline
12217
12218 \newline
12219 Assemble the assembler routine with the following command:
12220 \newline
12221
12222 \newline
12223
12224 \family sans
12225 \series bold
12226 asx8051 -losg asmfunc.asm
12227 \newline
12228
12229 \newline
12230
12231 \family default
12232 \series default
12233 Then compile and link the assembler routine to the C source file with the
12234  following command:
12235 \newline
12236
12237 \newline
12238
12239 \family sans
12240 \series bold
12241 sdcc cfunc.c asmfunc.rel
12242 \layout Subsection
12243
12244 Assembler Routine (reentrant)
12245 \layout Standard
12246
12247 In this case
12248 \begin_inset LatexCommand \index{reentrant}
12249
12250 \end_inset
12251
12252
12253 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
12254
12255 \end_inset
12256
12257  the second parameter
12258 \begin_inset LatexCommand \index{function parameter}
12259
12260 \end_inset
12261
12262  onwards will be passed on the stack, the parameters are pushed from right
12263  to left i.e.
12264  after the call the leftmost parameter will be on the top of the stack.
12265  Here is an example:
12266 \layout Verse
12267
12268
12269 \family typewriter
12270 extern int asm_func(unsigned char, unsigned char);
12271 \newline
12272
12273 \newline
12274 int c_func (unsigned char i, unsigned char j) reentrant
12275 \newline
12276 {
12277 \newline
12278 \SpecialChar ~
12279 \SpecialChar ~
12280 \SpecialChar ~
12281 \SpecialChar ~
12282 return asm_func(i,j);
12283 \newline
12284 }
12285 \newline
12286
12287 \newline
12288 int main()
12289 \newline
12290 {
12291 \newline
12292 \SpecialChar ~
12293 \SpecialChar ~
12294 \SpecialChar ~
12295 \SpecialChar ~
12296 return c_func(10,9);
12297 \newline
12298 }
12299 \layout Standard
12300
12301 The corresponding assembler routine is:
12302 \layout Verse
12303
12304
12305 \family typewriter
12306 .globl _asm_func
12307 \newline
12308 _asm_func:
12309 \newline
12310 \SpecialChar ~
12311 \SpecialChar ~
12312 \SpecialChar ~
12313 \SpecialChar ~
12314 push  _bp
12315 \newline
12316 \SpecialChar ~
12317 \SpecialChar ~
12318 \SpecialChar ~
12319 \SpecialChar ~
12320 mov _bp,sp
12321 \newline
12322 \SpecialChar ~
12323 \SpecialChar ~
12324 \SpecialChar ~
12325 \SpecialChar ~
12326 mov r2,dpl
12327 \newline
12328 \SpecialChar ~
12329 \SpecialChar ~
12330 \SpecialChar ~
12331 \SpecialChar ~
12332 mov a,_bp
12333 \newline
12334 \SpecialChar ~
12335 \SpecialChar ~
12336 \SpecialChar ~
12337 \SpecialChar ~
12338 add a,#0xfd
12339 \newline
12340 \SpecialChar ~
12341 \SpecialChar ~
12342 \SpecialChar ~
12343 \SpecialChar ~
12344 mov r0,a
12345 \newline
12346 \SpecialChar ~
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 \SpecialChar ~
12350 add  a,#0xfc ;?
12351 \newline
12352 \SpecialChar ~
12353 \SpecialChar ~
12354 \SpecialChar ~
12355 \SpecialChar ~
12356 mov  r1,a
12357 \newline
12358 \SpecialChar ~
12359 \SpecialChar ~
12360 \SpecialChar ~
12361 \SpecialChar ~
12362 mov  a,@r0
12363 \newline
12364 \SpecialChar ~
12365 \SpecialChar ~
12366 \SpecialChar ~
12367 \SpecialChar ~
12368 add  a,r2 ;?
12369 \newline
12370 \SpecialChar ~
12371 \SpecialChar ~
12372 \SpecialChar ~
12373 \SpecialChar ~
12374 mov  dpl,a
12375 \newline
12376 \SpecialChar ~
12377 \SpecialChar ~
12378 \SpecialChar ~
12379 \SpecialChar ~
12380 mov  dph,#0x00
12381 \newline
12382 \SpecialChar ~
12383 \SpecialChar ~
12384 \SpecialChar ~
12385 \SpecialChar ~
12386 mov  sp,_bp
12387 \newline
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 \SpecialChar ~
12392 pop  _bp
12393 \newline
12394 \SpecialChar ~
12395 \SpecialChar ~
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 ret
12399 \layout Standard
12400
12401 The compiling and linking procedure remains the same, however note the extra
12402  entry & exit linkage required for the assembler code, _bp is the stack
12403  frame pointer and is used to compute the offset into the stack for parameters
12404  and local variables.
12405 \layout Section
12406
12407 int (16 bit)
12408 \begin_inset LatexCommand \index{int (16 bit)}
12409
12410 \end_inset
12411
12412  and long (32 bit)
12413 \begin_inset LatexCommand \index{long (32 bit)}
12414
12415 \end_inset
12416
12417  Support
12418 \layout Standard
12419
12420 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
12421  multiplication and modulus operations are implemented by support routines.
12422  These support routines are all developed in ANSI-C to facilitate porting
12423  to other MCUs, although some model specific assembler optimizations are
12424  used.
12425  The following files contain the described routines, all of them can be
12426  found in <installdir>/share/sdcc/lib.
12427 \newline
12428
12429 \layout Standard
12430 \align center
12431
12432 \begin_inset  Tabular
12433 <lyxtabular version="3" rows="11" columns="2">
12434 <features>
12435 <column alignment="center" valignment="top" leftline="true" width="0">
12436 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12437 <row topline="true" bottomline="true">
12438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12439 \begin_inset Text
12440
12441 \layout Standard
12442
12443
12444 \series bold
12445 Function
12446 \end_inset
12447 </cell>
12448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12449 \begin_inset Text
12450
12451 \layout Standard
12452
12453
12454 \series bold
12455 Description
12456 \end_inset
12457 </cell>
12458 </row>
12459 <row topline="true">
12460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12461 \begin_inset Text
12462
12463 \layout Standard
12464
12465 _mulint.c
12466 \end_inset
12467 </cell>
12468 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12469 \begin_inset Text
12470
12471 \layout Standard
12472
12473 16 bit multiplication
12474 \end_inset
12475 </cell>
12476 </row>
12477 <row topline="true">
12478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12479 \begin_inset Text
12480
12481 \layout Standard
12482
12483 _divsint.c
12484 \end_inset
12485 </cell>
12486 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12487 \begin_inset Text
12488
12489 \layout Standard
12490
12491  signed 16 bit division (calls _divuint)
12492 \end_inset
12493 </cell>
12494 </row>
12495 <row topline="true">
12496 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12497 \begin_inset Text
12498
12499 \layout Standard
12500
12501 _divuint.c
12502 \end_inset
12503 </cell>
12504 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12505 \begin_inset Text
12506
12507 \layout Standard
12508
12509  unsigned 16 bit division
12510 \end_inset
12511 </cell>
12512 </row>
12513 <row topline="true">
12514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12515 \begin_inset Text
12516
12517 \layout Standard
12518
12519 _modsint.c
12520 \end_inset
12521 </cell>
12522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12523 \begin_inset Text
12524
12525 \layout Standard
12526
12527 signed 16 bit modulus (calls _moduint)
12528 \end_inset
12529 </cell>
12530 </row>
12531 <row topline="true">
12532 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12533 \begin_inset Text
12534
12535 \layout Standard
12536
12537 _moduint.c
12538 \end_inset
12539 </cell>
12540 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12541 \begin_inset Text
12542
12543 \layout Standard
12544
12545 unsigned 16 bit modulus
12546 \end_inset
12547 </cell>
12548 </row>
12549 <row topline="true">
12550 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12551 \begin_inset Text
12552
12553 \layout Standard
12554
12555 _mullong.c
12556 \end_inset
12557 </cell>
12558 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12559 \begin_inset Text
12560
12561 \layout Standard
12562
12563 32 bit multiplication
12564 \end_inset
12565 </cell>
12566 </row>
12567 <row topline="true">
12568 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12569 \begin_inset Text
12570
12571 \layout Standard
12572
12573 _divslong.c
12574 \end_inset
12575 </cell>
12576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12577 \begin_inset Text
12578
12579 \layout Standard
12580
12581  signed 32 division (calls _divulong)
12582 \end_inset
12583 </cell>
12584 </row>
12585 <row topline="true">
12586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12587 \begin_inset Text
12588
12589 \layout Standard
12590
12591 _divulong.c
12592 \end_inset
12593 </cell>
12594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12595 \begin_inset Text
12596
12597 \layout Standard
12598
12599 unsigned 32 division
12600 \end_inset
12601 </cell>
12602 </row>
12603 <row topline="true">
12604 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12605 \begin_inset Text
12606
12607 \layout Standard
12608
12609 _modslong.c
12610 \end_inset
12611 </cell>
12612 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12613 \begin_inset Text
12614
12615 \layout Standard
12616
12617  signed 32 bit modulus (calls _modulong)
12618 \end_inset
12619 </cell>
12620 </row>
12621 <row topline="true" bottomline="true">
12622 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12623 \begin_inset Text
12624
12625 \layout Standard
12626
12627 _modulong.c
12628 \end_inset
12629 </cell>
12630 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12631 \begin_inset Text
12632
12633 \layout Standard
12634
12635 unsigned 32 bit modulus
12636 \end_inset
12637 </cell>
12638 </row>
12639 </lyxtabular>
12640
12641 \end_inset
12642
12643
12644 \newline
12645
12646 \layout Standard
12647
12648 Since they are compiled as
12649 \emph on
12650 non-reentrant
12651 \emph default
12652
12653 \begin_inset LatexCommand \index{reentrant}
12654
12655 \end_inset
12656
12657 , interrupt
12658 \begin_inset LatexCommand \index{interrupt}
12659
12660 \end_inset
12661
12662  service routines should not do any of the above operations.
12663  If this is unavoidable then the above routines will need to be compiled
12664  with the
12665 \emph on
12666 -
12667 \begin_inset ERT
12668 status Collapsed
12669
12670 \layout Standard
12671
12672 \backslash
12673 /
12674 \end_inset
12675
12676 -stack-auto
12677 \begin_inset LatexCommand \index{-\/-stack-auto}
12678
12679 \end_inset
12680
12681
12682 \emph default
12683  option, after which the source program will have to be compiled with
12684 \emph on
12685 -
12686 \begin_inset ERT
12687 status Collapsed
12688
12689 \layout Standard
12690
12691 \backslash
12692 /
12693 \end_inset
12694
12695 -int-long-reent
12696 \begin_inset LatexCommand \index{-\/-int-long-reent}
12697
12698 \end_inset
12699
12700
12701 \emph default
12702  option.
12703  Notice that you don't have to call these routines directly.
12704  The compiler will use them automatically every time an integer operation
12705  is required.
12706 \layout Section
12707
12708 Floating Point Support
12709 \begin_inset LatexCommand \index{Floating point support}
12710
12711 \end_inset
12712
12713
12714 \layout Standard
12715
12716 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
12717  floating point support routines are derived from gcc's floatlib.c and consist
12718  of the following routines:
12719 \newline
12720
12721 \layout Standard
12722 \align center
12723
12724 \size footnotesize
12725
12726 \begin_inset  Tabular
12727 <lyxtabular version="3" rows="17" columns="2">
12728 <features>
12729 <column alignment="center" valignment="top" leftline="true" width="0">
12730 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12731 <row topline="true" bottomline="true">
12732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12733 \begin_inset Text
12734
12735 \layout Standard
12736
12737
12738 \family roman
12739 \series medium
12740 \shape up
12741 \size normal
12742 \emph off
12743 \bar no
12744 \noun off
12745 \color none
12746 Function
12747 \end_inset
12748 </cell>
12749 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12750 \begin_inset Text
12751
12752 \layout Standard
12753
12754 Description
12755 \end_inset
12756 </cell>
12757 </row>
12758 <row topline="true">
12759 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12760 \begin_inset Text
12761
12762 \layout Standard
12763
12764
12765 \family roman
12766 \series medium
12767 \shape up
12768 \size normal
12769 \emph off
12770 \bar no
12771 \noun off
12772 \color none
12773 _fsadd.c
12774 \end_inset
12775 </cell>
12776 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12777 \begin_inset Text
12778
12779 \layout Standard
12780
12781
12782 \family roman
12783 \series medium
12784 \shape up
12785 \size normal
12786 \emph off
12787 \bar no
12788 \noun off
12789 \color none
12790 add floating point numbers
12791 \end_inset
12792 </cell>
12793 </row>
12794 <row topline="true">
12795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12796 \begin_inset Text
12797
12798 \layout Standard
12799
12800
12801 \family roman
12802 \series medium
12803 \shape up
12804 \size normal
12805 \emph off
12806 \bar no
12807 \noun off
12808 \color none
12809 _fssub.c
12810 \end_inset
12811 </cell>
12812 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12813 \begin_inset Text
12814
12815 \layout Standard
12816
12817
12818 \family roman
12819 \series medium
12820 \shape up
12821 \size normal
12822 \emph off
12823 \bar no
12824 \noun off
12825 \color none
12826 subtract floating point numbers
12827 \end_inset
12828 </cell>
12829 </row>
12830 <row topline="true">
12831 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12832 \begin_inset Text
12833
12834 \layout Standard
12835
12836
12837 \family roman
12838 \series medium
12839 \shape up
12840 \size normal
12841 \emph off
12842 \bar no
12843 \noun off
12844 \color none
12845 _fsdiv.c
12846 \end_inset
12847 </cell>
12848 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12849 \begin_inset Text
12850
12851 \layout Standard
12852
12853
12854 \family roman
12855 \series medium
12856 \shape up
12857 \size normal
12858 \emph off
12859 \bar no
12860 \noun off
12861 \color none
12862 divide floating point numbers
12863 \end_inset
12864 </cell>
12865 </row>
12866 <row topline="true">
12867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12868 \begin_inset Text
12869
12870 \layout Standard
12871
12872
12873 \family roman
12874 \series medium
12875 \shape up
12876 \size normal
12877 \emph off
12878 \bar no
12879 \noun off
12880 \color none
12881 _fsmul.c
12882 \end_inset
12883 </cell>
12884 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12885 \begin_inset Text
12886
12887 \layout Standard
12888
12889
12890 \family roman
12891 \series medium
12892 \shape up
12893 \size normal
12894 \emph off
12895 \bar no
12896 \noun off
12897 \color none
12898 multiply floating point numbers
12899 \end_inset
12900 </cell>
12901 </row>
12902 <row topline="true">
12903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12904 \begin_inset Text
12905
12906 \layout Standard
12907
12908
12909 \family roman
12910 \series medium
12911 \shape up
12912 \size normal
12913 \emph off
12914 \bar no
12915 \noun off
12916 \color none
12917 _fs2uchar.c
12918 \end_inset
12919 </cell>
12920 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12921 \begin_inset Text
12922
12923 \layout Standard
12924
12925
12926 \family roman
12927 \series medium
12928 \shape up
12929 \size normal
12930 \emph off
12931 \bar no
12932 \noun off
12933 \color none
12934 convert floating point to unsigned char
12935 \end_inset
12936 </cell>
12937 </row>
12938 <row topline="true">
12939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12940 \begin_inset Text
12941
12942 \layout Standard
12943
12944
12945 \family roman
12946 \series medium
12947 \shape up
12948 \size normal
12949 \emph off
12950 \bar no
12951 \noun off
12952 \color none
12953 _fs2char.c
12954 \end_inset
12955 </cell>
12956 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12957 \begin_inset Text
12958
12959 \layout Standard
12960
12961
12962 \family roman
12963 \series medium
12964 \shape up
12965 \size normal
12966 \emph off
12967 \bar no
12968 \noun off
12969 \color none
12970 convert floating point to signed char
12971 \end_inset
12972 </cell>
12973 </row>
12974 <row topline="true">
12975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12976 \begin_inset Text
12977
12978 \layout Standard
12979
12980
12981 \family roman
12982 \series medium
12983 \shape up
12984 \size normal
12985 \emph off
12986 \bar no
12987 \noun off
12988 \color none
12989 _fs2uint.c
12990 \end_inset
12991 </cell>
12992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12993 \begin_inset Text
12994
12995 \layout Standard
12996
12997
12998 \family roman
12999 \series medium
13000 \shape up
13001 \size normal
13002 \emph off
13003 \bar no
13004 \noun off
13005 \color none
13006 convert floating point to unsigned int
13007 \end_inset
13008 </cell>
13009 </row>
13010 <row topline="true">
13011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13012 \begin_inset Text
13013
13014 \layout Standard
13015
13016
13017 \family roman
13018 \series medium
13019 \shape up
13020 \size normal
13021 \emph off
13022 \bar no
13023 \noun off
13024 \color none
13025 _fs2int.c
13026 \end_inset
13027 </cell>
13028 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13029 \begin_inset Text
13030
13031 \layout Standard
13032
13033
13034 \family roman
13035 \series medium
13036 \shape up
13037 \size normal
13038 \emph off
13039 \bar no
13040 \noun off
13041 \color none
13042 convert floating point to signed int
13043 \end_inset
13044 </cell>
13045 </row>
13046 <row topline="true">
13047 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13048 \begin_inset Text
13049
13050 \layout Standard
13051
13052
13053 \family roman
13054 \series medium
13055 \shape up
13056 \size normal
13057 \emph off
13058 \bar no
13059 \noun off
13060 \color none
13061 _fs2ulong.
13062 \family default
13063 \series default
13064 \shape default
13065 \size default
13066 \emph default
13067 \bar default
13068 \noun default
13069 \color default
13070 c
13071 \end_inset
13072 </cell>
13073 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13074 \begin_inset Text
13075
13076 \layout Standard
13077
13078
13079 \family roman
13080 \series medium
13081 \shape up
13082 \size normal
13083 \emph off
13084 \bar no
13085 \noun off
13086 \color none
13087 convert floating point to unsigned long
13088 \end_inset
13089 </cell>
13090 </row>
13091 <row topline="true">
13092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13093 \begin_inset Text
13094
13095 \layout Standard
13096
13097
13098 \family roman
13099 \series medium
13100 \shape up
13101 \size normal
13102 \emph off
13103 \bar no
13104 \noun off
13105 \color none
13106 _fs2long.c
13107 \end_inset
13108 </cell>
13109 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13110 \begin_inset Text
13111
13112 \layout Standard
13113
13114
13115 \family roman
13116 \series medium
13117 \shape up
13118 \size normal
13119 \emph off
13120 \bar no
13121 \noun off
13122 \color none
13123 convert floating point to signed long
13124 \end_inset
13125 </cell>
13126 </row>
13127 <row topline="true">
13128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13129 \begin_inset Text
13130
13131 \layout Standard
13132
13133
13134 \family roman
13135 \series medium
13136 \shape up
13137 \size normal
13138 \emph off
13139 \bar no
13140 \noun off
13141 \color none
13142 _uchar2fs.c
13143 \end_inset
13144 </cell>
13145 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13146 \begin_inset Text
13147
13148 \layout Standard
13149
13150
13151 \family roman
13152 \series medium
13153 \shape up
13154 \size normal
13155 \emph off
13156 \bar no
13157 \noun off
13158 \color none
13159 convert unsigned char to floating point
13160 \end_inset
13161 </cell>
13162 </row>
13163 <row topline="true">
13164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13165 \begin_inset Text
13166
13167 \layout Standard
13168
13169
13170 \family roman
13171 \series medium
13172 \shape up
13173 \size normal
13174 \emph off
13175 \bar no
13176 \noun off
13177 \color none
13178 _char2fs.c
13179 \end_inset
13180 </cell>
13181 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13182 \begin_inset Text
13183
13184 \layout Standard
13185
13186
13187 \family roman
13188 \series medium
13189 \shape up
13190 \size normal
13191 \emph off
13192 \bar no
13193 \noun off
13194 \color none
13195 convert char to floating point number
13196 \end_inset
13197 </cell>
13198 </row>
13199 <row topline="true">
13200 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13201 \begin_inset Text
13202
13203 \layout Standard
13204
13205
13206 \family roman
13207 \series medium
13208 \shape up
13209 \size normal
13210 \emph off
13211 \bar no
13212 \noun off
13213 \color none
13214 _uint2fs.c
13215 \end_inset
13216 </cell>
13217 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13218 \begin_inset Text
13219
13220 \layout Standard
13221
13222
13223 \family roman
13224 \series medium
13225 \shape up
13226 \size normal
13227 \emph off
13228 \bar no
13229 \noun off
13230 \color none
13231 convert unsigned int to floating point
13232 \end_inset
13233 </cell>
13234 </row>
13235 <row topline="true">
13236 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13237 \begin_inset Text
13238
13239 \layout Standard
13240
13241
13242 \family roman
13243 \series medium
13244 \shape up
13245 \size normal
13246 \emph off
13247 \bar no
13248 \noun off
13249 \color none
13250 _int2fs.c
13251 \end_inset
13252 </cell>
13253 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13254 \begin_inset Text
13255
13256 \layout Standard
13257
13258
13259 \family roman
13260 \series medium
13261 \shape up
13262 \size normal
13263 \emph off
13264 \bar no
13265 \noun off
13266 \color none
13267 convert int to floating point numbers
13268 \end_inset
13269 </cell>
13270 </row>
13271 <row topline="true">
13272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13273 \begin_inset Text
13274
13275 \layout Standard
13276
13277
13278 \family roman
13279 \series medium
13280 \shape up
13281 \size normal
13282 \emph off
13283 \bar no
13284 \noun off
13285 \color none
13286 _ulong2fs.c
13287 \end_inset
13288 </cell>
13289 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13290 \begin_inset Text
13291
13292 \layout Standard
13293
13294
13295 \family roman
13296 \series medium
13297 \shape up
13298 \size normal
13299 \emph off
13300 \bar no
13301 \noun off
13302 \color none
13303 convert unsigned long to floating point number
13304 \end_inset
13305 </cell>
13306 </row>
13307 <row topline="true" bottomline="true">
13308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13309 \begin_inset Text
13310
13311 \layout Standard
13312
13313
13314 \family roman
13315 \series medium
13316 \shape up
13317 \size normal
13318 \emph off
13319 \bar no
13320 \noun off
13321 \color none
13322 _long2fs.c
13323 \end_inset
13324 </cell>
13325 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13326 \begin_inset Text
13327
13328 \layout Standard
13329
13330
13331 \family roman
13332 \series medium
13333 \shape up
13334 \size normal
13335 \emph off
13336 \bar no
13337 \noun off
13338 \color none
13339 convert long to floating point number
13340 \end_inset
13341 </cell>
13342 </row>
13343 </lyxtabular>
13344
13345 \end_inset
13346
13347
13348 \newline
13349
13350 \layout Standard
13351
13352 These support routines are developed in ANSI-C so there is room for space
13353  and speed improvement.
13354  Note if all these routines are used simultaneously the data space might
13355  overflow.
13356  For serious floating point usage it is recommended that the large model
13357  be used.
13358  Also notice that you don't have to call this routines directly.
13359  The compiler will use them automatically every time a floating point operation
13360  is required.
13361 \layout Section
13362
13363 Library Routines
13364 \begin_inset LatexCommand \index{Libraries}
13365
13366 \end_inset
13367
13368
13369 \layout Standard
13370
13371
13372 \emph on
13373 <pending: this is messy and incomplete - a little more information is in
13374  sdcc/doc/libdoc.txt
13375 \emph default
13376  >
13377 \layout Subsection
13378
13379 Compiler support routines (_gptrget, _mulint etc.)
13380 \layout Subsection
13381
13382 Stdclib functions (puts, printf, strcat etc.)
13383 \layout Subsubsection
13384
13385 <stdio.h>
13386 \layout Standard
13387
13388
13389 \begin_inset LatexCommand \index{<stdio.h>}
13390
13391 \end_inset
13392
13393 As usual on embedded systems you have to provide your own
13394 \family typewriter
13395 getchar()
13396 \begin_inset LatexCommand \index{getchar()}
13397
13398 \end_inset
13399
13400
13401 \family default
13402 and
13403 \family typewriter
13404 putchar()
13405 \begin_inset LatexCommand \index{putchar()}
13406
13407 \end_inset
13408
13409
13410 \family default
13411  routines.
13412  SDCC does not know whether the system connects to a serial line with or
13413  without handshake, LCD, keyboard or other device.
13414  You'll find examples for serial routines f.e.
13415  in sdcc/device/lib.
13416 \layout Standard
13417
13418 If you're short on memory you might want to use
13419 \family typewriter
13420 printf_small()
13421 \family default
13422
13423 \emph on
13424 instead
13425 \emph default
13426  of
13427 \family typewriter
13428  printf()
13429 \begin_inset LatexCommand \index{printf()}
13430
13431 \end_inset
13432
13433 .
13434
13435 \family default
13436  For the mcs51 there is an assembly version
13437 \family typewriter
13438 printf_fast()
13439 \family default
13440  which should fit the requirements of many embedded systems (by unsetting
13441  #defines it can be customized to
13442 \emph on
13443 not
13444 \emph default
13445  support long variables and field widths).
13446 \layout Subsection
13447
13448 Math functions (sin, pow, sqrt etc.)
13449 \layout Subsection
13450
13451 Other libraries
13452 \layout Standard
13453
13454 Libraries
13455 \begin_inset LatexCommand \index{Libraries}
13456
13457 \end_inset
13458
13459  included in SDCC should have a license at least as liberal as the GNU Lesser
13460  General Public License
13461 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
13462
13463 \end_inset
13464
13465
13466 \emph on
13467 LGPL
13468 \emph default
13469 .
13470 \layout Comment
13471
13472 license statements for the libraries are missing.
13473  sdcc/device/lib/ser_ir.c
13474 \layout Comment
13475
13476 or _decdptr f.e.
13477  come with a GPL (as opposed to LGPL) License - this will not be liberal
13478  enough for many embedded programmers.
13479 \layout Standard
13480
13481 If you have ported some library or want to share experience about some code
13482  which f.e.
13483  falls into any of these categories Busses (I
13484 \begin_inset Formula $^{\textrm{2}}$
13485 \end_inset
13486
13487 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
13488  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
13489  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
13490 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
13491
13492 \end_inset
13493
13494 \SpecialChar ~
13495 would certainly like to hear about it.
13496  Programmers coding for embedded systems are not especially famous for being
13497  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
13498 e these references are very valuable.
13499  Let's help to create a climate where information is shared.
13500 \layout Section
13501
13502 Memory Models
13503 \layout Subsection
13504
13505 MCS51 Memory Models
13506 \begin_inset LatexCommand \index{Memory model}
13507
13508 \end_inset
13509
13510
13511 \begin_inset LatexCommand \index{MCS51 memory model}
13512
13513 \end_inset
13514
13515
13516 \layout Subsubsection
13517
13518 Small and Large
13519 \layout Standard
13520
13521 SDCC allows two memory models for MCS51 code,
13522 \shape slanted
13523 small
13524 \shape default
13525  and
13526 \shape slanted
13527 large
13528 \shape default
13529 .
13530  Modules compiled with different memory models should
13531 \emph on
13532 never
13533 \emph default
13534  be combined together or the results would be unpredictable.
13535  The library routines supplied with the compiler are compiled as both small
13536  and large.
13537  The compiled library modules are contained in separate directories as small
13538  and large so that you can link to either set.
13539
13540 \layout Standard
13541
13542 When the large model is used all variables declared without a storage class
13543  will be allocated into the external ram, this includes all parameters and
13544  local variables (for non-reentrant
13545 \begin_inset LatexCommand \index{reentrant}
13546
13547 \end_inset
13548
13549  functions).
13550  When the small model is used variables without storage class are allocated
13551  in the internal ram.
13552 \layout Standard
13553
13554 Judicious usage of the processor specific storage classes
13555 \begin_inset LatexCommand \index{Storage class}
13556
13557 \end_inset
13558
13559  and the 'reentrant' function type will yield much more efficient code,
13560  than using the large model.
13561  Several optimizations are disabled when the program is compiled using the
13562  large model, it is therefore recommended that the small model be used unless
13563  absolutely required.
13564 \layout Subsubsection
13565
13566 External Stack
13567 \begin_inset LatexCommand \label{sub:External-Stack}
13568
13569 \end_inset
13570
13571
13572 \begin_inset LatexCommand \index{stack}
13573
13574 \end_inset
13575
13576
13577 \begin_inset LatexCommand \index{External stack (mcs51)}
13578
13579 \end_inset
13580
13581
13582 \layout Standard
13583
13584
13585 \series bold
13586 Attention
13587 \series default
13588 : this option wasn't maintained for a long time and is quite buggy.
13589  Small programs might work.
13590  You've been warned!
13591 \layout Standard
13592
13593 The external stack (-
13594 \begin_inset ERT
13595 status Collapsed
13596
13597 \layout Standard
13598
13599 \backslash
13600 /
13601 \end_inset
13602
13603 -xstack option
13604 \begin_inset LatexCommand \index{-\/-xstack}
13605
13606 \end_inset
13607
13608 ) is located in pdata
13609 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
13610
13611 \end_inset
13612
13613  memory (usually at the start of the external ram segment) and is 256 bytes
13614  in size.
13615  When -
13616 \begin_inset ERT
13617 status Collapsed
13618
13619 \layout Standard
13620
13621 \backslash
13622 /
13623 \end_inset
13624
13625 -xstack option is used to compile the program, the parameters and local
13626  variables
13627 \begin_inset LatexCommand \index{local variables}
13628
13629 \end_inset
13630
13631  of all reentrant functions are allocated in this area.
13632  This option is provided for programs with large stack space requirements.
13633  When used with the -
13634 \begin_inset ERT
13635 status Collapsed
13636
13637 \layout Standard
13638
13639 \backslash
13640 /
13641 \end_inset
13642
13643 -stack-auto
13644 \begin_inset LatexCommand \index{-\/-stack-auto}
13645
13646 \end_inset
13647
13648  option, all parameters and local variables are allocated on the external
13649  stack (note: support libraries will need to be recompiled with the same
13650  options).
13651 \layout Standard
13652
13653 The compiler outputs the higher order address byte of the external ram segment
13654  into port P2
13655 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
13656
13657 \end_inset
13658
13659  (see also section
13660 \begin_inset LatexCommand \ref{sub:MCS51-variants}
13661
13662 \end_inset
13663
13664 ), therefore when using the External Stack option, this port
13665 \emph on
13666 may not
13667 \emph default
13668  be used by the application program.
13669 \layout Subsection
13670
13671 DS390 Memory Model
13672 \begin_inset LatexCommand \index{Memory model}
13673
13674 \end_inset
13675
13676
13677 \begin_inset LatexCommand \index{DS390 memory model}
13678
13679 \end_inset
13680
13681
13682 \layout Standard
13683
13684 The only model supported is Flat 24
13685 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
13686
13687 \end_inset
13688
13689 .
13690  This generates code for the 24 bit contiguous addressing mode of the Dallas
13691  DS80C390 part.
13692  In this mode, up to four meg of external RAM or code space can be directly
13693  addressed.
13694  See the data sheets at www.dalsemi.com for further information on this part.
13695 \newline
13696
13697 \newline
13698 Note that the compiler does not generate any code to place the processor
13699  into 24 bitmode (although
13700 \emph on
13701 tinibios
13702 \emph default
13703  in the ds390 libraries will do that for you).
13704  If you don't use
13705 \emph on
13706 tinibios
13707 \emph default
13708
13709 \begin_inset LatexCommand \index{Tinibios (DS390)}
13710
13711 \end_inset
13712
13713 , the boot loader or similar code must ensure that the processor is in 24
13714  bit contiguous addressing mode before calling the SDCC startup code.
13715 \newline
13716
13717 \newline
13718 Like the
13719 \emph on
13720 -
13721 \begin_inset ERT
13722 status Collapsed
13723
13724 \layout Standard
13725
13726 \backslash
13727 /
13728 \end_inset
13729
13730 -model-large
13731 \emph default
13732  option, variables will by default be placed into the XDATA segment.
13733
13734 \newline
13735
13736 \newline
13737 Segments may be placed anywhere in the 4 meg address space using the usual
13738  -
13739 \begin_inset ERT
13740 status Collapsed
13741
13742 \layout Standard
13743
13744 \backslash
13745 /
13746 \end_inset
13747
13748 -*-loc options.
13749  Note that if any segments are located above 64K, the -r flag must be passed
13750  to the linker to generate the proper segment relocations, and the Intel
13751  HEX output format must be used.
13752  The -r flag can be passed to the linker by using the option
13753 \emph on
13754 -Wl-r
13755 \emph default
13756  on the SDCC command line.
13757  However, currently the linker can not handle code segments > 64k.
13758 \layout Section
13759
13760 Pragmas
13761 \begin_inset LatexCommand \index{Pragmas}
13762
13763 \end_inset
13764
13765
13766 \layout Standard
13767
13768 SDCC supports the following #pragma directives:
13769 \layout Itemize
13770
13771 save
13772 \begin_inset LatexCommand \index{\#pragma save}
13773
13774 \end_inset
13775
13776  - this will save all current options to the save/restore stack.
13777  See #pragma\SpecialChar ~
13778 restore.
13779 \layout Itemize
13780
13781 restore
13782 \begin_inset LatexCommand \index{\#pragma restore}
13783
13784 \end_inset
13785
13786  - will restore saved options from the last save.
13787  saves & restores can be nested.
13788  SDCC uses a save/restore stack: save pushes current options to the stack,
13789  restore pulls current options from the stack.
13790  See #pragma\SpecialChar ~
13791 save.
13792 \newline
13793
13794 \layout Itemize
13795
13796 callee_saves
13797 \begin_inset LatexCommand \index{\#pragma callee\_saves}
13798
13799 \end_inset
13800
13801
13802 \begin_inset LatexCommand \index{function prologue}
13803
13804 \end_inset
13805
13806  function1[,function2[,function3...]] - The compiler by default uses a caller
13807  saves convention for register saving across function calls, however this
13808  can cause unnecessary register pushing & popping
13809 \begin_inset LatexCommand \index{push/pop}
13810
13811 \end_inset
13812
13813  when calling small functions from larger functions.
13814  This option can be used to switch off the register saving convention for
13815  the function names specified.
13816  The compiler will not save registers when calling these functions, extra
13817  code need to be manually inserted at the entry & exit for these functions
13818  to save & restore the registers used by these functions, this can SUBSTANTIALLY
13819  reduce code & improve run time performance of the generated code.
13820  In the future the compiler (with inter procedural analysis) may be able
13821  to determine the appropriate scheme to use for each function call.
13822  If -
13823 \begin_inset ERT
13824 status Collapsed
13825
13826 \layout Standard
13827
13828 \backslash
13829 /
13830 \end_inset
13831
13832 -callee-saves command line option is used, the function names specified
13833  in #pragma\SpecialChar ~
13834 callee_saves
13835 \begin_inset LatexCommand \index{\#pragma callee\_saves}
13836
13837 \end_inset
13838
13839  is appended to the list of functions specified in the command line.
13840 \layout Itemize
13841
13842 exclude
13843 \begin_inset LatexCommand \index{\#pragma exclude}
13844
13845 \end_inset
13846
13847  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
13848  of pairs of push/pop
13849 \begin_inset LatexCommand \index{push/pop}
13850
13851 \end_inset
13852
13853  instructions in
13854 \emph on
13855 I
13856 \emph default
13857 nterrupt
13858 \begin_inset LatexCommand \index{interrupt}
13859
13860 \end_inset
13861
13862
13863 \emph on
13864 S
13865 \emph default
13866 ervice
13867 \emph on
13868 R
13869 \emph default
13870 outines.
13871  The directive should be placed immediately before the ISR function definition
13872  and it affects ALL ISR functions following it.
13873  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
13874 exclude\SpecialChar ~
13875 none
13876 \begin_inset LatexCommand \index{\#pragma exclude}
13877
13878 \end_inset
13879
13880 .
13881  See also the related keyword _naked
13882 \begin_inset LatexCommand \index{\_naked}
13883
13884 \end_inset
13885
13886 .
13887 \layout Itemize
13888
13889 less_pedantic
13890 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
13891
13892 \end_inset
13893
13894  - the compiler will not warn you anymore for obvious mistakes, you'r on
13895  your own now ;-(
13896 \layout Itemize
13897
13898 nogcse
13899 \begin_inset LatexCommand \index{\#pragma nogcse}
13900
13901 \end_inset
13902
13903  - will stop global common subexpression elimination.
13904 \layout Itemize
13905
13906 noinduction
13907 \begin_inset LatexCommand \index{\#pragma noinduction}
13908
13909 \end_inset
13910
13911  - will stop loop induction optimizations.
13912 \layout Itemize
13913
13914 noinvariant
13915 \begin_inset LatexCommand \index{\#pragma noinvariant}
13916
13917 \end_inset
13918
13919  - will not do loop invariant optimizations.
13920  For more details see Loop Invariants in section
13921 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
13922
13923 \end_inset
13924
13925 .
13926 \layout Itemize
13927
13928 noiv
13929 \begin_inset LatexCommand \index{\#pragma noiv}
13930
13931 \end_inset
13932
13933  - Do not generate interrupt
13934 \begin_inset LatexCommand \index{interrupt}
13935
13936 \end_inset
13937
13938  vector table entries for all ISR functions defined after the pragma.
13939  This is useful in cases where the interrupt vector table must be defined
13940  manually, or when there is a secondary, manually defined interrupt vector
13941  table (e.g.
13942  for the autovector feature of the Cypress EZ-USB FX2).
13943  More elegantly this can be achieved by obmitting the optional interrupt
13944  number after the interrupt keyword, see section
13945 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
13946
13947 \end_inset
13948
13949 \SpecialChar ~
13950 about interrupts.
13951 \layout Itemize
13952
13953 nojtbound
13954 \begin_inset LatexCommand \index{\#pragma nojtbound}
13955
13956 \end_inset
13957
13958  - will not generate code for boundary value checking, when switch statements
13959  are turned into jump-tables (dangerous).
13960  For more details see section
13961 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
13962
13963 \end_inset
13964
13965 .
13966 \layout Itemize
13967
13968 noloopreverse
13969 \begin_inset LatexCommand \index{\#pragma noloopreverse}
13970
13971 \end_inset
13972
13973  - Will not do loop reversal optimization
13974 \layout Itemize
13975
13976 nooverlay
13977 \begin_inset LatexCommand \index{\#pragma nooverlay}
13978
13979 \end_inset
13980
13981  - the compiler will not overlay the parameters and local variables of a
13982  function.
13983 \layout Itemize
13984
13985 stackauto
13986 \begin_inset LatexCommand \index{\#pragma stackauto}
13987
13988 \end_inset
13989
13990 - See option -
13991 \begin_inset ERT
13992 status Collapsed
13993
13994 \layout Standard
13995
13996 \backslash
13997 /
13998 \end_inset
13999
14000 -stack-auto
14001 \begin_inset LatexCommand \index{-\/-stack-auto}
14002
14003 \end_inset
14004
14005  and section
14006 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
14007
14008 \end_inset
14009
14010  Parameters and Local Variables.
14011 \layout Standard
14012
14013 SDCPP supports the following #pragma directives:
14014 \layout Itemize
14015
14016 preproc_asm
14017 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
14018
14019 \end_inset
14020
14021  (+ | -) - switch _asm _endasm block preprocessing on / off.
14022  Default is on.
14023 \layout Standard
14024
14025 The pragma's are intended to be used to turn-on or off certain optimizations
14026  which might cause the compiler to generate extra stack / data space to
14027  store compiler generated temporary variables.
14028  This usually happens in large functions.
14029  Pragma directives should be used as shown in the following example, they
14030  are used to control options & optimizations for a given function; pragmas
14031  should be placed before and/or after a function, placing pragma's inside
14032  a function body could have unpredictable results.
14033 \layout Verse
14034
14035
14036 \family typewriter
14037 #pragma save
14038 \begin_inset LatexCommand \index{\#pragma save}
14039
14040 \end_inset
14041
14042  \SpecialChar ~
14043 \SpecialChar ~
14044 \SpecialChar ~
14045 \SpecialChar ~
14046 \SpecialChar ~
14047 \SpecialChar ~
14048 \SpecialChar ~
14049 /* save the current settings */
14050 \newline
14051 #pragma nogcse
14052 \begin_inset LatexCommand \index{\#pragma nogcse}
14053
14054 \end_inset
14055
14056  \SpecialChar ~
14057 \SpecialChar ~
14058 \SpecialChar ~
14059 \SpecialChar ~
14060 \SpecialChar ~
14061 /* turnoff global subexpression elimination */
14062 \newline
14063 #pragma noinduction
14064 \begin_inset LatexCommand \index{\#pragma noinduction}
14065
14066 \end_inset
14067
14068  /* turn off induction optimizations */
14069 \newline
14070 int foo ()
14071 \newline
14072 {
14073 \newline
14074 \SpecialChar ~
14075  \SpecialChar ~
14076  ...
14077
14078 \newline
14079 \SpecialChar ~
14080  \SpecialChar ~
14081  /* large code */
14082 \newline
14083 \SpecialChar ~
14084  \SpecialChar ~
14085  ...
14086
14087 \newline
14088 }
14089 \newline
14090 #pragma restore
14091 \begin_inset LatexCommand \index{\#pragma restore}
14092
14093 \end_inset
14094
14095  /* turn the optimizations back on */
14096 \layout Standard
14097
14098 The compiler will generate a warning message when extra space is allocated.
14099  It is strongly recommended that the save and restore pragma's be used when
14100  changing options for a function.
14101 \layout Section
14102
14103 Defines Created by the Compiler
14104 \layout Standard
14105
14106 The compiler creates the following #defines
14107 \begin_inset LatexCommand \index{\#defines}
14108
14109 \end_inset
14110
14111
14112 \begin_inset LatexCommand \index{Defines created by the compiler}
14113
14114 \end_inset
14115
14116 :
14117 \newline
14118
14119 \layout Standard
14120
14121
14122 \begin_inset  Tabular
14123 <lyxtabular version="3" rows="10" columns="2">
14124 <features>
14125 <column alignment="center" valignment="top" leftline="true" width="0">
14126 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
14127 <row topline="true" bottomline="true">
14128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14129 \begin_inset Text
14130
14131 \layout Standard
14132
14133
14134 \series bold
14135 #define
14136 \end_inset
14137 </cell>
14138 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14139 \begin_inset Text
14140
14141 \layout Standard
14142
14143
14144 \series bold
14145 Description
14146 \end_inset
14147 </cell>
14148 </row>
14149 <row topline="true">
14150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14151 \begin_inset Text
14152
14153 \layout Standard
14154
14155 SDCC
14156 \begin_inset LatexCommand \index{SDCC}
14157
14158 \end_inset
14159
14160
14161 \end_inset
14162 </cell>
14163 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14164 \begin_inset Text
14165
14166 \layout Standard
14167
14168 this Symbol is always defined
14169 \end_inset
14170 </cell>
14171 </row>
14172 <row topline="true">
14173 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14174 \begin_inset Text
14175
14176 \layout Standard
14177
14178 SDCC_mcs51
14179 \begin_inset LatexCommand \index{SDCC\_mcs51}
14180
14181 \end_inset
14182
14183  or SDCC_ds390
14184 \begin_inset LatexCommand \index{SDCC\_ds390}
14185
14186 \end_inset
14187
14188  or SDCC_z80
14189 \begin_inset LatexCommand \index{SDCC\_z80}
14190
14191 \end_inset
14192
14193 , etc
14194 \end_inset
14195 </cell>
14196 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14197 \begin_inset Text
14198
14199 \layout Standard
14200
14201 depending on the model used (e.g.: -mds390
14202 \end_inset
14203 </cell>
14204 </row>
14205 <row topline="true">
14206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14207 \begin_inset Text
14208
14209 \layout Standard
14210
14211 __mcs51
14212 \begin_inset LatexCommand \index{\_\_mcs51}
14213
14214 \end_inset
14215
14216 , __ds390
14217 \begin_inset LatexCommand \index{\_\_ds390}
14218
14219 \end_inset
14220
14221 , __hc08
14222 \begin_inset LatexCommand \index{\_\_hc08}
14223
14224 \end_inset
14225
14226 , __z80
14227 \begin_inset LatexCommand \index{\_\_z80}
14228
14229 \end_inset
14230
14231 , etc
14232 \end_inset
14233 </cell>
14234 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14235 \begin_inset Text
14236
14237 \layout Standard
14238
14239 depending on the model used (e.g.
14240  -mz80)
14241 \end_inset
14242 </cell>
14243 </row>
14244 <row topline="true">
14245 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14246 \begin_inset Text
14247
14248 \layout Standard
14249
14250 SDCC_STACK_AUTO
14251 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
14252
14253 \end_inset
14254
14255
14256 \end_inset
14257 </cell>
14258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14259 \begin_inset Text
14260
14261 \layout Standard
14262
14263 when
14264 \emph on
14265 -
14266 \begin_inset ERT
14267 status Collapsed
14268
14269 \layout Standard
14270
14271 \backslash
14272 /
14273 \end_inset
14274
14275 -stack-auto
14276 \emph default
14277  option is used
14278 \end_inset
14279 </cell>
14280 </row>
14281 <row topline="true">
14282 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14283 \begin_inset Text
14284
14285 \layout Standard
14286
14287 SDCC_MODEL_SMALL
14288 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
14289
14290 \end_inset
14291
14292
14293 \end_inset
14294 </cell>
14295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14296 \begin_inset Text
14297
14298 \layout Standard
14299
14300 when
14301 \emph on
14302 -
14303 \begin_inset ERT
14304 status Collapsed
14305
14306 \layout Standard
14307
14308 \backslash
14309 /
14310 \end_inset
14311
14312 -model-small
14313 \emph default
14314  is used
14315 \end_inset
14316 </cell>
14317 </row>
14318 <row topline="true">
14319 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14320 \begin_inset Text
14321
14322 \layout Standard
14323
14324 SDCC_MODEL_LARGE
14325 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
14326
14327 \end_inset
14328
14329
14330 \end_inset
14331 </cell>
14332 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14333 \begin_inset Text
14334
14335 \layout Standard
14336
14337 when
14338 \emph on
14339 -
14340 \begin_inset ERT
14341 status Collapsed
14342
14343 \layout Standard
14344
14345 \backslash
14346 /
14347 \end_inset
14348
14349 -model-large
14350 \emph default
14351  is used
14352 \end_inset
14353 </cell>
14354 </row>
14355 <row topline="true">
14356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14357 \begin_inset Text
14358
14359 \layout Standard
14360
14361 SDCC_USE_XSTACK
14362 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
14363
14364 \end_inset
14365
14366
14367 \end_inset
14368 </cell>
14369 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14370 \begin_inset Text
14371
14372 \layout Standard
14373
14374 when
14375 \emph on
14376 -
14377 \begin_inset ERT
14378 status Collapsed
14379
14380 \layout Standard
14381
14382 \backslash
14383 /
14384 \end_inset
14385
14386 -xstack
14387 \emph default
14388  option is used
14389 \end_inset
14390 </cell>
14391 </row>
14392 <row topline="true">
14393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14394 \begin_inset Text
14395
14396 \layout Standard
14397
14398 SDCC_STACK_TENBIT
14399 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
14400
14401 \end_inset
14402
14403
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 when
14412 \emph on
14413 -mds390
14414 \emph default
14415  is used
14416 \end_inset
14417 </cell>
14418 </row>
14419 <row topline="true" bottomline="true">
14420 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14421 \begin_inset Text
14422
14423 \layout Standard
14424
14425 SDCC_MODEL_FLAT24
14426 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
14427
14428 \end_inset
14429
14430
14431 \end_inset
14432 </cell>
14433 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14434 \begin_inset Text
14435
14436 \layout Standard
14437
14438 when
14439 \emph on
14440 -mds390
14441 \emph default
14442  is used
14443 \end_inset
14444 </cell>
14445 </row>
14446 </lyxtabular>
14447
14448 \end_inset
14449
14450
14451 \layout Chapter
14452
14453 Notes on supported Processors
14454 \layout Section
14455
14456 MCS51 variants
14457 \begin_inset LatexCommand \label{sub:MCS51-variants}
14458
14459 \end_inset
14460
14461
14462 \begin_inset LatexCommand \index{MCS51 variants}
14463
14464 \end_inset
14465
14466
14467 \layout Standard
14468
14469 MCS51 processors are available from many vendors and come in many different
14470  flavours.
14471  While they might differ considerably in respect to Special Function Registers
14472  the core MCS51 is usually not modified or is kept compatible.
14473
14474 \layout Subsection
14475
14476 pdata access by SFR
14477 \layout Standard
14478
14479 With the upcome of devices with internal xdata and flash memory devices
14480  using port P2
14481 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14482
14483 \end_inset
14484
14485  as dedicated I/O port is becoming more popular.
14486  Switching the high byte for pdata
14487 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14488
14489 \end_inset
14490
14491  access which was formerly done by port P2 is then achieved by a Special
14492  Function Register
14493 \begin_inset LatexCommand \index{sfr}
14494
14495 \end_inset
14496
14497 .
14498  In well-established MCS51 tradition the address of this
14499 \emph on
14500 sfr
14501 \emph default
14502  is where the chip designers decided to put it.
14503  Needless to say that they didn't agree on a common name either.
14504  So that the startup code can correctly initialize xdata variables, you
14505  should define an sfr with the name _XPAGE
14506 \family typewriter
14507
14508 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
14509
14510 \end_inset
14511
14512
14513 \family default
14514  at the appropriate location if the default, port P2, is not used for this.
14515  Some examples are:
14516 \layout Verse
14517
14518
14519 \family typewriter
14520 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
14521 \layout Verse
14522
14523
14524 \family typewriter
14525 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
14526 \layout Verse
14527
14528
14529 \family typewriter
14530 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
14531 \layout Standard
14532
14533 For more exotic implementations further customizations may be needed.
14534  See section
14535 \begin_inset LatexCommand \ref{sub:Startup-Code}
14536
14537 \end_inset
14538
14539  for other possibilities.
14540 \layout Subsection
14541
14542 Other Features available by SFR
14543 \layout Standard
14544
14545 Some MCS51 variants offer features like Double DPTR
14546 \begin_inset LatexCommand \index{DPTR}
14547
14548 \end_inset
14549
14550 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
14551  These are currently not used for the MCS51 port.
14552  If you absolutely need them you can fall back to inline assembly or submit
14553  a patch to SDCC.
14554 \layout Section
14555
14556 DS400 port
14557 \layout Standard
14558
14559 The DS80C400 microcontroller has a rich set of peripherals.
14560  In its built-in ROM library it includes functions to access some of the
14561  features, among them is a TCP stack with IP4 and IP6 support.
14562  Library headers (currently in beta status) and other files are provided
14563  at
14564 \size footnotesize
14565
14566 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
14567
14568 \end_inset
14569
14570 .
14571
14572 \layout Section
14573
14574 The Z80 and gbz80 port
14575 \layout Standard
14576
14577 SDCC can target both the Zilog
14578 \begin_inset LatexCommand \index{Z80}
14579
14580 \end_inset
14581
14582  and the Nintendo Gameboy's Z80-like gbz80
14583 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
14584
14585 \end_inset
14586
14587 .
14588  The Z80 port is passed through the same
14589 \emph on
14590 regressions tests
14591 \begin_inset LatexCommand \index{Regression test}
14592
14593 \end_inset
14594
14595
14596 \emph default
14597  as the MCS51 and DS390 ports, so floating point support, support for long
14598  variables and bitfield support is fine.
14599  See mailing lists and forums about interrupt routines.
14600 \layout Standard
14601
14602 As always, the code is the authoritative reference - see z80/ralloc.c and
14603  z80/gen.c.
14604  The stack
14605 \begin_inset LatexCommand \index{stack}
14606
14607 \end_inset
14608
14609  frame is similar to that generated by the IAR Z80 compiler.
14610  IX is used as the base pointer, HL and IY are used as a temporary registers,
14611  and BC and DE are available for holding variables.
14612  Return values
14613 \begin_inset LatexCommand \index{return value}
14614
14615 \end_inset
14616
14617  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
14618  bytes).
14619  The gbz80 port use the same set of registers for the return values, but
14620  in a different order of significance: E (one byte), DE (two bytes), or
14621  HLDE (four bytes).
14622 \layout Section
14623
14624 The HC08 port
14625 \layout Standard
14626
14627 The port to the Motorola HC08
14628 \begin_inset LatexCommand \index{HC08}
14629
14630 \end_inset
14631
14632  family has been added in October 2003, and is still undergoing some basic
14633  development.
14634  The code generator is complete, but the register allocation is still quite
14635  unoptimized.
14636  Some of the SDCC's standard C library functions have embedded non-HC08
14637  inline assembly and so are not yet usable.
14638 \newline
14639
14640 \newline
14641
14642 \layout Section
14643
14644 The PIC14 port
14645 \layout Standard
14646
14647 The 14bit PIC
14648 \begin_inset LatexCommand \index{PIC14}
14649
14650 \end_inset
14651
14652  port still requires a major effort from the development community.
14653  However it can work for very simple code.
14654 \layout Subsection
14655
14656 C code and 14bit PIC code page
14657 \begin_inset LatexCommand \index{code page (pic14)}
14658
14659 \end_inset
14660
14661  and RAM banks
14662 \begin_inset LatexCommand \index{RAM bank (pic14)}
14663
14664 \end_inset
14665
14666
14667 \layout Standard
14668
14669 The linker organizes allocation for the code page and RAM banks.
14670  It does not have intimate knowledge of the code flow.
14671  It will put all the code section of a single asm file into a single code
14672  page.
14673  In order to make use of multiple code pages, separate asm files must be
14674  used.
14675  The compiler treats all functions of a single C file as being in the same
14676  code page unless it is non static.
14677  The compiler treats all local variables of a single C file as being in
14678  the same RAM bank unless it is an extern.
14679 \newline
14680
14681 \newline
14682 To get the best follow these guide lines:
14683 \layout Enumerate
14684
14685 make local functions static, as non static functions require code page selection
14686  overhead.
14687 \layout Enumerate
14688
14689 Make local variables static as extern variables require RAM bank selection
14690  overhead.
14691 \layout Enumerate
14692
14693 For devices that have multiple code pages it is more efficient to use the
14694  same number of files as pages, i.e.
14695  for the 16F877 use 4 separate files and i.e.
14696  for the 16F874 use 2 separate files.
14697  This way the linker can put the code for each file into different code
14698  pages and the compiler can allocate reusable variables more efficiently
14699  and there's less page selection overhead.
14700  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
14701  instruction set) use 'unsigned char' whereever possible instead of 'int'.
14702 \layout Subsection
14703
14704 Creating a device include file
14705 \layout Standard
14706
14707 For generating a device include file use the support perl script inc2h.pl
14708  kept in directory support/script.
14709 \layout Subsection
14710
14711 Interrupt code
14712 \layout Standard
14713
14714 For the interrupt function, use the keyword 'interrupt'
14715 \begin_inset LatexCommand \index{interrupt}
14716
14717 \end_inset
14718
14719  with level number of 0 (PIC14 only has 1 interrupt so this number is only
14720  there to avoid a syntax error - it ought to be fixed).
14721  E.g.:
14722 \layout Verse
14723
14724
14725 \family typewriter
14726 void Intr(void) interrupt 0
14727 \newline
14728 {
14729 \newline
14730 \SpecialChar ~
14731 \SpecialChar ~
14732 T0IF = 0; /* Clear timer interrupt */
14733 \newline
14734 }
14735 \layout Subsection
14736
14737 Linking and assembling
14738 \layout Standard
14739
14740 For assembling you can use either GPUTILS'
14741 \begin_inset LatexCommand \index{gputils (pic tools)}
14742
14743 \end_inset
14744
14745  gpasm.exe or MPLAB's mpasmwin.exe.
14746  GPUTILS is available from
14747 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
14748
14749 \end_inset
14750
14751 .
14752  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
14753  If you use MPLAB and an interrupt function then the linker script file
14754  vectors section will need to be enlarged to link with mplink.
14755 \newline
14756
14757 \newline
14758 Here is a
14759 \family typewriter
14760 Makefile
14761 \family default
14762  using GPUTILS:
14763 \layout Verse
14764
14765
14766 \family typewriter
14767 .c.o:
14768 \newline
14769 \SpecialChar ~
14770 \SpecialChar ~
14771 \SpecialChar ~
14772 \SpecialChar ~
14773 \SpecialChar ~
14774 \SpecialChar ~
14775 \SpecialChar ~
14776 \SpecialChar ~
14777 sdcc -S -V -mpic14 -p16F877 $<
14778 \newline
14779 \SpecialChar ~
14780 \SpecialChar ~
14781 \SpecialChar ~
14782 \SpecialChar ~
14783 \SpecialChar ~
14784 \SpecialChar ~
14785 \SpecialChar ~
14786 \SpecialChar ~
14787 gpasm -c $*.asm
14788 \newline
14789
14790 \newline
14791 $(PRJ).hex: $(OBJS)
14792 \newline
14793 \SpecialChar ~
14794 \SpecialChar ~
14795 \SpecialChar ~
14796 \SpecialChar ~
14797 \SpecialChar ~
14798 \SpecialChar ~
14799 \SpecialChar ~
14800 \SpecialChar ~
14801 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
14802 \layout Standard
14803
14804 Here is a
14805 \family typewriter
14806 Makefile
14807 \family default
14808  using MPLAB:
14809 \layout Verse
14810
14811
14812 \family typewriter
14813 .c.o:
14814 \newline
14815 \SpecialChar ~
14816 \SpecialChar ~
14817 \SpecialChar ~
14818 \SpecialChar ~
14819 \SpecialChar ~
14820 \SpecialChar ~
14821 \SpecialChar ~
14822 \SpecialChar ~
14823 sdcc -S -V -mpic14 -p16F877 $<
14824 \newline
14825 \SpecialChar ~
14826 \SpecialChar ~
14827 \SpecialChar ~
14828 \SpecialChar ~
14829 \SpecialChar ~
14830 \SpecialChar ~
14831 \SpecialChar ~
14832 \SpecialChar ~
14833 mpasmwin /q /o $*.asm
14834 \newline
14835
14836 \newline
14837 $(PRJ).hex: $(OBJS)
14838 \newline
14839 \SpecialChar ~
14840 \SpecialChar ~
14841 \SpecialChar ~
14842 \SpecialChar ~
14843 \SpecialChar ~
14844 \SpecialChar ~
14845 \SpecialChar ~
14846 \SpecialChar ~
14847 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
14848 \layout Standard
14849
14850 Please note that indentations within a
14851 \family typewriter
14852  Makefile
14853 \family default
14854  have to be done with a tabulator character.
14855 \layout Section
14856
14857 The PIC16
14858 \begin_inset LatexCommand \index{PIC16}
14859
14860 \end_inset
14861
14862  port
14863 \layout Standard
14864
14865 The PIC16
14866 \begin_inset LatexCommand \index{PIC16}
14867
14868 \end_inset
14869
14870  port is the portion of SDCC that is responsible to produce code for the
14871  Microchip
14872 \begin_inset LatexCommand \index{Microchip}
14873
14874 \end_inset
14875
14876 (TM) microcontrollers with 16 bit core.
14877  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
14878 \layout Subsection
14879
14880 Global Options
14881 \layout Standard
14882
14883 PIC16 port supports the standard command line arguments as supposed, with
14884  the exception of certain cases that will be mentioned in the following
14885  list:
14886 \layout List
14887 \labelwidthstring 00.00.0000
14888
14889 -
14890 \begin_inset ERT
14891 status Collapsed
14892
14893 \layout Standard
14894
14895 \backslash
14896 /
14897 \end_inset
14898
14899 -stack-auto Auto variables that are function parameters, will be saved on
14900  stack by default.
14901
14902 \emph on
14903 There is no need to specify this in the command line.
14904 \layout List
14905 \labelwidthstring 00.00.0000
14906
14907 -
14908 \begin_inset ERT
14909 status Collapsed
14910
14911 \layout Standard
14912
14913 \backslash
14914 /
14915 \end_inset
14916
14917 -float-reent All floating point functions are reentrant by default.
14918
14919 \emph on
14920 There is no need to specifiy this in the command line.
14921 \layout List
14922 \labelwidthstring 00.00.0000
14923
14924 -
14925 \begin_inset ERT
14926 status Collapsed
14927
14928 \layout Standard
14929
14930 \backslash
14931 /
14932 \end_inset
14933
14934 -callee-saves See -
14935 \begin_inset ERT
14936 status Collapsed
14937
14938 \layout Standard
14939
14940 \backslash
14941 /
14942 \end_inset
14943
14944 -all-callee-saves
14945 \layout List
14946 \labelwidthstring 00.00.0000
14947
14948 -
14949 \begin_inset ERT
14950 status Collapsed
14951
14952 \layout Standard
14953
14954 \backslash
14955 /
14956 \end_inset
14957
14958 -all-callee-saves All function arguments are passed on stack by default.
14959
14960 \emph on
14961 There is no need to specify this in the command line.
14962 \layout List
14963 \labelwidthstring 00.00.0000
14964
14965 -
14966 \begin_inset ERT
14967 status Collapsed
14968
14969 \layout Standard
14970
14971 \backslash
14972 /
14973 \end_inset
14974
14975 -fommit-frame-pointer Frame pointer will be omitted when the function uses
14976  no local variables.
14977 \layout Subsection
14978
14979 Port Specific Options
14980 \begin_inset LatexCommand \index{Options PIC16}
14981
14982 \end_inset
14983
14984
14985 \layout Standard
14986
14987 The port specific options appear after the global options in the sdcc --help
14988  output.
14989 \layout Subsubsection
14990
14991 General Options
14992 \layout Standard
14993
14994 General options enable certain port features and optimizations.
14995 \layout List
14996 \labelwidthstring 00.00.0000
14997
14998 -
14999 \begin_inset ERT
15000 status Collapsed
15001
15002 \layout Standard
15003
15004 \backslash
15005 /
15006 \end_inset
15007
15008 -pgen-bank Instructs the port to insert BANKSEL directives before instructions
15009  that use the Bank Select Register (BSR).
15010 \layout List
15011 \labelwidthstring 00.00.0000
15012
15013 -
15014 \begin_inset ERT
15015 status Collapsed
15016
15017 \layout Standard
15018
15019 \backslash
15020 /
15021 \end_inset
15022
15023 -pomit-config-words Instructs the port to omit the generation of the configurati
15024 on words.
15025 \layout List
15026 \labelwidthstring 00.00.0000
15027
15028 -
15029 \begin_inset ERT
15030 status Collapsed
15031
15032 \layout Standard
15033
15034 \backslash
15035 /
15036 \end_inset
15037
15038 -pomit-ivt Instructs the port to omit the generation of the interrupt vectors
15039 \layout List
15040 \labelwidthstring 00.00.0000
15041
15042 -
15043 \begin_inset ERT
15044 status Collapsed
15045
15046 \layout Standard
15047
15048 \backslash
15049 /
15050 \end_inset
15051
15052 -pleave-reset-vector Used in conjuction with the previous command, instructs
15053  the port NOT to omit the reset vector.
15054 \layout List
15055 \labelwidthstring 00.00.0000
15056
15057 -
15058 \begin_inset ERT
15059 status Collapsed
15060
15061 \layout Standard
15062
15063 \backslash
15064 /
15065 \end_inset
15066
15067 -stack-model=[model] Used in conjuction with the command above.
15068  Defines the stack model to be used, valid stack models are :
15069 \begin_deeper
15070 \layout List
15071 \labelwidthstring 00.00.0000
15072
15073
15074 \emph on
15075 small
15076 \emph default
15077  Selects small stack model.
15078  8 bit stack and frame pointers.
15079  Supports 256 bytes stack size.
15080 \layout List
15081 \labelwidthstring 00.00.0000
15082
15083
15084 \emph on
15085 large
15086 \emph default
15087  Selects large stack model.
15088  16 bit stack and frame pointers.
15089  Supports 65536 bytes stack size.
15090 \end_deeper
15091 \layout List
15092 \labelwidthstring 00.00.0000
15093
15094 -
15095 \begin_inset ERT
15096 status Collapsed
15097
15098 \layout Standard
15099
15100 \backslash
15101 /
15102 \end_inset
15103
15104 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
15105  unitialized data variables with [kword].
15106  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
15107 \layout List
15108 \labelwidthstring 00.00.0000
15109
15110 -
15111 \begin_inset ERT
15112 status Collapsed
15113
15114 \layout Standard
15115
15116 \backslash
15117 /
15118 \end_inset
15119
15120 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
15121  Useful for bootloaders.
15122 \layout List
15123 \labelwidthstring 00.00.0000
15124
15125 -
15126 \begin_inset ERT
15127 status Collapsed
15128
15129 \layout Standard
15130
15131 \backslash
15132 /
15133 \end_inset
15134
15135 -asm= sets the full path and name of an external assembler to call.
15136 \layout List
15137 \labelwidthstring 00.00.0000
15138
15139 -
15140 \begin_inset ERT
15141 status Collapsed
15142
15143 \layout Standard
15144
15145 \backslash
15146 /
15147 \end_inset
15148
15149 -link= sets the full path and name of an external linker to call.
15150 \layout Subsubsection
15151
15152 Debugging Options
15153 \layout Standard
15154
15155 Debugging options enable extra debugging information in the output files.
15156 \layout List
15157 \labelwidthstring 00.00.0000
15158
15159 -
15160 \begin_inset ERT
15161 status Collapsed
15162
15163 \layout Standard
15164
15165 \backslash
15166 /
15167 \end_inset
15168
15169 -debug-xtra Similar to -
15170 \begin_inset ERT
15171 status Collapsed
15172
15173 \layout Standard
15174
15175 \backslash
15176 /
15177 \end_inset
15178
15179 -debug
15180 \begin_inset LatexCommand \index{-\/-debug}
15181
15182 \end_inset
15183
15184 , but dumps more information.
15185 \layout List
15186 \labelwidthstring 00.00.0000
15187
15188 -
15189 \begin_inset ERT
15190 status Collapsed
15191
15192 \layout Standard
15193
15194 \backslash
15195 /
15196 \end_inset
15197
15198 -debug-ralloc Force register allocator to dump <source>.d file with debugging
15199  information.
15200  <source> is the name of the file compiled.
15201 \layout List
15202 \labelwidthstring 00.00.0000
15203
15204 -
15205 \begin_inset ERT
15206 status Collapsed
15207
15208 \layout Standard
15209
15210 \backslash
15211 /
15212 \end_inset
15213
15214 -pcode-verbose Enable pcode debugging information in translation.
15215 \layout Subsection
15216
15217 Preprocessor Macros
15218 \layout Standard
15219
15220 PIC16 port defines the following preprocessor macros while translating a
15221  source.
15222 \layout Standard
15223 \align center
15224
15225 \begin_inset  Tabular
15226 <lyxtabular version="3" rows="2" columns="2">
15227 <features>
15228 <column alignment="center" valignment="top" leftline="true" width="0">
15229 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15230 <row topline="true" bottomline="true">
15231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15232 \begin_inset Text
15233
15234 \layout Standard
15235
15236 Macro
15237 \end_inset
15238 </cell>
15239 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15240 \begin_inset Text
15241
15242 \layout Standard
15243
15244 Description
15245 \end_inset
15246 </cell>
15247 </row>
15248 <row topline="true" bottomline="true">
15249 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15250 \begin_inset Text
15251
15252 \layout Standard
15253
15254 pic18fxxxx
15255 \end_inset
15256 </cell>
15257 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15258 \begin_inset Text
15259
15260 \layout Standard
15261
15262 MCU Identification.
15263
15264 \emph on
15265 xxxx
15266 \emph default
15267  is the microcontrol identification number, i.e.
15268  452, 6620, etc
15269 \end_inset
15270 </cell>
15271 </row>
15272 </lyxtabular>
15273
15274 \end_inset
15275
15276
15277 \layout Subsection
15278
15279 Directories
15280 \layout Standard
15281
15282 PIC16
15283 \begin_inset LatexCommand \index{PIC16}
15284
15285 \end_inset
15286
15287  port uses the following directories for searching header files and libraries.
15288 \layout Standard
15289 \align center
15290
15291 \begin_inset  Tabular
15292 <lyxtabular version="3" rows="3" columns="4">
15293 <features>
15294 <column alignment="center" valignment="top" leftline="true" width="0">
15295 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15296 <column alignment="center" valignment="top" width="0">
15297 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15298 <row topline="true" bottomline="true">
15299 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15300 \begin_inset Text
15301
15302 \layout Standard
15303
15304 Directory
15305 \end_inset
15306 </cell>
15307 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15308 \begin_inset Text
15309
15310 \layout Standard
15311
15312 Description
15313 \end_inset
15314 </cell>
15315 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15316 \begin_inset Text
15317
15318 \layout Standard
15319
15320 Target
15321 \end_inset
15322 </cell>
15323 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15324 \begin_inset Text
15325
15326 \layout Standard
15327
15328 Command prefix
15329 \end_inset
15330 </cell>
15331 </row>
15332 <row topline="true">
15333 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15334 \begin_inset Text
15335
15336 \layout Standard
15337
15338 PREFIX/sdcc/include/pic16
15339 \end_inset
15340 </cell>
15341 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15342 \begin_inset Text
15343
15344 \layout Standard
15345
15346 PIC16 specific headers
15347 \end_inset
15348 </cell>
15349 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15350 \begin_inset Text
15351
15352 \layout Standard
15353
15354 Compiler
15355 \end_inset
15356 </cell>
15357 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15358 \begin_inset Text
15359
15360 \layout Standard
15361
15362 -I
15363 \end_inset
15364 </cell>
15365 </row>
15366 <row topline="true" bottomline="true">
15367 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15368 \begin_inset Text
15369
15370 \layout Standard
15371
15372 PREFIX/sdcc/lib/pic16
15373 \end_inset
15374 </cell>
15375 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15376 \begin_inset Text
15377
15378 \layout Standard
15379
15380 PIC16 specific libraries
15381 \end_inset
15382 </cell>
15383 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15384 \begin_inset Text
15385
15386 \layout Standard
15387
15388 Linker
15389 \end_inset
15390 </cell>
15391 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15392 \begin_inset Text
15393
15394 \layout Standard
15395
15396 -L
15397 \end_inset
15398 </cell>
15399 </row>
15400 </lyxtabular>
15401
15402 \end_inset
15403
15404
15405 \layout Subsection
15406
15407 Pragmas
15408 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
15409
15410 \end_inset
15411
15412
15413 \layout Standard
15414
15415 PIC16 port currently supports the following pragmas:
15416 \layout List
15417 \labelwidthstring 00.00.0000
15418
15419 stack pragma stack forces the code generator to initialize the stack & frame
15420  pointers at a specific address.
15421  This is an adhoc solution since gplink does not support yet stack.
15422  When the gplink issue is resolved the pragma will be deprecated
15423 \begin_inset Foot
15424 collapsed true
15425
15426 \layout Standard
15427
15428
15429 \emph on
15430 It is important to initialize the stack, otherwise strange things can happen.
15431  Stack is not initialized by default because there are some sources that
15432  do not require it.
15433  (like library sources)
15434 \end_inset
15435
15436 .
15437 \newline
15438 The stack pragma should be used only once in a project.
15439  Multiple pragmas may result in indeterminate behaviour of the program.
15440 \layout LyX-Code
15441
15442 Example:
15443 \layout LyX-Code
15444
15445 \layout LyX-Code
15446
15447 /* initializes stack at RAM address 0x5ff */
15448 \layout LyX-Code
15449
15450 #pragma stack 0x5ff
15451 \layout List
15452 \labelwidthstring 00.00.0000
15453
15454 udata pragma udata instructs the compiler to emit code so that linker will
15455  place a variable at a specific memory bank
15456 \layout LyX-Code
15457
15458 Example:
15459 \layout LyX-Code
15460
15461 \layout LyX-Code
15462
15463 /* places variable foo at bank2 */
15464 \layout LyX-Code
15465
15466 #pragma udata bank2 foo
15467 \layout LyX-Code
15468
15469 char foo;
15470 \layout Standard
15471
15472 In order for this pragma to work there are some changes that must be made
15473  in the .lkr script used in link stage.
15474  In the following example a sample .lkr file is shown:
15475 \layout LyX-Code
15476
15477 \layout LyX-Code
15478
15479 // Sample linker script for the PIC18F452 processor
15480 \layout LyX-Code
15481
15482 LIBPATH .
15483 \layout LyX-Code
15484
15485 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
15486 \layout LyX-Code
15487
15488 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
15489 \layout LyX-Code
15490
15491 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
15492 \layout LyX-Code
15493
15494 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
15495 \layout LyX-Code
15496
15497 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
15498 \layout LyX-Code
15499
15500 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
15501 \layout LyX-Code
15502
15503 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
15504 \layout LyX-Code
15505
15506 \layout LyX-Code
15507
15508 DATABANK   NAME=gpr0       START=0x80           END=0xFF
15509 \layout LyX-Code
15510
15511 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
15512 \layout LyX-Code
15513
15514 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
15515 \layout LyX-Code
15516
15517 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
15518 \layout LyX-Code
15519
15520 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
15521 \layout LyX-Code
15522
15523 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
15524 \layout LyX-Code
15525
15526 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
15527 \layout LyX-Code
15528
15529 \layout LyX-Code
15530
15531 SECTION    NAME=CONFIG     ROM=config
15532 \layout LyX-Code
15533
15534 \layout LyX-Code
15535
15536 SECTION    NAME=bank0      RAM=gpr0
15537 \layout LyX-Code
15538
15539 SECTION    NAME=bank1      RAM=gpr1
15540 \layout LyX-Code
15541
15542 SECTION    NAME=bank2      RAM=gpr2
15543 \layout LyX-Code
15544
15545 SECTION    NAME=bank3      RAM=gpr3
15546 \layout LyX-Code
15547
15548 SECTION    NAME=bank4      RAM=gpr4
15549 \layout LyX-Code
15550
15551 SECTION    NAME=bank5      RAM=gpr5
15552 \layout Standard
15553
15554 The linker will recognise the section name set in the pragma statement and
15555  will position the variable at the memory bank set with the RAM field at
15556  the SECTION line in the linker script file.
15557 \layout Subsection
15558
15559 Header Files
15560 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
15561
15562 \end_inset
15563
15564
15565 \layout Standard
15566
15567 There is one main header file that can be included to the source files using
15568  the pic16 port.
15569  That file is the
15570 \series bold
15571 pic18fregs.h
15572 \series default
15573 .
15574  This header file contains the definitions for the processor special registers,
15575  so it is necessary if the source accesses them.
15576  It can be included by adding the following line in the beginning of the
15577  file:
15578 \layout LyX-Code
15579
15580 #include <pic18fregs.h>
15581 \layout Standard
15582
15583 The specific microcontroller is selected within the pic18fregs.h automatically,
15584  so the same source can be used with a variety of devices.
15585 \layout Subsection
15586
15587 Libraries
15588 \layout Standard
15589
15590 The libraries that PIC16
15591 \begin_inset LatexCommand \index{PIC16}
15592
15593 \end_inset
15594
15595  port depends on are the microcontroller device libraries which contain
15596  the symbol definitions for the microcontroller special function registers.
15597  These libraries have the format pic18fxxxx.lib, where
15598 \emph on
15599 xxxx
15600 \emph default
15601  is the microcontroller identification number.
15602  The specific library is selected automatically by the compiler at link
15603  stage according to the selected device.
15604 \layout Standard
15605
15606 Libraries are created with gplib which is part of the gputils package
15607 \begin_inset LatexCommand \url{http://gputils.sourceforge.net}
15608
15609 \end_inset
15610
15611 .
15612 \layout Subsection
15613
15614 Memory Models
15615 \layout Standard
15616
15617 The following memory models are supported by the PIC16 port:
15618 \layout Itemize
15619
15620 small model
15621 \layout Itemize
15622
15623 large model
15624 \layout Standard
15625
15626 Memory model affects the default size of pointers within the source.
15627  The sizes are shown in the next table:
15628 \layout Standard
15629 \align center
15630
15631 \begin_inset  Tabular
15632 <lyxtabular version="3" rows="3" columns="3">
15633 <features>
15634 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15635 <column alignment="center" valignment="top" leftline="true" width="0">
15636 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15637 <row topline="true" bottomline="true">
15638 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15639 \begin_inset Text
15640
15641 \layout Standard
15642
15643 Pointer sizes according to memory model
15644 \end_inset
15645 </cell>
15646 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15647 \begin_inset Text
15648
15649 \layout Standard
15650
15651 small model
15652 \end_inset
15653 </cell>
15654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15655 \begin_inset Text
15656
15657 \layout Standard
15658
15659 large model
15660 \end_inset
15661 </cell>
15662 </row>
15663 <row topline="true" bottomline="true">
15664 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15665 \begin_inset Text
15666
15667 \layout Standard
15668
15669 code pointers
15670 \end_inset
15671 </cell>
15672 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15673 \begin_inset Text
15674
15675 \layout Standard
15676
15677 16-bits
15678 \end_inset
15679 </cell>
15680 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15681 \begin_inset Text
15682
15683 \layout Standard
15684
15685 24-bits
15686 \end_inset
15687 </cell>
15688 </row>
15689 <row topline="true" bottomline="true">
15690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15691 \begin_inset Text
15692
15693 \layout Standard
15694
15695 data pointers
15696 \end_inset
15697 </cell>
15698 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
15699 \begin_inset Text
15700
15701 \layout Standard
15702
15703 16-bits
15704 \end_inset
15705 </cell>
15706 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15707 \begin_inset Text
15708
15709 \layout Standard
15710
15711 16-bits
15712 \end_inset
15713 </cell>
15714 </row>
15715 </lyxtabular>
15716
15717 \end_inset
15718
15719
15720 \layout Standard
15721
15722 It is advisable that all sources within a project are compiled with the
15723  same memory model.
15724  If one wants to override the default memory model, this can be done by
15725  declaring a pointer as
15726 \series bold
15727 far
15728 \series default
15729  or
15730 \series bold
15731 near
15732 \series default
15733 .
15734  Far selects large memory model's pointers, while near selects small memory
15735  model's pointers.
15736 \layout Standard
15737
15738 The standard device libraries (see
15739 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
15740
15741 \end_inset
15742
15743 ) contain no reference to pointers, so they can be used with both memory
15744  models.
15745 \layout Subsection
15746
15747 Stack
15748 \layout Standard
15749
15750 The stack implementation for the PIC16 port uses two indirect registers,
15751  FSR1 and FSR2.
15752 \layout List
15753 \labelwidthstring 00.00.0000
15754
15755 FSR1 is assigned as stack pointer
15756 \layout List
15757 \labelwidthstring 00.00.0000
15758
15759 FSR2 is assigned as frame pointer
15760 \layout Standard
15761
15762 The following stack models are supported by the PIC16 port
15763 \layout Itemize
15764
15765 small model
15766 \layout Itemize
15767
15768 large model
15769 \layout Standard
15770
15771
15772 \noun on
15773 Small
15774 \noun default
15775  model means that only the FSRxL byte is used to access stack and frame,
15776  while
15777 \emph on
15778 \noun on
15779 large
15780 \emph default
15781 \noun default
15782  uses both FSRxL and FSRxH registers.
15783  The following table shows the stack/frame pointers sizes according to stack
15784  model and the maximum space they can address:
15785 \layout Standard
15786 \align center
15787
15788 \begin_inset  Tabular
15789 <lyxtabular version="3" rows="3" columns="3">
15790 <features>
15791 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15792 <column alignment="center" valignment="top" leftline="true" width="0">
15793 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15794 <row topline="true" bottomline="true">
15795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15796 \begin_inset Text
15797
15798 \layout Standard
15799
15800 Stack & Frame pointer sizes according to stack model
15801 \end_inset
15802 </cell>
15803 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15804 \begin_inset Text
15805
15806 \layout Standard
15807
15808 small
15809 \end_inset
15810 </cell>
15811 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15812 \begin_inset Text
15813
15814 \layout Standard
15815
15816 large
15817 \end_inset
15818 </cell>
15819 </row>
15820 <row topline="true">
15821 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15822 \begin_inset Text
15823
15824 \layout Standard
15825
15826 Stack pointer FSR1
15827 \end_inset
15828 </cell>
15829 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15830 \begin_inset Text
15831
15832 \layout Standard
15833
15834 8-bits
15835 \end_inset
15836 </cell>
15837 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15838 \begin_inset Text
15839
15840 \layout Standard
15841
15842 16-bits
15843 \end_inset
15844 </cell>
15845 </row>
15846 <row topline="true" bottomline="true">
15847 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15848 \begin_inset Text
15849
15850 \layout Standard
15851
15852 Frame pointer FSR2
15853 \end_inset
15854 </cell>
15855 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15856 \begin_inset Text
15857
15858 \layout Standard
15859
15860 8-bits
15861 \end_inset
15862 </cell>
15863 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15864 \begin_inset Text
15865
15866 \layout Standard
15867
15868 16-bits
15869 \end_inset
15870 </cell>
15871 </row>
15872 </lyxtabular>
15873
15874 \end_inset
15875
15876
15877 \layout Standard
15878
15879
15880 \series bold
15881 Currently stack and frame pointers should be initialized explicit by the
15882  user at the desired Data RAM position (see
15883 \begin_inset LatexCommand \ref{sub:PIC16_Pragmas}
15884
15885 \end_inset
15886
15887  Pragma stack).
15888  Uninitialized stack and frame pointers can result in unexpected behavior
15889  of the resulting binary.
15890 \layout Subsection
15891
15892 Function return values
15893 \layout Standard
15894
15895 Return values from functions are placed to the appropriate registers following
15896  a modified Microchip policy optimized for SDCC.
15897  The following table shows these registers:
15898 \layout Standard
15899 \align center
15900
15901 \begin_inset  Tabular
15902 <lyxtabular version="3" rows="6" columns="2">
15903 <features>
15904 <column alignment="center" valignment="top" leftline="true" width="0">
15905 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15906 <row topline="true" bottomline="true">
15907 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15908 \begin_inset Text
15909
15910 \layout Standard
15911
15912 size
15913 \end_inset
15914 </cell>
15915 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15916 \begin_inset Text
15917
15918 \layout Standard
15919
15920 destination register
15921 \end_inset
15922 </cell>
15923 </row>
15924 <row topline="true">
15925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15926 \begin_inset Text
15927
15928 \layout Standard
15929
15930 8 bits
15931 \end_inset
15932 </cell>
15933 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15934 \begin_inset Text
15935
15936 \layout Standard
15937
15938 WREG
15939 \end_inset
15940 </cell>
15941 </row>
15942 <row topline="true">
15943 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15944 \begin_inset Text
15945
15946 \layout Standard
15947
15948 16 bits
15949 \end_inset
15950 </cell>
15951 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15952 \begin_inset Text
15953
15954 \layout Standard
15955
15956 PRODL:WREG
15957 \end_inset
15958 </cell>
15959 </row>
15960 <row topline="true">
15961 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15962 \begin_inset Text
15963
15964 \layout Standard
15965
15966 24 bits
15967 \end_inset
15968 </cell>
15969 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15970 \begin_inset Text
15971
15972 \layout Standard
15973
15974 PRODH:PRODL:WREG
15975 \end_inset
15976 </cell>
15977 </row>
15978 <row topline="true">
15979 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15980 \begin_inset Text
15981
15982 \layout Standard
15983
15984 32 bits
15985 \end_inset
15986 </cell>
15987 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15988 \begin_inset Text
15989
15990 \layout Standard
15991
15992 FSR0L:PRODH:PRODL:WREG
15993 \end_inset
15994 </cell>
15995 </row>
15996 <row topline="true" bottomline="true">
15997 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15998 \begin_inset Text
15999
16000 \layout Standard
16001
16002 >32 bits
16003 \end_inset
16004 </cell>
16005 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16006 \begin_inset Text
16007
16008 \layout Standard
16009
16010 on stack, FSR0 points to the beginning
16011 \end_inset
16012 </cell>
16013 </row>
16014 </lyxtabular>
16015
16016 \end_inset
16017
16018
16019 \layout Subsection
16020
16021 Interrupts
16022 \layout Standard
16023
16024 When entering an interrupt, currently the PIC16
16025 \begin_inset LatexCommand \index{PIC16}
16026
16027 \end_inset
16028
16029  port automatically saves the following registers:
16030 \layout Itemize
16031
16032 WREG
16033 \layout Itemize
16034
16035 STATUS
16036 \layout Itemize
16037
16038 BSR
16039 \layout Itemize
16040
16041 PROD (PRODL and PRODH)
16042 \layout Itemize
16043
16044 FSR0 (FSR0L and FSR0H)
16045 \layout Standard
16046
16047 These registers are restored upon return from the interrupt routine.
16048
16049 \layout Standard
16050
16051 When entering a high priority interrupt WREG, STATUS and BSR are not explicit
16052  saved by software.
16053  The hardware shadow registers for WREG, STATUS and BSR are used in these
16054  cases.
16055 \layout Standard
16056
16057
16058 \begin_inset Foot
16059 collapsed false
16060
16061 \layout Standard
16062
16063 NOTE that when the _naked attribute is specified for an interrupt routine,
16064  then NO registers are stored or restored.
16065 \end_inset
16066
16067 .
16068 \layout Chapter
16069
16070 Debugging with SDCDB
16071 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
16072
16073 \end_inset
16074
16075
16076 \begin_inset LatexCommand \index{sdcdb (debugger)}
16077
16078 \end_inset
16079
16080
16081 \layout Standard
16082
16083 SDCC is distributed with a source level debugger
16084 \begin_inset LatexCommand \index{Debugger}
16085
16086 \end_inset
16087
16088 .
16089  The debugger uses a command line interface, the command repertoire of the
16090  debugger has been kept as close to gdb
16091 \begin_inset LatexCommand \index{gdb}
16092
16093 \end_inset
16094
16095  (the GNU debugger) as possible.
16096  The configuration and build process is part of the standard compiler installati
16097 on, which also builds and installs the debugger in the target directory
16098  specified during configuration.
16099  The debugger allows you debug BOTH at the C source and at the ASM source
16100  level.
16101  Sdcdb is available on Unix platforms only.
16102 \layout Section
16103
16104 Compiling for Debugging
16105 \layout Standard
16106
16107 The -
16108 \begin_inset ERT
16109 status Collapsed
16110
16111 \layout Standard
16112
16113 \backslash
16114 /
16115 \end_inset
16116
16117 -debug
16118 \begin_inset LatexCommand \index{-\/-debug}
16119
16120 \end_inset
16121
16122  option must be specified for all files for which debug information is to
16123  be generated.
16124  The complier generates a .adb file for each of these files.
16125  The linker creates the .cdb
16126 \begin_inset LatexCommand \index{<file>.cdb}
16127
16128 \end_inset
16129
16130  file from the .adb
16131 \begin_inset LatexCommand \index{<file>.adb}
16132
16133 \end_inset
16134
16135  files and the address information.
16136  This .cdb is used by the debugger.
16137 \layout Section
16138
16139 How the Debugger Works
16140 \layout Standard
16141
16142 When the -
16143 \begin_inset ERT
16144 status Collapsed
16145
16146 \layout Standard
16147
16148 \backslash
16149 /
16150 \end_inset
16151
16152 -debug option is specified the compiler generates extra symbol information
16153  some of which are put into the assembler source and some are put into the
16154  .adb file.
16155   Then the linker creates the .cdb file from the individual .adb files with
16156  the address information for the symbols.
16157  The debugger reads the symbolic information generated by the compiler &
16158  the address information generated by the linker.
16159  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
16160  execution is controlled by the debugger.
16161  When a command is issued for the debugger, it translates it into appropriate
16162  commands for the simulator.
16163 \layout Section
16164
16165 Starting the Debugger
16166 \layout Standard
16167
16168 The debugger can be started using the following command line.
16169  (Assume the file you are debugging has the file name foo).
16170 \newline
16171
16172 \newline
16173
16174 \family sans
16175 \series bold
16176 sdcdb foo
16177 \newline
16178
16179 \family default
16180 \series default
16181
16182 \newline
16183 The debugger will look for the following files.
16184 \layout Itemize
16185
16186 foo.c - the source file.
16187 \layout Itemize
16188
16189 foo.cdb - the debugger symbol information file.
16190 \layout Itemize
16191
16192 foo.ihx - the Intel hex format
16193 \begin_inset LatexCommand \index{Intel hex format}
16194
16195 \end_inset
16196
16197  object file.
16198 \layout Section
16199
16200 Command Line Options.
16201 \layout Itemize
16202
16203 -
16204 \begin_inset ERT
16205 status Collapsed
16206
16207 \layout Standard
16208
16209 \backslash
16210 /
16211 \end_inset
16212
16213 -directory=<source file directory> this option can used to specify the directory
16214  search list.
16215  The debugger will look into the directory list specified for source, cdb
16216  & ihx files.
16217  The items in the directory list must be separated by ':', e.g.
16218  if the source files can be in the directories /home/src1 and /home/src2,
16219  the -
16220 \begin_inset ERT
16221 status Collapsed
16222
16223 \layout Standard
16224
16225 \backslash
16226 /
16227 \end_inset
16228
16229 -directory option should be -
16230 \begin_inset ERT
16231 status Collapsed
16232
16233 \layout Standard
16234
16235 \backslash
16236 /
16237 \end_inset
16238
16239 -directory=/home/src1:/home/src2.
16240  Note there can be no spaces in the option.
16241
16242 \layout Itemize
16243
16244 -cd <directory> - change to the <directory>.
16245 \layout Itemize
16246
16247 -fullname - used by GUI front ends.
16248 \layout Itemize
16249
16250 -cpu <cpu-type> - this argument is passed to the simulator please see the
16251  simulator docs for details.
16252 \layout Itemize
16253
16254 -X <Clock frequency > this options is passed to the simulator please see
16255  the simulator docs for details.
16256 \layout Itemize
16257
16258 -s <serial port file> passed to simulator see the simulator docs for details.
16259 \layout Itemize
16260
16261 -S <serial in,out> passed to simulator see the simulator docs for details.
16262 \layout Itemize
16263
16264 -k <port number> passed to simulator see the simulator docs for details.
16265 \layout Section
16266
16267 Debugger Commands.
16268 \layout Standard
16269
16270 As mentioned earlier the command interface for the debugger has been deliberatel
16271 y kept as close the GNU debugger gdb, as possible.
16272  This will help the integration with existing graphical user interfaces
16273  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
16274  If you use a graphical user interface for the debugger you can skip the
16275  next sections.
16276 \layout Subsubsection*
16277
16278 break [line | file:line | function | file:function]
16279 \layout Standard
16280
16281 Set breakpoint at specified line or function:
16282 \newline
16283
16284 \newline
16285
16286 \family sans
16287 \series bold
16288 sdcdb>break 100
16289 \newline
16290 sdcdb>break foo.c:100
16291 \newline
16292 sdcdb>break funcfoo
16293 \newline
16294 sdcdb>break foo.c:funcfoo
16295 \layout Subsubsection*
16296
16297 clear [line | file:line | function | file:function ]
16298 \layout Standard
16299
16300 Clear breakpoint at specified line or function:
16301 \newline
16302
16303 \newline
16304
16305 \family sans
16306 \series bold
16307 sdcdb>clear 100
16308 \newline
16309 sdcdb>clear foo.c:100
16310 \newline
16311 sdcdb>clear funcfoo
16312 \newline
16313 sdcdb>clear foo.c:funcfoo
16314 \layout Subsubsection*
16315
16316 continue
16317 \layout Standard
16318
16319 Continue program being debugged, after breakpoint.
16320 \layout Subsubsection*
16321
16322 finish
16323 \layout Standard
16324
16325 Execute till the end of the current function.
16326 \layout Subsubsection*
16327
16328 delete [n]
16329 \layout Standard
16330
16331 Delete breakpoint number 'n'.
16332  If used without any option clear ALL user defined break points.
16333 \layout Subsubsection*
16334
16335 info [break | stack | frame | registers ]
16336 \layout Itemize
16337
16338 info break - list all breakpoints
16339 \layout Itemize
16340
16341 info stack - show the function call stack.
16342 \layout Itemize
16343
16344 info frame - show information about the current execution frame.
16345 \layout Itemize
16346
16347 info registers - show content of all registers.
16348 \layout Subsubsection*
16349
16350 step
16351 \layout Standard
16352
16353 Step program until it reaches a different source line.
16354  Note: pressing <return> repeats the last command.
16355 \layout Subsubsection*
16356
16357 next
16358 \layout Standard
16359
16360 Step program, proceeding through subroutine calls.
16361 \layout Subsubsection*
16362
16363 run
16364 \layout Standard
16365
16366 Start debugged program.
16367 \layout Subsubsection*
16368
16369 ptype variable
16370 \layout Standard
16371
16372 Print type information of the variable.
16373 \layout Subsubsection*
16374
16375 print variable
16376 \layout Standard
16377
16378 print value of variable.
16379 \layout Subsubsection*
16380
16381 file filename
16382 \layout Standard
16383
16384 load the given file name.
16385  Note this is an alternate method of loading file for debugging.
16386 \layout Subsubsection*
16387
16388 frame
16389 \layout Standard
16390
16391 print information about current frame.
16392 \layout Subsubsection*
16393
16394 set srcmode
16395 \layout Standard
16396
16397 Toggle between C source & assembly source.
16398 \layout Subsubsection*
16399
16400 ! simulator command
16401 \layout Standard
16402
16403 Send the string following '!' to the simulator, the simulator response is
16404  displayed.
16405  Note the debugger does not interpret the command being sent to the simulator,
16406  so if a command like 'go' is sent the debugger can loose its execution
16407  context and may display incorrect values.
16408 \layout Subsubsection*
16409
16410 quit
16411 \layout Standard
16412
16413 "Watch me now.
16414  Iam going Down.
16415  My name is Bobby Brown"
16416 \layout Section
16417
16418 Interfacing with XEmacs
16419 \begin_inset LatexCommand \index{XEmacs}
16420
16421 \end_inset
16422
16423
16424 \begin_inset LatexCommand \index{Emacs}
16425
16426 \end_inset
16427
16428 .
16429 \layout Standard
16430
16431 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
16432  sdcdb.el and sdcdbsrc.el.
16433  These two files can be found in the $(prefix)/bin directory after the installat
16434 ion is complete.
16435  These files need to be loaded into XEmacs for the interface to work.
16436  This can be done at XEmacs startup time by inserting the following into
16437  your '.xemacs' file (which can be found in your HOME directory):
16438 \newline
16439
16440 \newline
16441
16442 \family typewriter
16443 (load-file sdcdbsrc.el)
16444 \family default
16445
16446 \newline
16447
16448 \newline
16449 .xemacs is a lisp file so the () around the command is REQUIRED.
16450  The files can also be loaded dynamically while XEmacs is running, set the
16451  environment variable 'EMACSLOADPATH' to the installation bin directory
16452  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
16453  To start the interface enter the following command:
16454 \newline
16455
16456 \newline
16457
16458 \family sans
16459 \series bold
16460 ESC-x sdcdbsrc
16461 \family default
16462 \series default
16463
16464 \newline
16465
16466 \newline
16467 You will prompted to enter the file name to be debugged.
16468
16469 \newline
16470
16471 \newline
16472 The command line options that are passed to the simulator directly are bound
16473  to default values in the file sdcdbsrc.el.
16474  The variables are listed below, these values maybe changed as required.
16475 \layout Itemize
16476
16477 sdcdbsrc-cpu-type '51
16478 \layout Itemize
16479
16480 sdcdbsrc-frequency '11059200
16481 \layout Itemize
16482
16483 sdcdbsrc-serial nil
16484 \layout Standard
16485
16486 The following is a list of key mapping for the debugger interface.
16487 \layout Standard
16488
16489 \SpecialChar ~
16490
16491 \family typewriter
16492
16493 \newline
16494 ;;\SpecialChar ~
16495 Current Listing ::
16496 \newline
16497 ;;key\SpecialChar ~
16498 \SpecialChar ~
16499 \SpecialChar ~
16500 \SpecialChar ~
16501 \SpecialChar ~
16502 \SpecialChar ~
16503 \SpecialChar ~
16504 \SpecialChar ~
16505 \SpecialChar ~
16506 \SpecialChar ~
16507 \SpecialChar ~
16508 \SpecialChar ~
16509 \SpecialChar ~
16510 \SpecialChar ~
16511 binding\SpecialChar ~
16512 \SpecialChar ~
16513 \SpecialChar ~
16514 \SpecialChar ~
16515 \SpecialChar ~
16516 \SpecialChar ~
16517 \SpecialChar ~
16518 \SpecialChar ~
16519 \SpecialChar ~
16520 \SpecialChar ~
16521 \SpecialChar ~
16522 \SpecialChar ~
16523 \SpecialChar ~
16524 \SpecialChar ~
16525 \SpecialChar ~
16526 \SpecialChar ~
16527 \SpecialChar ~
16528 \SpecialChar ~
16529 \SpecialChar ~
16530 \SpecialChar ~
16531 \SpecialChar ~
16532 \SpecialChar ~
16533 Comment
16534 \newline
16535 ;;---\SpecialChar ~
16536 \SpecialChar ~
16537 \SpecialChar ~
16538 \SpecialChar ~
16539 \SpecialChar ~
16540 \SpecialChar ~
16541 \SpecialChar ~
16542 \SpecialChar ~
16543 \SpecialChar ~
16544 \SpecialChar ~
16545 \SpecialChar ~
16546 \SpecialChar ~
16547 \SpecialChar ~
16548 \SpecialChar ~
16549 -------\SpecialChar ~
16550 \SpecialChar ~
16551 \SpecialChar ~
16552 \SpecialChar ~
16553 \SpecialChar ~
16554 \SpecialChar ~
16555 \SpecialChar ~
16556 \SpecialChar ~
16557 \SpecialChar ~
16558 \SpecialChar ~
16559 \SpecialChar ~
16560 \SpecialChar ~
16561 \SpecialChar ~
16562 \SpecialChar ~
16563 \SpecialChar ~
16564 \SpecialChar ~
16565 \SpecialChar ~
16566 \SpecialChar ~
16567 \SpecialChar ~
16568 \SpecialChar ~
16569 \SpecialChar ~
16570 \SpecialChar ~
16571 -------
16572 \newline
16573 ;;
16574 \newline
16575 ;;\SpecialChar ~
16576 n\SpecialChar ~
16577 \SpecialChar ~
16578 \SpecialChar ~
16579 \SpecialChar ~
16580 \SpecialChar ~
16581 \SpecialChar ~
16582 \SpecialChar ~
16583 \SpecialChar ~
16584 \SpecialChar ~
16585 \SpecialChar ~
16586 \SpecialChar ~
16587 \SpecialChar ~
16588 \SpecialChar ~
16589 \SpecialChar ~
16590 \SpecialChar ~
16591 sdcdb-next-from-src\SpecialChar ~
16592 \SpecialChar ~
16593 \SpecialChar ~
16594 \SpecialChar ~
16595 \SpecialChar ~
16596 \SpecialChar ~
16597 \SpecialChar ~
16598 \SpecialChar ~
16599 \SpecialChar ~
16600 \SpecialChar ~
16601 SDCDB next command
16602 \newline
16603 ;;\SpecialChar ~
16604 b\SpecialChar ~
16605 \SpecialChar ~
16606 \SpecialChar ~
16607 \SpecialChar ~
16608 \SpecialChar ~
16609 \SpecialChar ~
16610 \SpecialChar ~
16611 \SpecialChar ~
16612 \SpecialChar ~
16613 \SpecialChar ~
16614 \SpecialChar ~
16615 \SpecialChar ~
16616 \SpecialChar ~
16617 \SpecialChar ~
16618 \SpecialChar ~
16619 sdcdb-back-from-src\SpecialChar ~
16620 \SpecialChar ~
16621 \SpecialChar ~
16622 \SpecialChar ~
16623 \SpecialChar ~
16624 \SpecialChar ~
16625 \SpecialChar ~
16626 \SpecialChar ~
16627 \SpecialChar ~
16628 \SpecialChar ~
16629 SDCDB back command
16630 \newline
16631 ;;\SpecialChar ~
16632 c\SpecialChar ~
16633 \SpecialChar ~
16634 \SpecialChar ~
16635 \SpecialChar ~
16636 \SpecialChar ~
16637 \SpecialChar ~
16638 \SpecialChar ~
16639 \SpecialChar ~
16640 \SpecialChar ~
16641 \SpecialChar ~
16642 \SpecialChar ~
16643 \SpecialChar ~
16644 \SpecialChar ~
16645 \SpecialChar ~
16646 \SpecialChar ~
16647 sdcdb-cont-from-src\SpecialChar ~
16648 \SpecialChar ~
16649 \SpecialChar ~
16650 \SpecialChar ~
16651 \SpecialChar ~
16652 \SpecialChar ~
16653 \SpecialChar ~
16654 \SpecialChar ~
16655 \SpecialChar ~
16656 \SpecialChar ~
16657 SDCDB continue command
16658 \newline
16659 ;;\SpecialChar ~
16660 s\SpecialChar ~
16661 \SpecialChar ~
16662 \SpecialChar ~
16663 \SpecialChar ~
16664 \SpecialChar ~
16665 \SpecialChar ~
16666 \SpecialChar ~
16667 \SpecialChar ~
16668 \SpecialChar ~
16669 \SpecialChar ~
16670 \SpecialChar ~
16671 \SpecialChar ~
16672 \SpecialChar ~
16673 \SpecialChar ~
16674 \SpecialChar ~
16675 sdcdb-step-from-src\SpecialChar ~
16676 \SpecialChar ~
16677 \SpecialChar ~
16678 \SpecialChar ~
16679 \SpecialChar ~
16680 \SpecialChar ~
16681 \SpecialChar ~
16682 \SpecialChar ~
16683 \SpecialChar ~
16684 \SpecialChar ~
16685 SDCDB step command
16686 \newline
16687 ;;\SpecialChar ~
16688 ?\SpecialChar ~
16689 \SpecialChar ~
16690 \SpecialChar ~
16691 \SpecialChar ~
16692 \SpecialChar ~
16693 \SpecialChar ~
16694 \SpecialChar ~
16695 \SpecialChar ~
16696 \SpecialChar ~
16697 \SpecialChar ~
16698 \SpecialChar ~
16699 \SpecialChar ~
16700 \SpecialChar ~
16701 \SpecialChar ~
16702 \SpecialChar ~
16703 sdcdb-whatis-c-sexp\SpecialChar ~
16704 \SpecialChar ~
16705 \SpecialChar ~
16706 \SpecialChar ~
16707 \SpecialChar ~
16708 \SpecialChar ~
16709 \SpecialChar ~
16710 \SpecialChar ~
16711 \SpecialChar ~
16712 \SpecialChar ~
16713 SDCDB ptypecommand for data at
16714 \newline
16715 ;;\SpecialChar ~
16716 \SpecialChar ~
16717 \SpecialChar ~
16718 \SpecialChar ~
16719 \SpecialChar ~
16720 \SpecialChar ~
16721 \SpecialChar ~
16722 \SpecialChar ~
16723 \SpecialChar ~
16724 \SpecialChar ~
16725 \SpecialChar ~
16726 \SpecialChar ~
16727 \SpecialChar ~
16728 \SpecialChar ~
16729 \SpecialChar ~
16730 \SpecialChar ~
16731 \SpecialChar ~
16732 \SpecialChar ~
16733 \SpecialChar ~
16734 \SpecialChar ~
16735 \SpecialChar ~
16736 \SpecialChar ~
16737 \SpecialChar ~
16738 \SpecialChar ~
16739 \SpecialChar ~
16740 \SpecialChar ~
16741 \SpecialChar ~
16742 \SpecialChar ~
16743 \SpecialChar ~
16744 \SpecialChar ~
16745 \SpecialChar ~
16746 \SpecialChar ~
16747 \SpecialChar ~
16748 \SpecialChar ~
16749 \SpecialChar ~
16750 \SpecialChar ~
16751 \SpecialChar ~
16752 \SpecialChar ~
16753 \SpecialChar ~
16754 \SpecialChar ~
16755 \SpecialChar ~
16756 \SpecialChar ~
16757 \SpecialChar ~
16758 \SpecialChar ~
16759 \SpecialChar ~
16760 \SpecialChar ~
16761 \SpecialChar ~
16762 buffer point
16763 \newline
16764 ;;\SpecialChar ~
16765 x\SpecialChar ~
16766 \SpecialChar ~
16767 \SpecialChar ~
16768 \SpecialChar ~
16769 \SpecialChar ~
16770 \SpecialChar ~
16771 \SpecialChar ~
16772 \SpecialChar ~
16773 \SpecialChar ~
16774 \SpecialChar ~
16775 \SpecialChar ~
16776 \SpecialChar ~
16777 \SpecialChar ~
16778 \SpecialChar ~
16779 \SpecialChar ~
16780 sdcdbsrc-delete\SpecialChar ~
16781 \SpecialChar ~
16782 \SpecialChar ~
16783 \SpecialChar ~
16784 \SpecialChar ~
16785 \SpecialChar ~
16786 \SpecialChar ~
16787 \SpecialChar ~
16788 \SpecialChar ~
16789 \SpecialChar ~
16790 \SpecialChar ~
16791 \SpecialChar ~
16792 \SpecialChar ~
16793 \SpecialChar ~
16794 SDCDB Delete all breakpoints if no arg
16795 \newline
16796 ;;\SpecialChar ~
16797 \SpecialChar ~
16798 \SpecialChar ~
16799 \SpecialChar ~
16800 \SpecialChar ~
16801 \SpecialChar ~
16802 \SpecialChar ~
16803 \SpecialChar ~
16804 \SpecialChar ~
16805 \SpecialChar ~
16806 \SpecialChar ~
16807 \SpecialChar ~
16808 \SpecialChar ~
16809 \SpecialChar ~
16810 \SpecialChar ~
16811 \SpecialChar ~
16812 \SpecialChar ~
16813 \SpecialChar ~
16814 \SpecialChar ~
16815 \SpecialChar ~
16816 \SpecialChar ~
16817 \SpecialChar ~
16818 \SpecialChar ~
16819 \SpecialChar ~
16820 \SpecialChar ~
16821 \SpecialChar ~
16822 \SpecialChar ~
16823 \SpecialChar ~
16824 \SpecialChar ~
16825 \SpecialChar ~
16826 \SpecialChar ~
16827 \SpecialChar ~
16828 \SpecialChar ~
16829 \SpecialChar ~
16830 \SpecialChar ~
16831 \SpecialChar ~
16832 \SpecialChar ~
16833 \SpecialChar ~
16834 \SpecialChar ~
16835 \SpecialChar ~
16836 \SpecialChar ~
16837 \SpecialChar ~
16838 \SpecialChar ~
16839 \SpecialChar ~
16840 \SpecialChar ~
16841 \SpecialChar ~
16842 \SpecialChar ~
16843 given or delete arg (C-u arg x)
16844 \newline
16845 ;;\SpecialChar ~
16846 m\SpecialChar ~
16847 \SpecialChar ~
16848 \SpecialChar ~
16849 \SpecialChar ~
16850 \SpecialChar ~
16851 \SpecialChar ~
16852 \SpecialChar ~
16853 \SpecialChar ~
16854 \SpecialChar ~
16855 \SpecialChar ~
16856 \SpecialChar ~
16857 \SpecialChar ~
16858 \SpecialChar ~
16859 \SpecialChar ~
16860 \SpecialChar ~
16861 sdcdbsrc-frame\SpecialChar ~
16862 \SpecialChar ~
16863 \SpecialChar ~
16864 \SpecialChar ~
16865 \SpecialChar ~
16866 \SpecialChar ~
16867 \SpecialChar ~
16868 \SpecialChar ~
16869 \SpecialChar ~
16870 \SpecialChar ~
16871 \SpecialChar ~
16872 \SpecialChar ~
16873 \SpecialChar ~
16874 \SpecialChar ~
16875 \SpecialChar ~
16876 SDCDB Display current frame if no arg,
16877 \newline
16878 ;;\SpecialChar ~
16879 \SpecialChar ~
16880 \SpecialChar ~
16881 \SpecialChar ~
16882 \SpecialChar ~
16883 \SpecialChar ~
16884 \SpecialChar ~
16885 \SpecialChar ~
16886 \SpecialChar ~
16887 \SpecialChar ~
16888 \SpecialChar ~
16889 \SpecialChar ~
16890 \SpecialChar ~
16891 \SpecialChar ~
16892 \SpecialChar ~
16893 \SpecialChar ~
16894 \SpecialChar ~
16895 \SpecialChar ~
16896 \SpecialChar ~
16897 \SpecialChar ~
16898 \SpecialChar ~
16899 \SpecialChar ~
16900 \SpecialChar ~
16901 \SpecialChar ~
16902 \SpecialChar ~
16903 \SpecialChar ~
16904 \SpecialChar ~
16905 \SpecialChar ~
16906 \SpecialChar ~
16907 \SpecialChar ~
16908 \SpecialChar ~
16909 \SpecialChar ~
16910 \SpecialChar ~
16911 \SpecialChar ~
16912 \SpecialChar ~
16913 \SpecialChar ~
16914 \SpecialChar ~
16915 \SpecialChar ~
16916 \SpecialChar ~
16917 \SpecialChar ~
16918 \SpecialChar ~
16919 \SpecialChar ~
16920 \SpecialChar ~
16921 \SpecialChar ~
16922 \SpecialChar ~
16923 \SpecialChar ~
16924 \SpecialChar ~
16925 given or display frame arg
16926 \newline
16927 ;;\SpecialChar ~
16928 \SpecialChar ~
16929 \SpecialChar ~
16930 \SpecialChar ~
16931 \SpecialChar ~
16932 \SpecialChar ~
16933 \SpecialChar ~
16934 \SpecialChar ~
16935 \SpecialChar ~
16936 \SpecialChar ~
16937 \SpecialChar ~
16938 \SpecialChar ~
16939 \SpecialChar ~
16940 \SpecialChar ~
16941 \SpecialChar ~
16942 \SpecialChar ~
16943 \SpecialChar ~
16944 \SpecialChar ~
16945 \SpecialChar ~
16946 \SpecialChar ~
16947 \SpecialChar ~
16948 \SpecialChar ~
16949 \SpecialChar ~
16950 \SpecialChar ~
16951 \SpecialChar ~
16952 \SpecialChar ~
16953 \SpecialChar ~
16954 \SpecialChar ~
16955 \SpecialChar ~
16956 \SpecialChar ~
16957 \SpecialChar ~
16958 \SpecialChar ~
16959 \SpecialChar ~
16960 \SpecialChar ~
16961 \SpecialChar ~
16962 \SpecialChar ~
16963 \SpecialChar ~
16964 \SpecialChar ~
16965 \SpecialChar ~
16966 \SpecialChar ~
16967 \SpecialChar ~
16968 \SpecialChar ~
16969 \SpecialChar ~
16970 \SpecialChar ~
16971 \SpecialChar ~
16972 \SpecialChar ~
16973 \SpecialChar ~
16974 buffer point
16975 \newline
16976 ;;\SpecialChar ~
16977 !\SpecialChar ~
16978 \SpecialChar ~
16979 \SpecialChar ~
16980 \SpecialChar ~
16981 \SpecialChar ~
16982 \SpecialChar ~
16983 \SpecialChar ~
16984 \SpecialChar ~
16985 \SpecialChar ~
16986 \SpecialChar ~
16987 \SpecialChar ~
16988 \SpecialChar ~
16989 \SpecialChar ~
16990 \SpecialChar ~
16991 \SpecialChar ~
16992 sdcdbsrc-goto-sdcdb\SpecialChar ~
16993 \SpecialChar ~
16994 \SpecialChar ~
16995 \SpecialChar ~
16996 \SpecialChar ~
16997 \SpecialChar ~
16998 \SpecialChar ~
16999 \SpecialChar ~
17000 \SpecialChar ~
17001 \SpecialChar ~
17002 Goto the SDCDB output buffer
17003 \newline
17004 ;;\SpecialChar ~
17005 p\SpecialChar ~
17006 \SpecialChar ~
17007 \SpecialChar ~
17008 \SpecialChar ~
17009 \SpecialChar ~
17010 \SpecialChar ~
17011 \SpecialChar ~
17012 \SpecialChar ~
17013 \SpecialChar ~
17014 \SpecialChar ~
17015 \SpecialChar ~
17016 \SpecialChar ~
17017 \SpecialChar ~
17018 \SpecialChar ~
17019 \SpecialChar ~
17020 sdcdb-print-c-sexp\SpecialChar ~
17021 \SpecialChar ~
17022 \SpecialChar ~
17023 \SpecialChar ~
17024 \SpecialChar ~
17025 \SpecialChar ~
17026 \SpecialChar ~
17027 \SpecialChar ~
17028 \SpecialChar ~
17029 \SpecialChar ~
17030 \SpecialChar ~
17031 SDCDB print command for data at
17032 \newline
17033 ;;\SpecialChar ~
17034 \SpecialChar ~
17035 \SpecialChar ~
17036 \SpecialChar ~
17037 \SpecialChar ~
17038 \SpecialChar ~
17039 \SpecialChar ~
17040 \SpecialChar ~
17041 \SpecialChar ~
17042 \SpecialChar ~
17043 \SpecialChar ~
17044 \SpecialChar ~
17045 \SpecialChar ~
17046 \SpecialChar ~
17047 \SpecialChar ~
17048 \SpecialChar ~
17049 \SpecialChar ~
17050 \SpecialChar ~
17051 \SpecialChar ~
17052 \SpecialChar ~
17053 \SpecialChar ~
17054 \SpecialChar ~
17055 \SpecialChar ~
17056 \SpecialChar ~
17057 \SpecialChar ~
17058 \SpecialChar ~
17059 \SpecialChar ~
17060 \SpecialChar ~
17061 \SpecialChar ~
17062 \SpecialChar ~
17063 \SpecialChar ~
17064 \SpecialChar ~
17065 \SpecialChar ~
17066 \SpecialChar ~
17067 \SpecialChar ~
17068 \SpecialChar ~
17069 \SpecialChar ~
17070 \SpecialChar ~
17071 \SpecialChar ~
17072 \SpecialChar ~
17073 \SpecialChar ~
17074 \SpecialChar ~
17075 \SpecialChar ~
17076 \SpecialChar ~
17077 \SpecialChar ~
17078 \SpecialChar ~
17079 \SpecialChar ~
17080 buffer point
17081 \newline
17082 ;;\SpecialChar ~
17083 g\SpecialChar ~
17084 \SpecialChar ~
17085 \SpecialChar ~
17086 \SpecialChar ~
17087 \SpecialChar ~
17088 \SpecialChar ~
17089 \SpecialChar ~
17090 \SpecialChar ~
17091 \SpecialChar ~
17092 \SpecialChar ~
17093 \SpecialChar ~
17094 \SpecialChar ~
17095 \SpecialChar ~
17096 \SpecialChar ~
17097 \SpecialChar ~
17098 sdcdbsrc-goto-sdcdb\SpecialChar ~
17099 \SpecialChar ~
17100 \SpecialChar ~
17101 \SpecialChar ~
17102 \SpecialChar ~
17103 \SpecialChar ~
17104 \SpecialChar ~
17105 \SpecialChar ~
17106 \SpecialChar ~
17107 \SpecialChar ~
17108 Goto the SDCDB output buffer
17109 \newline
17110 ;;\SpecialChar ~
17111 t\SpecialChar ~
17112 \SpecialChar ~
17113 \SpecialChar ~
17114 \SpecialChar ~
17115 \SpecialChar ~
17116 \SpecialChar ~
17117 \SpecialChar ~
17118 \SpecialChar ~
17119 \SpecialChar ~
17120 \SpecialChar ~
17121 \SpecialChar ~
17122 \SpecialChar ~
17123 \SpecialChar ~
17124 \SpecialChar ~
17125 \SpecialChar ~
17126 sdcdbsrc-mode\SpecialChar ~
17127 \SpecialChar ~
17128 \SpecialChar ~
17129 \SpecialChar ~
17130 \SpecialChar ~
17131 \SpecialChar ~
17132 \SpecialChar ~
17133 \SpecialChar ~
17134 \SpecialChar ~
17135 \SpecialChar ~
17136 \SpecialChar ~
17137 \SpecialChar ~
17138 \SpecialChar ~
17139 \SpecialChar ~
17140 \SpecialChar ~
17141 \SpecialChar ~
17142 Toggles Sdcdbsrc mode (turns it off)
17143 \newline
17144 ;;
17145 \newline
17146 ;;\SpecialChar ~
17147 C-c\SpecialChar ~
17148 C-f\SpecialChar ~
17149 \SpecialChar ~
17150 \SpecialChar ~
17151 \SpecialChar ~
17152 \SpecialChar ~
17153 \SpecialChar ~
17154 \SpecialChar ~
17155 \SpecialChar ~
17156 \SpecialChar ~
17157 sdcdb-finish-from-src\SpecialChar ~
17158 \SpecialChar ~
17159 \SpecialChar ~
17160 \SpecialChar ~
17161 \SpecialChar ~
17162 \SpecialChar ~
17163 \SpecialChar ~
17164 \SpecialChar ~
17165 SDCDB finish command
17166 \newline
17167 ;;
17168 \newline
17169 ;;\SpecialChar ~
17170 C-x\SpecialChar ~
17171 SPC\SpecialChar ~
17172 \SpecialChar ~
17173 \SpecialChar ~
17174 \SpecialChar ~
17175 \SpecialChar ~
17176 \SpecialChar ~
17177 \SpecialChar ~
17178 \SpecialChar ~
17179 \SpecialChar ~
17180 sdcdb-break\SpecialChar ~
17181 \SpecialChar ~
17182 \SpecialChar ~
17183 \SpecialChar ~
17184 \SpecialChar ~
17185 \SpecialChar ~
17186 \SpecialChar ~
17187 \SpecialChar ~
17188 \SpecialChar ~
17189 \SpecialChar ~
17190 \SpecialChar ~
17191 \SpecialChar ~
17192 \SpecialChar ~
17193 \SpecialChar ~
17194 \SpecialChar ~
17195 \SpecialChar ~
17196 \SpecialChar ~
17197 \SpecialChar ~
17198 Set break for line with point
17199 \newline
17200 ;;\SpecialChar ~
17201 ESC\SpecialChar ~
17202 t\SpecialChar ~
17203 \SpecialChar ~
17204 \SpecialChar ~
17205 \SpecialChar ~
17206 \SpecialChar ~
17207 \SpecialChar ~
17208 \SpecialChar ~
17209 \SpecialChar ~
17210 \SpecialChar ~
17211 \SpecialChar ~
17212 \SpecialChar ~
17213 sdcdbsrc-mode\SpecialChar ~
17214 \SpecialChar ~
17215 \SpecialChar ~
17216 \SpecialChar ~
17217 \SpecialChar ~
17218 \SpecialChar ~
17219 \SpecialChar ~
17220 \SpecialChar ~
17221 \SpecialChar ~
17222 \SpecialChar ~
17223 \SpecialChar ~
17224 \SpecialChar ~
17225 \SpecialChar ~
17226 \SpecialChar ~
17227 \SpecialChar ~
17228 \SpecialChar ~
17229 Toggle Sdcdbsrc mode
17230 \newline
17231 ;;\SpecialChar ~
17232 ESC\SpecialChar ~
17233 m\SpecialChar ~
17234 \SpecialChar ~
17235 \SpecialChar ~
17236 \SpecialChar ~
17237 \SpecialChar ~
17238 \SpecialChar ~
17239 \SpecialChar ~
17240 \SpecialChar ~
17241 \SpecialChar ~
17242 \SpecialChar ~
17243 \SpecialChar ~
17244 sdcdbsrc-srcmode\SpecialChar ~
17245 \SpecialChar ~
17246 \SpecialChar ~
17247 \SpecialChar ~
17248 \SpecialChar ~
17249 \SpecialChar ~
17250 \SpecialChar ~
17251 \SpecialChar ~
17252 \SpecialChar ~
17253 \SpecialChar ~
17254 \SpecialChar ~
17255 \SpecialChar ~
17256 \SpecialChar ~
17257 Toggle list mode
17258 \newline
17259 ;;
17260 \newline
17261
17262 \layout Chapter
17263 \pagebreak_top
17264 TIPS
17265 \layout Standard
17266
17267 Here are a few guidelines that will help the compiler generate more efficient
17268  code, some of the tips are specific to this compiler others are generally
17269  good programming practice.
17270 \layout Itemize
17271
17272 Use the smallest data type to represent your data-value.
17273  If it is known in advance that the value is going to be less than 256 then
17274  use an 'unsigned char' instead of a 'short' or 'int'.
17275  Please note, that ANSI C requires both signed and unsigned chars to be
17276  promoted to 'signed int' before doing any operation.
17277  This promotion can be omitted, if the result is the same.
17278  The effect of the promotion rules together with the sign-extension is often
17279  surprising:
17280 \begin_deeper
17281 \layout Verse
17282
17283
17284 \family typewriter
17285 unsigned char uc = 0xfe;
17286 \newline
17287 if (uc * uc < 0) /* this is true! */
17288 \newline
17289 {
17290 \newline
17291 \SpecialChar ~
17292 \SpecialChar ~
17293 \SpecialChar ~
17294 \SpecialChar ~
17295 ....
17296 \newline
17297 }
17298 \layout Standard
17299
17300
17301 \family typewriter
17302 uc * uc
17303 \family default
17304  is evaluated as
17305 \family typewriter
17306 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
17307 \family default
17308 .
17309
17310 \newline
17311 Another one:
17312 \layout Verse
17313
17314
17315 \family typewriter
17316 (unsigned char) -12 / (signed char) -3 = ...
17317 \layout Standard
17318
17319 No, the result is not 4:
17320 \layout Verse
17321
17322
17323 \family typewriter
17324 (int) (unsigned char) -12 / (int) (signed char) -3 =
17325 \newline
17326 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
17327 \newline
17328 (int) 0x00f4 / (int) 0xfffd =
17329 \newline
17330 (int) 0x00f4 / (int) 0xfffd =
17331 \newline
17332 (int) 244 / (int) -3 =
17333 \newline
17334 (int) -81 = (int) 0xffaf;
17335 \layout Standard
17336
17337 Don't complain, that gcc gives you a different result.
17338  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
17339  Therefore the results are different.
17340 \newline
17341 From
17342 \begin_inset Quotes sld
17343 \end_inset
17344
17345 comp.lang.c FAQ
17346 \begin_inset Quotes srd
17347 \end_inset
17348
17349 :
17350 \layout Quote
17351
17352 If well-defined overflow characteristics are important and negative values
17353  are not, or if you want to steer clear of sign-extension problems when
17354  manipulating bits or bytes, use one of the corresponding unsigned types.
17355  (Beware when mixing signed and unsigned values in expressions, though.)
17356 \newline
17357 Although character types (especially unsigned char) can be used as "tiny"
17358  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
17359 ble sign extension and increased code size.
17360 \end_deeper
17361 \layout Itemize
17362
17363 Use unsigned when it is known in advance that the value is not going to
17364  be negative.
17365  This helps especially if you are doing division or multiplication, bit-shifting
17366  or are using an array index.
17367 \layout Itemize
17368
17369 NEVER jump into a LOOP.
17370 \layout Itemize
17371
17372 Declare the variables to be local
17373 \begin_inset LatexCommand \index{local variables}
17374
17375 \end_inset
17376
17377  whenever possible, especially loop control variables (induction).
17378 \layout Itemize
17379
17380 Since the compiler does not always do implicit integral promotion, the programme
17381 r should do an explicit cast when integral promotion is required.
17382 \layout Itemize
17383
17384 Reducing the size of division, multiplication & modulus operations can reduce
17385  code size substantially.
17386  Take the following code for example.
17387 \begin_deeper
17388 \layout Verse
17389
17390
17391 \family typewriter
17392 foobar(unsigned int p1, unsigned char ch)
17393 \newline
17394 {
17395 \newline
17396 \SpecialChar ~
17397 \SpecialChar ~
17398 \SpecialChar ~
17399 \SpecialChar ~
17400 unsigned char ch1 = p1 % ch ;
17401 \newline
17402 \SpecialChar ~
17403 \SpecialChar ~
17404 \SpecialChar ~
17405 \SpecialChar ~
17406 ....
17407 \newline
17408 }
17409 \layout Standard
17410
17411 For the modulus operation the variable ch will be promoted to unsigned int
17412  first then the modulus operation will be performed (this will lead to a
17413  call to support routine _moduint()), and the result will be casted to a
17414  char.
17415  If the code is changed to
17416 \layout Verse
17417
17418
17419 \family typewriter
17420 foobar(unsigned int p1, unsigned char ch)
17421 \newline
17422 {
17423 \newline
17424 \SpecialChar ~
17425 \SpecialChar ~
17426 \SpecialChar ~
17427 \SpecialChar ~
17428 unsigned char ch1 = (unsigned char)p1 % ch ;
17429 \newline
17430 \SpecialChar ~
17431 \SpecialChar ~
17432 \SpecialChar ~
17433 \SpecialChar ~
17434 ....
17435 \newline
17436 }
17437 \layout Standard
17438
17439 It would substantially reduce the code generated (future versions of the
17440  compiler will be smart enough to detect such optimization opportunities).
17441 \end_deeper
17442 \layout Itemize
17443
17444 Have a look at the assembly listing to get a
17445 \begin_inset Quotes sld
17446 \end_inset
17447
17448 feeling
17449 \begin_inset Quotes srd
17450 \end_inset
17451
17452  for the code generation.
17453 \layout Section
17454
17455 Tools
17456 \begin_inset LatexCommand \index{Tools}
17457
17458 \end_inset
17459
17460  included in the distribution
17461 \layout Standard
17462 \align center
17463
17464 \begin_inset  Tabular
17465 <lyxtabular version="3" rows="12" columns="3">
17466 <features>
17467 <column alignment="center" valignment="top" leftline="true" width="0pt">
17468 <column alignment="center" valignment="top" leftline="true" width="0pt">
17469 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
17470 <row topline="true" bottomline="true">
17471 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17472 \begin_inset Text
17473
17474 \layout Standard
17475
17476 Name
17477 \end_inset
17478 </cell>
17479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17480 \begin_inset Text
17481
17482 \layout Standard
17483
17484 Purpose
17485 \end_inset
17486 </cell>
17487 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17488 \begin_inset Text
17489
17490 \layout Standard
17491
17492 Directory
17493 \end_inset
17494 </cell>
17495 </row>
17496 <row topline="true">
17497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17498 \begin_inset Text
17499
17500 \layout Standard
17501
17502 uCsim
17503 \end_inset
17504 </cell>
17505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17506 \begin_inset Text
17507
17508 \layout Standard
17509
17510 Simulator for various architectures
17511 \end_inset
17512 </cell>
17513 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17514 \begin_inset Text
17515
17516 \layout Standard
17517
17518 sdcc/sim/ucsim
17519 \end_inset
17520 </cell>
17521 </row>
17522 <row topline="true">
17523 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17524 \begin_inset Text
17525
17526 \layout Standard
17527
17528 keil2sdcc.pl
17529 \end_inset
17530 </cell>
17531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17532 \begin_inset Text
17533
17534 \layout Standard
17535
17536 header file conversion
17537 \end_inset
17538 </cell>
17539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17540 \begin_inset Text
17541
17542 \layout Standard
17543
17544 sdcc/support/scripts
17545 \end_inset
17546 </cell>
17547 </row>
17548 <row topline="true">
17549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17550 \begin_inset Text
17551
17552 \layout Standard
17553
17554 mh2h.c
17555 \end_inset
17556 </cell>
17557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17558 \begin_inset Text
17559
17560 \layout Standard
17561
17562 header file conversion
17563 \end_inset
17564 </cell>
17565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17566 \begin_inset Text
17567
17568 \layout Standard
17569
17570 sdcc/support/scripts
17571 \end_inset
17572 </cell>
17573 </row>
17574 <row topline="true">
17575 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17576 \begin_inset Text
17577
17578 \layout Standard
17579
17580 as-gbz80
17581 \end_inset
17582 </cell>
17583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17584 \begin_inset Text
17585
17586 \layout Standard
17587
17588 Assembler
17589 \end_inset
17590 </cell>
17591 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17592 \begin_inset Text
17593
17594 \layout Standard
17595
17596
17597 \family roman
17598 \series medium
17599 \shape up
17600 \size normal
17601 \emph off
17602 \bar no
17603 \noun off
17604 \color none
17605 sdcc/bin
17606 \end_inset
17607 </cell>
17608 </row>
17609 <row topline="true">
17610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17611 \begin_inset Text
17612
17613 \layout Standard
17614
17615 as-z80
17616 \end_inset
17617 </cell>
17618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17619 \begin_inset Text
17620
17621 \layout Standard
17622
17623 Assembler
17624 \end_inset
17625 </cell>
17626 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17627 \begin_inset Text
17628
17629 \layout Standard
17630
17631
17632 \family roman
17633 \series medium
17634 \shape up
17635 \size normal
17636 \emph off
17637 \bar no
17638 \noun off
17639 \color none
17640 sdcc/bin
17641 \end_inset
17642 </cell>
17643 </row>
17644 <row topline="true">
17645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17646 \begin_inset Text
17647
17648 \layout Standard
17649
17650 asx8051
17651 \end_inset
17652 </cell>
17653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17654 \begin_inset Text
17655
17656 \layout Standard
17657
17658 Assembler
17659 \end_inset
17660 </cell>
17661 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17662 \begin_inset Text
17663
17664 \layout Standard
17665
17666
17667 \family roman
17668 \series medium
17669 \shape up
17670 \size normal
17671 \emph off
17672 \bar no
17673 \noun off
17674 \color none
17675 sdcc/bin
17676 \end_inset
17677 </cell>
17678 </row>
17679 <row topline="true">
17680 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17681 \begin_inset Text
17682
17683 \layout Standard
17684
17685 sdcdb
17686 \end_inset
17687 </cell>
17688 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17689 \begin_inset Text
17690
17691 \layout Standard
17692
17693 Simulator
17694 \end_inset
17695 </cell>
17696 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17697 \begin_inset Text
17698
17699 \layout Standard
17700
17701
17702 \family roman
17703 \series medium
17704 \shape up
17705 \size normal
17706 \emph off
17707 \bar no
17708 \noun off
17709 \color none
17710 sdcc/bin
17711 \end_inset
17712 </cell>
17713 </row>
17714 <row topline="true">
17715 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17716 \begin_inset Text
17717
17718 \layout Standard
17719
17720 aslink
17721 \end_inset
17722 </cell>
17723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17724 \begin_inset Text
17725
17726 \layout Standard
17727
17728 Linker
17729 \end_inset
17730 </cell>
17731 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17732 \begin_inset Text
17733
17734 \layout Standard
17735
17736
17737 \family roman
17738 \series medium
17739 \shape up
17740 \size normal
17741 \emph off
17742 \bar no
17743 \noun off
17744 \color none
17745 sdcc/bin
17746 \end_inset
17747 </cell>
17748 </row>
17749 <row topline="true">
17750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17751 \begin_inset Text
17752
17753 \layout Standard
17754
17755 link-z80
17756 \end_inset
17757 </cell>
17758 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17759 \begin_inset Text
17760
17761 \layout Standard
17762
17763 Linker
17764 \end_inset
17765 </cell>
17766 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17767 \begin_inset Text
17768
17769 \layout Standard
17770
17771
17772 \family roman
17773 \series medium
17774 \shape up
17775 \size normal
17776 \emph off
17777 \bar no
17778 \noun off
17779 \color none
17780 sdcc/bin
17781 \end_inset
17782 </cell>
17783 </row>
17784 <row topline="true">
17785 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17786 \begin_inset Text
17787
17788 \layout Standard
17789
17790 link-gbz80
17791 \end_inset
17792 </cell>
17793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17794 \begin_inset Text
17795
17796 \layout Standard
17797
17798 Linker
17799 \end_inset
17800 </cell>
17801 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17802 \begin_inset Text
17803
17804 \layout Standard
17805
17806
17807 \family roman
17808 \series medium
17809 \shape up
17810 \size normal
17811 \emph off
17812 \bar no
17813 \noun off
17814 \color none
17815 sdcc/bin
17816 \end_inset
17817 </cell>
17818 </row>
17819 <row topline="true" bottomline="true">
17820 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17821 \begin_inset Text
17822
17823 \layout Standard
17824
17825 packihx
17826 \end_inset
17827 </cell>
17828 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17829 \begin_inset Text
17830
17831 \layout Standard
17832
17833 ihx packer
17834 \end_inset
17835 </cell>
17836 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17837 \begin_inset Text
17838
17839 \layout Standard
17840
17841
17842 \family roman
17843 \series medium
17844 \shape up
17845 \size normal
17846 \emph off
17847 \bar no
17848 \noun off
17849 \color none
17850 sdcc/bin
17851 \end_inset
17852 </cell>
17853 </row>
17854 </lyxtabular>
17855
17856 \end_inset
17857
17858
17859 \newline
17860
17861 \layout Section
17862
17863 Documentation
17864 \begin_inset LatexCommand \index{Documentation}
17865
17866 \end_inset
17867
17868  included in the distribution
17869 \layout Standard
17870 \align center
17871
17872 \begin_inset  Tabular
17873 <lyxtabular version="3" rows="10" columns="2">
17874 <features>
17875 <column alignment="left" valignment="top" leftline="true" width="0">
17876 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
17877 <row topline="true" bottomline="true">
17878 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17879 \begin_inset Text
17880
17881 \layout Standard
17882
17883 Subject / Title
17884 \end_inset
17885 </cell>
17886 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17887 \begin_inset Text
17888
17889 \layout Standard
17890
17891 Where to get / filename
17892 \end_inset
17893 </cell>
17894 </row>
17895 <row topline="true">
17896 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17897 \begin_inset Text
17898
17899 \layout Standard
17900
17901 SDCC Compiler User Guide
17902 \end_inset
17903 </cell>
17904 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17905 \begin_inset Text
17906
17907 \layout Standard
17908
17909 You're reading it right now
17910 \end_inset
17911 </cell>
17912 </row>
17913 <row topline="true">
17914 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17915 \begin_inset Text
17916
17917 \layout Standard
17918
17919 Changelog of SDCC
17920 \end_inset
17921 </cell>
17922 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17923 \begin_inset Text
17924
17925 \layout Standard
17926
17927 sdcc/Changelog
17928 \end_inset
17929 </cell>
17930 </row>
17931 <row topline="true">
17932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17933 \begin_inset Text
17934
17935 \layout Standard
17936
17937 ASXXXX Assemblers and ASLINK Relocating Linker
17938 \end_inset
17939 </cell>
17940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17941 \begin_inset Text
17942
17943 \layout Standard
17944
17945 sdcc/as/doc/asxhtm.html
17946 \end_inset
17947 </cell>
17948 </row>
17949 <row topline="true">
17950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17951 \begin_inset Text
17952
17953 \layout Standard
17954
17955 SDCC regression test
17956 \begin_inset LatexCommand \index{Regression test}
17957
17958 \end_inset
17959
17960
17961 \end_inset
17962 </cell>
17963 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17964 \begin_inset Text
17965
17966 \layout Standard
17967
17968 sdcc/doc/test_suite_spec.pdf
17969 \end_inset
17970 </cell>
17971 </row>
17972 <row topline="true">
17973 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17974 \begin_inset Text
17975
17976 \layout Standard
17977
17978 Various notes
17979 \end_inset
17980 </cell>
17981 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17982 \begin_inset Text
17983
17984 \layout Standard
17985
17986 sdcc/doc/*
17987 \end_inset
17988 </cell>
17989 </row>
17990 <row topline="true">
17991 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17992 \begin_inset Text
17993
17994 \layout Standard
17995
17996 Notes on debugging with sdcdb
17997 \begin_inset LatexCommand \index{sdcdb (debugger)}
17998
17999 \end_inset
18000
18001
18002 \end_inset
18003 </cell>
18004 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18005 \begin_inset Text
18006
18007 \layout Standard
18008
18009 sdcc/debugger/README
18010 \end_inset
18011 </cell>
18012 </row>
18013 <row topline="true">
18014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18015 \begin_inset Text
18016
18017 \layout Standard
18018
18019 Software simulator for microcontrollers
18020 \end_inset
18021 </cell>
18022 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18023 \begin_inset Text
18024
18025 \layout Standard
18026
18027
18028 \family roman
18029 \series medium
18030 \shape up
18031 \size normal
18032 \emph off
18033 \bar no
18034 \noun off
18035 \color none
18036 sdcc/sim/ucsim/doc
18037 \family default
18038 \series default
18039 \shape default
18040 \size default
18041 \emph default
18042 \bar default
18043 \noun default
18044 \color default
18045 /index.html
18046 \end_inset
18047 </cell>
18048 </row>
18049 <row topline="true">
18050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18051 \begin_inset Text
18052
18053 \layout Standard
18054
18055 Temporary notes on the pic16
18056 \begin_inset LatexCommand \index{PIC16}
18057
18058 \end_inset
18059
18060  port
18061 \end_inset
18062 </cell>
18063 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18064 \begin_inset Text
18065
18066 \layout Standard
18067
18068 sdcc/src/pic16/NOTES
18069 \end_inset
18070 </cell>
18071 </row>
18072 <row topline="true" bottomline="true">
18073 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18074 \begin_inset Text
18075
18076 \layout Standard
18077
18078 SDCC internal documentation (debugging file format)
18079 \end_inset
18080 </cell>
18081 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18082 \begin_inset Text
18083
18084 \layout Standard
18085
18086 sdcc/doc/
18087 \family roman
18088 \series medium
18089 \shape up
18090 \size normal
18091 \emph off
18092 \bar no
18093 \noun off
18094 \color none
18095 cdbfileformat.pd
18096 \family default
18097 \series default
18098 \shape default
18099 \size default
18100 \emph default
18101 \bar default
18102 \noun default
18103 \color default
18104 f
18105 \end_inset
18106 </cell>
18107 </row>
18108 </lyxtabular>
18109
18110 \end_inset
18111
18112
18113 \newline
18114
18115 \layout Section
18116
18117 Related open source tools
18118 \begin_inset LatexCommand \index{Related tools}
18119
18120 \end_inset
18121
18122
18123 \layout Standard
18124 \align center
18125
18126 \begin_inset  Tabular
18127 <lyxtabular version="3" rows="11" columns="3">
18128 <features>
18129 <column alignment="center" valignment="top" leftline="true" width="0pt">
18130 <column alignment="block" valignment="top" leftline="true" width="30line%">
18131 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18132 <row topline="true" bottomline="true">
18133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18134 \begin_inset Text
18135
18136 \layout Standard
18137
18138 Name
18139 \end_inset
18140 </cell>
18141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18142 \begin_inset Text
18143
18144 \layout Standard
18145
18146 Purpose
18147 \end_inset
18148 </cell>
18149 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18150 \begin_inset Text
18151
18152 \layout Standard
18153
18154 Where to get
18155 \end_inset
18156 </cell>
18157 </row>
18158 <row topline="true">
18159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18160 \begin_inset Text
18161
18162 \layout Standard
18163
18164 gpsim
18165 \begin_inset LatexCommand \index{gpsim (pic simulator)}
18166
18167 \end_inset
18168
18169
18170 \end_inset
18171 </cell>
18172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18173 \begin_inset Text
18174
18175 \layout Standard
18176
18177 PIC simulator
18178 \end_inset
18179 </cell>
18180 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18181 \begin_inset Text
18182
18183 \layout Standard
18184
18185
18186 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
18187
18188 \end_inset
18189
18190
18191 \end_inset
18192 </cell>
18193 </row>
18194 <row topline="true">
18195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18196 \begin_inset Text
18197
18198 \layout Standard
18199
18200 gputils
18201 \begin_inset LatexCommand \index{gputils (pic tools)}
18202
18203 \end_inset
18204
18205
18206 \end_inset
18207 </cell>
18208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18209 \begin_inset Text
18210
18211 \layout Standard
18212
18213 GNU PIC utilities
18214 \end_inset
18215 </cell>
18216 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18217 \begin_inset Text
18218
18219 \layout Standard
18220
18221
18222 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
18223
18224 \end_inset
18225
18226
18227 \end_inset
18228 </cell>
18229 </row>
18230 <row topline="true">
18231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18232 \begin_inset Text
18233
18234 \layout Standard
18235
18236 flP5
18237 \end_inset
18238 </cell>
18239 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18240 \begin_inset Text
18241
18242 \layout Standard
18243
18244 PIC programmer
18245 \end_inset
18246 </cell>
18247 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18248 \begin_inset Text
18249
18250 \layout Standard
18251
18252
18253 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
18254
18255 \end_inset
18256
18257
18258 \end_inset
18259 </cell>
18260 </row>
18261 <row topline="true">
18262 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18263 \begin_inset Text
18264
18265 \layout Standard
18266
18267 indent
18268 \begin_inset LatexCommand \index{indent (source formatting tool)}
18269
18270 \end_inset
18271
18272
18273 \end_inset
18274 </cell>
18275 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18276 \begin_inset Text
18277
18278 \layout Standard
18279
18280 Formats C source - Master of the white spaces
18281 \end_inset
18282 </cell>
18283 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18284 \begin_inset Text
18285
18286 \layout Standard
18287
18288
18289 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
18290
18291 \end_inset
18292
18293
18294 \end_inset
18295 </cell>
18296 </row>
18297 <row topline="true">
18298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18299 \begin_inset Text
18300
18301 \layout Standard
18302
18303 srecord
18304 \begin_inset LatexCommand \index{srecord (tool)}
18305
18306 \end_inset
18307
18308
18309 \end_inset
18310 </cell>
18311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18312 \begin_inset Text
18313
18314 \layout Standard
18315
18316 Object file conversion, checksumming, ...
18317 \end_inset
18318 </cell>
18319 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18320 \begin_inset Text
18321
18322 \layout Standard
18323
18324
18325 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
18326
18327 \end_inset
18328
18329
18330 \end_inset
18331 </cell>
18332 </row>
18333 <row topline="true">
18334 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18335 \begin_inset Text
18336
18337 \layout Standard
18338
18339 objdump
18340 \begin_inset LatexCommand \index{objdump (tool)}
18341
18342 \end_inset
18343
18344
18345 \end_inset
18346 </cell>
18347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18348 \begin_inset Text
18349
18350 \layout Standard
18351
18352 Object file conversion, ...
18353 \end_inset
18354 </cell>
18355 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18356 \begin_inset Text
18357
18358 \layout Standard
18359
18360 Part of binutils (should be there anyway)
18361 \end_inset
18362 </cell>
18363 </row>
18364 <row topline="true">
18365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18366 \begin_inset Text
18367
18368 \layout Standard
18369
18370 doxygen
18371 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
18372
18373 \end_inset
18374
18375
18376 \end_inset
18377 </cell>
18378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18379 \begin_inset Text
18380
18381 \layout Standard
18382
18383 Source code documentation system
18384 \end_inset
18385 </cell>
18386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18387 \begin_inset Text
18388
18389 \layout Standard
18390
18391
18392 \begin_inset LatexCommand \url{http://www.doxygen.org}
18393
18394 \end_inset
18395
18396
18397 \end_inset
18398 </cell>
18399 </row>
18400 <row topline="true">
18401 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18402 \begin_inset Text
18403
18404 \layout Standard
18405
18406 kdevelop
18407 \end_inset
18408 </cell>
18409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18410 \begin_inset Text
18411
18412 \layout Standard
18413
18414 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
18415 \end_inset
18416 </cell>
18417 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18418 \begin_inset Text
18419
18420 \layout Standard
18421
18422
18423 \begin_inset LatexCommand \url{http://www.kdevelop.org}
18424
18425 \end_inset
18426
18427
18428 \end_inset
18429 </cell>
18430 </row>
18431 <row topline="true">
18432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18433 \begin_inset Text
18434
18435 \layout Standard
18436
18437 splint
18438 \begin_inset LatexCommand \index{splint (syntax checking tool)}
18439
18440 \end_inset
18441
18442
18443 \end_inset
18444 </cell>
18445 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18446 \begin_inset Text
18447
18448 \layout Standard
18449
18450 Statically checks c sources (has anyone adapted splint for SDCC?)
18451 \end_inset
18452 </cell>
18453 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18454 \begin_inset Text
18455
18456 \layout Standard
18457
18458
18459 \begin_inset LatexCommand \url{http://www.splint.org}
18460
18461 \end_inset
18462
18463
18464 \end_inset
18465 </cell>
18466 </row>
18467 <row topline="true" bottomline="true">
18468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18469 \begin_inset Text
18470
18471 \layout Standard
18472
18473 ddd
18474 \begin_inset LatexCommand \index{ddd (debugger)}
18475
18476 \end_inset
18477
18478
18479 \end_inset
18480 </cell>
18481 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18482 \begin_inset Text
18483
18484 \layout Standard
18485
18486 Debugger, serves nicely as GUI to sdcdb
18487 \begin_inset LatexCommand \index{sdcdb (debugger)}
18488
18489 \end_inset
18490
18491  (Unix only)
18492 \end_inset
18493 </cell>
18494 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18495 \begin_inset Text
18496
18497 \layout Standard
18498
18499
18500 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
18501
18502 \end_inset
18503
18504
18505 \end_inset
18506 </cell>
18507 </row>
18508 </lyxtabular>
18509
18510 \end_inset
18511
18512
18513 \newline
18514
18515 \layout Section
18516
18517 Related documentation / recommended reading
18518 \layout Standard
18519 \align center
18520
18521 \begin_inset  Tabular
18522 <lyxtabular version="3" rows="6" columns="3">
18523 <features>
18524 <column alignment="center" valignment="top" leftline="true" width="0pt">
18525 <column alignment="block" valignment="top" leftline="true" width="30line%">
18526 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18527 <row topline="true" bottomline="true">
18528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18529 \begin_inset Text
18530
18531 \layout Standard
18532
18533 Name
18534 \end_inset
18535 </cell>
18536 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18537 \begin_inset Text
18538
18539 \layout Standard
18540
18541 Subject / Title
18542 \end_inset
18543 </cell>
18544 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18545 \begin_inset Text
18546
18547 \layout Standard
18548
18549 Where to get
18550 \end_inset
18551 </cell>
18552 </row>
18553 <row topline="true">
18554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18555 \begin_inset Text
18556
18557 \layout Standard
18558
18559
18560 \family roman
18561 \series medium
18562 \shape up
18563 \size normal
18564 \emph off
18565 \bar no
18566 \noun off
18567 \color none
18568 c-refcard.pdf
18569 \end_inset
18570 </cell>
18571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18572 \begin_inset Text
18573
18574 \layout Standard
18575
18576 C Reference Card
18577 \begin_inset LatexCommand \index{C Reference card}
18578
18579 \end_inset
18580
18581 , 2 pages
18582 \end_inset
18583 </cell>
18584 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18585 \begin_inset Text
18586
18587 \layout Standard
18588
18589
18590 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
18591
18592 \end_inset
18593
18594
18595 \end_inset
18596 </cell>
18597 </row>
18598 <row topline="true">
18599 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18600 \begin_inset Text
18601
18602 \layout Standard
18603
18604 c-faq
18605 \end_inset
18606 </cell>
18607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18608 \begin_inset Text
18609
18610 \layout Standard
18611
18612 C-FAQ-list
18613 \end_inset
18614 </cell>
18615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18616 \begin_inset Text
18617
18618 \layout Standard
18619
18620
18621 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
18622
18623 \end_inset
18624
18625
18626 \end_inset
18627 </cell>
18628 </row>
18629 <row topline="true">
18630 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18631 \begin_inset Text
18632
18633 \layout Standard
18634
18635 \end_inset
18636 </cell>
18637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18638 \begin_inset Text
18639
18640 \layout Standard
18641
18642 Latest datasheet of the target CPU
18643 \end_inset
18644 </cell>
18645 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18646 \begin_inset Text
18647
18648 \layout Standard
18649
18650 vendor
18651 \end_inset
18652 </cell>
18653 </row>
18654 <row topline="true">
18655 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18656 \begin_inset Text
18657
18658 \layout Standard
18659
18660 \end_inset
18661 </cell>
18662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18663 \begin_inset Text
18664
18665 \layout Standard
18666
18667 Revision history of datasheet
18668 \end_inset
18669 </cell>
18670 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18671 \begin_inset Text
18672
18673 \layout Standard
18674
18675 vendor
18676 \end_inset
18677 </cell>
18678 </row>
18679 <row topline="true" bottomline="true">
18680 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18681 \begin_inset Text
18682
18683 \layout Standard
18684
18685 S.
18686  S.
18687  Muchnick
18688 \end_inset
18689 </cell>
18690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18691 \begin_inset Text
18692
18693 \layout Standard
18694
18695 Advanced Compiler Design and Implementation
18696 \end_inset
18697 </cell>
18698 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18699 \begin_inset Text
18700
18701 \layout Standard
18702
18703 bookstore (very dedicated, probably read other books first)
18704 \end_inset
18705 </cell>
18706 </row>
18707 </lyxtabular>
18708
18709 \end_inset
18710
18711
18712 \newline
18713
18714 \layout Section
18715
18716 Some Questions
18717 \layout Standard
18718
18719 Some questions answered, some pointers given - it might be time to in turn
18720  ask
18721 \emph on
18722 you
18723 \emph default
18724  some questions:
18725 \layout Itemize
18726
18727 can you solve your project with the selected microcontroller? Would you
18728  find out early or rather late that your target is too small/slow/whatever?
18729  Can you switch to a slightly better device if it doesn't fit?
18730 \layout Itemize
18731
18732 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
18733  and/or another programming language be more adequate? Would an operating
18734  system on the target device help?
18735 \layout Itemize
18736
18737 if you solved the problem, will the marketing department be happy?
18738 \layout Itemize
18739
18740 if the marketing department is happy, will customers be happy?
18741 \layout Itemize
18742
18743 if you're the project manager, marketing department and maybe even the customer
18744  in one person, have you tried to see the project from the outside?
18745 \layout Itemize
18746
18747 is the project done if you think it is done? Or is just that other interface/pro
18748 tocol/feature/configuration/option missing? How about website, manual(s),
18749  internationali(z|s)ation, packaging, labels, 2nd source for components,
18750  electromagnetic compatability/interference, documentation for production,
18751  production test software, update mechanism, patent issues?
18752 \layout Itemize
18753
18754 is your project adequately positioned in that magic triangle: fame, fortune,
18755  fun?
18756 \layout Standard
18757
18758 Maybe not all answers to these questions are known and some answers may
18759  even be
18760 \emph on
18761 no
18762 \emph default
18763 , nevertheless knowing these questions may help you to avoid burnout
18764 \begin_inset Foot
18765 collapsed false
18766
18767 \layout Standard
18768
18769 burnout is bad for electronic devices, programmers and motorcycle tyres
18770 \end_inset
18771
18772 .
18773  Chances are you didn't want to hear some of them...
18774 \layout Chapter
18775
18776 Support
18777 \begin_inset LatexCommand \index{Support}
18778
18779 \end_inset
18780
18781
18782 \layout Standard
18783
18784 SDCC has grown to be a large project.
18785  The compiler alone (without the preprocessor, assembler and linker) is
18786  well over 100,000 lines of code (blank stripped).
18787  The open source nature of this project is a key to its continued growth
18788  and support.
18789  You gain the benefit and support of many active software developers and
18790  end users.
18791  Is SDCC perfect? No, that's why we need your help.
18792  The developers take pride in fixing reported bugs.
18793  You can help by reporting the bugs and helping other SDCC users.
18794  There are lots of ways to contribute, and we encourage you to take part
18795  in making SDCC a great software package.
18796
18797 \layout Standard
18798
18799 The SDCC project is hosted on the SDCC sourceforge site at
18800 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
18801
18802 \end_inset
18803
18804 .
18805  You'll find the complete set of mailing lists
18806 \begin_inset LatexCommand \index{Mailing list(s)}
18807
18808 \end_inset
18809
18810 , forums, bug reporting system, patch submission
18811 \begin_inset LatexCommand \index{Patch submission}
18812
18813 \end_inset
18814
18815  system, download
18816 \begin_inset LatexCommand \index{download}
18817
18818 \end_inset
18819
18820  area and cvs code repository
18821 \begin_inset LatexCommand \index{cvs code repository}
18822
18823 \end_inset
18824
18825  there.
18826 \layout Section
18827
18828 Reporting Bugs
18829 \begin_inset LatexCommand \index{Bug reporting}
18830
18831 \end_inset
18832
18833
18834 \begin_inset LatexCommand \index{Reporting bugs}
18835
18836 \end_inset
18837
18838
18839 \layout Standard
18840
18841 The recommended way of reporting bugs is using the infrastructure of the
18842  sourceforge site.
18843  You can follow the status of bug reports there and have an overview about
18844  the known bugs.
18845 \layout Standard
18846
18847 Bug reports are automatically forwarded to the developer mailing list and
18848  will be fixed ASAP.
18849  When reporting a bug, it is very useful to include a small test program
18850  (the smaller the better) which reproduces the problem.
18851  If you can isolate the problem by looking at the generated assembly code,
18852  this can be very helpful.
18853  Compiling your program with the -
18854 \begin_inset ERT
18855 status Collapsed
18856
18857 \layout Standard
18858
18859 \backslash
18860 /
18861 \end_inset
18862
18863 -dumpall
18864 \begin_inset LatexCommand \index{-\/-dumpall}
18865
18866 \end_inset
18867
18868  option can sometimes be useful in locating optimization problems.
18869  When reporting a bug please maker sure you:
18870 \layout Enumerate
18871
18872 Attach the code you are compiling with SDCC.
18873
18874 \layout Enumerate
18875
18876 Specify the exact command you use to run SDCC, or attach your Makefile.
18877
18878 \layout Enumerate
18879
18880 Specify the SDCC version (type "
18881 \family sans
18882 \series bold
18883 sdcc -v
18884 \family default
18885 \series default
18886 "), your platform, and operating system.
18887
18888 \layout Enumerate
18889
18890 Provide an exact copy of any error message or incorrect output.
18891
18892 \layout Enumerate
18893
18894 Put something meaningful in the subject of your message.
18895 \layout Standard
18896
18897 Please attempt to include these 5 important parts, as applicable, in all
18898  requests for support or when reporting any problems or bugs with SDCC.
18899  Though this will make your message lengthy, it will greatly improve your
18900  chance that SDCC users and developers will be able to help you.
18901  Some SDCC developers are frustrated by bug reports without code provided
18902  that they can use to reproduce and ultimately fix the problem, so please
18903  be sure to provide sample code if you are reporting a bug!
18904 \layout Standard
18905
18906 Please have a short check that you are using a recent version of SDCC and
18907  the bug is not yet known.
18908  This is the link for reporting bugs:
18909 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
18910
18911 \end_inset
18912
18913 .
18914 \layout Section
18915
18916 Requesting Features
18917 \begin_inset LatexCommand \label{sub:Requesting-Features}
18918
18919 \end_inset
18920
18921
18922 \begin_inset LatexCommand \index{Feature request}
18923
18924 \end_inset
18925
18926
18927 \begin_inset LatexCommand \index{Requesting features}
18928
18929 \end_inset
18930
18931
18932 \layout Standard
18933
18934 Like bug reports feature requests are forwarded to the developer mailing
18935  list.
18936  This is the link for requesting features:
18937 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
18938
18939 \end_inset
18940
18941 .
18942 \layout Section
18943
18944 Submitting patches
18945 \layout Standard
18946
18947 Like bug reports contributed patches are forwarded to the developer mailing
18948  list.
18949  This is the link for submitting patches
18950 \begin_inset LatexCommand \index{Patch submission}
18951
18952 \end_inset
18953
18954 :
18955 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
18956
18957 \end_inset
18958
18959 .
18960 \layout Standard
18961
18962 You need to specify some parameters to the
18963 \family typewriter
18964 diff
18965 \family default
18966  command for the patches to be useful.
18967  If you modified more than one file a patch created f.e.
18968  with
18969 \family sans
18970 \series bold
18971
18972 \begin_inset Quotes sld
18973 \end_inset
18974
18975 diff -Naur unmodified_directory modified_directory >my_changes.patch
18976 \begin_inset Quotes srd
18977 \end_inset
18978
18979
18980 \family default
18981 \series default
18982  will be fine, otherwise
18983 \family sans
18984 \series bold
18985
18986 \begin_inset Quotes sld
18987 \end_inset
18988
18989 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
18990 \begin_inset Quotes srd
18991 \end_inset
18992
18993
18994 \series default
18995
18996 \family default
18997 will do.
18998 \layout Section
18999
19000 Getting Help
19001 \layout Standard
19002
19003 These links should take you directly to the
19004 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
19005
19006 \end_inset
19007
19008
19009 \begin_inset Foot
19010 collapsed false
19011
19012 \layout Standard
19013
19014 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
19015  automated messages (mid 2003)
19016 \end_inset
19017
19018  and the
19019 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
19020
19021 \end_inset
19022
19023 , lists
19024 \begin_inset LatexCommand \index{Mailing list(s)}
19025
19026 \end_inset
19027
19028  and forums are archived and searchable so if you are lucky someone already
19029  had a similar problem.
19030  While mails to the lists themselves are delivered promptly their web front
19031  end on sourceforge sometimes shows a severe time lag (up to several weeks),
19032  if you're seriously using SDCC please consider subscribing to the lists.
19033 \layout Section
19034
19035 ChangeLog
19036 \layout Standard
19037
19038 You can follow the status of the cvs version
19039 \begin_inset LatexCommand \index{version}
19040
19041 \end_inset
19042
19043  of SDCC by watching the Changelog
19044 \begin_inset LatexCommand \index{Changelog}
19045
19046 \end_inset
19047
19048  in the cvs-repository
19049 \newline
19050
19051 \size footnotesize
19052
19053 \begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
19054
19055 \end_inset
19056
19057 .
19058 \layout Section
19059
19060 Release policy
19061 \begin_inset LatexCommand \index{Release policy}
19062
19063 \end_inset
19064
19065
19066 \layout Standard
19067
19068 Historically there often were long delays between official releases and
19069  the sourceforge download area tends to get not updated at all.
19070  Excuses in the past might have referred to problems with live range analysis,
19071  but as this was fixed a while ago, the current problem is that another
19072  excuse has to be found.
19073  Kidding aside, we have to get better there! On the other hand there are
19074  daily snapshots available at
19075 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
19076
19077 \end_inset
19078
19079 , and you can always build the very last version (hopefully with many bugs
19080  fixed, and features added) from the source code available at
19081 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
19082
19083 \end_inset
19084
19085 .
19086 \layout Section
19087
19088 Examples
19089 \begin_inset LatexCommand \index{Examples}
19090
19091 \end_inset
19092
19093
19094 \layout Standard
19095
19096 You'll find some small examples in the directory
19097 \emph on
19098 sdcc/device/examples/.
19099
19100 \emph default
19101 More examples and libraries are available at
19102 \emph on
19103  The SDCC Open Knowledge Resource
19104 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
19105
19106 \end_inset
19107
19108
19109 \emph default
19110 web site or at
19111 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
19112
19113 \end_inset
19114
19115 .
19116 \layout Comment
19117
19118 I did insert a reference to Paul's web site here although it seems rather
19119  dedicated to a specific 8032 board (I think it's okay because it f.e.
19120  shows LCD/Harddisc interface and has a free 8051 monitor.
19121  Independent 8032 board vendors face hard competition of heavily subsidized
19122  development boards anyway).
19123 \layout Comment
19124
19125 Maybe we should include some links to real world applications.
19126  Preferably pointer to pointers (one for each architecture) so this stays
19127  manageable here?
19128 \layout Section
19129
19130 Quality control
19131 \begin_inset LatexCommand \index{Quality control}
19132
19133 \end_inset
19134
19135
19136 \layout Standard
19137
19138 The compiler is passed through nightly compile and build checks.
19139  The so called
19140 \shape italic
19141 regression tests
19142 \shape default
19143
19144 \begin_inset LatexCommand \index{Regression test}
19145
19146 \end_inset
19147
19148  check that SDCC itself compiles flawlessly on several platforms and checks
19149  the quality of the code generated by SDCC by running the code through simulator
19150 s.
19151  There is a separate document
19152 \shape italic
19153 test_suite.pdf
19154 \begin_inset LatexCommand \index{Test suite}
19155
19156 \end_inset
19157
19158
19159 \shape default
19160  about this.
19161 \layout Standard
19162
19163 You'll find the test code in the directory
19164 \shape italic
19165 sdcc/support/regression
19166 \shape default
19167 .
19168  You can run these tests manually by running
19169 \family sans
19170 make
19171 \family default
19172  in this directory (or f.e.
19173
19174 \family sans
19175 \series bold
19176
19177 \begin_inset Quotes sld
19178 \end_inset
19179
19180 make test-mcs51
19181 \begin_inset Quotes srd
19182 \end_inset
19183
19184
19185 \family default
19186 \series default
19187  if you don't want to run the complete tests).
19188  The test code might also be interesting if you want to look for examples
19189 \begin_inset LatexCommand \index{Examples}
19190
19191 \end_inset
19192
19193  checking corner cases of SDCC or if you plan to submit patches
19194 \begin_inset LatexCommand \index{Patch submission}
19195
19196 \end_inset
19197
19198 .
19199 \layout Standard
19200
19201 The pic port uses a different set of regression tests, you'll find them
19202  in the directory
19203 \shape italic
19204 sdcc/src/regression
19205 \shape default
19206 .
19207 \layout Chapter
19208 \pagebreak_top
19209 SDCC Technical Data
19210 \layout Section
19211
19212 Optimizations
19213 \begin_inset LatexCommand \index{Optimizations}
19214
19215 \end_inset
19216
19217
19218 \layout Standard
19219
19220 SDCC performs a host of standard optimizations in addition to some MCU specific
19221  optimizations.
19222
19223 \layout Subsection
19224
19225 Sub-expression Elimination
19226 \begin_inset LatexCommand \index{Subexpression elimination}
19227
19228 \end_inset
19229
19230
19231 \layout Standard
19232
19233 The compiler does local and
19234 \emph on
19235 g
19236 \emph default
19237 lobal
19238 \emph on
19239 c
19240 \emph default
19241 ommon
19242 \emph on
19243 s
19244 \emph default
19245 ubexpression
19246 \emph on
19247 e
19248 \emph default
19249 limination, e.g.:
19250 \layout Verse
19251
19252
19253 \family typewriter
19254 i = x + y + 1;
19255 \newline
19256 j = x + y;
19257 \layout Standard
19258
19259 will be translated to
19260 \layout Verse
19261
19262
19263 \family typewriter
19264 iTemp = x + y;
19265 \newline
19266 i = iTemp + 1;
19267 \newline
19268 j = iTemp;
19269 \layout Standard
19270
19271 Some subexpressions are not as obvious as the above example, e.g.:
19272 \layout Verse
19273
19274
19275 \family typewriter
19276 a->b[i].c = 10;
19277 \newline
19278 a->b[i].d = 11;
19279 \layout Standard
19280
19281 In this case the address arithmetic a->b[i] will be computed only once;
19282  the equivalent code in C would be.
19283 \layout Verse
19284
19285
19286 \family typewriter
19287 iTemp = a->b[i];
19288 \newline
19289 iTemp.c = 10;
19290 \newline
19291 iTemp.d = 11;
19292 \layout Standard
19293
19294 The compiler will try to keep these temporary variables in registers.
19295 \layout Subsection
19296
19297 Dead-Code Elimination
19298 \begin_inset LatexCommand \index{Dead-code elimination}
19299
19300 \end_inset
19301
19302
19303 \layout Verse
19304
19305
19306 \family typewriter
19307 int global;
19308 \newline
19309
19310 \newline
19311 void f () {
19312 \newline
19313 \SpecialChar ~
19314 \SpecialChar ~
19315 int i;
19316 \newline
19317 \SpecialChar ~
19318 \SpecialChar ~
19319 i = 1; \SpecialChar ~
19320 \SpecialChar ~
19321 \SpecialChar ~
19322 \SpecialChar ~
19323 \SpecialChar ~
19324 /* dead store */
19325 \newline
19326 \SpecialChar ~
19327 \SpecialChar ~
19328 global = 1;\SpecialChar ~
19329 /* dead store */
19330 \newline
19331 \SpecialChar ~
19332 \SpecialChar ~
19333 global = 2;
19334 \newline
19335 \SpecialChar ~
19336 \SpecialChar ~
19337 return;
19338 \newline
19339 \SpecialChar ~
19340 \SpecialChar ~
19341 global = 3;\SpecialChar ~
19342 /* unreachable */
19343 \newline
19344 }
19345 \layout Standard
19346
19347 will be changed to
19348 \layout Verse
19349
19350
19351 \family typewriter
19352 int global;
19353 \newline
19354
19355 \newline
19356 void f () {
19357 \newline
19358 \SpecialChar ~
19359 \SpecialChar ~
19360 global = 2;
19361 \newline
19362 \SpecialChar ~
19363 \SpecialChar ~
19364 return;
19365 \newline
19366 }
19367 \layout Subsection
19368
19369 Copy-Propagation
19370 \begin_inset LatexCommand \index{Copy propagation}
19371
19372 \end_inset
19373
19374
19375 \layout Verse
19376
19377
19378 \family typewriter
19379 int f() {
19380 \newline
19381 \SpecialChar ~
19382 \SpecialChar ~
19383 int i, j;
19384 \newline
19385 \SpecialChar ~
19386 \SpecialChar ~
19387 i = 10;
19388 \newline
19389 \SpecialChar ~
19390 \SpecialChar ~
19391 j = i;
19392 \newline
19393 \SpecialChar ~
19394 \SpecialChar ~
19395 return j;
19396 \newline
19397 }
19398 \layout Standard
19399
19400 will be changed to
19401 \layout Verse
19402
19403
19404 \family typewriter
19405 int f() {
19406 \newline
19407 \SpecialChar ~
19408 \SpecialChar ~
19409 int i, j;
19410 \newline
19411 \SpecialChar ~
19412 \SpecialChar ~
19413 i = 10;
19414 \newline
19415 \SpecialChar ~
19416 \SpecialChar ~
19417 j = 10;
19418 \newline
19419 \SpecialChar ~
19420 \SpecialChar ~
19421 return 10;
19422 \newline
19423 }
19424 \layout Standard
19425
19426 Note: the dead stores created by this copy propagation will be eliminated
19427  by dead-code elimination.
19428 \layout Subsection
19429
19430 Loop Optimizations
19431 \begin_inset LatexCommand \index{Loop optimization}
19432
19433 \end_inset
19434
19435
19436 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
19437
19438 \end_inset
19439
19440
19441 \layout Standard
19442
19443 Two types of loop optimizations are done by SDCC
19444 \emph on
19445 loop invariant
19446 \emph default
19447  lifting and
19448 \emph on
19449  strength reduction
19450 \emph default
19451  of loop induction variables.
19452  In addition to the strength reduction the optimizer marks the induction
19453  variables and the register allocator tries to keep the induction variables
19454  in registers for the duration of the loop.
19455  Because of this preference of the register allocator
19456 \begin_inset LatexCommand \index{Register allocation}
19457
19458 \end_inset
19459
19460 , loop induction optimization causes an increase in register pressure, which
19461  may cause unwanted spilling of other temporary variables into the stack
19462 \begin_inset LatexCommand \index{stack}
19463
19464 \end_inset
19465
19466  / data space.
19467  The compiler will generate a warning message when it is forced to allocate
19468  extra space either on the stack or data space.
19469  If this extra space allocation is undesirable then induction optimization
19470  can be eliminated either for the entire source file (with -
19471 \begin_inset ERT
19472 status Collapsed
19473
19474 \layout Standard
19475
19476 \backslash
19477 /
19478 \end_inset
19479
19480 -noinduction option) or for a given function only using #pragma\SpecialChar ~
19481 noinduction
19482 \begin_inset LatexCommand \index{\#pragma noinduction}
19483
19484 \end_inset
19485
19486 .
19487 \newline
19488
19489 \newline
19490 Loop Invariant:
19491 \layout Verse
19492
19493
19494 \family typewriter
19495 for (i = 0 ; i < 100 ; i ++)
19496 \newline
19497 \SpecialChar ~
19498 \SpecialChar ~
19499 \SpecialChar ~
19500 \SpecialChar ~
19501 f += k + l;
19502 \layout Standard
19503
19504 changed to
19505 \layout Verse
19506
19507
19508 \family typewriter
19509 itemp = k + l;
19510 \newline
19511 for (i = 0; i < 100; i++)
19512 \newline
19513 \SpecialChar ~
19514 \SpecialChar ~
19515 \SpecialChar ~
19516 \SpecialChar ~
19517 f += itemp;
19518 \layout Standard
19519
19520 As mentioned previously some loop invariants are not as apparent, all static
19521  address computations are also moved out of the loop.
19522 \newline
19523
19524 \newline
19525 Strength Reduction
19526 \begin_inset LatexCommand \index{Strength reduction}
19527
19528 \end_inset
19529
19530 , this optimization substitutes an expression by a cheaper expression:
19531 \layout Verse
19532
19533
19534 \family typewriter
19535 for (i=0;i < 100; i++)
19536 \newline
19537 \SpecialChar ~
19538 \SpecialChar ~
19539 \SpecialChar ~
19540 \SpecialChar ~
19541 ar[i*5] = i*3;
19542 \layout Standard
19543
19544 changed to
19545 \layout Verse
19546
19547
19548 \family typewriter
19549 itemp1 = 0;
19550 \newline
19551 itemp2 = 0;
19552 \newline
19553 for (i=0;i< 100;i++) {
19554 \newline
19555 \SpecialChar ~
19556 \SpecialChar ~
19557 \SpecialChar ~
19558 \SpecialChar ~
19559 ar[itemp1] = itemp2;
19560 \newline
19561 \SpecialChar ~
19562 \SpecialChar ~
19563 \SpecialChar ~
19564 \SpecialChar ~
19565 itemp1 += 5;
19566 \newline
19567 \SpecialChar ~
19568 \SpecialChar ~
19569 \SpecialChar ~
19570 \SpecialChar ~
19571 itemp2 += 3;
19572 \newline
19573 }
19574 \layout Standard
19575
19576 The more expensive multiplication
19577 \begin_inset LatexCommand \index{Multiplication}
19578
19579 \end_inset
19580
19581  is changed to a less expensive addition.
19582 \layout Subsection
19583
19584 Loop Reversing
19585 \begin_inset LatexCommand \index{Loop reversing}
19586
19587 \end_inset
19588
19589
19590 \layout Standard
19591
19592 This optimization is done to reduce the overhead of checking loop boundaries
19593  for every iteration.
19594  Some simple loops can be reversed and implemented using a
19595 \begin_inset Quotes eld
19596 \end_inset
19597
19598 decrement and jump if not zero
19599 \begin_inset Quotes erd
19600 \end_inset
19601
19602  instruction.
19603  SDCC checks for the following criterion to determine if a loop is reversible
19604  (note: more sophisticated compilers use data-dependency analysis to make
19605  this determination, SDCC uses a more simple minded analysis).
19606 \layout Itemize
19607
19608 The 'for' loop is of the form
19609 \newline
19610
19611 \newline
19612
19613 \family typewriter
19614 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
19615  += 1])
19616 \newline
19617 \SpecialChar ~
19618 \SpecialChar ~
19619 \SpecialChar ~
19620 \SpecialChar ~
19621 <for body>
19622 \layout Itemize
19623
19624 The <for body> does not contain
19625 \begin_inset Quotes eld
19626 \end_inset
19627
19628 continue
19629 \begin_inset Quotes erd
19630 \end_inset
19631
19632  or 'break
19633 \begin_inset Quotes erd
19634 \end_inset
19635
19636 .
19637 \layout Itemize
19638
19639 All goto's are contained within the loop.
19640 \layout Itemize
19641
19642 No function calls within the loop.
19643 \layout Itemize
19644
19645 The loop control variable <sym> is not assigned any value within the loop
19646 \layout Itemize
19647
19648 The loop control variable does NOT participate in any arithmetic operation
19649  within the loop.
19650 \layout Itemize
19651
19652 There are NO switch statements in the loop.
19653 \layout Subsection
19654
19655 Algebraic Simplifications
19656 \layout Standard
19657
19658 SDCC does numerous algebraic simplifications, the following is a small sub-set
19659  of these optimizations.
19660 \layout Verse
19661
19662
19663 \family typewriter
19664 i = j + 0;\SpecialChar ~
19665 \SpecialChar ~
19666 \SpecialChar ~
19667 \SpecialChar ~
19668  /* changed to: */\SpecialChar ~
19669 \SpecialChar ~
19670 \SpecialChar ~
19671 \SpecialChar ~
19672  i = j;
19673 \newline
19674 i /= 2;\SpecialChar ~
19675 \SpecialChar ~
19676 \SpecialChar ~
19677 \SpecialChar ~
19678 \SpecialChar ~
19679 \SpecialChar ~
19680 \SpecialChar ~
19681  /* changed to: */\SpecialChar ~
19682 \SpecialChar ~
19683 \SpecialChar ~
19684 \SpecialChar ~
19685  i >>= 1;
19686 \newline
19687 i = j - j;\SpecialChar ~
19688 \SpecialChar ~
19689 \SpecialChar ~
19690 \SpecialChar ~
19691  /* changed to: */\SpecialChar ~
19692 \SpecialChar ~
19693 \SpecialChar ~
19694 \SpecialChar ~
19695  i = 0;
19696 \newline
19697 i = j / 1;\SpecialChar ~
19698 \SpecialChar ~
19699 \SpecialChar ~
19700 \SpecialChar ~
19701  /* changed to: */\SpecialChar ~
19702 \SpecialChar ~
19703 \SpecialChar ~
19704 \SpecialChar ~
19705  i = j;
19706 \layout Standard
19707
19708 Note the subexpressions
19709 \begin_inset LatexCommand \index{Subexpression}
19710
19711 \end_inset
19712
19713  given above are generally introduced by macro expansions or as a result
19714  of copy/constant propagation.
19715 \layout Subsection
19716
19717 'switch' Statements
19718 \begin_inset LatexCommand \label{sub:'switch'-Statements}
19719
19720 \end_inset
19721
19722
19723 \begin_inset LatexCommand \index{switch statement}
19724
19725 \end_inset
19726
19727
19728 \layout Standard
19729
19730 SDCC changes switch statements to jump tables
19731 \begin_inset LatexCommand \index{jump tables}
19732
19733 \end_inset
19734
19735  when the following conditions are true.
19736
19737 \layout Itemize
19738
19739 The case labels are in numerical sequence, the labels need not be in order,
19740  and the starting number need not be one or zero.
19741 \begin_deeper
19742 \layout Verse
19743
19744
19745 \family typewriter
19746 switch(i) {\SpecialChar ~
19747 \SpecialChar ~
19748 \SpecialChar ~
19749 \SpecialChar ~
19750 \SpecialChar ~
19751 \SpecialChar ~
19752 \SpecialChar ~
19753 \SpecialChar ~
19754 \SpecialChar ~
19755 \SpecialChar ~
19756 \SpecialChar ~
19757 \SpecialChar ~
19758 \SpecialChar ~
19759 \SpecialChar ~
19760 \SpecialChar ~
19761 \SpecialChar ~
19762 \SpecialChar ~
19763 \SpecialChar ~
19764 \SpecialChar ~
19765 \SpecialChar ~
19766 \SpecialChar ~
19767 \SpecialChar ~
19768 \SpecialChar ~
19769 \SpecialChar ~
19770 \SpecialChar ~
19771 \SpecialChar ~
19772 switch (i) {
19773 \newline
19774 \SpecialChar ~
19775 \SpecialChar ~
19776 \SpecialChar ~
19777 case 4: ...\SpecialChar ~
19778 \SpecialChar ~
19779 \SpecialChar ~
19780 \SpecialChar ~
19781 \SpecialChar ~
19782 \SpecialChar ~
19783 \SpecialChar ~
19784 \SpecialChar ~
19785 \SpecialChar ~
19786 \SpecialChar ~
19787 \SpecialChar ~
19788 \SpecialChar ~
19789 \SpecialChar ~
19790 \SpecialChar ~
19791 \SpecialChar ~
19792 \SpecialChar ~
19793 \SpecialChar ~
19794 \SpecialChar ~
19795 \SpecialChar ~
19796 \SpecialChar ~
19797 \SpecialChar ~
19798 \SpecialChar ~
19799 \SpecialChar ~
19800 \SpecialChar ~
19801 \SpecialChar ~
19802 \SpecialChar ~
19803 case 0: ...
19804
19805 \newline
19806 \SpecialChar ~
19807 \SpecialChar ~
19808 \SpecialChar ~
19809 case 5: ...\SpecialChar ~
19810 \SpecialChar ~
19811 \SpecialChar ~
19812 \SpecialChar ~
19813 \SpecialChar ~
19814 \SpecialChar ~
19815 \SpecialChar ~
19816 \SpecialChar ~
19817 \SpecialChar ~
19818 \SpecialChar ~
19819 \SpecialChar ~
19820 \SpecialChar ~
19821 \SpecialChar ~
19822 \SpecialChar ~
19823 \SpecialChar ~
19824 \SpecialChar ~
19825 \SpecialChar ~
19826 \SpecialChar ~
19827 \SpecialChar ~
19828 \SpecialChar ~
19829 \SpecialChar ~
19830 \SpecialChar ~
19831 \SpecialChar ~
19832 \SpecialChar ~
19833 \SpecialChar ~
19834 \SpecialChar ~
19835 case 1: ...
19836
19837 \newline
19838 \SpecialChar ~
19839 \SpecialChar ~
19840 \SpecialChar ~
19841 case 3: ...\SpecialChar ~
19842 \SpecialChar ~
19843 \SpecialChar ~
19844 \SpecialChar ~
19845 \SpecialChar ~
19846 \SpecialChar ~
19847 \SpecialChar ~
19848 \SpecialChar ~
19849 \SpecialChar ~
19850 \SpecialChar ~
19851 \SpecialChar ~
19852 \SpecialChar ~
19853 \SpecialChar ~
19854 \SpecialChar ~
19855 \SpecialChar ~
19856 \SpecialChar ~
19857 \SpecialChar ~
19858 \SpecialChar ~
19859 \SpecialChar ~
19860 \SpecialChar ~
19861 \SpecialChar ~
19862 \SpecialChar ~
19863 \SpecialChar ~
19864 \SpecialChar ~
19865 \SpecialChar ~
19866 \SpecialChar ~
19867 case 2: ...
19868
19869 \newline
19870 \SpecialChar ~
19871 \SpecialChar ~
19872 \SpecialChar ~
19873 case 6: ...\SpecialChar ~
19874 \SpecialChar ~
19875 \SpecialChar ~
19876 \SpecialChar ~
19877 \SpecialChar ~
19878 \SpecialChar ~
19879 \SpecialChar ~
19880 \SpecialChar ~
19881 \SpecialChar ~
19882 \SpecialChar ~
19883 \SpecialChar ~
19884 \SpecialChar ~
19885 \SpecialChar ~
19886 \SpecialChar ~
19887 \SpecialChar ~
19888 \SpecialChar ~
19889 \SpecialChar ~
19890 \SpecialChar ~
19891 \SpecialChar ~
19892 \SpecialChar ~
19893 \SpecialChar ~
19894 \SpecialChar ~
19895 \SpecialChar ~
19896 \SpecialChar ~
19897 \SpecialChar ~
19898 \SpecialChar ~
19899 case 3: ...
19900
19901 \newline
19902 }\SpecialChar ~
19903 \SpecialChar ~
19904 \SpecialChar ~
19905 \SpecialChar ~
19906 \SpecialChar ~
19907 \SpecialChar ~
19908 \SpecialChar ~
19909 \SpecialChar ~
19910 \SpecialChar ~
19911 \SpecialChar ~
19912 \SpecialChar ~
19913 \SpecialChar ~
19914 \SpecialChar ~
19915 \SpecialChar ~
19916 \SpecialChar ~
19917 \SpecialChar ~
19918 \SpecialChar ~
19919 \SpecialChar ~
19920 \SpecialChar ~
19921 \SpecialChar ~
19922 \SpecialChar ~
19923 \SpecialChar ~
19924 \SpecialChar ~
19925 \SpecialChar ~
19926 \SpecialChar ~
19927 \SpecialChar ~
19928 \SpecialChar ~
19929 \SpecialChar ~
19930 \SpecialChar ~
19931 \SpecialChar ~
19932 \SpecialChar ~
19933 \SpecialChar ~
19934 \SpecialChar ~
19935 \SpecialChar ~
19936 \SpecialChar ~
19937 \SpecialChar ~
19938 }
19939 \layout Standard
19940
19941 Both the above switch statements will be implemented using a jump-table.
19942  The example to the right side is slightly more efficient as the check for
19943  the lower boundary of the jump-table is not needed.
19944 \end_deeper
19945 \layout Itemize
19946
19947 The number of case labels is at least three, since it takes two conditional
19948  statements to handle the boundary conditions.
19949 \layout Itemize
19950
19951 The number of case labels is less than 84, since each label takes 3 bytes
19952  and a jump-table can be utmost 256 bytes long.
19953 \layout Standard
19954
19955 Switch statements which have gaps in the numeric sequence or those that
19956  have more that 84 case labels can be split into more than one switch statement
19957  for efficient code generation, e.g.:
19958 \layout Verse
19959
19960
19961 \family typewriter
19962 switch (i) {
19963 \newline
19964 \SpecialChar ~
19965 \SpecialChar ~
19966 case 1: ...
19967
19968 \newline
19969 \SpecialChar ~
19970 \SpecialChar ~
19971 case 2: ...
19972
19973 \newline
19974 \SpecialChar ~
19975 \SpecialChar ~
19976 case 3: ...
19977
19978 \newline
19979 \SpecialChar ~
19980 \SpecialChar ~
19981 case 4: ...
19982
19983 \newline
19984 \SpecialChar ~
19985 \SpecialChar ~
19986 case 9: ...
19987
19988 \newline
19989 \SpecialChar ~
19990 \SpecialChar ~
19991 case 10: ...
19992
19993 \newline
19994 \SpecialChar ~
19995 \SpecialChar ~
19996 case 11: ...
19997
19998 \newline
19999 \SpecialChar ~
20000 \SpecialChar ~
20001 case 12: ...
20002
20003 \newline
20004 }
20005 \layout Standard
20006
20007 If the above switch statement is broken down into two switch statements
20008 \layout Verse
20009
20010
20011 \family typewriter
20012 switch (i) {
20013 \newline
20014 \SpecialChar ~
20015 \SpecialChar ~
20016 case 1: ...
20017
20018 \newline
20019 \SpecialChar ~
20020 \SpecialChar ~
20021 case 2: ...
20022
20023 \newline
20024 \SpecialChar ~
20025 \SpecialChar ~
20026 case 3: ...
20027
20028 \newline
20029 \SpecialChar ~
20030 \SpecialChar ~
20031 case 4: ...
20032
20033 \newline
20034 }
20035 \layout Standard
20036
20037 and
20038 \layout Verse
20039
20040
20041 \family typewriter
20042 switch (i) {
20043 \newline
20044 \SpecialChar ~
20045 \SpecialChar ~
20046 case 9:\SpecialChar ~
20047 \SpecialChar ~
20048 ...
20049
20050 \newline
20051 \SpecialChar ~
20052 \SpecialChar ~
20053 case 10:\SpecialChar ~
20054 ...
20055
20056 \newline
20057 \SpecialChar ~
20058 \SpecialChar ~
20059 case 11:\SpecialChar ~
20060 ...
20061
20062 \newline
20063 \SpecialChar ~
20064 \SpecialChar ~
20065 case 12:\SpecialChar ~
20066 ...
20067
20068 \newline
20069 }
20070 \layout Standard
20071
20072 then both the switch statements will be implemented using jump-tables whereas
20073  the unmodified switch statement will not be.
20074  You might also consider inserting dummy cases 0 and 5 to 8 in this example.
20075
20076 \newline
20077 The pragma nojtbound
20078 \begin_inset LatexCommand \index{\#pragma nojtbound}
20079
20080 \end_inset
20081
20082  can be used to turn off checking the
20083 \emph on
20084 j
20085 \emph default
20086 ump
20087 \emph on
20088 t
20089 \emph default
20090 able
20091 \emph on
20092 bound
20093 \emph default
20094 aries.
20095  It has no effect if a default label is supplied.
20096  Use of this pragma is dangerous: if the switch argument is not matched
20097  by a case statement the processor will happily jump into Nirvana.
20098 \layout Subsection
20099
20100 Bit-shifting Operations
20101 \begin_inset LatexCommand \index{Bit shifting}
20102
20103 \end_inset
20104
20105 .
20106 \layout Standard
20107
20108 Bit shifting is one of the most frequently used operation in embedded programmin
20109 g.
20110  SDCC tries to implement bit-shift operations in the most efficient way
20111  possible, e.g.:
20112 \layout Verse
20113
20114
20115 \family typewriter
20116 unsigned char i;
20117 \newline
20118 ...
20119
20120 \newline
20121 i >>= 4;
20122 \newline
20123 ...
20124 \layout Standard
20125
20126 generates the following code:
20127 \layout Verse
20128
20129
20130 \family typewriter
20131 mov\SpecialChar ~
20132  a,_i
20133 \newline
20134 swap a
20135 \newline
20136 anl\SpecialChar ~
20137  a,#0x0f
20138 \newline
20139 mov\SpecialChar ~
20140  _i,a
20141 \layout Standard
20142
20143 In general SDCC will never setup a loop if the shift count is known.
20144  Another example:
20145 \layout Verse
20146
20147
20148 \family typewriter
20149 unsigned int i;
20150 \newline
20151 ...
20152
20153 \newline
20154 i >>= 9;
20155 \newline
20156 ...
20157 \layout Standard
20158
20159 will generate:
20160 \layout Verse
20161
20162
20163 \family typewriter
20164 mov\SpecialChar ~
20165 \SpecialChar ~
20166 a,(_i + 1)
20167 \newline
20168 mov\SpecialChar ~
20169 \SpecialChar ~
20170 (_i + 1),#0x00
20171 \newline
20172 clr\SpecialChar ~
20173 \SpecialChar ~
20174 c
20175 \newline
20176 rrc\SpecialChar ~
20177 \SpecialChar ~
20178 a
20179 \newline
20180 mov\SpecialChar ~
20181 \SpecialChar ~
20182 _i,a
20183 \layout Subsection
20184
20185 Bit-rotation
20186 \begin_inset LatexCommand \index{Bit rotation}
20187
20188 \end_inset
20189
20190
20191 \layout Standard
20192
20193 A special case of the bit-shift operation is bit rotation
20194 \begin_inset LatexCommand \index{rotating bits}
20195
20196 \end_inset
20197
20198 , SDCC recognizes the following expression to be a left bit-rotation:
20199 \layout Verse
20200
20201
20202 \family typewriter
20203 \series bold
20204 unsigned
20205 \series default
20206 \SpecialChar ~
20207 \SpecialChar ~
20208 char i;\SpecialChar ~
20209 \SpecialChar ~
20210 \SpecialChar ~
20211 \SpecialChar ~
20212 \SpecialChar ~
20213 \SpecialChar ~
20214 \SpecialChar ~
20215 \SpecialChar ~
20216 \SpecialChar ~
20217 \SpecialChar ~
20218 \SpecialChar ~
20219 /* unsigned is needed for rotation */
20220 \newline
20221 ...
20222
20223 \newline
20224 i = ((i << 1) | (i >> 7));
20225 \family default
20226
20227 \newline
20228
20229 \family typewriter
20230 ...
20231 \layout Standard
20232
20233 will generate the following code:
20234 \layout Verse
20235
20236
20237 \family typewriter
20238 mov\SpecialChar ~
20239 \SpecialChar ~
20240 a,_i
20241 \newline
20242 rl\SpecialChar ~
20243 \SpecialChar ~
20244 \SpecialChar ~
20245 a
20246 \newline
20247 mov\SpecialChar ~
20248 \SpecialChar ~
20249 _i,a
20250 \layout Standard
20251
20252 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
20253 ns of this case will also be recognized as bit-rotation, i.e.:
20254 \layout Verse
20255
20256
20257 \family typewriter
20258 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
20259 \layout Subsection
20260
20261 Nibble and Byte Swapping
20262 \layout Standard
20263
20264 Other special cases of the bit-shift operations are nibble or byte swapping
20265 \begin_inset LatexCommand \index{swapping nibbles/bytes}
20266
20267 \end_inset
20268
20269 , SDCC recognizes the following expressions:
20270 \layout Verse
20271
20272
20273 \family typewriter
20274 \series bold
20275 unsigned
20276 \series default
20277 \SpecialChar ~
20278 \SpecialChar ~
20279 char i;
20280 \newline
20281
20282 \series bold
20283 unsigned
20284 \series default
20285 \SpecialChar ~
20286 \SpecialChar ~
20287 int j;
20288 \newline
20289 ...
20290
20291 \newline
20292 i = ((i << 4) | (i >> 4));
20293 \family default
20294
20295 \newline
20296
20297 \family typewriter
20298 j = ((j << 8) | (j >> 8));
20299 \layout Standard
20300
20301 and generates a swap instruction for the nibble swapping
20302 \begin_inset LatexCommand \index{Nibble swapping}
20303
20304 \end_inset
20305
20306  or move instructions for the byte swapping
20307 \begin_inset LatexCommand \index{Byte swapping}
20308
20309 \end_inset
20310
20311 .
20312  The
20313 \begin_inset Quotes sld
20314 \end_inset
20315
20316 j
20317 \begin_inset Quotes srd
20318 \end_inset
20319
20320  example can be used to convert from little to big-endian or vice versa.
20321  If you want to change the endianness of a
20322 \emph on
20323 signed
20324 \emph default
20325  integer you have to cast to
20326 \family typewriter
20327 (unsigned int)
20328 \family default
20329  first.
20330 \layout Standard
20331
20332 Note that SDCC stores numbers in little-endian
20333 \begin_inset Foot
20334 collapsed false
20335
20336 \layout Standard
20337
20338 Usually 8-bit processors don't care much about endianness.
20339  This is not the case for the standard 8051 which only has an instruction
20340  to increment its
20341 \emph on
20342 dptr
20343 \emph default
20344
20345 \begin_inset LatexCommand \index{DPTR}
20346
20347 \end_inset
20348
20349 -datapointer
20350 \emph on
20351
20352 \emph default
20353 so little-endian is the more efficient byte order.
20354 \end_inset
20355
20356
20357 \begin_inset LatexCommand \index{little-endian}
20358
20359 \end_inset
20360
20361
20362 \begin_inset LatexCommand \index{Endianness}
20363
20364 \end_inset
20365
20366  format (i.e.
20367  lowest order first).
20368 \layout Subsection
20369
20370 Highest Order Bit
20371 \begin_inset LatexCommand \index{Highest Order Bit}
20372
20373 \end_inset
20374
20375
20376 \layout Standard
20377
20378 It is frequently required to obtain the highest order bit of an integral
20379  type (long, int, short or char types).
20380  SDCC recognizes the following expression to yield the highest order bit
20381  and generates optimized code for it, e.g.:
20382 \layout Verse
20383
20384
20385 \family typewriter
20386 unsigned int gint;
20387 \newline
20388
20389 \newline
20390 foo () {
20391 \newline
20392 \SpecialChar ~
20393 \SpecialChar ~
20394 unsigned char hob;
20395 \newline
20396 \SpecialChar ~
20397 \SpecialChar ~
20398 ...
20399
20400 \newline
20401 \SpecialChar ~
20402 \SpecialChar ~
20403 hob = (gint >> 15) & 1;
20404 \newline
20405 \SpecialChar ~
20406 \SpecialChar ~
20407 ..
20408
20409 \newline
20410 }
20411 \layout Standard
20412
20413 will generate the following code:
20414 \layout Verse
20415
20416
20417 \family typewriter
20418 \SpecialChar ~
20419 \SpecialChar ~
20420 \SpecialChar ~
20421 \SpecialChar ~
20422 \SpecialChar ~
20423 \SpecialChar ~
20424 \SpecialChar ~
20425 \SpecialChar ~
20426 \SpecialChar ~
20427 \SpecialChar ~
20428 \SpecialChar ~
20429 \SpecialChar ~
20430 \SpecialChar ~
20431 \SpecialChar ~
20432 \SpecialChar ~
20433 \SpecialChar ~
20434 \SpecialChar ~
20435 \SpecialChar ~
20436 \SpecialChar ~
20437 \SpecialChar ~
20438 \SpecialChar ~
20439 \SpecialChar ~
20440 \SpecialChar ~
20441 \SpecialChar ~
20442 \SpecialChar ~
20443  61 ;\SpecialChar ~
20444  hob.c 7
20445 \newline
20446 000A E5*01\SpecialChar ~
20447 \SpecialChar ~
20448 \SpecialChar ~
20449 \SpecialChar ~
20450 \SpecialChar ~
20451 \SpecialChar ~
20452 \SpecialChar ~
20453 \SpecialChar ~
20454 \SpecialChar ~
20455 \SpecialChar ~
20456 \SpecialChar ~
20457 \SpecialChar ~
20458 \SpecialChar ~
20459 \SpecialChar ~
20460 \SpecialChar ~
20461  62\SpecialChar ~
20462 \SpecialChar ~
20463 \SpecialChar ~
20464 \SpecialChar ~
20465 \SpecialChar ~
20466 \SpecialChar ~
20467 \SpecialChar ~
20468 \SpecialChar ~
20469  mov\SpecialChar ~
20470 \SpecialChar ~
20471  a,(_gint + 1)
20472 \newline
20473 000C 23\SpecialChar ~
20474 \SpecialChar ~
20475 \SpecialChar ~
20476 \SpecialChar ~
20477 \SpecialChar ~
20478 \SpecialChar ~
20479 \SpecialChar ~
20480 \SpecialChar ~
20481 \SpecialChar ~
20482 \SpecialChar ~
20483 \SpecialChar ~
20484 \SpecialChar ~
20485 \SpecialChar ~
20486 \SpecialChar ~
20487 \SpecialChar ~
20488 \SpecialChar ~
20489 \SpecialChar ~
20490 \SpecialChar ~
20491  63\SpecialChar ~
20492 \SpecialChar ~
20493 \SpecialChar ~
20494 \SpecialChar ~
20495 \SpecialChar ~
20496 \SpecialChar ~
20497 \SpecialChar ~
20498 \SpecialChar ~
20499  rl\SpecialChar ~
20500 \SpecialChar ~
20501 \SpecialChar ~
20502  a
20503 \newline
20504 000D 54 01\SpecialChar ~
20505 \SpecialChar ~
20506 \SpecialChar ~
20507 \SpecialChar ~
20508 \SpecialChar ~
20509 \SpecialChar ~
20510 \SpecialChar ~
20511 \SpecialChar ~
20512 \SpecialChar ~
20513 \SpecialChar ~
20514 \SpecialChar ~
20515 \SpecialChar ~
20516 \SpecialChar ~
20517 \SpecialChar ~
20518 \SpecialChar ~
20519  64\SpecialChar ~
20520 \SpecialChar ~
20521 \SpecialChar ~
20522 \SpecialChar ~
20523 \SpecialChar ~
20524 \SpecialChar ~
20525 \SpecialChar ~
20526 \SpecialChar ~
20527  anl\SpecialChar ~
20528 \SpecialChar ~
20529  a,#0x01
20530 \newline
20531 000F F5*02\SpecialChar ~
20532 \SpecialChar ~
20533 \SpecialChar ~
20534 \SpecialChar ~
20535 \SpecialChar ~
20536 \SpecialChar ~
20537 \SpecialChar ~
20538 \SpecialChar ~
20539 \SpecialChar ~
20540 \SpecialChar ~
20541 \SpecialChar ~
20542 \SpecialChar ~
20543 \SpecialChar ~
20544 \SpecialChar ~
20545 \SpecialChar ~
20546  65\SpecialChar ~
20547 \SpecialChar ~
20548 \SpecialChar ~
20549 \SpecialChar ~
20550 \SpecialChar ~
20551 \SpecialChar ~
20552 \SpecialChar ~
20553 \SpecialChar ~
20554  mov\SpecialChar ~
20555 \SpecialChar ~
20556  _foo_hob_1_1,a
20557 \layout Standard
20558
20559 Variations of this case however will
20560 \emph on
20561 not
20562 \emph default
20563  be recognized.
20564  It is a standard C expression, so I heartily recommend this be the only
20565  way to get the highest order bit, (it is portable).
20566  Of course it will be recognized even if it is embedded in other expressions,
20567  e.g.:
20568 \layout Verse
20569
20570
20571 \family typewriter
20572 xyz = gint + ((gint >> 15) & 1);
20573 \layout Standard
20574
20575 will still be recognized.
20576 \layout Subsection
20577
20578 Peephole Optimizer
20579 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
20580
20581 \end_inset
20582
20583
20584 \begin_inset LatexCommand \index{Peephole optimizer}
20585
20586 \end_inset
20587
20588
20589 \layout Standard
20590
20591 The compiler uses a rule based, pattern matching and re-writing mechanism
20592  for peep-hole optimization.
20593  It is inspired by
20594 \emph on
20595 copt
20596 \emph default
20597  a peep-hole optimizer by Christopher W.
20598  Fraser (cwfraser@microsoft.com).
20599  A default set of rules are compiled into the compiler, additional rules
20600  may be added with the
20601 \emph on
20602 -
20603 \begin_inset ERT
20604 status Collapsed
20605
20606 \layout Standard
20607
20608 \backslash
20609 /
20610 \end_inset
20611
20612 -peep-file
20613 \begin_inset LatexCommand \index{-\/-peep-file}
20614
20615 \end_inset
20616
20617  <filename>
20618 \emph default
20619  option.
20620  The rule language is best illustrated with examples.
20621 \layout Verse
20622
20623
20624 \family typewriter
20625 replace {
20626 \newline
20627 \SpecialChar ~
20628 \SpecialChar ~
20629 mov %1,a
20630 \newline
20631 \SpecialChar ~
20632 \SpecialChar ~
20633 mov a,%1
20634 \newline
20635 } by {
20636 \newline
20637 \SpecialChar ~
20638 \SpecialChar ~
20639 mov %1,a
20640 \newline
20641 }
20642 \layout Standard
20643
20644 The above rule will change the following assembly
20645 \begin_inset LatexCommand \index{Assembler routines}
20646
20647 \end_inset
20648
20649  sequence:
20650 \layout Verse
20651
20652
20653 \family typewriter
20654 mov r1,a
20655 \newline
20656 mov a,r1
20657 \layout Standard
20658
20659 to
20660 \layout Verse
20661
20662
20663 \family typewriter
20664 mov r1,a
20665 \layout Standard
20666
20667 Note: All occurrences of a
20668 \emph on
20669 %n
20670 \emph default
20671  (pattern variable) must denote the same string.
20672  With the above rule, the assembly sequence:
20673 \layout Verse
20674
20675
20676 \family typewriter
20677 mov r1,a
20678 \newline
20679 mov a,r2
20680 \layout Standard
20681
20682 will remain unmodified.
20683 \newline
20684
20685 \newline
20686 Other special case optimizations may be added by the user (via
20687 \emph on
20688 -
20689 \begin_inset ERT
20690 status Collapsed
20691
20692 \layout Standard
20693
20694 \backslash
20695 /
20696 \end_inset
20697
20698 -peep-file option
20699 \emph default
20700 ).
20701  E.g.
20702  some variants of the 8051 MCU
20703 \begin_inset LatexCommand \index{MCS51 variants}
20704
20705 \end_inset
20706
20707  allow only
20708 \family typewriter
20709 ajmp
20710 \family default
20711  and
20712 \family typewriter
20713 acall
20714 \family default
20715 .
20716  The following two rules will change all
20717 \family typewriter
20718 ljmp
20719 \family default
20720  and
20721 \family typewriter
20722 lcall
20723 \family default
20724  to
20725 \family typewriter
20726 ajmp
20727 \family default
20728  and
20729 \family typewriter
20730 acall
20731 \layout Verse
20732
20733
20734 \family typewriter
20735 replace { lcall %1 } by { acall %1 }
20736 \newline
20737 replace { ljmp %1 } by { ajmp %1 }
20738 \layout Standard
20739
20740 The
20741 \emph on
20742 inline-assembler code
20743 \emph default
20744  is also passed through the peep hole optimizer, thus the peephole optimizer
20745  can also be used as an assembly level macro expander.
20746  The rules themselves are MCU dependent whereas the rule language infra-structur
20747 e is MCU independent.
20748  Peephole optimization rules for other MCU can be easily programmed using
20749  the rule language.
20750 \newline
20751
20752 \newline
20753 The syntax for a rule is as follows:
20754 \layout Verse
20755
20756
20757 \family typewriter
20758 rule := replace [ restart ] '{' <assembly sequence> '
20759 \backslash
20760 n'
20761 \newline
20762 \SpecialChar ~
20763  \SpecialChar ~
20764  \SpecialChar ~
20765  \SpecialChar ~
20766  \SpecialChar ~
20767  \SpecialChar ~
20768  \SpecialChar ~
20769  \SpecialChar ~
20770  \SpecialChar ~
20771  \SpecialChar ~
20772  \SpecialChar ~
20773  \SpecialChar ~
20774  \SpecialChar ~
20775  \SpecialChar ~
20776  '}' by '{' '
20777 \backslash
20778 n'
20779 \newline
20780 \SpecialChar ~
20781  \SpecialChar ~
20782  \SpecialChar ~
20783  \SpecialChar ~
20784  \SpecialChar ~
20785  \SpecialChar ~
20786  \SpecialChar ~
20787  \SpecialChar ~
20788  \SpecialChar ~
20789  \SpecialChar ~
20790  \SpecialChar ~
20791  \SpecialChar ~
20792  \SpecialChar ~
20793  \SpecialChar ~
20794  \SpecialChar ~
20795  \SpecialChar ~
20796  <assembly sequence> '
20797 \backslash
20798 n'
20799 \newline
20800 \SpecialChar ~
20801  \SpecialChar ~
20802  \SpecialChar ~
20803  \SpecialChar ~
20804  \SpecialChar ~
20805  \SpecialChar ~
20806  \SpecialChar ~
20807  \SpecialChar ~
20808  \SpecialChar ~
20809  \SpecialChar ~
20810  \SpecialChar ~
20811  \SpecialChar ~
20812  \SpecialChar ~
20813  \SpecialChar ~
20814  '}' [if <functionName> ] '
20815 \backslash
20816 n'
20817 \layout Standard
20818
20819 <assembly sequence> := assembly instruction (each instruction including
20820  labels must be on a separate line).
20821 \newline
20822
20823 \newline
20824 The optimizer will apply to the rules one by one from the top in the sequence
20825  of their appearance, it will terminate when all rules are exhausted.
20826  If the 'restart' option is specified, then the optimizer will start matching
20827  the rules again from the top, this option for a rule is expensive (performance)
20828 , it is intended to be used in situations where a transformation will trigger
20829  the same rule again.
20830  An example of this (not a good one, it has side effects) is the following
20831  rule:
20832 \layout Verse
20833
20834
20835 \family typewriter
20836 replace restart {
20837 \newline
20838 \SpecialChar ~
20839 \SpecialChar ~
20840 pop %1
20841 \newline
20842 \SpecialChar ~
20843 \SpecialChar ~
20844 push %1 } by {
20845 \newline
20846 \SpecialChar ~
20847 \SpecialChar ~
20848 ; nop
20849 \newline
20850 }
20851 \layout Standard
20852
20853 Note that the replace pattern cannot be a blank, but can be a comment line.
20854  Without the 'restart' option only the innermost 'pop' 'push' pair would
20855  be eliminated, i.e.:
20856 \layout Verse
20857
20858
20859 \family typewriter
20860 pop ar1
20861 \newline
20862 pop ar2
20863 \newline
20864 push ar2
20865 \newline
20866 push ar1
20867 \layout Standard
20868
20869 would result in:
20870 \layout Verse
20871
20872
20873 \family typewriter
20874 pop ar1
20875 \newline
20876 ; nop
20877 \newline
20878 push ar1
20879 \layout Standard
20880
20881
20882 \emph on
20883 with
20884 \emph default
20885  the restart option the rule will be applied again to the resulting code
20886  and then all the pop-push pairs will be eliminated to yield:
20887 \layout Verse
20888
20889
20890 \family typewriter
20891 ; nop
20892 \newline
20893 ; nop
20894 \layout Standard
20895
20896 A conditional function can be attached to a rule.
20897  Attaching rules are somewhat more involved, let me illustrate this with
20898  an example.
20899 \layout Verse
20900
20901
20902 \family typewriter
20903 replace {
20904 \newline
20905 \SpecialChar ~
20906  \SpecialChar ~
20907  \SpecialChar ~
20908 ljmp %5
20909 \newline
20910 %2:
20911 \newline
20912 } by {
20913 \newline
20914 \SpecialChar ~
20915  \SpecialChar ~
20916  \SpecialChar ~
20917 sjmp %5
20918 \newline
20919 %2:
20920 \newline
20921 } if labelInRange
20922 \layout Standard
20923
20924 The optimizer does a look-up of a function name table defined in function
20925
20926 \emph on
20927 callFuncByName
20928 \emph default
20929  in the source file SDCCpeeph.c, with the name
20930 \emph on
20931 labelInRange
20932 \emph default
20933 .
20934  If it finds a corresponding entry the function is called.
20935  Note there can be no parameters specified for these functions, in this
20936  case the use of
20937 \emph on
20938 %5
20939 \emph default
20940  is crucial, since the function
20941 \emph on
20942 labelInRange
20943 \emph default
20944  expects to find the label in that particular variable (the hash table containin
20945 g the variable bindings is passed as a parameter).
20946  If you want to code more such functions, take a close look at the function
20947  labelInRange and the calling mechanism in source file SDCCpeeph.c.
20948  Currently implemented are
20949 \emph on
20950 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
20951  24bitMode, portIsDS390, 24bitModeAndPortDS390
20952 \emph default
20953 and
20954 \emph on
20955  notVolatile
20956 \emph default
20957 .
20958 \layout Standard
20959
20960 I know this whole thing is a little kludgey, but maybe some day we will
20961  have some better means.
20962  If you are looking at this file, you will see the default rules that are
20963  compiled into the compiler, you can add your own rules in the default set
20964  there if you get tired of specifying the -
20965 \begin_inset ERT
20966 status Collapsed
20967
20968 \layout Standard
20969
20970 \backslash
20971 /
20972 \end_inset
20973
20974 -peep-file option.
20975 \layout Section
20976
20977 ANSI-Compliance
20978 \begin_inset LatexCommand \index{ANSI-compliance}
20979
20980 \end_inset
20981
20982
20983 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
20984
20985 \end_inset
20986
20987
20988 \layout Standard
20989
20990 Deviations from the compliance:
20991 \layout Itemize
20992
20993 functions are not always reentrant
20994 \begin_inset LatexCommand \index{reentrant}
20995
20996 \end_inset
20997
20998 .
20999 \layout Itemize
21000
21001 structures cannot be assigned values directly, cannot be passed as function
21002  parameters or assigned to each other and cannot be a return value from
21003  a function, e.g.:
21004 \begin_deeper
21005 \layout Verse
21006
21007
21008 \family typewriter
21009 struct s { ...
21010  };
21011 \newline
21012 struct s s1, s2;
21013 \newline
21014 foo()
21015 \newline
21016 {
21017 \newline
21018 \SpecialChar ~
21019 \SpecialChar ~
21020 \SpecialChar ~
21021 \SpecialChar ~
21022 ...
21023
21024 \newline
21025 \SpecialChar ~
21026 \SpecialChar ~
21027 \SpecialChar ~
21028 \SpecialChar ~
21029 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
21030 \newline
21031 \SpecialChar ~
21032 \SpecialChar ~
21033 \SpecialChar ~
21034 \SpecialChar ~
21035 ...
21036
21037 \newline
21038 }
21039 \newline
21040 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
21041  */
21042 \newline
21043 {
21044 \newline
21045 \SpecialChar ~
21046 \SpecialChar ~
21047 \SpecialChar ~
21048 \SpecialChar ~
21049 struct s rets;
21050 \newline
21051 \SpecialChar ~
21052 \SpecialChar ~
21053 \SpecialChar ~
21054 \SpecialChar ~
21055 ...
21056
21057 \newline
21058 \SpecialChar ~
21059 \SpecialChar ~
21060 \SpecialChar ~
21061 \SpecialChar ~
21062 return rets;/* is invalid in SDCC although allowed in ANSI */
21063 \newline
21064 }
21065 \end_deeper
21066 \layout Itemize
21067
21068 'long long
21069 \begin_inset LatexCommand \index{long long (not supported)}
21070
21071 \end_inset
21072
21073 ' (64 bit integers
21074 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
21075
21076 \end_inset
21077
21078 ) not supported.
21079 \layout Itemize
21080
21081 'double
21082 \begin_inset LatexCommand \index{double (not supported)}
21083
21084 \end_inset
21085
21086 ' precision floating point
21087 \begin_inset LatexCommand \index{Floating point support}
21088
21089 \end_inset
21090
21091 not supported.
21092 \layout Itemize
21093
21094 No support for setjmp
21095 \begin_inset LatexCommand \index{setjmp (not supported)}
21096
21097 \end_inset
21098
21099  and longjmp
21100 \begin_inset LatexCommand \index{longjmp (not supported)}
21101
21102 \end_inset
21103
21104  (for now).
21105 \layout Itemize
21106
21107 Old K&R style
21108 \begin_inset LatexCommand \index{K\&R style}
21109
21110 \end_inset
21111
21112  function declarations are NOT allowed.
21113 \begin_deeper
21114 \layout Verse
21115
21116
21117 \family typewriter
21118 foo(i,j) /* this old style of function declarations */
21119 \newline
21120 int i,j; /* are valid in ANSI but not valid in SDCC */
21121 \newline
21122 {
21123 \newline
21124 \SpecialChar ~
21125 \SpecialChar ~
21126 \SpecialChar ~
21127 \SpecialChar ~
21128 ...
21129
21130 \newline
21131 }
21132 \end_deeper
21133 \layout Section
21134
21135 Cyclomatic Complexity
21136 \begin_inset LatexCommand \index{Cyclomatic complexity}
21137
21138 \end_inset
21139
21140
21141 \layout Standard
21142
21143 Cyclomatic complexity of a function is defined as the number of independent
21144  paths the program can take during execution of the function.
21145  This is an important number since it defines the number test cases you
21146  have to generate to validate the function.
21147  The accepted industry standard for complexity number is 10, if the cyclomatic
21148  complexity reported by SDCC exceeds 10 you should think about simplification
21149  of the function logic.
21150  Note that the complexity level is not related to the number of lines of
21151  code in a function.
21152  Large functions can have low complexity, and small functions can have large
21153  complexity levels.
21154
21155 \newline
21156
21157 \newline
21158 SDCC uses the following formula to compute the complexity:
21159 \newline
21160
21161 \layout Standard
21162
21163 complexity = (number of edges in control flow graph) - (number of nodes
21164  in control flow graph) + 2;
21165 \newline
21166
21167 \newline
21168 Having said that the industry standard is 10, you should be aware that in
21169  some cases it be may unavoidable to have a complexity level of less than
21170  10.
21171  For example if you have switch statement with more than 10 case labels,
21172  each case label adds one to the complexity level.
21173  The complexity level is by no means an absolute measure of the algorithmic
21174  complexity of the function, it does however provide a good starting point
21175  for which functions you might look at for further optimization.
21176 \layout Section
21177
21178 Retargetting for other Processors
21179 \layout Standard
21180
21181 The issues for retargetting the compiler are far too numerous to be covered
21182  by this document.
21183  What follows is a brief description of each of the seven phases of the
21184  compiler and its MCU dependency.
21185 \layout Itemize
21186
21187 Parsing the source and building the annotated parse tree.
21188  This phase is largely MCU independent (except for the language extensions).
21189  Syntax & semantic checks are also done in this phase, along with some initial
21190  optimizations like back patching labels and the pattern matching optimizations
21191  like bit-rotation etc.
21192 \layout Itemize
21193
21194 The second phase involves generating an intermediate code which can be easy
21195  manipulated during the later phases.
21196  This phase is entirely MCU independent.
21197  The intermediate code generation assumes the target machine has unlimited
21198  number of registers, and designates them with the name iTemp.
21199  The compiler can be made to dump a human readable form of the code generated
21200  by using the -
21201 \begin_inset ERT
21202 status Collapsed
21203
21204 \layout Standard
21205
21206 \backslash
21207 /
21208 \end_inset
21209
21210 -dumpraw option.
21211 \layout Itemize
21212
21213 This phase does the bulk of the standard optimizations and is also MCU independe
21214 nt.
21215  This phase can be broken down into several sub-phases:
21216 \newline
21217
21218 \newline
21219 Break down intermediate code (iCode) into basic blocks.
21220 \newline
21221 Do control flow & data flow analysis on the basic blocks.
21222 \newline
21223 Do local common subexpression elimination, then global subexpression elimination
21224 \newline
21225 Dead code elimination
21226 \newline
21227 Loop optimizations
21228 \newline
21229 If loop optimizations caused any changes then do 'global subexpression eliminati
21230 on' and 'dead code elimination' again.
21231 \layout Itemize
21232
21233 This phase determines the live-ranges; by live range I mean those iTemp
21234  variables defined by the compiler that still survive after all the optimization
21235 s.
21236  Live range analysis
21237 \begin_inset LatexCommand \index{Live range analysis}
21238
21239 \end_inset
21240
21241  is essential for register allocation, since these computation determines
21242  which of these iTemps will be assigned to registers, and for how long.
21243 \layout Itemize
21244
21245 Phase five is register allocation.
21246  There are two parts to this process.
21247 \newline
21248
21249 \newline
21250 The first part I call 'register packing' (for lack of a better term).
21251  In this case several MCU specific expression folding is done to reduce
21252  register pressure.
21253 \newline
21254
21255 \newline
21256 The second part is more MCU independent and deals with allocating registers
21257  to the remaining live ranges.
21258  A lot of MCU specific code does creep into this phase because of the limited
21259  number of index registers available in the 8051.
21260 \layout Itemize
21261
21262 The Code generation phase is (unhappily), entirely MCU dependent and very
21263  little (if any at all) of this code can be reused for other MCU.
21264  However the scheme for allocating a homogenized assembler operand for each
21265  iCode operand may be reused.
21266 \layout Itemize
21267
21268 As mentioned in the optimization section the peep-hole optimizer is rule
21269  based system, which can reprogrammed for other MCUs.
21270 \layout Chapter
21271
21272 Compiler internals
21273 \begin_inset LatexCommand \index{Compiler internals}
21274
21275 \end_inset
21276
21277
21278 \layout Section
21279
21280 The anatomy of the compiler
21281 \begin_inset LatexCommand \label{sub:The-anatomy-of}
21282
21283 \end_inset
21284
21285
21286 \layout Standard
21287
21288
21289 \shape italic
21290 This is an excerpt from an article published in Circuit Cellar Magazine
21291  in august 2000.
21292  It's a little outdated (the compiler is much more efficient now and user/develo
21293 per friendly), but pretty well exposes the guts of it all.
21294 \shape default
21295
21296 \newline
21297
21298 \newline
21299 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
21300  It is fairly easy to retarget for other 8-bit MCU.
21301  Here we take a look at some of the internals of the compiler.
21302
21303 \layout Paragraph*
21304
21305 Parsing
21306 \begin_inset LatexCommand \index{Parsing}
21307
21308 \end_inset
21309
21310
21311 \layout Standard
21312
21313 Parsing the input source file and creating an AST (Annotated Syntax Tree
21314 \begin_inset LatexCommand \index{Annotated syntax tree}
21315
21316 \end_inset
21317
21318 ).
21319  This phase also involves propagating types (annotating each node of the
21320  parse tree with type information) and semantic analysis.
21321  There are some MCU specific parsing rules.
21322  For example the storage classes, the extended storage classes are MCU specific
21323  while there may be a xdata storage class for 8051 there is no such storage
21324  class for z80 or Atmel AVR.
21325  SDCC allows MCU specific storage class extensions, i.e.
21326  xdata will be treated as a storage class specifier when parsing 8051 C
21327  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
21328  C code.
21329 \layout Paragraph*
21330
21331 Generating iCode
21332 \begin_inset LatexCommand \index{iCode}
21333
21334 \end_inset
21335
21336
21337 \layout Standard
21338
21339 Intermediate code generation.
21340  In this phase the AST is broken down into three-operand form (iCode).
21341  These three operand forms are represented as doubly linked lists.
21342  ICode is the term given to the intermediate form generated by the compiler.
21343  ICode example section shows some examples of iCode generated for some simple
21344  C source functions.
21345 \layout Paragraph*
21346
21347 Optimizations
21348 \begin_inset LatexCommand \index{Optimizations}
21349
21350 \end_inset
21351
21352 .
21353 \layout Standard
21354
21355 Bulk of the target independent optimizations is performed in this phase.
21356  The optimizations include constant propagation, common sub-expression eliminati
21357 on, loop invariant code movement, strength reduction of loop induction variables
21358  and dead-code elimination.
21359 \layout Paragraph*
21360
21361 Live range analysis
21362 \begin_inset LatexCommand \index{Live range analysis}
21363
21364 \end_inset
21365
21366
21367 \layout Standard
21368
21369 During intermediate code generation phase, the compiler assumes the target
21370  machine has infinite number of registers and generates a lot of temporary
21371  variables.
21372  The live range computation determines the lifetime of each of these compiler-ge
21373 nerated temporaries.
21374  A picture speaks a thousand words.
21375  ICode example sections show the live range annotations for each of the
21376  operand.
21377  It is important to note here, each iCode is assigned a number in the order
21378  of its execution in the function.
21379  The live ranges are computed in terms of these numbers.
21380  The from number is the number of the iCode which first defines the operand
21381  and the to number signifies the iCode which uses this operand last.
21382 \layout Paragraph*
21383
21384 Register Allocation
21385 \begin_inset LatexCommand \index{Register allocation}
21386
21387 \end_inset
21388
21389
21390 \layout Standard
21391
21392 The register allocation determines the type and number of registers needed
21393  by each operand.
21394  In most MCUs only a few registers can be used for indirect addressing.
21395  In case of 8051 for example the registers R0 & R1 can be used to indirectly
21396  address the internal ram and DPTR to indirectly address the external ram.
21397  The compiler will try to allocate the appropriate register to pointer variables
21398  if it can.
21399  ICode example section shows the operands annotated with the registers assigned
21400  to them.
21401  The compiler will try to keep operands in registers as much as possible;
21402  there are several schemes the compiler uses to do achieve this.
21403  When the compiler runs out of registers the compiler will check to see
21404  if there are any live operands which is not used or defined in the current
21405  basic block being processed, if there are any found then it will push that
21406  operand and use the registers in this block, the operand will then be popped
21407  at the end of the basic block.
21408
21409 \layout Standard
21410
21411 There are other MCU specific considerations in this phase.
21412  Some MCUs have an accumulator; very short-lived operands could be assigned
21413  to the accumulator instead of a general-purpose register.
21414 \layout Paragraph*
21415
21416 Code generation
21417 \layout Standard
21418
21419 Figure II gives a table of iCode operations supported by the compiler.
21420  The code generation involves translating these operations into corresponding
21421  assembly code for the processor.
21422  This sounds overly simple but that is the essence of code generation.
21423  Some of the iCode operations are generated on a MCU specific manner for
21424  example, the z80 port does not use registers to pass parameters so the
21425  SEND and RECV iCode operations will not be generated, and it also does
21426  not support JUMPTABLES.
21427
21428 \newline
21429
21430 \series bold
21431 \shape italic
21432 \color red
21433 <Where is Figure II ?>
21434 \layout Paragraph*
21435
21436 ICode Example
21437 \begin_inset LatexCommand \index{iCode}
21438
21439 \end_inset
21440
21441
21442 \layout Standard
21443
21444 This section shows some details of iCode.
21445  The example C code does not do anything useful; it is used as an example
21446  to illustrate the intermediate code generated by the compiler.
21447 \layout Verse
21448
21449
21450 \family typewriter
21451 1.\SpecialChar ~
21452 xdata int * p;
21453 \newline
21454 2.\SpecialChar ~
21455 int gint;
21456 \newline
21457 3.\SpecialChar ~
21458 /* This function does nothing useful.
21459  It is used
21460 \newline
21461 4.\SpecialChar ~
21462 \SpecialChar ~
21463 \SpecialChar ~
21464 \SpecialChar ~
21465 for the purpose of explaining iCode */
21466 \newline
21467 5.\SpecialChar ~
21468 short function (data int *x)
21469 \newline
21470 6.\SpecialChar ~
21471 {
21472 \newline
21473 7.\SpecialChar ~
21474 \SpecialChar ~
21475 \SpecialChar ~
21476 short i=10; \SpecialChar ~
21477 \SpecialChar ~
21478 /* dead initialization eliminated */
21479 \newline
21480 8.\SpecialChar ~
21481 \SpecialChar ~
21482 \SpecialChar ~
21483 short sum=10; /* dead initialization eliminated */
21484 \newline
21485 9.\SpecialChar ~
21486 \SpecialChar ~
21487 \SpecialChar ~
21488 short mul;
21489 \newline
21490 10.\SpecialChar ~
21491 \SpecialChar ~
21492 int j ;
21493 \newline
21494 11.\SpecialChar ~
21495 \SpecialChar ~
21496 while (*x) *x++ = *p++;
21497 \newline
21498 12.\SpecialChar ~
21499 \SpecialChar ~
21500 \SpecialChar ~
21501 \SpecialChar ~
21502 sum = 0 ;
21503 \newline
21504 13.\SpecialChar ~
21505 \SpecialChar ~
21506 mul = 0;
21507 \newline
21508 14.\SpecialChar ~
21509 \SpecialChar ~
21510 /* compiler detects i,j to be induction variables */
21511 \newline
21512 15.\SpecialChar ~
21513 \SpecialChar ~
21514 for (i = 0, j = 10 ; i < 10 ; i++, j
21515 \family default
21516 -
21517 \begin_inset ERT
21518 status Collapsed
21519
21520 \layout Standard
21521
21522 \backslash
21523 /
21524 \end_inset
21525
21526 -
21527 \family typewriter
21528 ) {
21529 \newline
21530 16.\SpecialChar ~
21531 \SpecialChar ~
21532 \SpecialChar ~
21533 \SpecialChar ~
21534 sum += i;
21535 \newline
21536 17.\SpecialChar ~
21537 \SpecialChar ~
21538 \SpecialChar ~
21539 \SpecialChar ~
21540 mul += i * 3; \SpecialChar ~
21541 \SpecialChar ~
21542 /* this multiplication remains */
21543 \newline
21544 18.\SpecialChar ~
21545 \SpecialChar ~
21546 \SpecialChar ~
21547 \SpecialChar ~
21548 gint += j * 3;\SpecialChar ~
21549 \SpecialChar ~
21550 /* this multiplication changed to addition */
21551 \newline
21552 19.\SpecialChar ~
21553 \SpecialChar ~
21554 }
21555 \newline
21556 20.\SpecialChar ~
21557 \SpecialChar ~
21558 return sum+mul;
21559 \newline
21560 21.\SpecialChar ~
21561 }
21562 \layout Standard
21563
21564 In addition to the operands each iCode contains information about the filename
21565  and line it corresponds to in the source file.
21566  The first field in the listing should be interpreted as follows:
21567 \newline
21568
21569 \shape italic
21570 \size footnotesize
21571 Filename(linenumber: iCode Execution sequence number : ICode hash table
21572  key : loop depth of the iCode).
21573 \shape default
21574 \size default
21575
21576 \newline
21577 Then follows the human readable form of the ICode operation.
21578  Each operand of this triplet form can be of three basic types a) compiler
21579  generated temporary b) user defined variable c) a constant value.
21580  Note that local variables and parameters are replaced by compiler generated
21581  temporaries.
21582  Live ranges
21583 \begin_inset LatexCommand \index{Live range analysis}
21584
21585 \end_inset
21586
21587  are computed only for temporaries (i.e.
21588  live ranges are not computed for global variables).
21589  Registers
21590 \begin_inset LatexCommand \index{Register allocation}
21591
21592 \end_inset
21593
21594  are allocated for temporaries only.
21595  Operands are formatted in the following manner:
21596 \newline
21597
21598 \shape italic
21599 \size footnotesize
21600 Operand Name [lr live-from : live-to ] { type information } [ registers
21601  allocated ].
21602 \shape default
21603 \size default
21604
21605 \newline
21606 As mentioned earlier the live ranges are computed in terms of the execution
21607  sequence number of the iCodes, for example
21608 \newline
21609 the iTemp0 is live from (i.e.
21610  first defined in iCode with execution sequence number 3, and is last used
21611  in the iCode with sequence number 5).
21612  For induction variables such as iTemp21 the live range computation extends
21613  the lifetime from the start to the end of the loop.
21614 \newline
21615 The register allocator used the live range information to allocate registers,
21616  the same registers may be used for different temporaries if their live
21617  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
21618  iTemp17 since their live ranges do not overlap.
21619  In addition the allocator also takes into consideration the type and usage
21620  of a temporary, for example itemp6 is a pointer to near space and is used
21621  as to fetch data from (i.e.
21622  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
21623  Some short lived temporaries are allocated to special registers which have
21624  meaning to the code generator e.g.
21625  iTemp13 is allocated to a pseudo register CC which tells the back end that
21626  the temporary is used only for a conditional jump the code generation makes
21627  use of this information to optimize a compare and jump ICode.
21628 \newline
21629 There are several loop optimizations
21630 \begin_inset LatexCommand \index{Loop optimization}
21631
21632 \end_inset
21633
21634  performed by the compiler.
21635  It can detect induction variables iTemp21(i) and iTemp23(j).
21636  Also note the compiler does selective strength reduction
21637 \begin_inset LatexCommand \index{Strength reduction}
21638
21639 \end_inset
21640
21641 , i.e.
21642  the multiplication of an induction variable in line 18 (gint = j * 3) is
21643  changed to addition, a new temporary iTemp17 is allocated and assigned
21644  a initial value, a constant 3 is then added for each iteration of the loop.
21645  The compiler does not change the multiplication
21646 \begin_inset LatexCommand \index{Multiplication}
21647
21648 \end_inset
21649
21650  in line 17 however since the processor does support an 8 * 8 bit multiplication.
21651 \newline
21652 Note the dead code elimination
21653 \begin_inset LatexCommand \index{Dead-code elimination}
21654
21655 \end_inset
21656
21657  optimization eliminated the dead assignments in line 7 & 8 to I and sum
21658  respectively.
21659 \newline
21660
21661 \layout Standard
21662
21663
21664 \size footnotesize
21665 Sample.c (5:1:0:0) _entry($9) :
21666 \layout Standard
21667
21668
21669 \size footnotesize
21670 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
21671 \layout Standard
21672
21673
21674 \size footnotesize
21675 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
21676 \layout Standard
21677
21678
21679 \size footnotesize
21680 Sample.c(11:4:53:0) preHeaderLbl0($11) :
21681 \layout Standard
21682
21683
21684 \size footnotesize
21685 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
21686  * int}[r2]
21687 \layout Standard
21688
21689
21690 \size footnotesize
21691 Sample.c(11:6:5:1) _whilecontinue_0($1) :
21692 \layout Standard
21693
21694
21695 \size footnotesize
21696 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
21697  int}[r0]]
21698 \layout Standard
21699
21700
21701 \size footnotesize
21702 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
21703 \layout Standard
21704
21705
21706 \size footnotesize
21707 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
21708  * int}
21709 \layout Standard
21710
21711
21712 \size footnotesize
21713 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
21714  {short}
21715 \layout Standard
21716
21717
21718 \size footnotesize
21719 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
21720  * int}[DPTR]]
21721 \layout Standard
21722
21723
21724 \size footnotesize
21725 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
21726 }[r2 r3]
21727 \layout Standard
21728
21729
21730 \size footnotesize
21731 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
21732  * int}[r0] + 0x2 {short}
21733 \layout Standard
21734
21735
21736 \size footnotesize
21737 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
21738 \layout Standard
21739
21740
21741 \size footnotesize
21742 Sample.c(11:17:21:0)_whilebreak_0($3) :
21743 \layout Standard
21744
21745
21746 \size footnotesize
21747 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
21748 \layout Standard
21749
21750
21751 \size footnotesize
21752 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
21753 \layout Standard
21754
21755
21756 \size footnotesize
21757 Sample.c(15:20:54:0)preHeaderLbl1($13) :
21758 \layout Standard
21759
21760
21761 \size footnotesize
21762 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
21763 \layout Standard
21764
21765
21766 \size footnotesize
21767 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
21768 \layout Standard
21769
21770
21771 \size footnotesize
21772 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
21773 \layout Standard
21774
21775
21776 \size footnotesize
21777 Sample.c(15:24:26:1)_forcond_0($4) :
21778 \layout Standard
21779
21780
21781 \size footnotesize
21782 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
21783  < 0xa {short}
21784 \layout Standard
21785
21786
21787 \size footnotesize
21788 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
21789 \layout Standard
21790
21791
21792 \size footnotesize
21793 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
21794  + ITemp21 [lr21:38]{short}[r4]
21795 \layout Standard
21796
21797
21798 \size footnotesize
21799 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
21800  * 0x3 {short}
21801 \layout Standard
21802
21803
21804 \size footnotesize
21805 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
21806  + iTemp15 [lr29:30]{short}[r1]
21807 \layout Standard
21808
21809
21810 \size footnotesize
21811 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
21812  r0]- 0x3 {short}
21813 \layout Standard
21814
21815
21816 \size footnotesize
21817 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
21818 int}[r7 r0]
21819 \layout Standard
21820
21821
21822 \size footnotesize
21823 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
21824  + 0x1 {short}
21825 \layout Standard
21826
21827
21828 \size footnotesize
21829 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
21830  r6]- 0x1 {short}
21831 \layout Standard
21832
21833
21834 \size footnotesize
21835 Sample.c(19:38:47:1) goto _forcond_0($4)
21836 \layout Standard
21837
21838
21839 \size footnotesize
21840 Sample.c(19:39:48:0)_forbreak_0($7) :
21841 \layout Standard
21842
21843
21844 \size footnotesize
21845 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
21846  + ITemp11 [lr19:40]{short}[r3]
21847 \layout Standard
21848
21849
21850 \size footnotesize
21851 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
21852 \layout Standard
21853
21854
21855 \size footnotesize
21856 Sample.c(20:42:51:0)_return($8) :
21857 \layout Standard
21858
21859
21860 \size footnotesize
21861 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
21862 \size default
21863
21864 \newline
21865
21866 \newline
21867 Finally the code generated for this function:
21868 \newline
21869
21870 \layout Standard
21871
21872
21873 \size footnotesize
21874 .area DSEG (DATA)
21875 \layout Standard
21876
21877
21878 \size footnotesize
21879 _p::
21880 \layout Standard
21881
21882
21883 \size footnotesize
21884 \SpecialChar ~
21885 \SpecialChar ~
21886 .ds 2
21887 \layout Standard
21888
21889
21890 \size footnotesize
21891 _gint::
21892 \layout Standard
21893
21894
21895 \size footnotesize
21896 \SpecialChar ~
21897 \SpecialChar ~
21898 .ds 2
21899 \layout Standard
21900
21901
21902 \size footnotesize
21903 ; sample.c 5
21904 \layout Standard
21905
21906
21907 \size footnotesize
21908 ; ----------------------------------------------
21909 \layout Standard
21910
21911
21912 \size footnotesize
21913 ; function function
21914 \layout Standard
21915
21916
21917 \size footnotesize
21918 ; ----------------------------------------------
21919 \layout Standard
21920
21921
21922 \size footnotesize
21923 _function:
21924 \layout Standard
21925
21926
21927 \size footnotesize
21928 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
21929 \layout Standard
21930
21931
21932 \size footnotesize
21933 \SpecialChar ~
21934 \SpecialChar ~
21935 mov r2,dpl
21936 \layout Standard
21937
21938
21939 \size footnotesize
21940 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
21941 \layout Standard
21942
21943
21944 \size footnotesize
21945 \SpecialChar ~
21946 \SpecialChar ~
21947 mov ar0,r2
21948 \layout Standard
21949
21950
21951 \size footnotesize
21952 ;_whilecontinue_0($1) :
21953 \layout Standard
21954
21955
21956 \size footnotesize
21957 00101$:
21958 \layout Standard
21959
21960
21961 \size footnotesize
21962 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
21963 \layout Standard
21964
21965
21966 \size footnotesize
21967 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
21968 \layout Standard
21969
21970
21971 \size footnotesize
21972 \SpecialChar ~
21973 \SpecialChar ~
21974 mov ar2,@r0
21975 \layout Standard
21976
21977
21978 \size footnotesize
21979 \SpecialChar ~
21980 \SpecialChar ~
21981 inc r0
21982 \layout Standard
21983
21984
21985 \size footnotesize
21986 \SpecialChar ~
21987 \SpecialChar ~
21988 mov ar3,@r0
21989 \layout Standard
21990
21991
21992 \size footnotesize
21993 \SpecialChar ~
21994 \SpecialChar ~
21995 dec r0
21996 \layout Standard
21997
21998
21999 \size footnotesize
22000 \SpecialChar ~
22001 \SpecialChar ~
22002 mov a,r2
22003 \layout Standard
22004
22005
22006 \size footnotesize
22007 \SpecialChar ~
22008 \SpecialChar ~
22009 orl a,r3
22010 \layout Standard
22011
22012
22013 \size footnotesize
22014 \SpecialChar ~
22015 \SpecialChar ~
22016 jz 00103$
22017 \layout Standard
22018
22019
22020 \size footnotesize
22021 00114$:
22022 \layout Standard
22023
22024
22025 \size footnotesize
22026 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
22027 \layout Standard
22028
22029
22030 \size footnotesize
22031 \SpecialChar ~
22032 \SpecialChar ~
22033 mov dpl,_p
22034 \layout Standard
22035
22036
22037 \size footnotesize
22038 \SpecialChar ~
22039 \SpecialChar ~
22040 mov dph,(_p + 1)
22041 \layout Standard
22042
22043
22044 \size footnotesize
22045 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
22046 \layout Standard
22047
22048
22049 \size footnotesize
22050 \SpecialChar ~
22051 \SpecialChar ~
22052 mov a,#0x02
22053 \layout Standard
22054
22055
22056 \size footnotesize
22057 \SpecialChar ~
22058 \SpecialChar ~
22059 add a,_p
22060 \layout Standard
22061
22062
22063 \size footnotesize
22064 \SpecialChar ~
22065 \SpecialChar ~
22066 mov _p,a
22067 \layout Standard
22068
22069
22070 \size footnotesize
22071 \SpecialChar ~
22072 \SpecialChar ~
22073 clr a
22074 \layout Standard
22075
22076
22077 \size footnotesize
22078 \SpecialChar ~
22079 \SpecialChar ~
22080 addc a,(_p + 1)
22081 \layout Standard
22082
22083
22084 \size footnotesize
22085 \SpecialChar ~
22086 \SpecialChar ~
22087 mov (_p + 1),a
22088 \layout Standard
22089
22090
22091 \size footnotesize
22092 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
22093 \layout Standard
22094
22095
22096 \size footnotesize
22097 \SpecialChar ~
22098 \SpecialChar ~
22099 movx a,@dptr
22100 \layout Standard
22101
22102
22103 \size footnotesize
22104 \SpecialChar ~
22105 \SpecialChar ~
22106 mov r2,a
22107 \layout Standard
22108
22109
22110 \size footnotesize
22111 \SpecialChar ~
22112 \SpecialChar ~
22113 inc dptr
22114 \layout Standard
22115
22116
22117 \size footnotesize
22118 \SpecialChar ~
22119 \SpecialChar ~
22120 movx a,@dptr
22121 \layout Standard
22122
22123
22124 \size footnotesize
22125 \SpecialChar ~
22126 \SpecialChar ~
22127 mov r3,a
22128 \layout Standard
22129
22130
22131 \size footnotesize
22132 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
22133 \layout Standard
22134
22135
22136 \size footnotesize
22137 \SpecialChar ~
22138 \SpecialChar ~
22139 mov @r0,ar2
22140 \layout Standard
22141
22142
22143 \size footnotesize
22144 \SpecialChar ~
22145 \SpecialChar ~
22146 inc r0
22147 \layout Standard
22148
22149
22150 \size footnotesize
22151 \SpecialChar ~
22152 \SpecialChar ~
22153 mov @r0,ar3
22154 \layout Standard
22155
22156
22157 \size footnotesize
22158 ; iTemp6 [lr5:16]{_near * int}[r0] =
22159 \layout Standard
22160
22161
22162 \size footnotesize
22163 ; iTemp6 [lr5:16]{_near * int}[r0] +
22164 \layout Standard
22165
22166
22167 \size footnotesize
22168 ; 0x2 {short}
22169 \layout Standard
22170
22171
22172 \size footnotesize
22173 \SpecialChar ~
22174 \SpecialChar ~
22175 inc r0
22176 \layout Standard
22177
22178
22179 \size footnotesize
22180 ; goto _whilecontinue_0($1)
22181 \layout Standard
22182
22183
22184 \size footnotesize
22185 \SpecialChar ~
22186 \SpecialChar ~
22187 sjmp 00101$
22188 \layout Standard
22189
22190
22191 \size footnotesize
22192 ; _whilebreak_0($3) :
22193 \layout Standard
22194
22195
22196 \size footnotesize
22197 00103$:
22198 \layout Standard
22199
22200
22201 \size footnotesize
22202 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
22203 \layout Standard
22204
22205
22206 \size footnotesize
22207 \SpecialChar ~
22208 \SpecialChar ~
22209 mov r2,#0x00
22210 \layout Standard
22211
22212
22213 \size footnotesize
22214 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
22215 \layout Standard
22216
22217
22218 \size footnotesize
22219 \SpecialChar ~
22220 \SpecialChar ~
22221 mov r3,#0x00
22222 \layout Standard
22223
22224
22225 \size footnotesize
22226 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
22227 \layout Standard
22228
22229
22230 \size footnotesize
22231 \SpecialChar ~
22232 \SpecialChar ~
22233 mov r4,#0x00
22234 \layout Standard
22235
22236
22237 \size footnotesize
22238 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
22239 \layout Standard
22240
22241
22242 \size footnotesize
22243 \SpecialChar ~
22244 \SpecialChar ~
22245 mov r5,#0x0A
22246 \layout Standard
22247
22248
22249 \size footnotesize
22250 \SpecialChar ~
22251 \SpecialChar ~
22252 mov r6,#0x00
22253 \layout Standard
22254
22255
22256 \size footnotesize
22257 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
22258 \layout Standard
22259
22260
22261 \size footnotesize
22262 \SpecialChar ~
22263 \SpecialChar ~
22264 mov r7,#0x1E
22265 \layout Standard
22266
22267
22268 \size footnotesize
22269 \SpecialChar ~
22270 \SpecialChar ~
22271 mov r0,#0x00
22272 \layout Standard
22273
22274
22275 \size footnotesize
22276 ; _forcond_0($4) :
22277 \layout Standard
22278
22279
22280 \size footnotesize
22281 00104$:
22282 \layout Standard
22283
22284
22285 \size footnotesize
22286 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
22287 \layout Standard
22288
22289
22290 \size footnotesize
22291 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
22292 \layout Standard
22293
22294
22295 \size footnotesize
22296 \SpecialChar ~
22297 \SpecialChar ~
22298 clr c
22299 \layout Standard
22300
22301
22302 \size footnotesize
22303 \SpecialChar ~
22304 \SpecialChar ~
22305 mov a,r4
22306 \layout Standard
22307
22308
22309 \size footnotesize
22310 \SpecialChar ~
22311 \SpecialChar ~
22312 xrl a,#0x80
22313 \layout Standard
22314
22315
22316 \size footnotesize
22317 \SpecialChar ~
22318 \SpecialChar ~
22319 subb a,#0x8a
22320 \layout Standard
22321
22322
22323 \size footnotesize
22324 \SpecialChar ~
22325 \SpecialChar ~
22326 jnc 00107$
22327 \layout Standard
22328
22329
22330 \size footnotesize
22331 00115$:
22332 \layout Standard
22333
22334
22335 \size footnotesize
22336 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
22337 \layout Standard
22338
22339
22340 \size footnotesize
22341 ; iTemp21 [lr21:38]{short}[r4]
22342 \layout Standard
22343
22344
22345 \size footnotesize
22346 \SpecialChar ~
22347 \SpecialChar ~
22348 mov a,r4
22349 \layout Standard
22350
22351
22352 \size footnotesize
22353 \SpecialChar ~
22354 \SpecialChar ~
22355 add a,r2
22356 \layout Standard
22357
22358
22359 \size footnotesize
22360 \SpecialChar ~
22361 \SpecialChar ~
22362 mov r2,a
22363 \layout Standard
22364
22365
22366 \size footnotesize
22367 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
22368 \layout Standard
22369
22370
22371 \size footnotesize
22372 \SpecialChar ~
22373 \SpecialChar ~
22374 mov b,#0x03
22375 \layout Standard
22376
22377
22378 \size footnotesize
22379 \SpecialChar ~
22380 \SpecialChar ~
22381 mov a,r4
22382 \layout Standard
22383
22384
22385 \size footnotesize
22386 \SpecialChar ~
22387 \SpecialChar ~
22388 mul ab
22389 \layout Standard
22390
22391
22392 \size footnotesize
22393 \SpecialChar ~
22394 \SpecialChar ~
22395 mov r1,a
22396 \layout Standard
22397
22398
22399 \size footnotesize
22400 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
22401 \layout Standard
22402
22403
22404 \size footnotesize
22405 ; iTemp15 [lr29:30]{short}[r1]
22406 \layout Standard
22407
22408
22409 \size footnotesize
22410 \SpecialChar ~
22411 \SpecialChar ~
22412 add a,r3
22413 \layout Standard
22414
22415
22416 \size footnotesize
22417 \SpecialChar ~
22418 \SpecialChar ~
22419 mov r3,a
22420 \layout Standard
22421
22422
22423 \size footnotesize
22424 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
22425 \layout Standard
22426
22427
22428 \size footnotesize
22429 \SpecialChar ~
22430 \SpecialChar ~
22431 mov a,r7
22432 \layout Standard
22433
22434
22435 \size footnotesize
22436 \SpecialChar ~
22437 \SpecialChar ~
22438 add a,#0xfd
22439 \layout Standard
22440
22441
22442 \size footnotesize
22443 \SpecialChar ~
22444 \SpecialChar ~
22445 mov r7,a
22446 \layout Standard
22447
22448
22449 \size footnotesize
22450 \SpecialChar ~
22451 \SpecialChar ~
22452 mov a,r0
22453 \layout Standard
22454
22455
22456 \size footnotesize
22457 \SpecialChar ~
22458 \SpecialChar ~
22459 addc a,#0xff
22460 \layout Standard
22461
22462
22463 \size footnotesize
22464 \SpecialChar ~
22465 \SpecialChar ~
22466 mov r0,a
22467 \layout Standard
22468
22469
22470 \size footnotesize
22471 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
22472 \layout Standard
22473
22474
22475 \size footnotesize
22476 \SpecialChar ~
22477 \SpecialChar ~
22478 mov a,r7
22479 \layout Standard
22480
22481
22482 \size footnotesize
22483 \SpecialChar ~
22484 \SpecialChar ~
22485 add a,_gint
22486 \layout Standard
22487
22488
22489 \size footnotesize
22490 \SpecialChar ~
22491 \SpecialChar ~
22492 mov _gint,a
22493 \layout Standard
22494
22495
22496 \size footnotesize
22497 \SpecialChar ~
22498 \SpecialChar ~
22499 mov a,r0
22500 \layout Standard
22501
22502
22503 \size footnotesize
22504 \SpecialChar ~
22505 \SpecialChar ~
22506 addc a,(_gint + 1)
22507 \layout Standard
22508
22509
22510 \size footnotesize
22511 \SpecialChar ~
22512 \SpecialChar ~
22513 mov (_gint + 1),a
22514 \layout Standard
22515
22516
22517 \size footnotesize
22518 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
22519 \layout Standard
22520
22521
22522 \size footnotesize
22523 \SpecialChar ~
22524 \SpecialChar ~
22525 inc r4
22526 \layout Standard
22527
22528
22529 \size footnotesize
22530 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
22531 \layout Standard
22532
22533
22534 \size footnotesize
22535 \SpecialChar ~
22536 \SpecialChar ~
22537 dec r5
22538 \layout Standard
22539
22540
22541 \size footnotesize
22542 \SpecialChar ~
22543 \SpecialChar ~
22544 cjne r5,#0xff,00104$
22545 \layout Standard
22546
22547
22548 \size footnotesize
22549 \SpecialChar ~
22550 \SpecialChar ~
22551 dec r6
22552 \layout Standard
22553
22554
22555 \size footnotesize
22556 ; goto _forcond_0($4)
22557 \layout Standard
22558
22559
22560 \size footnotesize
22561 \SpecialChar ~
22562 \SpecialChar ~
22563 sjmp 00104$
22564 \layout Standard
22565
22566
22567 \size footnotesize
22568 ; _forbreak_0($7) :
22569 \layout Standard
22570
22571
22572 \size footnotesize
22573 00107$:
22574 \layout Standard
22575
22576
22577 \size footnotesize
22578 ; ret iTemp24 [lr40:41]{short}
22579 \layout Standard
22580
22581
22582 \size footnotesize
22583 \SpecialChar ~
22584 \SpecialChar ~
22585 mov a,r3
22586 \layout Standard
22587
22588
22589 \size footnotesize
22590 \SpecialChar ~
22591 \SpecialChar ~
22592 add a,r2
22593 \layout Standard
22594
22595
22596 \size footnotesize
22597 \SpecialChar ~
22598 \SpecialChar ~
22599 mov dpl,a
22600 \layout Standard
22601
22602
22603 \size footnotesize
22604 ; _return($8) :
22605 \layout Standard
22606
22607
22608 \size footnotesize
22609 00108$:
22610 \layout Standard
22611
22612
22613 \size footnotesize
22614 \SpecialChar ~
22615 \SpecialChar ~
22616 ret
22617 \newline
22618
22619 \layout Section
22620
22621 A few words about basic block successors, predecessors and dominators
22622 \layout Standard
22623
22624 Successors are basic blocks
22625 \begin_inset LatexCommand \index{Basic blocks}
22626
22627 \end_inset
22628
22629  that might execute after this basic block.
22630 \newline
22631 Predecessors are basic blocks that might execute before reaching this basic
22632  block.
22633 \newline
22634 Dominators are basic blocks that WILL execute before reaching this basic
22635  block.
22636 \newline
22637
22638 \layout Standard
22639
22640 [basic block 1]
22641 \layout Standard
22642
22643 if (something)
22644 \layout Standard
22645
22646 \SpecialChar ~
22647 \SpecialChar ~
22648 \SpecialChar ~
22649 \SpecialChar ~
22650 [basic block 2]
22651 \layout Standard
22652
22653 else
22654 \layout Standard
22655
22656 \SpecialChar ~
22657 \SpecialChar ~
22658 \SpecialChar ~
22659 \SpecialChar ~
22660 [basic block 3]
22661 \layout Standard
22662
22663 [basic block 4]
22664 \newline
22665
22666 \layout Standard
22667
22668 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
22669 \layout Standard
22670
22671 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
22672 \layout Standard
22673
22674 c) domVect of [BB4] = BB1 ...
22675  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
22676  was executed.
22677 \layout Chapter
22678
22679 Acknowledgments
22680 \layout Standard
22681
22682
22683 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
22684
22685 \end_inset
22686
22687
22688 \newline
22689
22690 \newline
22691
22692 \emph on
22693 Thanks to all the other volunteer developers who have helped with coding,
22694  testing, web-page creation, distribution sets, etc.
22695  You know who you are :-)
22696 \emph default
22697
22698 \newline
22699
22700 \layout Standard
22701
22702 This document was initially written by Sandeep Dutta
22703 \layout Standard
22704
22705 All product names mentioned herein may be trademarks
22706 \begin_inset LatexCommand \index{Trademarks}
22707
22708 \end_inset
22709
22710  of their respective companies.
22711
22712 \layout Section*
22713
22714 Alphabetical index
22715 \layout Standard
22716
22717 To avoid confusion, the installation and building options for SDCC itself
22718  (chapter 2) are not part of the index.
22719 \layout Standard
22720
22721
22722 \begin_inset LatexCommand \printindex{}
22723
22724 \end_inset
22725
22726
22727 \the_end