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.1
  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 Subsubsection
15108
15109 Debugging Options
15110 \layout Standard
15111
15112 Debugging options enable extra debugging information in the output files.
15113 \layout List
15114 \labelwidthstring 00.00.0000
15115
15116 -
15117 \begin_inset ERT
15118 status Collapsed
15119
15120 \layout Standard
15121
15122 \backslash
15123 /
15124 \end_inset
15125
15126 -debug-xtra Similar to -
15127 \begin_inset ERT
15128 status Collapsed
15129
15130 \layout Standard
15131
15132 \backslash
15133 /
15134 \end_inset
15135
15136 -debug
15137 \begin_inset LatexCommand \index{-\/-debug}
15138
15139 \end_inset
15140
15141 , but dumps more information.
15142 \layout List
15143 \labelwidthstring 00.00.0000
15144
15145 -
15146 \begin_inset ERT
15147 status Collapsed
15148
15149 \layout Standard
15150
15151 \backslash
15152 /
15153 \end_inset
15154
15155 -debug-ralloc Force register allocator to dump <source>.d file with debugging
15156  information.
15157  <source> is the name of the file compiled.
15158 \layout List
15159 \labelwidthstring 00.00.0000
15160
15161 -
15162 \begin_inset ERT
15163 status Collapsed
15164
15165 \layout Standard
15166
15167 \backslash
15168 /
15169 \end_inset
15170
15171 -pcode-verbose Enable pcode debugging information in translation.
15172 \layout Subsection
15173
15174 Preprocessor Macros
15175 \layout Standard
15176
15177 PIC16 port defines the following preprocessor macros while translating a
15178  source.
15179 \layout Standard
15180 \align center
15181
15182 \begin_inset  Tabular
15183 <lyxtabular version="3" rows="2" columns="2">
15184 <features>
15185 <column alignment="center" valignment="top" leftline="true" width="0">
15186 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15187 <row topline="true" bottomline="true">
15188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15189 \begin_inset Text
15190
15191 \layout Standard
15192
15193 Macro
15194 \end_inset
15195 </cell>
15196 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15197 \begin_inset Text
15198
15199 \layout Standard
15200
15201 Description
15202 \end_inset
15203 </cell>
15204 </row>
15205 <row topline="true" bottomline="true">
15206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15207 \begin_inset Text
15208
15209 \layout Standard
15210
15211 pic18fxxxx
15212 \end_inset
15213 </cell>
15214 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15215 \begin_inset Text
15216
15217 \layout Standard
15218
15219 MCU Identification.
15220
15221 \emph on
15222 xxxx
15223 \emph default
15224  is the microcontrol identification number, i.e.
15225  452, 6620, etc
15226 \end_inset
15227 </cell>
15228 </row>
15229 </lyxtabular>
15230
15231 \end_inset
15232
15233
15234 \layout Subsection
15235
15236 Directories
15237 \layout Standard
15238
15239 PIC16
15240 \begin_inset LatexCommand \index{PIC16}
15241
15242 \end_inset
15243
15244  port uses the following directories for searching header files and libraries.
15245 \layout Standard
15246 \align center
15247
15248 \begin_inset  Tabular
15249 <lyxtabular version="3" rows="3" columns="4">
15250 <features>
15251 <column alignment="center" valignment="top" leftline="true" width="0">
15252 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15253 <column alignment="center" valignment="top" width="0">
15254 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15255 <row topline="true" bottomline="true">
15256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15257 \begin_inset Text
15258
15259 \layout Standard
15260
15261 Directory
15262 \end_inset
15263 </cell>
15264 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15265 \begin_inset Text
15266
15267 \layout Standard
15268
15269 Description
15270 \end_inset
15271 </cell>
15272 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15273 \begin_inset Text
15274
15275 \layout Standard
15276
15277 Target
15278 \end_inset
15279 </cell>
15280 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15281 \begin_inset Text
15282
15283 \layout Standard
15284
15285 Command prefix
15286 \end_inset
15287 </cell>
15288 </row>
15289 <row topline="true">
15290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15291 \begin_inset Text
15292
15293 \layout Standard
15294
15295 PREFIX/sdcc/include/pic16
15296 \end_inset
15297 </cell>
15298 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15299 \begin_inset Text
15300
15301 \layout Standard
15302
15303 PIC16 specific headers
15304 \end_inset
15305 </cell>
15306 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15307 \begin_inset Text
15308
15309 \layout Standard
15310
15311 Compiler
15312 \end_inset
15313 </cell>
15314 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15315 \begin_inset Text
15316
15317 \layout Standard
15318
15319 -I
15320 \end_inset
15321 </cell>
15322 </row>
15323 <row topline="true" bottomline="true">
15324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15325 \begin_inset Text
15326
15327 \layout Standard
15328
15329 PREFIX/sdcc/lib/pic16
15330 \end_inset
15331 </cell>
15332 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15333 \begin_inset Text
15334
15335 \layout Standard
15336
15337 PIC16 specific libraries
15338 \end_inset
15339 </cell>
15340 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15341 \begin_inset Text
15342
15343 \layout Standard
15344
15345 Linker
15346 \end_inset
15347 </cell>
15348 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15349 \begin_inset Text
15350
15351 \layout Standard
15352
15353 -L
15354 \end_inset
15355 </cell>
15356 </row>
15357 </lyxtabular>
15358
15359 \end_inset
15360
15361
15362 \layout Subsection
15363
15364 Pragmas
15365 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
15366
15367 \end_inset
15368
15369
15370 \layout Standard
15371
15372 PIC16 port currently supports the following pragmas:
15373 \layout List
15374 \labelwidthstring 00.00.0000
15375
15376 stack pragma stack forces the code generator to initialize the stack & frame
15377  pointers at a specific address.
15378  This is an adhoc solution since gplink does not support yet stack.
15379  When the gplink issue is resolved the pragma will be deprecated
15380 \begin_inset Foot
15381 collapsed true
15382
15383 \layout Standard
15384
15385
15386 \emph on
15387 It is important to initialize the stack, otherwise strange things can happen.
15388  Stack is not initialized by default because there are some sources that
15389  do not require it.
15390  (like library sources)
15391 \end_inset
15392
15393 .
15394 \newline
15395 The stack pragma should be used only once in a project.
15396  Multiple pragmas may result in indeterminate behaviour of the program.
15397 \newline
15398 If you omit setting the pragma the port emits a warning message before linking.
15399  If not initializing the stack is desired ignore the message.
15400 \layout LyX-Code
15401
15402 Example:
15403 \layout LyX-Code
15404
15405 \layout LyX-Code
15406
15407 /* initializes stack at RAM address 0x5ff */
15408 \layout LyX-Code
15409
15410 #pragma stack 0x5ff
15411 \layout LyX-Code
15412
15413 \layout Subsection
15414
15415 Header Files
15416 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
15417
15418 \end_inset
15419
15420
15421 \layout Standard
15422
15423 There is one main header file that can be included to the source files using
15424  the pic16 port.
15425  That file is the
15426 \series bold
15427 pic18fregs.h
15428 \series default
15429 .
15430  This header file contains the definitions for the processor special registers,
15431  so it is necessary if the source accesses them.
15432  It can be included by adding the following line in the beginning of the
15433  file:
15434 \layout LyX-Code
15435
15436 #include <pic18fregs.h>
15437 \layout Standard
15438
15439 The specific microcontroller is selected within the pic18fregs.h automatically,
15440  so the same source can be used with a variety of devices.
15441 \layout Subsection
15442
15443 Libraries
15444 \layout Standard
15445
15446 The libraries that PIC16
15447 \begin_inset LatexCommand \index{PIC16}
15448
15449 \end_inset
15450
15451  port depends on are the microcontroller device libraries which contain
15452  the symbol definitions for the microcontroller special function registers.
15453  These libraries have the format pic18fxxxx.lib, where
15454 \emph on
15455 xxxx
15456 \emph default
15457  is the microcontroller identification number.
15458  The specific library is selected automatically by the compiler at link
15459  stage according to the selected device.
15460 \layout Standard
15461
15462 Libraries are created with gplib which is part of the gputils package
15463 \begin_inset LatexCommand \url{http://gputils.sourceforge.net}
15464
15465 \end_inset
15466
15467 .
15468 \layout Subsection
15469
15470 Memory Models
15471 \layout Standard
15472
15473 The following memory models are supported by the PIC16 port:
15474 \layout Itemize
15475
15476 small model
15477 \layout Itemize
15478
15479 large model
15480 \layout Standard
15481
15482 Memory model affects the default size of pointers within the source.
15483  The sizes are shown in the next table:
15484 \layout Standard
15485 \align center
15486
15487 \begin_inset  Tabular
15488 <lyxtabular version="3" rows="3" columns="3">
15489 <features>
15490 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15491 <column alignment="center" valignment="top" leftline="true" width="0">
15492 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15493 <row topline="true" bottomline="true">
15494 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15495 \begin_inset Text
15496
15497 \layout Standard
15498
15499 Pointer sizes according to memory model
15500 \end_inset
15501 </cell>
15502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15503 \begin_inset Text
15504
15505 \layout Standard
15506
15507 small model
15508 \end_inset
15509 </cell>
15510 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15511 \begin_inset Text
15512
15513 \layout Standard
15514
15515 large model
15516 \end_inset
15517 </cell>
15518 </row>
15519 <row topline="true" bottomline="true">
15520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15521 \begin_inset Text
15522
15523 \layout Standard
15524
15525 code pointers
15526 \end_inset
15527 </cell>
15528 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15529 \begin_inset Text
15530
15531 \layout Standard
15532
15533 16-bits
15534 \end_inset
15535 </cell>
15536 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15537 \begin_inset Text
15538
15539 \layout Standard
15540
15541 24-bits
15542 \end_inset
15543 </cell>
15544 </row>
15545 <row topline="true" bottomline="true">
15546 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15547 \begin_inset Text
15548
15549 \layout Standard
15550
15551 data pointers
15552 \end_inset
15553 </cell>
15554 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
15555 \begin_inset Text
15556
15557 \layout Standard
15558
15559 16-bits
15560 \end_inset
15561 </cell>
15562 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15563 \begin_inset Text
15564
15565 \layout Standard
15566
15567 16-bits
15568 \end_inset
15569 </cell>
15570 </row>
15571 </lyxtabular>
15572
15573 \end_inset
15574
15575
15576 \layout Standard
15577
15578 It is advisable that all sources within a project are compiled with the
15579  same memory model.
15580  If one wants to override the default memory model, this can be done by
15581  declaring a pointer as
15582 \series bold
15583 far
15584 \series default
15585  or
15586 \series bold
15587 near
15588 \series default
15589 .
15590  Far selects large memory model's pointers, while near selects small memory
15591  model's pointers.
15592 \layout Standard
15593
15594 The standard device libraries (see
15595 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
15596
15597 \end_inset
15598
15599 ) contain no reference to pointers, so they can be used with both memory
15600  models.
15601 \layout Subsection
15602
15603 Stack
15604 \layout Standard
15605
15606 The stack implementation for the PIC16 port uses two indirect registers,
15607  FSR1 and FSR2.
15608 \layout List
15609 \labelwidthstring 00.00.0000
15610
15611 FSR1 is assigned as stack pointer
15612 \layout List
15613 \labelwidthstring 00.00.0000
15614
15615 FSR2 is assigned as frame pointer
15616 \layout Standard
15617
15618 The following stack models are supported by the PIC16 port
15619 \layout Itemize
15620
15621 small model
15622 \layout Itemize
15623
15624 large model
15625 \layout Standard
15626
15627
15628 \noun on
15629 Small
15630 \noun default
15631  model means that only the FSRxL byte is used to access stack and frame,
15632  while
15633 \emph on
15634 \noun on
15635 large
15636 \emph default
15637 \noun default
15638  uses both FSRxL and FSRxH registers.
15639  The following table shows the stack/frame pointers sizes according to stack
15640  model and the maximum space they can address:
15641 \layout Standard
15642 \align center
15643
15644 \begin_inset  Tabular
15645 <lyxtabular version="3" rows="3" columns="3">
15646 <features>
15647 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15648 <column alignment="center" valignment="top" leftline="true" width="0">
15649 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15650 <row topline="true" bottomline="true">
15651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15652 \begin_inset Text
15653
15654 \layout Standard
15655
15656 Stack & Frame pointer sizes according to stack model
15657 \end_inset
15658 </cell>
15659 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15660 \begin_inset Text
15661
15662 \layout Standard
15663
15664 small
15665 \end_inset
15666 </cell>
15667 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15668 \begin_inset Text
15669
15670 \layout Standard
15671
15672 large
15673 \end_inset
15674 </cell>
15675 </row>
15676 <row topline="true">
15677 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15678 \begin_inset Text
15679
15680 \layout Standard
15681
15682 Stack pointer FSR1
15683 \end_inset
15684 </cell>
15685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15686 \begin_inset Text
15687
15688 \layout Standard
15689
15690 8-bits
15691 \end_inset
15692 </cell>
15693 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15694 \begin_inset Text
15695
15696 \layout Standard
15697
15698 16-bits
15699 \end_inset
15700 </cell>
15701 </row>
15702 <row topline="true" bottomline="true">
15703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15704 \begin_inset Text
15705
15706 \layout Standard
15707
15708 Frame pointer FSR2
15709 \end_inset
15710 </cell>
15711 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15712 \begin_inset Text
15713
15714 \layout Standard
15715
15716 8-bits
15717 \end_inset
15718 </cell>
15719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15720 \begin_inset Text
15721
15722 \layout Standard
15723
15724 16-bits
15725 \end_inset
15726 </cell>
15727 </row>
15728 </lyxtabular>
15729
15730 \end_inset
15731
15732
15733 \layout Standard
15734
15735
15736 \series bold
15737 Currently stack and frame pointers should be initialized explicit by the
15738  user at the desired Data RAM position (see
15739 \begin_inset LatexCommand \ref{sub:PIC16_Pragmas}
15740
15741 \end_inset
15742
15743  Pragma stack).
15744  Uninitialized stack and frame pointers can result in unexpected behavior
15745  of the resulting binary.
15746 \layout Subsection
15747
15748 Function return values
15749 \layout Standard
15750
15751 Return values from functions are placed to the appropriate registers following
15752  a modified Microchip policy optimized for SDCC.
15753  The following table shows these registers:
15754 \layout Standard
15755 \align center
15756
15757 \begin_inset  Tabular
15758 <lyxtabular version="3" rows="6" columns="2">
15759 <features>
15760 <column alignment="center" valignment="top" leftline="true" width="0">
15761 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15762 <row topline="true" bottomline="true">
15763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15764 \begin_inset Text
15765
15766 \layout Standard
15767
15768 size
15769 \end_inset
15770 </cell>
15771 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15772 \begin_inset Text
15773
15774 \layout Standard
15775
15776 destination register
15777 \end_inset
15778 </cell>
15779 </row>
15780 <row topline="true">
15781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15782 \begin_inset Text
15783
15784 \layout Standard
15785
15786 8 bits
15787 \end_inset
15788 </cell>
15789 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15790 \begin_inset Text
15791
15792 \layout Standard
15793
15794 WREG
15795 \end_inset
15796 </cell>
15797 </row>
15798 <row topline="true">
15799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15800 \begin_inset Text
15801
15802 \layout Standard
15803
15804 16 bits
15805 \end_inset
15806 </cell>
15807 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15808 \begin_inset Text
15809
15810 \layout Standard
15811
15812 PRODL:WREG
15813 \end_inset
15814 </cell>
15815 </row>
15816 <row topline="true">
15817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15818 \begin_inset Text
15819
15820 \layout Standard
15821
15822 24 bits
15823 \end_inset
15824 </cell>
15825 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15826 \begin_inset Text
15827
15828 \layout Standard
15829
15830 PRODH:PRODL:WREG
15831 \end_inset
15832 </cell>
15833 </row>
15834 <row topline="true">
15835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15836 \begin_inset Text
15837
15838 \layout Standard
15839
15840 32 bits
15841 \end_inset
15842 </cell>
15843 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15844 \begin_inset Text
15845
15846 \layout Standard
15847
15848 FSR0L:PRODH:PRODL:WREG
15849 \end_inset
15850 </cell>
15851 </row>
15852 <row topline="true" bottomline="true">
15853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15854 \begin_inset Text
15855
15856 \layout Standard
15857
15858 >32 bits
15859 \end_inset
15860 </cell>
15861 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15862 \begin_inset Text
15863
15864 \layout Standard
15865
15866 on stack, FSR0 points to the beginning
15867 \end_inset
15868 </cell>
15869 </row>
15870 </lyxtabular>
15871
15872 \end_inset
15873
15874
15875 \layout Subsection
15876
15877 Interrupts
15878 \layout Standard
15879
15880 When entering an interrupt, currently the PIC16
15881 \begin_inset LatexCommand \index{PIC16}
15882
15883 \end_inset
15884
15885  port automatically saves the following registers:
15886 \layout Itemize
15887
15888 WREG
15889 \layout Itemize
15890
15891 STATUS
15892 \layout Itemize
15893
15894 BSR
15895 \layout Itemize
15896
15897 PROD (PRODL and PRODH)
15898 \layout Itemize
15899
15900 FSR0 (FSR0L and FSR0H)
15901 \layout Standard
15902
15903 These registers are restored upon return from the interrupt routine
15904 \begin_inset Foot
15905 collapsed false
15906
15907 \layout Standard
15908
15909 NOTE that when the _naked attribute is specified for an interrupt routine,
15910  then NO registers are stored or restored.
15911 \end_inset
15912
15913 .
15914 \layout Chapter
15915
15916 Debugging with SDCDB
15917 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
15918
15919 \end_inset
15920
15921
15922 \begin_inset LatexCommand \index{sdcdb (debugger)}
15923
15924 \end_inset
15925
15926
15927 \layout Standard
15928
15929 SDCC is distributed with a source level debugger
15930 \begin_inset LatexCommand \index{Debugger}
15931
15932 \end_inset
15933
15934 .
15935  The debugger uses a command line interface, the command repertoire of the
15936  debugger has been kept as close to gdb
15937 \begin_inset LatexCommand \index{gdb}
15938
15939 \end_inset
15940
15941  (the GNU debugger) as possible.
15942  The configuration and build process is part of the standard compiler installati
15943 on, which also builds and installs the debugger in the target directory
15944  specified during configuration.
15945  The debugger allows you debug BOTH at the C source and at the ASM source
15946  level.
15947  Sdcdb is available on Unix platforms only.
15948 \layout Section
15949
15950 Compiling for Debugging
15951 \layout Standard
15952
15953 The -
15954 \begin_inset ERT
15955 status Collapsed
15956
15957 \layout Standard
15958
15959 \backslash
15960 /
15961 \end_inset
15962
15963 -debug
15964 \begin_inset LatexCommand \index{-\/-debug}
15965
15966 \end_inset
15967
15968  option must be specified for all files for which debug information is to
15969  be generated.
15970  The complier generates a .adb file for each of these files.
15971  The linker creates the .cdb
15972 \begin_inset LatexCommand \index{<file>.cdb}
15973
15974 \end_inset
15975
15976  file from the .adb
15977 \begin_inset LatexCommand \index{<file>.adb}
15978
15979 \end_inset
15980
15981  files and the address information.
15982  This .cdb is used by the debugger.
15983 \layout Section
15984
15985 How the Debugger Works
15986 \layout Standard
15987
15988 When the -
15989 \begin_inset ERT
15990 status Collapsed
15991
15992 \layout Standard
15993
15994 \backslash
15995 /
15996 \end_inset
15997
15998 -debug option is specified the compiler generates extra symbol information
15999  some of which are put into the assembler source and some are put into the
16000  .adb file.
16001   Then the linker creates the .cdb file from the individual .adb files with
16002  the address information for the symbols.
16003  The debugger reads the symbolic information generated by the compiler &
16004  the address information generated by the linker.
16005  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
16006  execution is controlled by the debugger.
16007  When a command is issued for the debugger, it translates it into appropriate
16008  commands for the simulator.
16009 \layout Section
16010
16011 Starting the Debugger
16012 \layout Standard
16013
16014 The debugger can be started using the following command line.
16015  (Assume the file you are debugging has the file name foo).
16016 \newline
16017
16018 \newline
16019
16020 \family sans
16021 \series bold
16022 sdcdb foo
16023 \newline
16024
16025 \family default
16026 \series default
16027
16028 \newline
16029 The debugger will look for the following files.
16030 \layout Itemize
16031
16032 foo.c - the source file.
16033 \layout Itemize
16034
16035 foo.cdb - the debugger symbol information file.
16036 \layout Itemize
16037
16038 foo.ihx - the Intel hex format
16039 \begin_inset LatexCommand \index{Intel hex format}
16040
16041 \end_inset
16042
16043  object file.
16044 \layout Section
16045
16046 Command Line Options.
16047 \layout Itemize
16048
16049 -
16050 \begin_inset ERT
16051 status Collapsed
16052
16053 \layout Standard
16054
16055 \backslash
16056 /
16057 \end_inset
16058
16059 -directory=<source file directory> this option can used to specify the directory
16060  search list.
16061  The debugger will look into the directory list specified for source, cdb
16062  & ihx files.
16063  The items in the directory list must be separated by ':', e.g.
16064  if the source files can be in the directories /home/src1 and /home/src2,
16065  the -
16066 \begin_inset ERT
16067 status Collapsed
16068
16069 \layout Standard
16070
16071 \backslash
16072 /
16073 \end_inset
16074
16075 -directory option should be -
16076 \begin_inset ERT
16077 status Collapsed
16078
16079 \layout Standard
16080
16081 \backslash
16082 /
16083 \end_inset
16084
16085 -directory=/home/src1:/home/src2.
16086  Note there can be no spaces in the option.
16087
16088 \layout Itemize
16089
16090 -cd <directory> - change to the <directory>.
16091 \layout Itemize
16092
16093 -fullname - used by GUI front ends.
16094 \layout Itemize
16095
16096 -cpu <cpu-type> - this argument is passed to the simulator please see the
16097  simulator docs for details.
16098 \layout Itemize
16099
16100 -X <Clock frequency > this options is passed to the simulator please see
16101  the simulator docs for details.
16102 \layout Itemize
16103
16104 -s <serial port file> passed to simulator see the simulator docs for details.
16105 \layout Itemize
16106
16107 -S <serial in,out> passed to simulator see the simulator docs for details.
16108 \layout Itemize
16109
16110 -k <port number> passed to simulator see the simulator docs for details.
16111 \layout Section
16112
16113 Debugger Commands.
16114 \layout Standard
16115
16116 As mentioned earlier the command interface for the debugger has been deliberatel
16117 y kept as close the GNU debugger gdb, as possible.
16118  This will help the integration with existing graphical user interfaces
16119  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
16120  If you use a graphical user interface for the debugger you can skip the
16121  next sections.
16122 \layout Subsubsection*
16123
16124 break [line | file:line | function | file:function]
16125 \layout Standard
16126
16127 Set breakpoint at specified line or function:
16128 \newline
16129
16130 \newline
16131
16132 \family sans
16133 \series bold
16134 sdcdb>break 100
16135 \newline
16136 sdcdb>break foo.c:100
16137 \newline
16138 sdcdb>break funcfoo
16139 \newline
16140 sdcdb>break foo.c:funcfoo
16141 \layout Subsubsection*
16142
16143 clear [line | file:line | function | file:function ]
16144 \layout Standard
16145
16146 Clear breakpoint at specified line or function:
16147 \newline
16148
16149 \newline
16150
16151 \family sans
16152 \series bold
16153 sdcdb>clear 100
16154 \newline
16155 sdcdb>clear foo.c:100
16156 \newline
16157 sdcdb>clear funcfoo
16158 \newline
16159 sdcdb>clear foo.c:funcfoo
16160 \layout Subsubsection*
16161
16162 continue
16163 \layout Standard
16164
16165 Continue program being debugged, after breakpoint.
16166 \layout Subsubsection*
16167
16168 finish
16169 \layout Standard
16170
16171 Execute till the end of the current function.
16172 \layout Subsubsection*
16173
16174 delete [n]
16175 \layout Standard
16176
16177 Delete breakpoint number 'n'.
16178  If used without any option clear ALL user defined break points.
16179 \layout Subsubsection*
16180
16181 info [break | stack | frame | registers ]
16182 \layout Itemize
16183
16184 info break - list all breakpoints
16185 \layout Itemize
16186
16187 info stack - show the function call stack.
16188 \layout Itemize
16189
16190 info frame - show information about the current execution frame.
16191 \layout Itemize
16192
16193 info registers - show content of all registers.
16194 \layout Subsubsection*
16195
16196 step
16197 \layout Standard
16198
16199 Step program until it reaches a different source line.
16200  Note: pressing <return> repeats the last command.
16201 \layout Subsubsection*
16202
16203 next
16204 \layout Standard
16205
16206 Step program, proceeding through subroutine calls.
16207 \layout Subsubsection*
16208
16209 run
16210 \layout Standard
16211
16212 Start debugged program.
16213 \layout Subsubsection*
16214
16215 ptype variable
16216 \layout Standard
16217
16218 Print type information of the variable.
16219 \layout Subsubsection*
16220
16221 print variable
16222 \layout Standard
16223
16224 print value of variable.
16225 \layout Subsubsection*
16226
16227 file filename
16228 \layout Standard
16229
16230 load the given file name.
16231  Note this is an alternate method of loading file for debugging.
16232 \layout Subsubsection*
16233
16234 frame
16235 \layout Standard
16236
16237 print information about current frame.
16238 \layout Subsubsection*
16239
16240 set srcmode
16241 \layout Standard
16242
16243 Toggle between C source & assembly source.
16244 \layout Subsubsection*
16245
16246 ! simulator command
16247 \layout Standard
16248
16249 Send the string following '!' to the simulator, the simulator response is
16250  displayed.
16251  Note the debugger does not interpret the command being sent to the simulator,
16252  so if a command like 'go' is sent the debugger can loose its execution
16253  context and may display incorrect values.
16254 \layout Subsubsection*
16255
16256 quit
16257 \layout Standard
16258
16259 "Watch me now.
16260  Iam going Down.
16261  My name is Bobby Brown"
16262 \layout Section
16263
16264 Interfacing with XEmacs
16265 \begin_inset LatexCommand \index{XEmacs}
16266
16267 \end_inset
16268
16269
16270 \begin_inset LatexCommand \index{Emacs}
16271
16272 \end_inset
16273
16274 .
16275 \layout Standard
16276
16277 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
16278  sdcdb.el and sdcdbsrc.el.
16279  These two files can be found in the $(prefix)/bin directory after the installat
16280 ion is complete.
16281  These files need to be loaded into XEmacs for the interface to work.
16282  This can be done at XEmacs startup time by inserting the following into
16283  your '.xemacs' file (which can be found in your HOME directory):
16284 \newline
16285
16286 \newline
16287
16288 \family typewriter
16289 (load-file sdcdbsrc.el)
16290 \family default
16291
16292 \newline
16293
16294 \newline
16295 .xemacs is a lisp file so the () around the command is REQUIRED.
16296  The files can also be loaded dynamically while XEmacs is running, set the
16297  environment variable 'EMACSLOADPATH' to the installation bin directory
16298  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
16299  To start the interface enter the following command:
16300 \newline
16301
16302 \newline
16303
16304 \family sans
16305 \series bold
16306 ESC-x sdcdbsrc
16307 \family default
16308 \series default
16309
16310 \newline
16311
16312 \newline
16313 You will prompted to enter the file name to be debugged.
16314
16315 \newline
16316
16317 \newline
16318 The command line options that are passed to the simulator directly are bound
16319  to default values in the file sdcdbsrc.el.
16320  The variables are listed below, these values maybe changed as required.
16321 \layout Itemize
16322
16323 sdcdbsrc-cpu-type '51
16324 \layout Itemize
16325
16326 sdcdbsrc-frequency '11059200
16327 \layout Itemize
16328
16329 sdcdbsrc-serial nil
16330 \layout Standard
16331
16332 The following is a list of key mapping for the debugger interface.
16333 \layout Standard
16334
16335 \SpecialChar ~
16336
16337 \family typewriter
16338
16339 \newline
16340 ;;\SpecialChar ~
16341 Current Listing ::
16342 \newline
16343 ;;key\SpecialChar ~
16344 \SpecialChar ~
16345 \SpecialChar ~
16346 \SpecialChar ~
16347 \SpecialChar ~
16348 \SpecialChar ~
16349 \SpecialChar ~
16350 \SpecialChar ~
16351 \SpecialChar ~
16352 \SpecialChar ~
16353 \SpecialChar ~
16354 \SpecialChar ~
16355 \SpecialChar ~
16356 \SpecialChar ~
16357 binding\SpecialChar ~
16358 \SpecialChar ~
16359 \SpecialChar ~
16360 \SpecialChar ~
16361 \SpecialChar ~
16362 \SpecialChar ~
16363 \SpecialChar ~
16364 \SpecialChar ~
16365 \SpecialChar ~
16366 \SpecialChar ~
16367 \SpecialChar ~
16368 \SpecialChar ~
16369 \SpecialChar ~
16370 \SpecialChar ~
16371 \SpecialChar ~
16372 \SpecialChar ~
16373 \SpecialChar ~
16374 \SpecialChar ~
16375 \SpecialChar ~
16376 \SpecialChar ~
16377 \SpecialChar ~
16378 \SpecialChar ~
16379 Comment
16380 \newline
16381 ;;---\SpecialChar ~
16382 \SpecialChar ~
16383 \SpecialChar ~
16384 \SpecialChar ~
16385 \SpecialChar ~
16386 \SpecialChar ~
16387 \SpecialChar ~
16388 \SpecialChar ~
16389 \SpecialChar ~
16390 \SpecialChar ~
16391 \SpecialChar ~
16392 \SpecialChar ~
16393 \SpecialChar ~
16394 \SpecialChar ~
16395 -------\SpecialChar ~
16396 \SpecialChar ~
16397 \SpecialChar ~
16398 \SpecialChar ~
16399 \SpecialChar ~
16400 \SpecialChar ~
16401 \SpecialChar ~
16402 \SpecialChar ~
16403 \SpecialChar ~
16404 \SpecialChar ~
16405 \SpecialChar ~
16406 \SpecialChar ~
16407 \SpecialChar ~
16408 \SpecialChar ~
16409 \SpecialChar ~
16410 \SpecialChar ~
16411 \SpecialChar ~
16412 \SpecialChar ~
16413 \SpecialChar ~
16414 \SpecialChar ~
16415 \SpecialChar ~
16416 \SpecialChar ~
16417 -------
16418 \newline
16419 ;;
16420 \newline
16421 ;;\SpecialChar ~
16422 n\SpecialChar ~
16423 \SpecialChar ~
16424 \SpecialChar ~
16425 \SpecialChar ~
16426 \SpecialChar ~
16427 \SpecialChar ~
16428 \SpecialChar ~
16429 \SpecialChar ~
16430 \SpecialChar ~
16431 \SpecialChar ~
16432 \SpecialChar ~
16433 \SpecialChar ~
16434 \SpecialChar ~
16435 \SpecialChar ~
16436 \SpecialChar ~
16437 sdcdb-next-from-src\SpecialChar ~
16438 \SpecialChar ~
16439 \SpecialChar ~
16440 \SpecialChar ~
16441 \SpecialChar ~
16442 \SpecialChar ~
16443 \SpecialChar ~
16444 \SpecialChar ~
16445 \SpecialChar ~
16446 \SpecialChar ~
16447 SDCDB next command
16448 \newline
16449 ;;\SpecialChar ~
16450 b\SpecialChar ~
16451 \SpecialChar ~
16452 \SpecialChar ~
16453 \SpecialChar ~
16454 \SpecialChar ~
16455 \SpecialChar ~
16456 \SpecialChar ~
16457 \SpecialChar ~
16458 \SpecialChar ~
16459 \SpecialChar ~
16460 \SpecialChar ~
16461 \SpecialChar ~
16462 \SpecialChar ~
16463 \SpecialChar ~
16464 \SpecialChar ~
16465 sdcdb-back-from-src\SpecialChar ~
16466 \SpecialChar ~
16467 \SpecialChar ~
16468 \SpecialChar ~
16469 \SpecialChar ~
16470 \SpecialChar ~
16471 \SpecialChar ~
16472 \SpecialChar ~
16473 \SpecialChar ~
16474 \SpecialChar ~
16475 SDCDB back command
16476 \newline
16477 ;;\SpecialChar ~
16478 c\SpecialChar ~
16479 \SpecialChar ~
16480 \SpecialChar ~
16481 \SpecialChar ~
16482 \SpecialChar ~
16483 \SpecialChar ~
16484 \SpecialChar ~
16485 \SpecialChar ~
16486 \SpecialChar ~
16487 \SpecialChar ~
16488 \SpecialChar ~
16489 \SpecialChar ~
16490 \SpecialChar ~
16491 \SpecialChar ~
16492 \SpecialChar ~
16493 sdcdb-cont-from-src\SpecialChar ~
16494 \SpecialChar ~
16495 \SpecialChar ~
16496 \SpecialChar ~
16497 \SpecialChar ~
16498 \SpecialChar ~
16499 \SpecialChar ~
16500 \SpecialChar ~
16501 \SpecialChar ~
16502 \SpecialChar ~
16503 SDCDB continue command
16504 \newline
16505 ;;\SpecialChar ~
16506 s\SpecialChar ~
16507 \SpecialChar ~
16508 \SpecialChar ~
16509 \SpecialChar ~
16510 \SpecialChar ~
16511 \SpecialChar ~
16512 \SpecialChar ~
16513 \SpecialChar ~
16514 \SpecialChar ~
16515 \SpecialChar ~
16516 \SpecialChar ~
16517 \SpecialChar ~
16518 \SpecialChar ~
16519 \SpecialChar ~
16520 \SpecialChar ~
16521 sdcdb-step-from-src\SpecialChar ~
16522 \SpecialChar ~
16523 \SpecialChar ~
16524 \SpecialChar ~
16525 \SpecialChar ~
16526 \SpecialChar ~
16527 \SpecialChar ~
16528 \SpecialChar ~
16529 \SpecialChar ~
16530 \SpecialChar ~
16531 SDCDB step command
16532 \newline
16533 ;;\SpecialChar ~
16534 ?\SpecialChar ~
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 sdcdb-whatis-c-sexp\SpecialChar ~
16550 \SpecialChar ~
16551 \SpecialChar ~
16552 \SpecialChar ~
16553 \SpecialChar ~
16554 \SpecialChar ~
16555 \SpecialChar ~
16556 \SpecialChar ~
16557 \SpecialChar ~
16558 \SpecialChar ~
16559 SDCDB ptypecommand for data at
16560 \newline
16561 ;;\SpecialChar ~
16562 \SpecialChar ~
16563 \SpecialChar ~
16564 \SpecialChar ~
16565 \SpecialChar ~
16566 \SpecialChar ~
16567 \SpecialChar ~
16568 \SpecialChar ~
16569 \SpecialChar ~
16570 \SpecialChar ~
16571 \SpecialChar ~
16572 \SpecialChar ~
16573 \SpecialChar ~
16574 \SpecialChar ~
16575 \SpecialChar ~
16576 \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 \SpecialChar ~
16592 \SpecialChar ~
16593 \SpecialChar ~
16594 \SpecialChar ~
16595 \SpecialChar ~
16596 \SpecialChar ~
16597 \SpecialChar ~
16598 \SpecialChar ~
16599 \SpecialChar ~
16600 \SpecialChar ~
16601 \SpecialChar ~
16602 \SpecialChar ~
16603 \SpecialChar ~
16604 \SpecialChar ~
16605 \SpecialChar ~
16606 \SpecialChar ~
16607 \SpecialChar ~
16608 buffer point
16609 \newline
16610 ;;\SpecialChar ~
16611 x\SpecialChar ~
16612 \SpecialChar ~
16613 \SpecialChar ~
16614 \SpecialChar ~
16615 \SpecialChar ~
16616 \SpecialChar ~
16617 \SpecialChar ~
16618 \SpecialChar ~
16619 \SpecialChar ~
16620 \SpecialChar ~
16621 \SpecialChar ~
16622 \SpecialChar ~
16623 \SpecialChar ~
16624 \SpecialChar ~
16625 \SpecialChar ~
16626 sdcdbsrc-delete\SpecialChar ~
16627 \SpecialChar ~
16628 \SpecialChar ~
16629 \SpecialChar ~
16630 \SpecialChar ~
16631 \SpecialChar ~
16632 \SpecialChar ~
16633 \SpecialChar ~
16634 \SpecialChar ~
16635 \SpecialChar ~
16636 \SpecialChar ~
16637 \SpecialChar ~
16638 \SpecialChar ~
16639 \SpecialChar ~
16640 SDCDB Delete all breakpoints if no arg
16641 \newline
16642 ;;\SpecialChar ~
16643 \SpecialChar ~
16644 \SpecialChar ~
16645 \SpecialChar ~
16646 \SpecialChar ~
16647 \SpecialChar ~
16648 \SpecialChar ~
16649 \SpecialChar ~
16650 \SpecialChar ~
16651 \SpecialChar ~
16652 \SpecialChar ~
16653 \SpecialChar ~
16654 \SpecialChar ~
16655 \SpecialChar ~
16656 \SpecialChar ~
16657 \SpecialChar ~
16658 \SpecialChar ~
16659 \SpecialChar ~
16660 \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 \SpecialChar ~
16676 \SpecialChar ~
16677 \SpecialChar ~
16678 \SpecialChar ~
16679 \SpecialChar ~
16680 \SpecialChar ~
16681 \SpecialChar ~
16682 \SpecialChar ~
16683 \SpecialChar ~
16684 \SpecialChar ~
16685 \SpecialChar ~
16686 \SpecialChar ~
16687 \SpecialChar ~
16688 \SpecialChar ~
16689 given or delete arg (C-u arg x)
16690 \newline
16691 ;;\SpecialChar ~
16692 m\SpecialChar ~
16693 \SpecialChar ~
16694 \SpecialChar ~
16695 \SpecialChar ~
16696 \SpecialChar ~
16697 \SpecialChar ~
16698 \SpecialChar ~
16699 \SpecialChar ~
16700 \SpecialChar ~
16701 \SpecialChar ~
16702 \SpecialChar ~
16703 \SpecialChar ~
16704 \SpecialChar ~
16705 \SpecialChar ~
16706 \SpecialChar ~
16707 sdcdbsrc-frame\SpecialChar ~
16708 \SpecialChar ~
16709 \SpecialChar ~
16710 \SpecialChar ~
16711 \SpecialChar ~
16712 \SpecialChar ~
16713 \SpecialChar ~
16714 \SpecialChar ~
16715 \SpecialChar ~
16716 \SpecialChar ~
16717 \SpecialChar ~
16718 \SpecialChar ~
16719 \SpecialChar ~
16720 \SpecialChar ~
16721 \SpecialChar ~
16722 SDCDB Display current frame if no arg,
16723 \newline
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 \SpecialChar ~
16763 \SpecialChar ~
16764 \SpecialChar ~
16765 \SpecialChar ~
16766 \SpecialChar ~
16767 \SpecialChar ~
16768 \SpecialChar ~
16769 \SpecialChar ~
16770 \SpecialChar ~
16771 given or display frame arg
16772 \newline
16773 ;;\SpecialChar ~
16774 \SpecialChar ~
16775 \SpecialChar ~
16776 \SpecialChar ~
16777 \SpecialChar ~
16778 \SpecialChar ~
16779 \SpecialChar ~
16780 \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 \SpecialChar ~
16795 \SpecialChar ~
16796 \SpecialChar ~
16797 \SpecialChar ~
16798 \SpecialChar ~
16799 \SpecialChar ~
16800 \SpecialChar ~
16801 \SpecialChar ~
16802 \SpecialChar ~
16803 \SpecialChar ~
16804 \SpecialChar ~
16805 \SpecialChar ~
16806 \SpecialChar ~
16807 \SpecialChar ~
16808 \SpecialChar ~
16809 \SpecialChar ~
16810 \SpecialChar ~
16811 \SpecialChar ~
16812 \SpecialChar ~
16813 \SpecialChar ~
16814 \SpecialChar ~
16815 \SpecialChar ~
16816 \SpecialChar ~
16817 \SpecialChar ~
16818 \SpecialChar ~
16819 \SpecialChar ~
16820 buffer point
16821 \newline
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 sdcdbsrc-goto-sdcdb\SpecialChar ~
16839 \SpecialChar ~
16840 \SpecialChar ~
16841 \SpecialChar ~
16842 \SpecialChar ~
16843 \SpecialChar ~
16844 \SpecialChar ~
16845 \SpecialChar ~
16846 \SpecialChar ~
16847 \SpecialChar ~
16848 Goto the SDCDB output buffer
16849 \newline
16850 ;;\SpecialChar ~
16851 p\SpecialChar ~
16852 \SpecialChar ~
16853 \SpecialChar ~
16854 \SpecialChar ~
16855 \SpecialChar ~
16856 \SpecialChar ~
16857 \SpecialChar ~
16858 \SpecialChar ~
16859 \SpecialChar ~
16860 \SpecialChar ~
16861 \SpecialChar ~
16862 \SpecialChar ~
16863 \SpecialChar ~
16864 \SpecialChar ~
16865 \SpecialChar ~
16866 sdcdb-print-c-sexp\SpecialChar ~
16867 \SpecialChar ~
16868 \SpecialChar ~
16869 \SpecialChar ~
16870 \SpecialChar ~
16871 \SpecialChar ~
16872 \SpecialChar ~
16873 \SpecialChar ~
16874 \SpecialChar ~
16875 \SpecialChar ~
16876 \SpecialChar ~
16877 SDCDB print command for data at
16878 \newline
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 \SpecialChar ~
16926 buffer point
16927 \newline
16928 ;;\SpecialChar ~
16929 g\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 sdcdbsrc-goto-sdcdb\SpecialChar ~
16945 \SpecialChar ~
16946 \SpecialChar ~
16947 \SpecialChar ~
16948 \SpecialChar ~
16949 \SpecialChar ~
16950 \SpecialChar ~
16951 \SpecialChar ~
16952 \SpecialChar ~
16953 \SpecialChar ~
16954 Goto the SDCDB output buffer
16955 \newline
16956 ;;\SpecialChar ~
16957 t\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 sdcdbsrc-mode\SpecialChar ~
16973 \SpecialChar ~
16974 \SpecialChar ~
16975 \SpecialChar ~
16976 \SpecialChar ~
16977 \SpecialChar ~
16978 \SpecialChar ~
16979 \SpecialChar ~
16980 \SpecialChar ~
16981 \SpecialChar ~
16982 \SpecialChar ~
16983 \SpecialChar ~
16984 \SpecialChar ~
16985 \SpecialChar ~
16986 \SpecialChar ~
16987 \SpecialChar ~
16988 Toggles Sdcdbsrc mode (turns it off)
16989 \newline
16990 ;;
16991 \newline
16992 ;;\SpecialChar ~
16993 C-c\SpecialChar ~
16994 C-f\SpecialChar ~
16995 \SpecialChar ~
16996 \SpecialChar ~
16997 \SpecialChar ~
16998 \SpecialChar ~
16999 \SpecialChar ~
17000 \SpecialChar ~
17001 \SpecialChar ~
17002 \SpecialChar ~
17003 sdcdb-finish-from-src\SpecialChar ~
17004 \SpecialChar ~
17005 \SpecialChar ~
17006 \SpecialChar ~
17007 \SpecialChar ~
17008 \SpecialChar ~
17009 \SpecialChar ~
17010 \SpecialChar ~
17011 SDCDB finish command
17012 \newline
17013 ;;
17014 \newline
17015 ;;\SpecialChar ~
17016 C-x\SpecialChar ~
17017 SPC\SpecialChar ~
17018 \SpecialChar ~
17019 \SpecialChar ~
17020 \SpecialChar ~
17021 \SpecialChar ~
17022 \SpecialChar ~
17023 \SpecialChar ~
17024 \SpecialChar ~
17025 \SpecialChar ~
17026 sdcdb-break\SpecialChar ~
17027 \SpecialChar ~
17028 \SpecialChar ~
17029 \SpecialChar ~
17030 \SpecialChar ~
17031 \SpecialChar ~
17032 \SpecialChar ~
17033 \SpecialChar ~
17034 \SpecialChar ~
17035 \SpecialChar ~
17036 \SpecialChar ~
17037 \SpecialChar ~
17038 \SpecialChar ~
17039 \SpecialChar ~
17040 \SpecialChar ~
17041 \SpecialChar ~
17042 \SpecialChar ~
17043 \SpecialChar ~
17044 Set break for line with point
17045 \newline
17046 ;;\SpecialChar ~
17047 ESC\SpecialChar ~
17048 t\SpecialChar ~
17049 \SpecialChar ~
17050 \SpecialChar ~
17051 \SpecialChar ~
17052 \SpecialChar ~
17053 \SpecialChar ~
17054 \SpecialChar ~
17055 \SpecialChar ~
17056 \SpecialChar ~
17057 \SpecialChar ~
17058 \SpecialChar ~
17059 sdcdbsrc-mode\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 Toggle Sdcdbsrc mode
17076 \newline
17077 ;;\SpecialChar ~
17078 ESC\SpecialChar ~
17079 m\SpecialChar ~
17080 \SpecialChar ~
17081 \SpecialChar ~
17082 \SpecialChar ~
17083 \SpecialChar ~
17084 \SpecialChar ~
17085 \SpecialChar ~
17086 \SpecialChar ~
17087 \SpecialChar ~
17088 \SpecialChar ~
17089 \SpecialChar ~
17090 sdcdbsrc-srcmode\SpecialChar ~
17091 \SpecialChar ~
17092 \SpecialChar ~
17093 \SpecialChar ~
17094 \SpecialChar ~
17095 \SpecialChar ~
17096 \SpecialChar ~
17097 \SpecialChar ~
17098 \SpecialChar ~
17099 \SpecialChar ~
17100 \SpecialChar ~
17101 \SpecialChar ~
17102 \SpecialChar ~
17103 Toggle list mode
17104 \newline
17105 ;;
17106 \newline
17107
17108 \layout Chapter
17109 \pagebreak_top
17110 TIPS
17111 \layout Standard
17112
17113 Here are a few guidelines that will help the compiler generate more efficient
17114  code, some of the tips are specific to this compiler others are generally
17115  good programming practice.
17116 \layout Itemize
17117
17118 Use the smallest data type to represent your data-value.
17119  If it is known in advance that the value is going to be less than 256 then
17120  use an 'unsigned char' instead of a 'short' or 'int'.
17121  Please note, that ANSI C requires both signed and unsigned chars to be
17122  promoted to 'signed int' before doing any operation.
17123  This promotion can be omitted, if the result is the same.
17124  The effect of the promotion rules together with the sign-extension is often
17125  surprising:
17126 \begin_deeper
17127 \layout Verse
17128
17129
17130 \family typewriter
17131 unsigned char uc = 0xfe;
17132 \newline
17133 if (uc * uc < 0) /* this is true! */
17134 \newline
17135 {
17136 \newline
17137 \SpecialChar ~
17138 \SpecialChar ~
17139 \SpecialChar ~
17140 \SpecialChar ~
17141 ....
17142 \newline
17143 }
17144 \layout Standard
17145
17146
17147 \family typewriter
17148 uc * uc
17149 \family default
17150  is evaluated as
17151 \family typewriter
17152 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
17153 \family default
17154 .
17155
17156 \newline
17157 Another one:
17158 \layout Verse
17159
17160
17161 \family typewriter
17162 (unsigned char) -12 / (signed char) -3 = ...
17163 \layout Standard
17164
17165 No, the result is not 4:
17166 \layout Verse
17167
17168
17169 \family typewriter
17170 (int) (unsigned char) -12 / (int) (signed char) -3 =
17171 \newline
17172 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
17173 \newline
17174 (int) 0x00f4 / (int) 0xfffd =
17175 \newline
17176 (int) 0x00f4 / (int) 0xfffd =
17177 \newline
17178 (int) 244 / (int) -3 =
17179 \newline
17180 (int) -81 = (int) 0xffaf;
17181 \layout Standard
17182
17183 Don't complain, that gcc gives you a different result.
17184  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
17185  Therefore the results are different.
17186 \newline
17187 From
17188 \begin_inset Quotes sld
17189 \end_inset
17190
17191 comp.lang.c FAQ
17192 \begin_inset Quotes srd
17193 \end_inset
17194
17195 :
17196 \layout Quote
17197
17198 If well-defined overflow characteristics are important and negative values
17199  are not, or if you want to steer clear of sign-extension problems when
17200  manipulating bits or bytes, use one of the corresponding unsigned types.
17201  (Beware when mixing signed and unsigned values in expressions, though.)
17202 \newline
17203 Although character types (especially unsigned char) can be used as "tiny"
17204  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
17205 ble sign extension and increased code size.
17206 \end_deeper
17207 \layout Itemize
17208
17209 Use unsigned when it is known in advance that the value is not going to
17210  be negative.
17211  This helps especially if you are doing division or multiplication, bit-shifting
17212  or are using an array index.
17213 \layout Itemize
17214
17215 NEVER jump into a LOOP.
17216 \layout Itemize
17217
17218 Declare the variables to be local
17219 \begin_inset LatexCommand \index{local variables}
17220
17221 \end_inset
17222
17223  whenever possible, especially loop control variables (induction).
17224 \layout Itemize
17225
17226 Since the compiler does not always do implicit integral promotion, the programme
17227 r should do an explicit cast when integral promotion is required.
17228 \layout Itemize
17229
17230 Reducing the size of division, multiplication & modulus operations can reduce
17231  code size substantially.
17232  Take the following code for example.
17233 \begin_deeper
17234 \layout Verse
17235
17236
17237 \family typewriter
17238 foobar(unsigned int p1, unsigned char ch)
17239 \newline
17240 {
17241 \newline
17242 \SpecialChar ~
17243 \SpecialChar ~
17244 \SpecialChar ~
17245 \SpecialChar ~
17246 unsigned char ch1 = p1 % ch ;
17247 \newline
17248 \SpecialChar ~
17249 \SpecialChar ~
17250 \SpecialChar ~
17251 \SpecialChar ~
17252 ....
17253 \newline
17254 }
17255 \layout Standard
17256
17257 For the modulus operation the variable ch will be promoted to unsigned int
17258  first then the modulus operation will be performed (this will lead to a
17259  call to support routine _moduint()), and the result will be casted to a
17260  char.
17261  If the code is changed to
17262 \layout Verse
17263
17264
17265 \family typewriter
17266 foobar(unsigned int p1, unsigned char ch)
17267 \newline
17268 {
17269 \newline
17270 \SpecialChar ~
17271 \SpecialChar ~
17272 \SpecialChar ~
17273 \SpecialChar ~
17274 unsigned char ch1 = (unsigned char)p1 % ch ;
17275 \newline
17276 \SpecialChar ~
17277 \SpecialChar ~
17278 \SpecialChar ~
17279 \SpecialChar ~
17280 ....
17281 \newline
17282 }
17283 \layout Standard
17284
17285 It would substantially reduce the code generated (future versions of the
17286  compiler will be smart enough to detect such optimization opportunities).
17287 \end_deeper
17288 \layout Itemize
17289
17290 Have a look at the assembly listing to get a
17291 \begin_inset Quotes sld
17292 \end_inset
17293
17294 feeling
17295 \begin_inset Quotes srd
17296 \end_inset
17297
17298  for the code generation.
17299 \layout Section
17300
17301 Tools
17302 \begin_inset LatexCommand \index{Tools}
17303
17304 \end_inset
17305
17306  included in the distribution
17307 \layout Standard
17308 \align center
17309
17310 \begin_inset  Tabular
17311 <lyxtabular version="3" rows="12" columns="3">
17312 <features>
17313 <column alignment="center" valignment="top" leftline="true" width="0pt">
17314 <column alignment="center" valignment="top" leftline="true" width="0pt">
17315 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
17316 <row topline="true" bottomline="true">
17317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17318 \begin_inset Text
17319
17320 \layout Standard
17321
17322 Name
17323 \end_inset
17324 </cell>
17325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17326 \begin_inset Text
17327
17328 \layout Standard
17329
17330 Purpose
17331 \end_inset
17332 </cell>
17333 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17334 \begin_inset Text
17335
17336 \layout Standard
17337
17338 Directory
17339 \end_inset
17340 </cell>
17341 </row>
17342 <row topline="true">
17343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17344 \begin_inset Text
17345
17346 \layout Standard
17347
17348 uCsim
17349 \end_inset
17350 </cell>
17351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17352 \begin_inset Text
17353
17354 \layout Standard
17355
17356 Simulator for various architectures
17357 \end_inset
17358 </cell>
17359 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17360 \begin_inset Text
17361
17362 \layout Standard
17363
17364 sdcc/sim/ucsim
17365 \end_inset
17366 </cell>
17367 </row>
17368 <row topline="true">
17369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17370 \begin_inset Text
17371
17372 \layout Standard
17373
17374 keil2sdcc.pl
17375 \end_inset
17376 </cell>
17377 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17378 \begin_inset Text
17379
17380 \layout Standard
17381
17382 header file conversion
17383 \end_inset
17384 </cell>
17385 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17386 \begin_inset Text
17387
17388 \layout Standard
17389
17390 sdcc/support/scripts
17391 \end_inset
17392 </cell>
17393 </row>
17394 <row topline="true">
17395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17396 \begin_inset Text
17397
17398 \layout Standard
17399
17400 mh2h.c
17401 \end_inset
17402 </cell>
17403 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17404 \begin_inset Text
17405
17406 \layout Standard
17407
17408 header file conversion
17409 \end_inset
17410 </cell>
17411 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17412 \begin_inset Text
17413
17414 \layout Standard
17415
17416 sdcc/support/scripts
17417 \end_inset
17418 </cell>
17419 </row>
17420 <row topline="true">
17421 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17422 \begin_inset Text
17423
17424 \layout Standard
17425
17426 as-gbz80
17427 \end_inset
17428 </cell>
17429 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17430 \begin_inset Text
17431
17432 \layout Standard
17433
17434 Assembler
17435 \end_inset
17436 </cell>
17437 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17438 \begin_inset Text
17439
17440 \layout Standard
17441
17442
17443 \family roman
17444 \series medium
17445 \shape up
17446 \size normal
17447 \emph off
17448 \bar no
17449 \noun off
17450 \color none
17451 sdcc/bin
17452 \end_inset
17453 </cell>
17454 </row>
17455 <row topline="true">
17456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17457 \begin_inset Text
17458
17459 \layout Standard
17460
17461 as-z80
17462 \end_inset
17463 </cell>
17464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17465 \begin_inset Text
17466
17467 \layout Standard
17468
17469 Assembler
17470 \end_inset
17471 </cell>
17472 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17473 \begin_inset Text
17474
17475 \layout Standard
17476
17477
17478 \family roman
17479 \series medium
17480 \shape up
17481 \size normal
17482 \emph off
17483 \bar no
17484 \noun off
17485 \color none
17486 sdcc/bin
17487 \end_inset
17488 </cell>
17489 </row>
17490 <row topline="true">
17491 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17492 \begin_inset Text
17493
17494 \layout Standard
17495
17496 asx8051
17497 \end_inset
17498 </cell>
17499 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17500 \begin_inset Text
17501
17502 \layout Standard
17503
17504 Assembler
17505 \end_inset
17506 </cell>
17507 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17508 \begin_inset Text
17509
17510 \layout Standard
17511
17512
17513 \family roman
17514 \series medium
17515 \shape up
17516 \size normal
17517 \emph off
17518 \bar no
17519 \noun off
17520 \color none
17521 sdcc/bin
17522 \end_inset
17523 </cell>
17524 </row>
17525 <row topline="true">
17526 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17527 \begin_inset Text
17528
17529 \layout Standard
17530
17531 sdcdb
17532 \end_inset
17533 </cell>
17534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17535 \begin_inset Text
17536
17537 \layout Standard
17538
17539 Simulator
17540 \end_inset
17541 </cell>
17542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17543 \begin_inset Text
17544
17545 \layout Standard
17546
17547
17548 \family roman
17549 \series medium
17550 \shape up
17551 \size normal
17552 \emph off
17553 \bar no
17554 \noun off
17555 \color none
17556 sdcc/bin
17557 \end_inset
17558 </cell>
17559 </row>
17560 <row topline="true">
17561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17562 \begin_inset Text
17563
17564 \layout Standard
17565
17566 aslink
17567 \end_inset
17568 </cell>
17569 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17570 \begin_inset Text
17571
17572 \layout Standard
17573
17574 Linker
17575 \end_inset
17576 </cell>
17577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17578 \begin_inset Text
17579
17580 \layout Standard
17581
17582
17583 \family roman
17584 \series medium
17585 \shape up
17586 \size normal
17587 \emph off
17588 \bar no
17589 \noun off
17590 \color none
17591 sdcc/bin
17592 \end_inset
17593 </cell>
17594 </row>
17595 <row topline="true">
17596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17597 \begin_inset Text
17598
17599 \layout Standard
17600
17601 link-z80
17602 \end_inset
17603 </cell>
17604 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17605 \begin_inset Text
17606
17607 \layout Standard
17608
17609 Linker
17610 \end_inset
17611 </cell>
17612 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17613 \begin_inset Text
17614
17615 \layout Standard
17616
17617
17618 \family roman
17619 \series medium
17620 \shape up
17621 \size normal
17622 \emph off
17623 \bar no
17624 \noun off
17625 \color none
17626 sdcc/bin
17627 \end_inset
17628 </cell>
17629 </row>
17630 <row topline="true">
17631 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17632 \begin_inset Text
17633
17634 \layout Standard
17635
17636 link-gbz80
17637 \end_inset
17638 </cell>
17639 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17640 \begin_inset Text
17641
17642 \layout Standard
17643
17644 Linker
17645 \end_inset
17646 </cell>
17647 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17648 \begin_inset Text
17649
17650 \layout Standard
17651
17652
17653 \family roman
17654 \series medium
17655 \shape up
17656 \size normal
17657 \emph off
17658 \bar no
17659 \noun off
17660 \color none
17661 sdcc/bin
17662 \end_inset
17663 </cell>
17664 </row>
17665 <row topline="true" bottomline="true">
17666 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17667 \begin_inset Text
17668
17669 \layout Standard
17670
17671 packihx
17672 \end_inset
17673 </cell>
17674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17675 \begin_inset Text
17676
17677 \layout Standard
17678
17679 ihx packer
17680 \end_inset
17681 </cell>
17682 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17683 \begin_inset Text
17684
17685 \layout Standard
17686
17687
17688 \family roman
17689 \series medium
17690 \shape up
17691 \size normal
17692 \emph off
17693 \bar no
17694 \noun off
17695 \color none
17696 sdcc/bin
17697 \end_inset
17698 </cell>
17699 </row>
17700 </lyxtabular>
17701
17702 \end_inset
17703
17704
17705 \newline
17706
17707 \layout Section
17708
17709 Documentation
17710 \begin_inset LatexCommand \index{Documentation}
17711
17712 \end_inset
17713
17714  included in the distribution
17715 \layout Standard
17716 \align center
17717
17718 \begin_inset  Tabular
17719 <lyxtabular version="3" rows="10" columns="2">
17720 <features>
17721 <column alignment="left" valignment="top" leftline="true" width="0">
17722 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
17723 <row topline="true" bottomline="true">
17724 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17725 \begin_inset Text
17726
17727 \layout Standard
17728
17729 Subject / Title
17730 \end_inset
17731 </cell>
17732 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17733 \begin_inset Text
17734
17735 \layout Standard
17736
17737 Where to get / filename
17738 \end_inset
17739 </cell>
17740 </row>
17741 <row topline="true">
17742 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17743 \begin_inset Text
17744
17745 \layout Standard
17746
17747 SDCC Compiler User Guide
17748 \end_inset
17749 </cell>
17750 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17751 \begin_inset Text
17752
17753 \layout Standard
17754
17755 You're reading it right now
17756 \end_inset
17757 </cell>
17758 </row>
17759 <row topline="true">
17760 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17761 \begin_inset Text
17762
17763 \layout Standard
17764
17765 Changelog of SDCC
17766 \end_inset
17767 </cell>
17768 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17769 \begin_inset Text
17770
17771 \layout Standard
17772
17773 sdcc/Changelog
17774 \end_inset
17775 </cell>
17776 </row>
17777 <row topline="true">
17778 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17779 \begin_inset Text
17780
17781 \layout Standard
17782
17783 ASXXXX Assemblers and ASLINK Relocating Linker
17784 \end_inset
17785 </cell>
17786 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17787 \begin_inset Text
17788
17789 \layout Standard
17790
17791 sdcc/as/doc/asxhtm.html
17792 \end_inset
17793 </cell>
17794 </row>
17795 <row topline="true">
17796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17797 \begin_inset Text
17798
17799 \layout Standard
17800
17801 SDCC regression test
17802 \begin_inset LatexCommand \index{Regression test}
17803
17804 \end_inset
17805
17806
17807 \end_inset
17808 </cell>
17809 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17810 \begin_inset Text
17811
17812 \layout Standard
17813
17814 sdcc/doc/test_suite_spec.pdf
17815 \end_inset
17816 </cell>
17817 </row>
17818 <row topline="true">
17819 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17820 \begin_inset Text
17821
17822 \layout Standard
17823
17824 Various notes
17825 \end_inset
17826 </cell>
17827 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17828 \begin_inset Text
17829
17830 \layout Standard
17831
17832 sdcc/doc/*
17833 \end_inset
17834 </cell>
17835 </row>
17836 <row topline="true">
17837 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17838 \begin_inset Text
17839
17840 \layout Standard
17841
17842 Notes on debugging with sdcdb
17843 \begin_inset LatexCommand \index{sdcdb (debugger)}
17844
17845 \end_inset
17846
17847
17848 \end_inset
17849 </cell>
17850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17851 \begin_inset Text
17852
17853 \layout Standard
17854
17855 sdcc/debugger/README
17856 \end_inset
17857 </cell>
17858 </row>
17859 <row topline="true">
17860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17861 \begin_inset Text
17862
17863 \layout Standard
17864
17865 Software simulator for microcontrollers
17866 \end_inset
17867 </cell>
17868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17869 \begin_inset Text
17870
17871 \layout Standard
17872
17873
17874 \family roman
17875 \series medium
17876 \shape up
17877 \size normal
17878 \emph off
17879 \bar no
17880 \noun off
17881 \color none
17882 sdcc/sim/ucsim/doc
17883 \family default
17884 \series default
17885 \shape default
17886 \size default
17887 \emph default
17888 \bar default
17889 \noun default
17890 \color default
17891 /index.html
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 Temporary notes on the pic16
17902 \begin_inset LatexCommand \index{PIC16}
17903
17904 \end_inset
17905
17906  port
17907 \end_inset
17908 </cell>
17909 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17910 \begin_inset Text
17911
17912 \layout Standard
17913
17914 sdcc/src/pic16/NOTES
17915 \end_inset
17916 </cell>
17917 </row>
17918 <row topline="true" bottomline="true">
17919 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17920 \begin_inset Text
17921
17922 \layout Standard
17923
17924 SDCC internal documentation (debugging file format)
17925 \end_inset
17926 </cell>
17927 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17928 \begin_inset Text
17929
17930 \layout Standard
17931
17932 sdcc/doc/
17933 \family roman
17934 \series medium
17935 \shape up
17936 \size normal
17937 \emph off
17938 \bar no
17939 \noun off
17940 \color none
17941 cdbfileformat.pd
17942 \family default
17943 \series default
17944 \shape default
17945 \size default
17946 \emph default
17947 \bar default
17948 \noun default
17949 \color default
17950 f
17951 \end_inset
17952 </cell>
17953 </row>
17954 </lyxtabular>
17955
17956 \end_inset
17957
17958
17959 \newline
17960
17961 \layout Section
17962
17963 Related open source tools
17964 \begin_inset LatexCommand \index{Related tools}
17965
17966 \end_inset
17967
17968
17969 \layout Standard
17970 \align center
17971
17972 \begin_inset  Tabular
17973 <lyxtabular version="3" rows="11" columns="3">
17974 <features>
17975 <column alignment="center" valignment="top" leftline="true" width="0pt">
17976 <column alignment="block" valignment="top" leftline="true" width="30line%">
17977 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
17978 <row topline="true" bottomline="true">
17979 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17980 \begin_inset Text
17981
17982 \layout Standard
17983
17984 Name
17985 \end_inset
17986 </cell>
17987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17988 \begin_inset Text
17989
17990 \layout Standard
17991
17992 Purpose
17993 \end_inset
17994 </cell>
17995 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17996 \begin_inset Text
17997
17998 \layout Standard
17999
18000 Where to get
18001 \end_inset
18002 </cell>
18003 </row>
18004 <row topline="true">
18005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18006 \begin_inset Text
18007
18008 \layout Standard
18009
18010 gpsim
18011 \begin_inset LatexCommand \index{gpsim (pic simulator)}
18012
18013 \end_inset
18014
18015
18016 \end_inset
18017 </cell>
18018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18019 \begin_inset Text
18020
18021 \layout Standard
18022
18023 PIC simulator
18024 \end_inset
18025 </cell>
18026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18027 \begin_inset Text
18028
18029 \layout Standard
18030
18031
18032 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
18033
18034 \end_inset
18035
18036
18037 \end_inset
18038 </cell>
18039 </row>
18040 <row topline="true">
18041 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18042 \begin_inset Text
18043
18044 \layout Standard
18045
18046 gputils
18047 \begin_inset LatexCommand \index{gputils (pic tools)}
18048
18049 \end_inset
18050
18051
18052 \end_inset
18053 </cell>
18054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18055 \begin_inset Text
18056
18057 \layout Standard
18058
18059 GNU PIC utilities
18060 \end_inset
18061 </cell>
18062 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18063 \begin_inset Text
18064
18065 \layout Standard
18066
18067
18068 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
18069
18070 \end_inset
18071
18072
18073 \end_inset
18074 </cell>
18075 </row>
18076 <row topline="true">
18077 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18078 \begin_inset Text
18079
18080 \layout Standard
18081
18082 flP5
18083 \end_inset
18084 </cell>
18085 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18086 \begin_inset Text
18087
18088 \layout Standard
18089
18090 PIC programmer
18091 \end_inset
18092 </cell>
18093 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18094 \begin_inset Text
18095
18096 \layout Standard
18097
18098
18099 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
18100
18101 \end_inset
18102
18103
18104 \end_inset
18105 </cell>
18106 </row>
18107 <row topline="true">
18108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18109 \begin_inset Text
18110
18111 \layout Standard
18112
18113 indent
18114 \begin_inset LatexCommand \index{indent (source formatting tool)}
18115
18116 \end_inset
18117
18118
18119 \end_inset
18120 </cell>
18121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18122 \begin_inset Text
18123
18124 \layout Standard
18125
18126 Formats C source - Master of the white spaces
18127 \end_inset
18128 </cell>
18129 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18130 \begin_inset Text
18131
18132 \layout Standard
18133
18134
18135 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
18136
18137 \end_inset
18138
18139
18140 \end_inset
18141 </cell>
18142 </row>
18143 <row topline="true">
18144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18145 \begin_inset Text
18146
18147 \layout Standard
18148
18149 srecord
18150 \begin_inset LatexCommand \index{srecord (tool)}
18151
18152 \end_inset
18153
18154
18155 \end_inset
18156 </cell>
18157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18158 \begin_inset Text
18159
18160 \layout Standard
18161
18162 Object file conversion, checksumming, ...
18163 \end_inset
18164 </cell>
18165 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18166 \begin_inset Text
18167
18168 \layout Standard
18169
18170
18171 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
18172
18173 \end_inset
18174
18175
18176 \end_inset
18177 </cell>
18178 </row>
18179 <row topline="true">
18180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18181 \begin_inset Text
18182
18183 \layout Standard
18184
18185 objdump
18186 \begin_inset LatexCommand \index{objdump (tool)}
18187
18188 \end_inset
18189
18190
18191 \end_inset
18192 </cell>
18193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18194 \begin_inset Text
18195
18196 \layout Standard
18197
18198 Object file conversion, ...
18199 \end_inset
18200 </cell>
18201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18202 \begin_inset Text
18203
18204 \layout Standard
18205
18206 Part of binutils (should be there anyway)
18207 \end_inset
18208 </cell>
18209 </row>
18210 <row topline="true">
18211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18212 \begin_inset Text
18213
18214 \layout Standard
18215
18216 doxygen
18217 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
18218
18219 \end_inset
18220
18221
18222 \end_inset
18223 </cell>
18224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18225 \begin_inset Text
18226
18227 \layout Standard
18228
18229 Source code documentation system
18230 \end_inset
18231 </cell>
18232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18233 \begin_inset Text
18234
18235 \layout Standard
18236
18237
18238 \begin_inset LatexCommand \url{http://www.doxygen.org}
18239
18240 \end_inset
18241
18242
18243 \end_inset
18244 </cell>
18245 </row>
18246 <row topline="true">
18247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18248 \begin_inset Text
18249
18250 \layout Standard
18251
18252 kdevelop
18253 \end_inset
18254 </cell>
18255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18256 \begin_inset Text
18257
18258 \layout Standard
18259
18260 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
18261 \end_inset
18262 </cell>
18263 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18264 \begin_inset Text
18265
18266 \layout Standard
18267
18268
18269 \begin_inset LatexCommand \url{http://www.kdevelop.org}
18270
18271 \end_inset
18272
18273
18274 \end_inset
18275 </cell>
18276 </row>
18277 <row topline="true">
18278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18279 \begin_inset Text
18280
18281 \layout Standard
18282
18283 splint
18284 \begin_inset LatexCommand \index{splint (syntax checking tool)}
18285
18286 \end_inset
18287
18288
18289 \end_inset
18290 </cell>
18291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18292 \begin_inset Text
18293
18294 \layout Standard
18295
18296 Statically checks c sources (has anyone adapted splint for SDCC?)
18297 \end_inset
18298 </cell>
18299 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18300 \begin_inset Text
18301
18302 \layout Standard
18303
18304
18305 \begin_inset LatexCommand \url{http://www.splint.org}
18306
18307 \end_inset
18308
18309
18310 \end_inset
18311 </cell>
18312 </row>
18313 <row topline="true" bottomline="true">
18314 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18315 \begin_inset Text
18316
18317 \layout Standard
18318
18319 ddd
18320 \begin_inset LatexCommand \index{ddd (debugger)}
18321
18322 \end_inset
18323
18324
18325 \end_inset
18326 </cell>
18327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18328 \begin_inset Text
18329
18330 \layout Standard
18331
18332 Debugger, serves nicely as GUI to sdcdb
18333 \begin_inset LatexCommand \index{sdcdb (debugger)}
18334
18335 \end_inset
18336
18337  (Unix only)
18338 \end_inset
18339 </cell>
18340 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18341 \begin_inset Text
18342
18343 \layout Standard
18344
18345
18346 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
18347
18348 \end_inset
18349
18350
18351 \end_inset
18352 </cell>
18353 </row>
18354 </lyxtabular>
18355
18356 \end_inset
18357
18358
18359 \newline
18360
18361 \layout Section
18362
18363 Related documentation / recommended reading
18364 \layout Standard
18365 \align center
18366
18367 \begin_inset  Tabular
18368 <lyxtabular version="3" rows="6" columns="3">
18369 <features>
18370 <column alignment="center" valignment="top" leftline="true" width="0pt">
18371 <column alignment="block" valignment="top" leftline="true" width="30line%">
18372 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18373 <row topline="true" bottomline="true">
18374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18375 \begin_inset Text
18376
18377 \layout Standard
18378
18379 Name
18380 \end_inset
18381 </cell>
18382 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18383 \begin_inset Text
18384
18385 \layout Standard
18386
18387 Subject / Title
18388 \end_inset
18389 </cell>
18390 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18391 \begin_inset Text
18392
18393 \layout Standard
18394
18395 Where to get
18396 \end_inset
18397 </cell>
18398 </row>
18399 <row topline="true">
18400 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18401 \begin_inset Text
18402
18403 \layout Standard
18404
18405
18406 \family roman
18407 \series medium
18408 \shape up
18409 \size normal
18410 \emph off
18411 \bar no
18412 \noun off
18413 \color none
18414 c-refcard.pdf
18415 \end_inset
18416 </cell>
18417 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18418 \begin_inset Text
18419
18420 \layout Standard
18421
18422 C Reference Card
18423 \begin_inset LatexCommand \index{C Reference card}
18424
18425 \end_inset
18426
18427 , 2 pages
18428 \end_inset
18429 </cell>
18430 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18431 \begin_inset Text
18432
18433 \layout Standard
18434
18435
18436 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
18437
18438 \end_inset
18439
18440
18441 \end_inset
18442 </cell>
18443 </row>
18444 <row topline="true">
18445 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18446 \begin_inset Text
18447
18448 \layout Standard
18449
18450 c-faq
18451 \end_inset
18452 </cell>
18453 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18454 \begin_inset Text
18455
18456 \layout Standard
18457
18458 C-FAQ-list
18459 \end_inset
18460 </cell>
18461 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18462 \begin_inset Text
18463
18464 \layout Standard
18465
18466
18467 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
18468
18469 \end_inset
18470
18471
18472 \end_inset
18473 </cell>
18474 </row>
18475 <row topline="true">
18476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18477 \begin_inset Text
18478
18479 \layout Standard
18480
18481 \end_inset
18482 </cell>
18483 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18484 \begin_inset Text
18485
18486 \layout Standard
18487
18488 Latest datasheet of the target CPU
18489 \end_inset
18490 </cell>
18491 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18492 \begin_inset Text
18493
18494 \layout Standard
18495
18496 vendor
18497 \end_inset
18498 </cell>
18499 </row>
18500 <row topline="true">
18501 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18502 \begin_inset Text
18503
18504 \layout Standard
18505
18506 \end_inset
18507 </cell>
18508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18509 \begin_inset Text
18510
18511 \layout Standard
18512
18513 Revision history of datasheet
18514 \end_inset
18515 </cell>
18516 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18517 \begin_inset Text
18518
18519 \layout Standard
18520
18521 vendor
18522 \end_inset
18523 </cell>
18524 </row>
18525 <row topline="true" bottomline="true">
18526 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18527 \begin_inset Text
18528
18529 \layout Standard
18530
18531 S.
18532  S.
18533  Muchnick
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 Advanced Compiler Design and Implementation
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 bookstore (very dedicated, probably read other books first)
18550 \end_inset
18551 </cell>
18552 </row>
18553 </lyxtabular>
18554
18555 \end_inset
18556
18557
18558 \newline
18559
18560 \layout Section
18561
18562 Some Questions
18563 \layout Standard
18564
18565 Some questions answered, some pointers given - it might be time to in turn
18566  ask
18567 \emph on
18568 you
18569 \emph default
18570  some questions:
18571 \layout Itemize
18572
18573 can you solve your project with the selected microcontroller? Would you
18574  find out early or rather late that your target is too small/slow/whatever?
18575  Can you switch to a slightly better device if it doesn't fit?
18576 \layout Itemize
18577
18578 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
18579  and/or another programming language be more adequate? Would an operating
18580  system on the target device help?
18581 \layout Itemize
18582
18583 if you solved the problem, will the marketing department be happy?
18584 \layout Itemize
18585
18586 if the marketing department is happy, will customers be happy?
18587 \layout Itemize
18588
18589 if you're the project manager, marketing department and maybe even the customer
18590  in one person, have you tried to see the project from the outside?
18591 \layout Itemize
18592
18593 is the project done if you think it is done? Or is just that other interface/pro
18594 tocol/feature/configuration/option missing? How about website, manual(s),
18595  internationali(z|s)ation, packaging, labels, 2nd source for components,
18596  electromagnetic compatability/interference, documentation for production,
18597  production test software, update mechanism, patent issues?
18598 \layout Itemize
18599
18600 is your project adequately positioned in that magic triangle: fame, fortune,
18601  fun?
18602 \layout Standard
18603
18604 Maybe not all answers to these questions are known and some answers may
18605  even be
18606 \emph on
18607 no
18608 \emph default
18609 , nevertheless knowing these questions may help you to avoid burnout
18610 \begin_inset Foot
18611 collapsed false
18612
18613 \layout Standard
18614
18615 burnout is bad for electronic devices, programmers and motorcycle tyres
18616 \end_inset
18617
18618 .
18619  Chances are you didn't want to hear some of them...
18620 \layout Chapter
18621
18622 Support
18623 \begin_inset LatexCommand \index{Support}
18624
18625 \end_inset
18626
18627
18628 \layout Standard
18629
18630 SDCC has grown to be a large project.
18631  The compiler alone (without the preprocessor, assembler and linker) is
18632  well over 100,000 lines of code (blank stripped).
18633  The open source nature of this project is a key to its continued growth
18634  and support.
18635  You gain the benefit and support of many active software developers and
18636  end users.
18637  Is SDCC perfect? No, that's why we need your help.
18638  The developers take pride in fixing reported bugs.
18639  You can help by reporting the bugs and helping other SDCC users.
18640  There are lots of ways to contribute, and we encourage you to take part
18641  in making SDCC a great software package.
18642
18643 \layout Standard
18644
18645 The SDCC project is hosted on the SDCC sourceforge site at
18646 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
18647
18648 \end_inset
18649
18650 .
18651  You'll find the complete set of mailing lists
18652 \begin_inset LatexCommand \index{Mailing list(s)}
18653
18654 \end_inset
18655
18656 , forums, bug reporting system, patch submission
18657 \begin_inset LatexCommand \index{Patch submission}
18658
18659 \end_inset
18660
18661  system, download
18662 \begin_inset LatexCommand \index{download}
18663
18664 \end_inset
18665
18666  area and cvs code repository
18667 \begin_inset LatexCommand \index{cvs code repository}
18668
18669 \end_inset
18670
18671  there.
18672 \layout Section
18673
18674 Reporting Bugs
18675 \begin_inset LatexCommand \index{Bug reporting}
18676
18677 \end_inset
18678
18679
18680 \begin_inset LatexCommand \index{Reporting bugs}
18681
18682 \end_inset
18683
18684
18685 \layout Standard
18686
18687 The recommended way of reporting bugs is using the infrastructure of the
18688  sourceforge site.
18689  You can follow the status of bug reports there and have an overview about
18690  the known bugs.
18691 \layout Standard
18692
18693 Bug reports are automatically forwarded to the developer mailing list and
18694  will be fixed ASAP.
18695  When reporting a bug, it is very useful to include a small test program
18696  (the smaller the better) which reproduces the problem.
18697  If you can isolate the problem by looking at the generated assembly code,
18698  this can be very helpful.
18699  Compiling your program with the -
18700 \begin_inset ERT
18701 status Collapsed
18702
18703 \layout Standard
18704
18705 \backslash
18706 /
18707 \end_inset
18708
18709 -dumpall
18710 \begin_inset LatexCommand \index{-\/-dumpall}
18711
18712 \end_inset
18713
18714  option can sometimes be useful in locating optimization problems.
18715  When reporting a bug please maker sure you:
18716 \layout Enumerate
18717
18718 Attach the code you are compiling with SDCC.
18719
18720 \layout Enumerate
18721
18722 Specify the exact command you use to run SDCC, or attach your Makefile.
18723
18724 \layout Enumerate
18725
18726 Specify the SDCC version (type "
18727 \family sans
18728 \series bold
18729 sdcc -v
18730 \family default
18731 \series default
18732 "), your platform, and operating system.
18733
18734 \layout Enumerate
18735
18736 Provide an exact copy of any error message or incorrect output.
18737
18738 \layout Enumerate
18739
18740 Put something meaningful in the subject of your message.
18741 \layout Standard
18742
18743 Please attempt to include these 5 important parts, as applicable, in all
18744  requests for support or when reporting any problems or bugs with SDCC.
18745  Though this will make your message lengthy, it will greatly improve your
18746  chance that SDCC users and developers will be able to help you.
18747  Some SDCC developers are frustrated by bug reports without code provided
18748  that they can use to reproduce and ultimately fix the problem, so please
18749  be sure to provide sample code if you are reporting a bug!
18750 \layout Standard
18751
18752 Please have a short check that you are using a recent version of SDCC and
18753  the bug is not yet known.
18754  This is the link for reporting bugs:
18755 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
18756
18757 \end_inset
18758
18759 .
18760 \layout Section
18761
18762 Requesting Features
18763 \begin_inset LatexCommand \label{sub:Requesting-Features}
18764
18765 \end_inset
18766
18767
18768 \begin_inset LatexCommand \index{Feature request}
18769
18770 \end_inset
18771
18772
18773 \begin_inset LatexCommand \index{Requesting features}
18774
18775 \end_inset
18776
18777
18778 \layout Standard
18779
18780 Like bug reports feature requests are forwarded to the developer mailing
18781  list.
18782  This is the link for requesting features:
18783 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
18784
18785 \end_inset
18786
18787 .
18788 \layout Section
18789
18790 Submitting patches
18791 \layout Standard
18792
18793 Like bug reports contributed patches are forwarded to the developer mailing
18794  list.
18795  This is the link for submitting patches
18796 \begin_inset LatexCommand \index{Patch submission}
18797
18798 \end_inset
18799
18800 :
18801 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
18802
18803 \end_inset
18804
18805 .
18806 \layout Standard
18807
18808 You need to specify some parameters to the
18809 \family typewriter
18810 diff
18811 \family default
18812  command for the patches to be useful.
18813  If you modified more than one file a patch created f.e.
18814  with
18815 \family sans
18816 \series bold
18817
18818 \begin_inset Quotes sld
18819 \end_inset
18820
18821 diff -Naur unmodified_directory modified_directory >my_changes.patch
18822 \begin_inset Quotes srd
18823 \end_inset
18824
18825
18826 \family default
18827 \series default
18828  will be fine, otherwise
18829 \family sans
18830 \series bold
18831
18832 \begin_inset Quotes sld
18833 \end_inset
18834
18835 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
18836 \begin_inset Quotes srd
18837 \end_inset
18838
18839
18840 \series default
18841
18842 \family default
18843 will do.
18844 \layout Section
18845
18846 Getting Help
18847 \layout Standard
18848
18849 These links should take you directly to the
18850 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
18851
18852 \end_inset
18853
18854
18855 \begin_inset Foot
18856 collapsed false
18857
18858 \layout Standard
18859
18860 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
18861  automated messages (mid 2003)
18862 \end_inset
18863
18864  and the
18865 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
18866
18867 \end_inset
18868
18869 , lists
18870 \begin_inset LatexCommand \index{Mailing list(s)}
18871
18872 \end_inset
18873
18874  and forums are archived and searchable so if you are lucky someone already
18875  had a similar problem.
18876  While mails to the lists themselves are delivered promptly their web front
18877  end on sourceforge sometimes shows a severe time lag (up to several weeks),
18878  if you're seriously using SDCC please consider subscribing to the lists.
18879 \layout Section
18880
18881 ChangeLog
18882 \layout Standard
18883
18884 You can follow the status of the cvs version
18885 \begin_inset LatexCommand \index{version}
18886
18887 \end_inset
18888
18889  of SDCC by watching the Changelog
18890 \begin_inset LatexCommand \index{Changelog}
18891
18892 \end_inset
18893
18894  in the cvs-repository
18895 \newline
18896
18897 \size footnotesize
18898
18899 \begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
18900
18901 \end_inset
18902
18903 .
18904 \layout Section
18905
18906 Release policy
18907 \begin_inset LatexCommand \index{Release policy}
18908
18909 \end_inset
18910
18911
18912 \layout Standard
18913
18914 Historically there often were long delays between official releases and
18915  the sourceforge download area tends to get not updated at all.
18916  Excuses in the past might have referred to problems with live range analysis,
18917  but as this was fixed a while ago, the current problem is that another
18918  excuse has to be found.
18919  Kidding aside, we have to get better there! On the other hand there are
18920  daily snapshots available at
18921 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
18922
18923 \end_inset
18924
18925 , and you can always build the very last version (hopefully with many bugs
18926  fixed, and features added) from the source code available at
18927 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
18928
18929 \end_inset
18930
18931 .
18932 \layout Section
18933
18934 Examples
18935 \begin_inset LatexCommand \index{Examples}
18936
18937 \end_inset
18938
18939
18940 \layout Standard
18941
18942 You'll find some small examples in the directory
18943 \emph on
18944 sdcc/device/examples/.
18945
18946 \emph default
18947 More examples and libraries are available at
18948 \emph on
18949  The SDCC Open Knowledge Resource
18950 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
18951
18952 \end_inset
18953
18954
18955 \emph default
18956 web site or at
18957 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
18958
18959 \end_inset
18960
18961 .
18962 \layout Comment
18963
18964 I did insert a reference to Paul's web site here although it seems rather
18965  dedicated to a specific 8032 board (I think it's okay because it f.e.
18966  shows LCD/Harddisc interface and has a free 8051 monitor.
18967  Independent 8032 board vendors face hard competition of heavily subsidized
18968  development boards anyway).
18969 \layout Comment
18970
18971 Maybe we should include some links to real world applications.
18972  Preferably pointer to pointers (one for each architecture) so this stays
18973  manageable here?
18974 \layout Section
18975
18976 Quality control
18977 \begin_inset LatexCommand \index{Quality control}
18978
18979 \end_inset
18980
18981
18982 \layout Standard
18983
18984 The compiler is passed through nightly compile and build checks.
18985  The so called
18986 \shape italic
18987 regression tests
18988 \shape default
18989
18990 \begin_inset LatexCommand \index{Regression test}
18991
18992 \end_inset
18993
18994  check that SDCC itself compiles flawlessly on several platforms and checks
18995  the quality of the code generated by SDCC by running the code through simulator
18996 s.
18997  There is a separate document
18998 \shape italic
18999 test_suite.pdf
19000 \begin_inset LatexCommand \index{Test suite}
19001
19002 \end_inset
19003
19004
19005 \shape default
19006  about this.
19007 \layout Standard
19008
19009 You'll find the test code in the directory
19010 \shape italic
19011 sdcc/support/regression
19012 \shape default
19013 .
19014  You can run these tests manually by running
19015 \family sans
19016 make
19017 \family default
19018  in this directory (or f.e.
19019
19020 \family sans
19021 \series bold
19022
19023 \begin_inset Quotes sld
19024 \end_inset
19025
19026 make test-mcs51
19027 \begin_inset Quotes srd
19028 \end_inset
19029
19030
19031 \family default
19032 \series default
19033  if you don't want to run the complete tests).
19034  The test code might also be interesting if you want to look for examples
19035 \begin_inset LatexCommand \index{Examples}
19036
19037 \end_inset
19038
19039  checking corner cases of SDCC or if you plan to submit patches
19040 \begin_inset LatexCommand \index{Patch submission}
19041
19042 \end_inset
19043
19044 .
19045 \layout Standard
19046
19047 The pic port uses a different set of regression tests, you'll find them
19048  in the directory
19049 \shape italic
19050 sdcc/src/regression
19051 \shape default
19052 .
19053 \layout Chapter
19054 \pagebreak_top
19055 SDCC Technical Data
19056 \layout Section
19057
19058 Optimizations
19059 \begin_inset LatexCommand \index{Optimizations}
19060
19061 \end_inset
19062
19063
19064 \layout Standard
19065
19066 SDCC performs a host of standard optimizations in addition to some MCU specific
19067  optimizations.
19068
19069 \layout Subsection
19070
19071 Sub-expression Elimination
19072 \begin_inset LatexCommand \index{Subexpression elimination}
19073
19074 \end_inset
19075
19076
19077 \layout Standard
19078
19079 The compiler does local and
19080 \emph on
19081 g
19082 \emph default
19083 lobal
19084 \emph on
19085 c
19086 \emph default
19087 ommon
19088 \emph on
19089 s
19090 \emph default
19091 ubexpression
19092 \emph on
19093 e
19094 \emph default
19095 limination, e.g.:
19096 \layout Verse
19097
19098
19099 \family typewriter
19100 i = x + y + 1;
19101 \newline
19102 j = x + y;
19103 \layout Standard
19104
19105 will be translated to
19106 \layout Verse
19107
19108
19109 \family typewriter
19110 iTemp = x + y;
19111 \newline
19112 i = iTemp + 1;
19113 \newline
19114 j = iTemp;
19115 \layout Standard
19116
19117 Some subexpressions are not as obvious as the above example, e.g.:
19118 \layout Verse
19119
19120
19121 \family typewriter
19122 a->b[i].c = 10;
19123 \newline
19124 a->b[i].d = 11;
19125 \layout Standard
19126
19127 In this case the address arithmetic a->b[i] will be computed only once;
19128  the equivalent code in C would be.
19129 \layout Verse
19130
19131
19132 \family typewriter
19133 iTemp = a->b[i];
19134 \newline
19135 iTemp.c = 10;
19136 \newline
19137 iTemp.d = 11;
19138 \layout Standard
19139
19140 The compiler will try to keep these temporary variables in registers.
19141 \layout Subsection
19142
19143 Dead-Code Elimination
19144 \begin_inset LatexCommand \index{Dead-code elimination}
19145
19146 \end_inset
19147
19148
19149 \layout Verse
19150
19151
19152 \family typewriter
19153 int global;
19154 \newline
19155
19156 \newline
19157 void f () {
19158 \newline
19159 \SpecialChar ~
19160 \SpecialChar ~
19161 int i;
19162 \newline
19163 \SpecialChar ~
19164 \SpecialChar ~
19165 i = 1; \SpecialChar ~
19166 \SpecialChar ~
19167 \SpecialChar ~
19168 \SpecialChar ~
19169 \SpecialChar ~
19170 /* dead store */
19171 \newline
19172 \SpecialChar ~
19173 \SpecialChar ~
19174 global = 1;\SpecialChar ~
19175 /* dead store */
19176 \newline
19177 \SpecialChar ~
19178 \SpecialChar ~
19179 global = 2;
19180 \newline
19181 \SpecialChar ~
19182 \SpecialChar ~
19183 return;
19184 \newline
19185 \SpecialChar ~
19186 \SpecialChar ~
19187 global = 3;\SpecialChar ~
19188 /* unreachable */
19189 \newline
19190 }
19191 \layout Standard
19192
19193 will be changed to
19194 \layout Verse
19195
19196
19197 \family typewriter
19198 int global;
19199 \newline
19200
19201 \newline
19202 void f () {
19203 \newline
19204 \SpecialChar ~
19205 \SpecialChar ~
19206 global = 2;
19207 \newline
19208 \SpecialChar ~
19209 \SpecialChar ~
19210 return;
19211 \newline
19212 }
19213 \layout Subsection
19214
19215 Copy-Propagation
19216 \begin_inset LatexCommand \index{Copy propagation}
19217
19218 \end_inset
19219
19220
19221 \layout Verse
19222
19223
19224 \family typewriter
19225 int f() {
19226 \newline
19227 \SpecialChar ~
19228 \SpecialChar ~
19229 int i, j;
19230 \newline
19231 \SpecialChar ~
19232 \SpecialChar ~
19233 i = 10;
19234 \newline
19235 \SpecialChar ~
19236 \SpecialChar ~
19237 j = i;
19238 \newline
19239 \SpecialChar ~
19240 \SpecialChar ~
19241 return j;
19242 \newline
19243 }
19244 \layout Standard
19245
19246 will be changed to
19247 \layout Verse
19248
19249
19250 \family typewriter
19251 int f() {
19252 \newline
19253 \SpecialChar ~
19254 \SpecialChar ~
19255 int i, j;
19256 \newline
19257 \SpecialChar ~
19258 \SpecialChar ~
19259 i = 10;
19260 \newline
19261 \SpecialChar ~
19262 \SpecialChar ~
19263 j = 10;
19264 \newline
19265 \SpecialChar ~
19266 \SpecialChar ~
19267 return 10;
19268 \newline
19269 }
19270 \layout Standard
19271
19272 Note: the dead stores created by this copy propagation will be eliminated
19273  by dead-code elimination.
19274 \layout Subsection
19275
19276 Loop Optimizations
19277 \begin_inset LatexCommand \index{Loop optimization}
19278
19279 \end_inset
19280
19281
19282 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
19283
19284 \end_inset
19285
19286
19287 \layout Standard
19288
19289 Two types of loop optimizations are done by SDCC
19290 \emph on
19291 loop invariant
19292 \emph default
19293  lifting and
19294 \emph on
19295  strength reduction
19296 \emph default
19297  of loop induction variables.
19298  In addition to the strength reduction the optimizer marks the induction
19299  variables and the register allocator tries to keep the induction variables
19300  in registers for the duration of the loop.
19301  Because of this preference of the register allocator
19302 \begin_inset LatexCommand \index{Register allocation}
19303
19304 \end_inset
19305
19306 , loop induction optimization causes an increase in register pressure, which
19307  may cause unwanted spilling of other temporary variables into the stack
19308 \begin_inset LatexCommand \index{stack}
19309
19310 \end_inset
19311
19312  / data space.
19313  The compiler will generate a warning message when it is forced to allocate
19314  extra space either on the stack or data space.
19315  If this extra space allocation is undesirable then induction optimization
19316  can be eliminated either for the entire source file (with -
19317 \begin_inset ERT
19318 status Collapsed
19319
19320 \layout Standard
19321
19322 \backslash
19323 /
19324 \end_inset
19325
19326 -noinduction option) or for a given function only using #pragma\SpecialChar ~
19327 noinduction
19328 \begin_inset LatexCommand \index{\#pragma noinduction}
19329
19330 \end_inset
19331
19332 .
19333 \newline
19334
19335 \newline
19336 Loop Invariant:
19337 \layout Verse
19338
19339
19340 \family typewriter
19341 for (i = 0 ; i < 100 ; i ++)
19342 \newline
19343 \SpecialChar ~
19344 \SpecialChar ~
19345 \SpecialChar ~
19346 \SpecialChar ~
19347 f += k + l;
19348 \layout Standard
19349
19350 changed to
19351 \layout Verse
19352
19353
19354 \family typewriter
19355 itemp = k + l;
19356 \newline
19357 for (i = 0; i < 100; i++)
19358 \newline
19359 \SpecialChar ~
19360 \SpecialChar ~
19361 \SpecialChar ~
19362 \SpecialChar ~
19363 f += itemp;
19364 \layout Standard
19365
19366 As mentioned previously some loop invariants are not as apparent, all static
19367  address computations are also moved out of the loop.
19368 \newline
19369
19370 \newline
19371 Strength Reduction
19372 \begin_inset LatexCommand \index{Strength reduction}
19373
19374 \end_inset
19375
19376 , this optimization substitutes an expression by a cheaper expression:
19377 \layout Verse
19378
19379
19380 \family typewriter
19381 for (i=0;i < 100; i++)
19382 \newline
19383 \SpecialChar ~
19384 \SpecialChar ~
19385 \SpecialChar ~
19386 \SpecialChar ~
19387 ar[i*5] = i*3;
19388 \layout Standard
19389
19390 changed to
19391 \layout Verse
19392
19393
19394 \family typewriter
19395 itemp1 = 0;
19396 \newline
19397 itemp2 = 0;
19398 \newline
19399 for (i=0;i< 100;i++) {
19400 \newline
19401 \SpecialChar ~
19402 \SpecialChar ~
19403 \SpecialChar ~
19404 \SpecialChar ~
19405 ar[itemp1] = itemp2;
19406 \newline
19407 \SpecialChar ~
19408 \SpecialChar ~
19409 \SpecialChar ~
19410 \SpecialChar ~
19411 itemp1 += 5;
19412 \newline
19413 \SpecialChar ~
19414 \SpecialChar ~
19415 \SpecialChar ~
19416 \SpecialChar ~
19417 itemp2 += 3;
19418 \newline
19419 }
19420 \layout Standard
19421
19422 The more expensive multiplication
19423 \begin_inset LatexCommand \index{Multiplication}
19424
19425 \end_inset
19426
19427  is changed to a less expensive addition.
19428 \layout Subsection
19429
19430 Loop Reversing
19431 \begin_inset LatexCommand \index{Loop reversing}
19432
19433 \end_inset
19434
19435
19436 \layout Standard
19437
19438 This optimization is done to reduce the overhead of checking loop boundaries
19439  for every iteration.
19440  Some simple loops can be reversed and implemented using a
19441 \begin_inset Quotes eld
19442 \end_inset
19443
19444 decrement and jump if not zero
19445 \begin_inset Quotes erd
19446 \end_inset
19447
19448  instruction.
19449  SDCC checks for the following criterion to determine if a loop is reversible
19450  (note: more sophisticated compilers use data-dependency analysis to make
19451  this determination, SDCC uses a more simple minded analysis).
19452 \layout Itemize
19453
19454 The 'for' loop is of the form
19455 \newline
19456
19457 \newline
19458
19459 \family typewriter
19460 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
19461  += 1])
19462 \newline
19463 \SpecialChar ~
19464 \SpecialChar ~
19465 \SpecialChar ~
19466 \SpecialChar ~
19467 <for body>
19468 \layout Itemize
19469
19470 The <for body> does not contain
19471 \begin_inset Quotes eld
19472 \end_inset
19473
19474 continue
19475 \begin_inset Quotes erd
19476 \end_inset
19477
19478  or 'break
19479 \begin_inset Quotes erd
19480 \end_inset
19481
19482 .
19483 \layout Itemize
19484
19485 All goto's are contained within the loop.
19486 \layout Itemize
19487
19488 No function calls within the loop.
19489 \layout Itemize
19490
19491 The loop control variable <sym> is not assigned any value within the loop
19492 \layout Itemize
19493
19494 The loop control variable does NOT participate in any arithmetic operation
19495  within the loop.
19496 \layout Itemize
19497
19498 There are NO switch statements in the loop.
19499 \layout Subsection
19500
19501 Algebraic Simplifications
19502 \layout Standard
19503
19504 SDCC does numerous algebraic simplifications, the following is a small sub-set
19505  of these optimizations.
19506 \layout Verse
19507
19508
19509 \family typewriter
19510 i = j + 0;\SpecialChar ~
19511 \SpecialChar ~
19512 \SpecialChar ~
19513 \SpecialChar ~
19514  /* changed to: */\SpecialChar ~
19515 \SpecialChar ~
19516 \SpecialChar ~
19517 \SpecialChar ~
19518  i = j;
19519 \newline
19520 i /= 2;\SpecialChar ~
19521 \SpecialChar ~
19522 \SpecialChar ~
19523 \SpecialChar ~
19524 \SpecialChar ~
19525 \SpecialChar ~
19526 \SpecialChar ~
19527  /* changed to: */\SpecialChar ~
19528 \SpecialChar ~
19529 \SpecialChar ~
19530 \SpecialChar ~
19531  i >>= 1;
19532 \newline
19533 i = j - j;\SpecialChar ~
19534 \SpecialChar ~
19535 \SpecialChar ~
19536 \SpecialChar ~
19537  /* changed to: */\SpecialChar ~
19538 \SpecialChar ~
19539 \SpecialChar ~
19540 \SpecialChar ~
19541  i = 0;
19542 \newline
19543 i = j / 1;\SpecialChar ~
19544 \SpecialChar ~
19545 \SpecialChar ~
19546 \SpecialChar ~
19547  /* changed to: */\SpecialChar ~
19548 \SpecialChar ~
19549 \SpecialChar ~
19550 \SpecialChar ~
19551  i = j;
19552 \layout Standard
19553
19554 Note the subexpressions
19555 \begin_inset LatexCommand \index{Subexpression}
19556
19557 \end_inset
19558
19559  given above are generally introduced by macro expansions or as a result
19560  of copy/constant propagation.
19561 \layout Subsection
19562
19563 'switch' Statements
19564 \begin_inset LatexCommand \label{sub:'switch'-Statements}
19565
19566 \end_inset
19567
19568
19569 \begin_inset LatexCommand \index{switch statement}
19570
19571 \end_inset
19572
19573
19574 \layout Standard
19575
19576 SDCC changes switch statements to jump tables
19577 \begin_inset LatexCommand \index{jump tables}
19578
19579 \end_inset
19580
19581  when the following conditions are true.
19582
19583 \layout Itemize
19584
19585 The case labels are in numerical sequence, the labels need not be in order,
19586  and the starting number need not be one or zero.
19587 \begin_deeper
19588 \layout Verse
19589
19590
19591 \family typewriter
19592 switch(i) {\SpecialChar ~
19593 \SpecialChar ~
19594 \SpecialChar ~
19595 \SpecialChar ~
19596 \SpecialChar ~
19597 \SpecialChar ~
19598 \SpecialChar ~
19599 \SpecialChar ~
19600 \SpecialChar ~
19601 \SpecialChar ~
19602 \SpecialChar ~
19603 \SpecialChar ~
19604 \SpecialChar ~
19605 \SpecialChar ~
19606 \SpecialChar ~
19607 \SpecialChar ~
19608 \SpecialChar ~
19609 \SpecialChar ~
19610 \SpecialChar ~
19611 \SpecialChar ~
19612 \SpecialChar ~
19613 \SpecialChar ~
19614 \SpecialChar ~
19615 \SpecialChar ~
19616 \SpecialChar ~
19617 \SpecialChar ~
19618 switch (i) {
19619 \newline
19620 \SpecialChar ~
19621 \SpecialChar ~
19622 \SpecialChar ~
19623 case 4: ...\SpecialChar ~
19624 \SpecialChar ~
19625 \SpecialChar ~
19626 \SpecialChar ~
19627 \SpecialChar ~
19628 \SpecialChar ~
19629 \SpecialChar ~
19630 \SpecialChar ~
19631 \SpecialChar ~
19632 \SpecialChar ~
19633 \SpecialChar ~
19634 \SpecialChar ~
19635 \SpecialChar ~
19636 \SpecialChar ~
19637 \SpecialChar ~
19638 \SpecialChar ~
19639 \SpecialChar ~
19640 \SpecialChar ~
19641 \SpecialChar ~
19642 \SpecialChar ~
19643 \SpecialChar ~
19644 \SpecialChar ~
19645 \SpecialChar ~
19646 \SpecialChar ~
19647 \SpecialChar ~
19648 \SpecialChar ~
19649 case 0: ...
19650
19651 \newline
19652 \SpecialChar ~
19653 \SpecialChar ~
19654 \SpecialChar ~
19655 case 5: ...\SpecialChar ~
19656 \SpecialChar ~
19657 \SpecialChar ~
19658 \SpecialChar ~
19659 \SpecialChar ~
19660 \SpecialChar ~
19661 \SpecialChar ~
19662 \SpecialChar ~
19663 \SpecialChar ~
19664 \SpecialChar ~
19665 \SpecialChar ~
19666 \SpecialChar ~
19667 \SpecialChar ~
19668 \SpecialChar ~
19669 \SpecialChar ~
19670 \SpecialChar ~
19671 \SpecialChar ~
19672 \SpecialChar ~
19673 \SpecialChar ~
19674 \SpecialChar ~
19675 \SpecialChar ~
19676 \SpecialChar ~
19677 \SpecialChar ~
19678 \SpecialChar ~
19679 \SpecialChar ~
19680 \SpecialChar ~
19681 case 1: ...
19682
19683 \newline
19684 \SpecialChar ~
19685 \SpecialChar ~
19686 \SpecialChar ~
19687 case 3: ...\SpecialChar ~
19688 \SpecialChar ~
19689 \SpecialChar ~
19690 \SpecialChar ~
19691 \SpecialChar ~
19692 \SpecialChar ~
19693 \SpecialChar ~
19694 \SpecialChar ~
19695 \SpecialChar ~
19696 \SpecialChar ~
19697 \SpecialChar ~
19698 \SpecialChar ~
19699 \SpecialChar ~
19700 \SpecialChar ~
19701 \SpecialChar ~
19702 \SpecialChar ~
19703 \SpecialChar ~
19704 \SpecialChar ~
19705 \SpecialChar ~
19706 \SpecialChar ~
19707 \SpecialChar ~
19708 \SpecialChar ~
19709 \SpecialChar ~
19710 \SpecialChar ~
19711 \SpecialChar ~
19712 \SpecialChar ~
19713 case 2: ...
19714
19715 \newline
19716 \SpecialChar ~
19717 \SpecialChar ~
19718 \SpecialChar ~
19719 case 6: ...\SpecialChar ~
19720 \SpecialChar ~
19721 \SpecialChar ~
19722 \SpecialChar ~
19723 \SpecialChar ~
19724 \SpecialChar ~
19725 \SpecialChar ~
19726 \SpecialChar ~
19727 \SpecialChar ~
19728 \SpecialChar ~
19729 \SpecialChar ~
19730 \SpecialChar ~
19731 \SpecialChar ~
19732 \SpecialChar ~
19733 \SpecialChar ~
19734 \SpecialChar ~
19735 \SpecialChar ~
19736 \SpecialChar ~
19737 \SpecialChar ~
19738 \SpecialChar ~
19739 \SpecialChar ~
19740 \SpecialChar ~
19741 \SpecialChar ~
19742 \SpecialChar ~
19743 \SpecialChar ~
19744 \SpecialChar ~
19745 case 3: ...
19746
19747 \newline
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 \SpecialChar ~
19773 \SpecialChar ~
19774 \SpecialChar ~
19775 \SpecialChar ~
19776 \SpecialChar ~
19777 \SpecialChar ~
19778 \SpecialChar ~
19779 \SpecialChar ~
19780 \SpecialChar ~
19781 \SpecialChar ~
19782 \SpecialChar ~
19783 \SpecialChar ~
19784 }
19785 \layout Standard
19786
19787 Both the above switch statements will be implemented using a jump-table.
19788  The example to the right side is slightly more efficient as the check for
19789  the lower boundary of the jump-table is not needed.
19790 \end_deeper
19791 \layout Itemize
19792
19793 The number of case labels is at least three, since it takes two conditional
19794  statements to handle the boundary conditions.
19795 \layout Itemize
19796
19797 The number of case labels is less than 84, since each label takes 3 bytes
19798  and a jump-table can be utmost 256 bytes long.
19799 \layout Standard
19800
19801 Switch statements which have gaps in the numeric sequence or those that
19802  have more that 84 case labels can be split into more than one switch statement
19803  for efficient code generation, e.g.:
19804 \layout Verse
19805
19806
19807 \family typewriter
19808 switch (i) {
19809 \newline
19810 \SpecialChar ~
19811 \SpecialChar ~
19812 case 1: ...
19813
19814 \newline
19815 \SpecialChar ~
19816 \SpecialChar ~
19817 case 2: ...
19818
19819 \newline
19820 \SpecialChar ~
19821 \SpecialChar ~
19822 case 3: ...
19823
19824 \newline
19825 \SpecialChar ~
19826 \SpecialChar ~
19827 case 4: ...
19828
19829 \newline
19830 \SpecialChar ~
19831 \SpecialChar ~
19832 case 9: ...
19833
19834 \newline
19835 \SpecialChar ~
19836 \SpecialChar ~
19837 case 10: ...
19838
19839 \newline
19840 \SpecialChar ~
19841 \SpecialChar ~
19842 case 11: ...
19843
19844 \newline
19845 \SpecialChar ~
19846 \SpecialChar ~
19847 case 12: ...
19848
19849 \newline
19850 }
19851 \layout Standard
19852
19853 If the above switch statement is broken down into two switch statements
19854 \layout Verse
19855
19856
19857 \family typewriter
19858 switch (i) {
19859 \newline
19860 \SpecialChar ~
19861 \SpecialChar ~
19862 case 1: ...
19863
19864 \newline
19865 \SpecialChar ~
19866 \SpecialChar ~
19867 case 2: ...
19868
19869 \newline
19870 \SpecialChar ~
19871 \SpecialChar ~
19872 case 3: ...
19873
19874 \newline
19875 \SpecialChar ~
19876 \SpecialChar ~
19877 case 4: ...
19878
19879 \newline
19880 }
19881 \layout Standard
19882
19883 and
19884 \layout Verse
19885
19886
19887 \family typewriter
19888 switch (i) {
19889 \newline
19890 \SpecialChar ~
19891 \SpecialChar ~
19892 case 9:\SpecialChar ~
19893 \SpecialChar ~
19894 ...
19895
19896 \newline
19897 \SpecialChar ~
19898 \SpecialChar ~
19899 case 10:\SpecialChar ~
19900 ...
19901
19902 \newline
19903 \SpecialChar ~
19904 \SpecialChar ~
19905 case 11:\SpecialChar ~
19906 ...
19907
19908 \newline
19909 \SpecialChar ~
19910 \SpecialChar ~
19911 case 12:\SpecialChar ~
19912 ...
19913
19914 \newline
19915 }
19916 \layout Standard
19917
19918 then both the switch statements will be implemented using jump-tables whereas
19919  the unmodified switch statement will not be.
19920  You might also consider inserting dummy cases 0 and 5 to 8 in this example.
19921
19922 \newline
19923 The pragma nojtbound
19924 \begin_inset LatexCommand \index{\#pragma nojtbound}
19925
19926 \end_inset
19927
19928  can be used to turn off checking the
19929 \emph on
19930 j
19931 \emph default
19932 ump
19933 \emph on
19934 t
19935 \emph default
19936 able
19937 \emph on
19938 bound
19939 \emph default
19940 aries.
19941  It has no effect if a default label is supplied.
19942  Use of this pragma is dangerous: if the switch argument is not matched
19943  by a case statement the processor will happily jump into Nirvana.
19944 \layout Subsection
19945
19946 Bit-shifting Operations
19947 \begin_inset LatexCommand \index{Bit shifting}
19948
19949 \end_inset
19950
19951 .
19952 \layout Standard
19953
19954 Bit shifting is one of the most frequently used operation in embedded programmin
19955 g.
19956  SDCC tries to implement bit-shift operations in the most efficient way
19957  possible, e.g.:
19958 \layout Verse
19959
19960
19961 \family typewriter
19962 unsigned char i;
19963 \newline
19964 ...
19965
19966 \newline
19967 i >>= 4;
19968 \newline
19969 ...
19970 \layout Standard
19971
19972 generates the following code:
19973 \layout Verse
19974
19975
19976 \family typewriter
19977 mov\SpecialChar ~
19978  a,_i
19979 \newline
19980 swap a
19981 \newline
19982 anl\SpecialChar ~
19983  a,#0x0f
19984 \newline
19985 mov\SpecialChar ~
19986  _i,a
19987 \layout Standard
19988
19989 In general SDCC will never setup a loop if the shift count is known.
19990  Another example:
19991 \layout Verse
19992
19993
19994 \family typewriter
19995 unsigned int i;
19996 \newline
19997 ...
19998
19999 \newline
20000 i >>= 9;
20001 \newline
20002 ...
20003 \layout Standard
20004
20005 will generate:
20006 \layout Verse
20007
20008
20009 \family typewriter
20010 mov\SpecialChar ~
20011 \SpecialChar ~
20012 a,(_i + 1)
20013 \newline
20014 mov\SpecialChar ~
20015 \SpecialChar ~
20016 (_i + 1),#0x00
20017 \newline
20018 clr\SpecialChar ~
20019 \SpecialChar ~
20020 c
20021 \newline
20022 rrc\SpecialChar ~
20023 \SpecialChar ~
20024 a
20025 \newline
20026 mov\SpecialChar ~
20027 \SpecialChar ~
20028 _i,a
20029 \layout Subsection
20030
20031 Bit-rotation
20032 \begin_inset LatexCommand \index{Bit rotation}
20033
20034 \end_inset
20035
20036
20037 \layout Standard
20038
20039 A special case of the bit-shift operation is bit rotation
20040 \begin_inset LatexCommand \index{rotating bits}
20041
20042 \end_inset
20043
20044 , SDCC recognizes the following expression to be a left bit-rotation:
20045 \layout Verse
20046
20047
20048 \family typewriter
20049 \series bold
20050 unsigned
20051 \series default
20052 \SpecialChar ~
20053 \SpecialChar ~
20054 char i;\SpecialChar ~
20055 \SpecialChar ~
20056 \SpecialChar ~
20057 \SpecialChar ~
20058 \SpecialChar ~
20059 \SpecialChar ~
20060 \SpecialChar ~
20061 \SpecialChar ~
20062 \SpecialChar ~
20063 \SpecialChar ~
20064 \SpecialChar ~
20065 /* unsigned is needed for rotation */
20066 \newline
20067 ...
20068
20069 \newline
20070 i = ((i << 1) | (i >> 7));
20071 \family default
20072
20073 \newline
20074
20075 \family typewriter
20076 ...
20077 \layout Standard
20078
20079 will generate the following code:
20080 \layout Verse
20081
20082
20083 \family typewriter
20084 mov\SpecialChar ~
20085 \SpecialChar ~
20086 a,_i
20087 \newline
20088 rl\SpecialChar ~
20089 \SpecialChar ~
20090 \SpecialChar ~
20091 a
20092 \newline
20093 mov\SpecialChar ~
20094 \SpecialChar ~
20095 _i,a
20096 \layout Standard
20097
20098 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
20099 ns of this case will also be recognized as bit-rotation, i.e.:
20100 \layout Verse
20101
20102
20103 \family typewriter
20104 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
20105 \layout Subsection
20106
20107 Nibble and Byte Swapping
20108 \layout Standard
20109
20110 Other special cases of the bit-shift operations are nibble or byte swapping
20111 \begin_inset LatexCommand \index{swapping nibbles/bytes}
20112
20113 \end_inset
20114
20115 , SDCC recognizes the following expressions:
20116 \layout Verse
20117
20118
20119 \family typewriter
20120 \series bold
20121 unsigned
20122 \series default
20123 \SpecialChar ~
20124 \SpecialChar ~
20125 char i;
20126 \newline
20127
20128 \series bold
20129 unsigned
20130 \series default
20131 \SpecialChar ~
20132 \SpecialChar ~
20133 int j;
20134 \newline
20135 ...
20136
20137 \newline
20138 i = ((i << 4) | (i >> 4));
20139 \family default
20140
20141 \newline
20142
20143 \family typewriter
20144 j = ((j << 8) | (j >> 8));
20145 \layout Standard
20146
20147 and generates a swap instruction for the nibble swapping
20148 \begin_inset LatexCommand \index{Nibble swapping}
20149
20150 \end_inset
20151
20152  or move instructions for the byte swapping
20153 \begin_inset LatexCommand \index{Byte swapping}
20154
20155 \end_inset
20156
20157 .
20158  The
20159 \begin_inset Quotes sld
20160 \end_inset
20161
20162 j
20163 \begin_inset Quotes srd
20164 \end_inset
20165
20166  example can be used to convert from little to big-endian or vice versa.
20167  If you want to change the endianness of a
20168 \emph on
20169 signed
20170 \emph default
20171  integer you have to cast to
20172 \family typewriter
20173 (unsigned int)
20174 \family default
20175  first.
20176 \layout Standard
20177
20178 Note that SDCC stores numbers in little-endian
20179 \begin_inset Foot
20180 collapsed false
20181
20182 \layout Standard
20183
20184 Usually 8-bit processors don't care much about endianness.
20185  This is not the case for the standard 8051 which only has an instruction
20186  to increment its
20187 \emph on
20188 dptr
20189 \emph default
20190
20191 \begin_inset LatexCommand \index{DPTR}
20192
20193 \end_inset
20194
20195 -datapointer
20196 \emph on
20197
20198 \emph default
20199 so little-endian is the more efficient byte order.
20200 \end_inset
20201
20202
20203 \begin_inset LatexCommand \index{little-endian}
20204
20205 \end_inset
20206
20207
20208 \begin_inset LatexCommand \index{Endianness}
20209
20210 \end_inset
20211
20212  format (i.e.
20213  lowest order first).
20214 \layout Subsection
20215
20216 Highest Order Bit
20217 \begin_inset LatexCommand \index{Highest Order Bit}
20218
20219 \end_inset
20220
20221
20222 \layout Standard
20223
20224 It is frequently required to obtain the highest order bit of an integral
20225  type (long, int, short or char types).
20226  SDCC recognizes the following expression to yield the highest order bit
20227  and generates optimized code for it, e.g.:
20228 \layout Verse
20229
20230
20231 \family typewriter
20232 unsigned int gint;
20233 \newline
20234
20235 \newline
20236 foo () {
20237 \newline
20238 \SpecialChar ~
20239 \SpecialChar ~
20240 unsigned char hob;
20241 \newline
20242 \SpecialChar ~
20243 \SpecialChar ~
20244 ...
20245
20246 \newline
20247 \SpecialChar ~
20248 \SpecialChar ~
20249 hob = (gint >> 15) & 1;
20250 \newline
20251 \SpecialChar ~
20252 \SpecialChar ~
20253 ..
20254
20255 \newline
20256 }
20257 \layout Standard
20258
20259 will generate the following code:
20260 \layout Verse
20261
20262
20263 \family typewriter
20264 \SpecialChar ~
20265 \SpecialChar ~
20266 \SpecialChar ~
20267 \SpecialChar ~
20268 \SpecialChar ~
20269 \SpecialChar ~
20270 \SpecialChar ~
20271 \SpecialChar ~
20272 \SpecialChar ~
20273 \SpecialChar ~
20274 \SpecialChar ~
20275 \SpecialChar ~
20276 \SpecialChar ~
20277 \SpecialChar ~
20278 \SpecialChar ~
20279 \SpecialChar ~
20280 \SpecialChar ~
20281 \SpecialChar ~
20282 \SpecialChar ~
20283 \SpecialChar ~
20284 \SpecialChar ~
20285 \SpecialChar ~
20286 \SpecialChar ~
20287 \SpecialChar ~
20288 \SpecialChar ~
20289  61 ;\SpecialChar ~
20290  hob.c 7
20291 \newline
20292 000A E5*01\SpecialChar ~
20293 \SpecialChar ~
20294 \SpecialChar ~
20295 \SpecialChar ~
20296 \SpecialChar ~
20297 \SpecialChar ~
20298 \SpecialChar ~
20299 \SpecialChar ~
20300 \SpecialChar ~
20301 \SpecialChar ~
20302 \SpecialChar ~
20303 \SpecialChar ~
20304 \SpecialChar ~
20305 \SpecialChar ~
20306 \SpecialChar ~
20307  62\SpecialChar ~
20308 \SpecialChar ~
20309 \SpecialChar ~
20310 \SpecialChar ~
20311 \SpecialChar ~
20312 \SpecialChar ~
20313 \SpecialChar ~
20314 \SpecialChar ~
20315  mov\SpecialChar ~
20316 \SpecialChar ~
20317  a,(_gint + 1)
20318 \newline
20319 000C 23\SpecialChar ~
20320 \SpecialChar ~
20321 \SpecialChar ~
20322 \SpecialChar ~
20323 \SpecialChar ~
20324 \SpecialChar ~
20325 \SpecialChar ~
20326 \SpecialChar ~
20327 \SpecialChar ~
20328 \SpecialChar ~
20329 \SpecialChar ~
20330 \SpecialChar ~
20331 \SpecialChar ~
20332 \SpecialChar ~
20333 \SpecialChar ~
20334 \SpecialChar ~
20335 \SpecialChar ~
20336 \SpecialChar ~
20337  63\SpecialChar ~
20338 \SpecialChar ~
20339 \SpecialChar ~
20340 \SpecialChar ~
20341 \SpecialChar ~
20342 \SpecialChar ~
20343 \SpecialChar ~
20344 \SpecialChar ~
20345  rl\SpecialChar ~
20346 \SpecialChar ~
20347 \SpecialChar ~
20348  a
20349 \newline
20350 000D 54 01\SpecialChar ~
20351 \SpecialChar ~
20352 \SpecialChar ~
20353 \SpecialChar ~
20354 \SpecialChar ~
20355 \SpecialChar ~
20356 \SpecialChar ~
20357 \SpecialChar ~
20358 \SpecialChar ~
20359 \SpecialChar ~
20360 \SpecialChar ~
20361 \SpecialChar ~
20362 \SpecialChar ~
20363 \SpecialChar ~
20364 \SpecialChar ~
20365  64\SpecialChar ~
20366 \SpecialChar ~
20367 \SpecialChar ~
20368 \SpecialChar ~
20369 \SpecialChar ~
20370 \SpecialChar ~
20371 \SpecialChar ~
20372 \SpecialChar ~
20373  anl\SpecialChar ~
20374 \SpecialChar ~
20375  a,#0x01
20376 \newline
20377 000F F5*02\SpecialChar ~
20378 \SpecialChar ~
20379 \SpecialChar ~
20380 \SpecialChar ~
20381 \SpecialChar ~
20382 \SpecialChar ~
20383 \SpecialChar ~
20384 \SpecialChar ~
20385 \SpecialChar ~
20386 \SpecialChar ~
20387 \SpecialChar ~
20388 \SpecialChar ~
20389 \SpecialChar ~
20390 \SpecialChar ~
20391 \SpecialChar ~
20392  65\SpecialChar ~
20393 \SpecialChar ~
20394 \SpecialChar ~
20395 \SpecialChar ~
20396 \SpecialChar ~
20397 \SpecialChar ~
20398 \SpecialChar ~
20399 \SpecialChar ~
20400  mov\SpecialChar ~
20401 \SpecialChar ~
20402  _foo_hob_1_1,a
20403 \layout Standard
20404
20405 Variations of this case however will
20406 \emph on
20407 not
20408 \emph default
20409  be recognized.
20410  It is a standard C expression, so I heartily recommend this be the only
20411  way to get the highest order bit, (it is portable).
20412  Of course it will be recognized even if it is embedded in other expressions,
20413  e.g.:
20414 \layout Verse
20415
20416
20417 \family typewriter
20418 xyz = gint + ((gint >> 15) & 1);
20419 \layout Standard
20420
20421 will still be recognized.
20422 \layout Subsection
20423
20424 Peephole Optimizer
20425 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
20426
20427 \end_inset
20428
20429
20430 \begin_inset LatexCommand \index{Peephole optimizer}
20431
20432 \end_inset
20433
20434
20435 \layout Standard
20436
20437 The compiler uses a rule based, pattern matching and re-writing mechanism
20438  for peep-hole optimization.
20439  It is inspired by
20440 \emph on
20441 copt
20442 \emph default
20443  a peep-hole optimizer by Christopher W.
20444  Fraser (cwfraser@microsoft.com).
20445  A default set of rules are compiled into the compiler, additional rules
20446  may be added with the
20447 \emph on
20448 -
20449 \begin_inset ERT
20450 status Collapsed
20451
20452 \layout Standard
20453
20454 \backslash
20455 /
20456 \end_inset
20457
20458 -peep-file
20459 \begin_inset LatexCommand \index{-\/-peep-file}
20460
20461 \end_inset
20462
20463  <filename>
20464 \emph default
20465  option.
20466  The rule language is best illustrated with examples.
20467 \layout Verse
20468
20469
20470 \family typewriter
20471 replace {
20472 \newline
20473 \SpecialChar ~
20474 \SpecialChar ~
20475 mov %1,a
20476 \newline
20477 \SpecialChar ~
20478 \SpecialChar ~
20479 mov a,%1
20480 \newline
20481 } by {
20482 \newline
20483 \SpecialChar ~
20484 \SpecialChar ~
20485 mov %1,a
20486 \newline
20487 }
20488 \layout Standard
20489
20490 The above rule will change the following assembly
20491 \begin_inset LatexCommand \index{Assembler routines}
20492
20493 \end_inset
20494
20495  sequence:
20496 \layout Verse
20497
20498
20499 \family typewriter
20500 mov r1,a
20501 \newline
20502 mov a,r1
20503 \layout Standard
20504
20505 to
20506 \layout Verse
20507
20508
20509 \family typewriter
20510 mov r1,a
20511 \layout Standard
20512
20513 Note: All occurrences of a
20514 \emph on
20515 %n
20516 \emph default
20517  (pattern variable) must denote the same string.
20518  With the above rule, the assembly sequence:
20519 \layout Verse
20520
20521
20522 \family typewriter
20523 mov r1,a
20524 \newline
20525 mov a,r2
20526 \layout Standard
20527
20528 will remain unmodified.
20529 \newline
20530
20531 \newline
20532 Other special case optimizations may be added by the user (via
20533 \emph on
20534 -
20535 \begin_inset ERT
20536 status Collapsed
20537
20538 \layout Standard
20539
20540 \backslash
20541 /
20542 \end_inset
20543
20544 -peep-file option
20545 \emph default
20546 ).
20547  E.g.
20548  some variants of the 8051 MCU
20549 \begin_inset LatexCommand \index{MCS51 variants}
20550
20551 \end_inset
20552
20553  allow only
20554 \family typewriter
20555 ajmp
20556 \family default
20557  and
20558 \family typewriter
20559 acall
20560 \family default
20561 .
20562  The following two rules will change all
20563 \family typewriter
20564 ljmp
20565 \family default
20566  and
20567 \family typewriter
20568 lcall
20569 \family default
20570  to
20571 \family typewriter
20572 ajmp
20573 \family default
20574  and
20575 \family typewriter
20576 acall
20577 \layout Verse
20578
20579
20580 \family typewriter
20581 replace { lcall %1 } by { acall %1 }
20582 \newline
20583 replace { ljmp %1 } by { ajmp %1 }
20584 \layout Standard
20585
20586 The
20587 \emph on
20588 inline-assembler code
20589 \emph default
20590  is also passed through the peep hole optimizer, thus the peephole optimizer
20591  can also be used as an assembly level macro expander.
20592  The rules themselves are MCU dependent whereas the rule language infra-structur
20593 e is MCU independent.
20594  Peephole optimization rules for other MCU can be easily programmed using
20595  the rule language.
20596 \newline
20597
20598 \newline
20599 The syntax for a rule is as follows:
20600 \layout Verse
20601
20602
20603 \family typewriter
20604 rule := replace [ restart ] '{' <assembly sequence> '
20605 \backslash
20606 n'
20607 \newline
20608 \SpecialChar ~
20609  \SpecialChar ~
20610  \SpecialChar ~
20611  \SpecialChar ~
20612  \SpecialChar ~
20613  \SpecialChar ~
20614  \SpecialChar ~
20615  \SpecialChar ~
20616  \SpecialChar ~
20617  \SpecialChar ~
20618  \SpecialChar ~
20619  \SpecialChar ~
20620  \SpecialChar ~
20621  \SpecialChar ~
20622  '}' by '{' '
20623 \backslash
20624 n'
20625 \newline
20626 \SpecialChar ~
20627  \SpecialChar ~
20628  \SpecialChar ~
20629  \SpecialChar ~
20630  \SpecialChar ~
20631  \SpecialChar ~
20632  \SpecialChar ~
20633  \SpecialChar ~
20634  \SpecialChar ~
20635  \SpecialChar ~
20636  \SpecialChar ~
20637  \SpecialChar ~
20638  \SpecialChar ~
20639  \SpecialChar ~
20640  \SpecialChar ~
20641  \SpecialChar ~
20642  <assembly sequence> '
20643 \backslash
20644 n'
20645 \newline
20646 \SpecialChar ~
20647  \SpecialChar ~
20648  \SpecialChar ~
20649  \SpecialChar ~
20650  \SpecialChar ~
20651  \SpecialChar ~
20652  \SpecialChar ~
20653  \SpecialChar ~
20654  \SpecialChar ~
20655  \SpecialChar ~
20656  \SpecialChar ~
20657  \SpecialChar ~
20658  \SpecialChar ~
20659  \SpecialChar ~
20660  '}' [if <functionName> ] '
20661 \backslash
20662 n'
20663 \layout Standard
20664
20665 <assembly sequence> := assembly instruction (each instruction including
20666  labels must be on a separate line).
20667 \newline
20668
20669 \newline
20670 The optimizer will apply to the rules one by one from the top in the sequence
20671  of their appearance, it will terminate when all rules are exhausted.
20672  If the 'restart' option is specified, then the optimizer will start matching
20673  the rules again from the top, this option for a rule is expensive (performance)
20674 , it is intended to be used in situations where a transformation will trigger
20675  the same rule again.
20676  An example of this (not a good one, it has side effects) is the following
20677  rule:
20678 \layout Verse
20679
20680
20681 \family typewriter
20682 replace restart {
20683 \newline
20684 \SpecialChar ~
20685 \SpecialChar ~
20686 pop %1
20687 \newline
20688 \SpecialChar ~
20689 \SpecialChar ~
20690 push %1 } by {
20691 \newline
20692 \SpecialChar ~
20693 \SpecialChar ~
20694 ; nop
20695 \newline
20696 }
20697 \layout Standard
20698
20699 Note that the replace pattern cannot be a blank, but can be a comment line.
20700  Without the 'restart' option only the innermost 'pop' 'push' pair would
20701  be eliminated, i.e.:
20702 \layout Verse
20703
20704
20705 \family typewriter
20706 pop ar1
20707 \newline
20708 pop ar2
20709 \newline
20710 push ar2
20711 \newline
20712 push ar1
20713 \layout Standard
20714
20715 would result in:
20716 \layout Verse
20717
20718
20719 \family typewriter
20720 pop ar1
20721 \newline
20722 ; nop
20723 \newline
20724 push ar1
20725 \layout Standard
20726
20727
20728 \emph on
20729 with
20730 \emph default
20731  the restart option the rule will be applied again to the resulting code
20732  and then all the pop-push pairs will be eliminated to yield:
20733 \layout Verse
20734
20735
20736 \family typewriter
20737 ; nop
20738 \newline
20739 ; nop
20740 \layout Standard
20741
20742 A conditional function can be attached to a rule.
20743  Attaching rules are somewhat more involved, let me illustrate this with
20744  an example.
20745 \layout Verse
20746
20747
20748 \family typewriter
20749 replace {
20750 \newline
20751 \SpecialChar ~
20752  \SpecialChar ~
20753  \SpecialChar ~
20754 ljmp %5
20755 \newline
20756 %2:
20757 \newline
20758 } by {
20759 \newline
20760 \SpecialChar ~
20761  \SpecialChar ~
20762  \SpecialChar ~
20763 sjmp %5
20764 \newline
20765 %2:
20766 \newline
20767 } if labelInRange
20768 \layout Standard
20769
20770 The optimizer does a look-up of a function name table defined in function
20771
20772 \emph on
20773 callFuncByName
20774 \emph default
20775  in the source file SDCCpeeph.c, with the name
20776 \emph on
20777 labelInRange
20778 \emph default
20779 .
20780  If it finds a corresponding entry the function is called.
20781  Note there can be no parameters specified for these functions, in this
20782  case the use of
20783 \emph on
20784 %5
20785 \emph default
20786  is crucial, since the function
20787 \emph on
20788 labelInRange
20789 \emph default
20790  expects to find the label in that particular variable (the hash table containin
20791 g the variable bindings is passed as a parameter).
20792  If you want to code more such functions, take a close look at the function
20793  labelInRange and the calling mechanism in source file SDCCpeeph.c.
20794  Currently implemented are
20795 \emph on
20796 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
20797  24bitMode, portIsDS390, 24bitModeAndPortDS390
20798 \emph default
20799 and
20800 \emph on
20801  notVolatile
20802 \emph default
20803 .
20804 \layout Standard
20805
20806 I know this whole thing is a little kludgey, but maybe some day we will
20807  have some better means.
20808  If you are looking at this file, you will see the default rules that are
20809  compiled into the compiler, you can add your own rules in the default set
20810  there if you get tired of specifying the -
20811 \begin_inset ERT
20812 status Collapsed
20813
20814 \layout Standard
20815
20816 \backslash
20817 /
20818 \end_inset
20819
20820 -peep-file option.
20821 \layout Section
20822
20823 ANSI-Compliance
20824 \begin_inset LatexCommand \index{ANSI-compliance}
20825
20826 \end_inset
20827
20828
20829 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
20830
20831 \end_inset
20832
20833
20834 \layout Standard
20835
20836 Deviations from the compliance:
20837 \layout Itemize
20838
20839 functions are not always reentrant
20840 \begin_inset LatexCommand \index{reentrant}
20841
20842 \end_inset
20843
20844 .
20845 \layout Itemize
20846
20847 structures cannot be assigned values directly, cannot be passed as function
20848  parameters or assigned to each other and cannot be a return value from
20849  a function, e.g.:
20850 \begin_deeper
20851 \layout Verse
20852
20853
20854 \family typewriter
20855 struct s { ...
20856  };
20857 \newline
20858 struct s s1, s2;
20859 \newline
20860 foo()
20861 \newline
20862 {
20863 \newline
20864 \SpecialChar ~
20865 \SpecialChar ~
20866 \SpecialChar ~
20867 \SpecialChar ~
20868 ...
20869
20870 \newline
20871 \SpecialChar ~
20872 \SpecialChar ~
20873 \SpecialChar ~
20874 \SpecialChar ~
20875 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
20876 \newline
20877 \SpecialChar ~
20878 \SpecialChar ~
20879 \SpecialChar ~
20880 \SpecialChar ~
20881 ...
20882
20883 \newline
20884 }
20885 \newline
20886 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
20887  */
20888 \newline
20889 {
20890 \newline
20891 \SpecialChar ~
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895 struct s rets;
20896 \newline
20897 \SpecialChar ~
20898 \SpecialChar ~
20899 \SpecialChar ~
20900 \SpecialChar ~
20901 ...
20902
20903 \newline
20904 \SpecialChar ~
20905 \SpecialChar ~
20906 \SpecialChar ~
20907 \SpecialChar ~
20908 return rets;/* is invalid in SDCC although allowed in ANSI */
20909 \newline
20910 }
20911 \end_deeper
20912 \layout Itemize
20913
20914 'long long
20915 \begin_inset LatexCommand \index{long long (not supported)}
20916
20917 \end_inset
20918
20919 ' (64 bit integers
20920 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
20921
20922 \end_inset
20923
20924 ) not supported.
20925 \layout Itemize
20926
20927 'double
20928 \begin_inset LatexCommand \index{double (not supported)}
20929
20930 \end_inset
20931
20932 ' precision floating point
20933 \begin_inset LatexCommand \index{Floating point support}
20934
20935 \end_inset
20936
20937 not supported.
20938 \layout Itemize
20939
20940 No support for setjmp
20941 \begin_inset LatexCommand \index{setjmp (not supported)}
20942
20943 \end_inset
20944
20945  and longjmp
20946 \begin_inset LatexCommand \index{longjmp (not supported)}
20947
20948 \end_inset
20949
20950  (for now).
20951 \layout Itemize
20952
20953 Old K&R style
20954 \begin_inset LatexCommand \index{K\&R style}
20955
20956 \end_inset
20957
20958  function declarations are NOT allowed.
20959 \begin_deeper
20960 \layout Verse
20961
20962
20963 \family typewriter
20964 foo(i,j) /* this old style of function declarations */
20965 \newline
20966 int i,j; /* are valid in ANSI but not valid in SDCC */
20967 \newline
20968 {
20969 \newline
20970 \SpecialChar ~
20971 \SpecialChar ~
20972 \SpecialChar ~
20973 \SpecialChar ~
20974 ...
20975
20976 \newline
20977 }
20978 \end_deeper
20979 \layout Section
20980
20981 Cyclomatic Complexity
20982 \begin_inset LatexCommand \index{Cyclomatic complexity}
20983
20984 \end_inset
20985
20986
20987 \layout Standard
20988
20989 Cyclomatic complexity of a function is defined as the number of independent
20990  paths the program can take during execution of the function.
20991  This is an important number since it defines the number test cases you
20992  have to generate to validate the function.
20993  The accepted industry standard for complexity number is 10, if the cyclomatic
20994  complexity reported by SDCC exceeds 10 you should think about simplification
20995  of the function logic.
20996  Note that the complexity level is not related to the number of lines of
20997  code in a function.
20998  Large functions can have low complexity, and small functions can have large
20999  complexity levels.
21000
21001 \newline
21002
21003 \newline
21004 SDCC uses the following formula to compute the complexity:
21005 \newline
21006
21007 \layout Standard
21008
21009 complexity = (number of edges in control flow graph) - (number of nodes
21010  in control flow graph) + 2;
21011 \newline
21012
21013 \newline
21014 Having said that the industry standard is 10, you should be aware that in
21015  some cases it be may unavoidable to have a complexity level of less than
21016  10.
21017  For example if you have switch statement with more than 10 case labels,
21018  each case label adds one to the complexity level.
21019  The complexity level is by no means an absolute measure of the algorithmic
21020  complexity of the function, it does however provide a good starting point
21021  for which functions you might look at for further optimization.
21022 \layout Section
21023
21024 Retargetting for other Processors
21025 \layout Standard
21026
21027 The issues for retargetting the compiler are far too numerous to be covered
21028  by this document.
21029  What follows is a brief description of each of the seven phases of the
21030  compiler and its MCU dependency.
21031 \layout Itemize
21032
21033 Parsing the source and building the annotated parse tree.
21034  This phase is largely MCU independent (except for the language extensions).
21035  Syntax & semantic checks are also done in this phase, along with some initial
21036  optimizations like back patching labels and the pattern matching optimizations
21037  like bit-rotation etc.
21038 \layout Itemize
21039
21040 The second phase involves generating an intermediate code which can be easy
21041  manipulated during the later phases.
21042  This phase is entirely MCU independent.
21043  The intermediate code generation assumes the target machine has unlimited
21044  number of registers, and designates them with the name iTemp.
21045  The compiler can be made to dump a human readable form of the code generated
21046  by using the -
21047 \begin_inset ERT
21048 status Collapsed
21049
21050 \layout Standard
21051
21052 \backslash
21053 /
21054 \end_inset
21055
21056 -dumpraw option.
21057 \layout Itemize
21058
21059 This phase does the bulk of the standard optimizations and is also MCU independe
21060 nt.
21061  This phase can be broken down into several sub-phases:
21062 \newline
21063
21064 \newline
21065 Break down intermediate code (iCode) into basic blocks.
21066 \newline
21067 Do control flow & data flow analysis on the basic blocks.
21068 \newline
21069 Do local common subexpression elimination, then global subexpression elimination
21070 \newline
21071 Dead code elimination
21072 \newline
21073 Loop optimizations
21074 \newline
21075 If loop optimizations caused any changes then do 'global subexpression eliminati
21076 on' and 'dead code elimination' again.
21077 \layout Itemize
21078
21079 This phase determines the live-ranges; by live range I mean those iTemp
21080  variables defined by the compiler that still survive after all the optimization
21081 s.
21082  Live range analysis
21083 \begin_inset LatexCommand \index{Live range analysis}
21084
21085 \end_inset
21086
21087  is essential for register allocation, since these computation determines
21088  which of these iTemps will be assigned to registers, and for how long.
21089 \layout Itemize
21090
21091 Phase five is register allocation.
21092  There are two parts to this process.
21093 \newline
21094
21095 \newline
21096 The first part I call 'register packing' (for lack of a better term).
21097  In this case several MCU specific expression folding is done to reduce
21098  register pressure.
21099 \newline
21100
21101 \newline
21102 The second part is more MCU independent and deals with allocating registers
21103  to the remaining live ranges.
21104  A lot of MCU specific code does creep into this phase because of the limited
21105  number of index registers available in the 8051.
21106 \layout Itemize
21107
21108 The Code generation phase is (unhappily), entirely MCU dependent and very
21109  little (if any at all) of this code can be reused for other MCU.
21110  However the scheme for allocating a homogenized assembler operand for each
21111  iCode operand may be reused.
21112 \layout Itemize
21113
21114 As mentioned in the optimization section the peep-hole optimizer is rule
21115  based system, which can reprogrammed for other MCUs.
21116 \layout Chapter
21117
21118 Compiler internals
21119 \begin_inset LatexCommand \index{Compiler internals}
21120
21121 \end_inset
21122
21123
21124 \layout Section
21125
21126 The anatomy of the compiler
21127 \begin_inset LatexCommand \label{sub:The-anatomy-of}
21128
21129 \end_inset
21130
21131
21132 \layout Standard
21133
21134
21135 \shape italic
21136 This is an excerpt from an article published in Circuit Cellar Magazine
21137  in august 2000.
21138  It's a little outdated (the compiler is much more efficient now and user/develo
21139 per friendly), but pretty well exposes the guts of it all.
21140 \shape default
21141
21142 \newline
21143
21144 \newline
21145 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
21146  It is fairly easy to retarget for other 8-bit MCU.
21147  Here we take a look at some of the internals of the compiler.
21148
21149 \layout Paragraph*
21150
21151 Parsing
21152 \begin_inset LatexCommand \index{Parsing}
21153
21154 \end_inset
21155
21156
21157 \layout Standard
21158
21159 Parsing the input source file and creating an AST (Annotated Syntax Tree
21160 \begin_inset LatexCommand \index{Annotated syntax tree}
21161
21162 \end_inset
21163
21164 ).
21165  This phase also involves propagating types (annotating each node of the
21166  parse tree with type information) and semantic analysis.
21167  There are some MCU specific parsing rules.
21168  For example the storage classes, the extended storage classes are MCU specific
21169  while there may be a xdata storage class for 8051 there is no such storage
21170  class for z80 or Atmel AVR.
21171  SDCC allows MCU specific storage class extensions, i.e.
21172  xdata will be treated as a storage class specifier when parsing 8051 C
21173  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
21174  C code.
21175 \layout Paragraph*
21176
21177 Generating iCode
21178 \begin_inset LatexCommand \index{iCode}
21179
21180 \end_inset
21181
21182
21183 \layout Standard
21184
21185 Intermediate code generation.
21186  In this phase the AST is broken down into three-operand form (iCode).
21187  These three operand forms are represented as doubly linked lists.
21188  ICode is the term given to the intermediate form generated by the compiler.
21189  ICode example section shows some examples of iCode generated for some simple
21190  C source functions.
21191 \layout Paragraph*
21192
21193 Optimizations
21194 \begin_inset LatexCommand \index{Optimizations}
21195
21196 \end_inset
21197
21198 .
21199 \layout Standard
21200
21201 Bulk of the target independent optimizations is performed in this phase.
21202  The optimizations include constant propagation, common sub-expression eliminati
21203 on, loop invariant code movement, strength reduction of loop induction variables
21204  and dead-code elimination.
21205 \layout Paragraph*
21206
21207 Live range analysis
21208 \begin_inset LatexCommand \index{Live range analysis}
21209
21210 \end_inset
21211
21212
21213 \layout Standard
21214
21215 During intermediate code generation phase, the compiler assumes the target
21216  machine has infinite number of registers and generates a lot of temporary
21217  variables.
21218  The live range computation determines the lifetime of each of these compiler-ge
21219 nerated temporaries.
21220  A picture speaks a thousand words.
21221  ICode example sections show the live range annotations for each of the
21222  operand.
21223  It is important to note here, each iCode is assigned a number in the order
21224  of its execution in the function.
21225  The live ranges are computed in terms of these numbers.
21226  The from number is the number of the iCode which first defines the operand
21227  and the to number signifies the iCode which uses this operand last.
21228 \layout Paragraph*
21229
21230 Register Allocation
21231 \begin_inset LatexCommand \index{Register allocation}
21232
21233 \end_inset
21234
21235
21236 \layout Standard
21237
21238 The register allocation determines the type and number of registers needed
21239  by each operand.
21240  In most MCUs only a few registers can be used for indirect addressing.
21241  In case of 8051 for example the registers R0 & R1 can be used to indirectly
21242  address the internal ram and DPTR to indirectly address the external ram.
21243  The compiler will try to allocate the appropriate register to pointer variables
21244  if it can.
21245  ICode example section shows the operands annotated with the registers assigned
21246  to them.
21247  The compiler will try to keep operands in registers as much as possible;
21248  there are several schemes the compiler uses to do achieve this.
21249  When the compiler runs out of registers the compiler will check to see
21250  if there are any live operands which is not used or defined in the current
21251  basic block being processed, if there are any found then it will push that
21252  operand and use the registers in this block, the operand will then be popped
21253  at the end of the basic block.
21254
21255 \layout Standard
21256
21257 There are other MCU specific considerations in this phase.
21258  Some MCUs have an accumulator; very short-lived operands could be assigned
21259  to the accumulator instead of a general-purpose register.
21260 \layout Paragraph*
21261
21262 Code generation
21263 \layout Standard
21264
21265 Figure II gives a table of iCode operations supported by the compiler.
21266  The code generation involves translating these operations into corresponding
21267  assembly code for the processor.
21268  This sounds overly simple but that is the essence of code generation.
21269  Some of the iCode operations are generated on a MCU specific manner for
21270  example, the z80 port does not use registers to pass parameters so the
21271  SEND and RECV iCode operations will not be generated, and it also does
21272  not support JUMPTABLES.
21273
21274 \newline
21275
21276 \series bold
21277 \shape italic
21278 \color red
21279 <Where is Figure II ?>
21280 \layout Paragraph*
21281
21282 ICode Example
21283 \begin_inset LatexCommand \index{iCode}
21284
21285 \end_inset
21286
21287
21288 \layout Standard
21289
21290 This section shows some details of iCode.
21291  The example C code does not do anything useful; it is used as an example
21292  to illustrate the intermediate code generated by the compiler.
21293 \layout Verse
21294
21295
21296 \family typewriter
21297 1.\SpecialChar ~
21298 xdata int * p;
21299 \newline
21300 2.\SpecialChar ~
21301 int gint;
21302 \newline
21303 3.\SpecialChar ~
21304 /* This function does nothing useful.
21305  It is used
21306 \newline
21307 4.\SpecialChar ~
21308 \SpecialChar ~
21309 \SpecialChar ~
21310 \SpecialChar ~
21311 for the purpose of explaining iCode */
21312 \newline
21313 5.\SpecialChar ~
21314 short function (data int *x)
21315 \newline
21316 6.\SpecialChar ~
21317 {
21318 \newline
21319 7.\SpecialChar ~
21320 \SpecialChar ~
21321 \SpecialChar ~
21322 short i=10; \SpecialChar ~
21323 \SpecialChar ~
21324 /* dead initialization eliminated */
21325 \newline
21326 8.\SpecialChar ~
21327 \SpecialChar ~
21328 \SpecialChar ~
21329 short sum=10; /* dead initialization eliminated */
21330 \newline
21331 9.\SpecialChar ~
21332 \SpecialChar ~
21333 \SpecialChar ~
21334 short mul;
21335 \newline
21336 10.\SpecialChar ~
21337 \SpecialChar ~
21338 int j ;
21339 \newline
21340 11.\SpecialChar ~
21341 \SpecialChar ~
21342 while (*x) *x++ = *p++;
21343 \newline
21344 12.\SpecialChar ~
21345 \SpecialChar ~
21346 \SpecialChar ~
21347 \SpecialChar ~
21348 sum = 0 ;
21349 \newline
21350 13.\SpecialChar ~
21351 \SpecialChar ~
21352 mul = 0;
21353 \newline
21354 14.\SpecialChar ~
21355 \SpecialChar ~
21356 /* compiler detects i,j to be induction variables */
21357 \newline
21358 15.\SpecialChar ~
21359 \SpecialChar ~
21360 for (i = 0, j = 10 ; i < 10 ; i++, j
21361 \family default
21362 -
21363 \begin_inset ERT
21364 status Collapsed
21365
21366 \layout Standard
21367
21368 \backslash
21369 /
21370 \end_inset
21371
21372 -
21373 \family typewriter
21374 ) {
21375 \newline
21376 16.\SpecialChar ~
21377 \SpecialChar ~
21378 \SpecialChar ~
21379 \SpecialChar ~
21380 sum += i;
21381 \newline
21382 17.\SpecialChar ~
21383 \SpecialChar ~
21384 \SpecialChar ~
21385 \SpecialChar ~
21386 mul += i * 3; \SpecialChar ~
21387 \SpecialChar ~
21388 /* this multiplication remains */
21389 \newline
21390 18.\SpecialChar ~
21391 \SpecialChar ~
21392 \SpecialChar ~
21393 \SpecialChar ~
21394 gint += j * 3;\SpecialChar ~
21395 \SpecialChar ~
21396 /* this multiplication changed to addition */
21397 \newline
21398 19.\SpecialChar ~
21399 \SpecialChar ~
21400 }
21401 \newline
21402 20.\SpecialChar ~
21403 \SpecialChar ~
21404 return sum+mul;
21405 \newline
21406 21.\SpecialChar ~
21407 }
21408 \layout Standard
21409
21410 In addition to the operands each iCode contains information about the filename
21411  and line it corresponds to in the source file.
21412  The first field in the listing should be interpreted as follows:
21413 \newline
21414
21415 \shape italic
21416 \size footnotesize
21417 Filename(linenumber: iCode Execution sequence number : ICode hash table
21418  key : loop depth of the iCode).
21419 \shape default
21420 \size default
21421
21422 \newline
21423 Then follows the human readable form of the ICode operation.
21424  Each operand of this triplet form can be of three basic types a) compiler
21425  generated temporary b) user defined variable c) a constant value.
21426  Note that local variables and parameters are replaced by compiler generated
21427  temporaries.
21428  Live ranges
21429 \begin_inset LatexCommand \index{Live range analysis}
21430
21431 \end_inset
21432
21433  are computed only for temporaries (i.e.
21434  live ranges are not computed for global variables).
21435  Registers
21436 \begin_inset LatexCommand \index{Register allocation}
21437
21438 \end_inset
21439
21440  are allocated for temporaries only.
21441  Operands are formatted in the following manner:
21442 \newline
21443
21444 \shape italic
21445 \size footnotesize
21446 Operand Name [lr live-from : live-to ] { type information } [ registers
21447  allocated ].
21448 \shape default
21449 \size default
21450
21451 \newline
21452 As mentioned earlier the live ranges are computed in terms of the execution
21453  sequence number of the iCodes, for example
21454 \newline
21455 the iTemp0 is live from (i.e.
21456  first defined in iCode with execution sequence number 3, and is last used
21457  in the iCode with sequence number 5).
21458  For induction variables such as iTemp21 the live range computation extends
21459  the lifetime from the start to the end of the loop.
21460 \newline
21461 The register allocator used the live range information to allocate registers,
21462  the same registers may be used for different temporaries if their live
21463  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
21464  iTemp17 since their live ranges do not overlap.
21465  In addition the allocator also takes into consideration the type and usage
21466  of a temporary, for example itemp6 is a pointer to near space and is used
21467  as to fetch data from (i.e.
21468  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
21469  Some short lived temporaries are allocated to special registers which have
21470  meaning to the code generator e.g.
21471  iTemp13 is allocated to a pseudo register CC which tells the back end that
21472  the temporary is used only for a conditional jump the code generation makes
21473  use of this information to optimize a compare and jump ICode.
21474 \newline
21475 There are several loop optimizations
21476 \begin_inset LatexCommand \index{Loop optimization}
21477
21478 \end_inset
21479
21480  performed by the compiler.
21481  It can detect induction variables iTemp21(i) and iTemp23(j).
21482  Also note the compiler does selective strength reduction
21483 \begin_inset LatexCommand \index{Strength reduction}
21484
21485 \end_inset
21486
21487 , i.e.
21488  the multiplication of an induction variable in line 18 (gint = j * 3) is
21489  changed to addition, a new temporary iTemp17 is allocated and assigned
21490  a initial value, a constant 3 is then added for each iteration of the loop.
21491  The compiler does not change the multiplication
21492 \begin_inset LatexCommand \index{Multiplication}
21493
21494 \end_inset
21495
21496  in line 17 however since the processor does support an 8 * 8 bit multiplication.
21497 \newline
21498 Note the dead code elimination
21499 \begin_inset LatexCommand \index{Dead-code elimination}
21500
21501 \end_inset
21502
21503  optimization eliminated the dead assignments in line 7 & 8 to I and sum
21504  respectively.
21505 \newline
21506
21507 \layout Standard
21508
21509
21510 \size footnotesize
21511 Sample.c (5:1:0:0) _entry($9) :
21512 \layout Standard
21513
21514
21515 \size footnotesize
21516 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
21517 \layout Standard
21518
21519
21520 \size footnotesize
21521 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
21522 \layout Standard
21523
21524
21525 \size footnotesize
21526 Sample.c(11:4:53:0) preHeaderLbl0($11) :
21527 \layout Standard
21528
21529
21530 \size footnotesize
21531 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
21532  * int}[r2]
21533 \layout Standard
21534
21535
21536 \size footnotesize
21537 Sample.c(11:6:5:1) _whilecontinue_0($1) :
21538 \layout Standard
21539
21540
21541 \size footnotesize
21542 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
21543  int}[r0]]
21544 \layout Standard
21545
21546
21547 \size footnotesize
21548 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
21549 \layout Standard
21550
21551
21552 \size footnotesize
21553 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
21554  * int}
21555 \layout Standard
21556
21557
21558 \size footnotesize
21559 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
21560  {short}
21561 \layout Standard
21562
21563
21564 \size footnotesize
21565 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
21566  * int}[DPTR]]
21567 \layout Standard
21568
21569
21570 \size footnotesize
21571 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
21572 }[r2 r3]
21573 \layout Standard
21574
21575
21576 \size footnotesize
21577 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
21578  * int}[r0] + 0x2 {short}
21579 \layout Standard
21580
21581
21582 \size footnotesize
21583 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
21584 \layout Standard
21585
21586
21587 \size footnotesize
21588 Sample.c(11:17:21:0)_whilebreak_0($3) :
21589 \layout Standard
21590
21591
21592 \size footnotesize
21593 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
21594 \layout Standard
21595
21596
21597 \size footnotesize
21598 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
21599 \layout Standard
21600
21601
21602 \size footnotesize
21603 Sample.c(15:20:54:0)preHeaderLbl1($13) :
21604 \layout Standard
21605
21606
21607 \size footnotesize
21608 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
21609 \layout Standard
21610
21611
21612 \size footnotesize
21613 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
21614 \layout Standard
21615
21616
21617 \size footnotesize
21618 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
21619 \layout Standard
21620
21621
21622 \size footnotesize
21623 Sample.c(15:24:26:1)_forcond_0($4) :
21624 \layout Standard
21625
21626
21627 \size footnotesize
21628 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
21629  < 0xa {short}
21630 \layout Standard
21631
21632
21633 \size footnotesize
21634 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
21635 \layout Standard
21636
21637
21638 \size footnotesize
21639 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
21640  + ITemp21 [lr21:38]{short}[r4]
21641 \layout Standard
21642
21643
21644 \size footnotesize
21645 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
21646  * 0x3 {short}
21647 \layout Standard
21648
21649
21650 \size footnotesize
21651 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
21652  + iTemp15 [lr29:30]{short}[r1]
21653 \layout Standard
21654
21655
21656 \size footnotesize
21657 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
21658  r0]- 0x3 {short}
21659 \layout Standard
21660
21661
21662 \size footnotesize
21663 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
21664 int}[r7 r0]
21665 \layout Standard
21666
21667
21668 \size footnotesize
21669 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
21670  + 0x1 {short}
21671 \layout Standard
21672
21673
21674 \size footnotesize
21675 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
21676  r6]- 0x1 {short}
21677 \layout Standard
21678
21679
21680 \size footnotesize
21681 Sample.c(19:38:47:1) goto _forcond_0($4)
21682 \layout Standard
21683
21684
21685 \size footnotesize
21686 Sample.c(19:39:48:0)_forbreak_0($7) :
21687 \layout Standard
21688
21689
21690 \size footnotesize
21691 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
21692  + ITemp11 [lr19:40]{short}[r3]
21693 \layout Standard
21694
21695
21696 \size footnotesize
21697 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
21698 \layout Standard
21699
21700
21701 \size footnotesize
21702 Sample.c(20:42:51:0)_return($8) :
21703 \layout Standard
21704
21705
21706 \size footnotesize
21707 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
21708 \size default
21709
21710 \newline
21711
21712 \newline
21713 Finally the code generated for this function:
21714 \newline
21715
21716 \layout Standard
21717
21718
21719 \size footnotesize
21720 .area DSEG (DATA)
21721 \layout Standard
21722
21723
21724 \size footnotesize
21725 _p::
21726 \layout Standard
21727
21728
21729 \size footnotesize
21730 \SpecialChar ~
21731 \SpecialChar ~
21732 .ds 2
21733 \layout Standard
21734
21735
21736 \size footnotesize
21737 _gint::
21738 \layout Standard
21739
21740
21741 \size footnotesize
21742 \SpecialChar ~
21743 \SpecialChar ~
21744 .ds 2
21745 \layout Standard
21746
21747
21748 \size footnotesize
21749 ; sample.c 5
21750 \layout Standard
21751
21752
21753 \size footnotesize
21754 ; ----------------------------------------------
21755 \layout Standard
21756
21757
21758 \size footnotesize
21759 ; function function
21760 \layout Standard
21761
21762
21763 \size footnotesize
21764 ; ----------------------------------------------
21765 \layout Standard
21766
21767
21768 \size footnotesize
21769 _function:
21770 \layout Standard
21771
21772
21773 \size footnotesize
21774 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
21775 \layout Standard
21776
21777
21778 \size footnotesize
21779 \SpecialChar ~
21780 \SpecialChar ~
21781 mov r2,dpl
21782 \layout Standard
21783
21784
21785 \size footnotesize
21786 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
21787 \layout Standard
21788
21789
21790 \size footnotesize
21791 \SpecialChar ~
21792 \SpecialChar ~
21793 mov ar0,r2
21794 \layout Standard
21795
21796
21797 \size footnotesize
21798 ;_whilecontinue_0($1) :
21799 \layout Standard
21800
21801
21802 \size footnotesize
21803 00101$:
21804 \layout Standard
21805
21806
21807 \size footnotesize
21808 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
21809 \layout Standard
21810
21811
21812 \size footnotesize
21813 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
21814 \layout Standard
21815
21816
21817 \size footnotesize
21818 \SpecialChar ~
21819 \SpecialChar ~
21820 mov ar2,@r0
21821 \layout Standard
21822
21823
21824 \size footnotesize
21825 \SpecialChar ~
21826 \SpecialChar ~
21827 inc r0
21828 \layout Standard
21829
21830
21831 \size footnotesize
21832 \SpecialChar ~
21833 \SpecialChar ~
21834 mov ar3,@r0
21835 \layout Standard
21836
21837
21838 \size footnotesize
21839 \SpecialChar ~
21840 \SpecialChar ~
21841 dec r0
21842 \layout Standard
21843
21844
21845 \size footnotesize
21846 \SpecialChar ~
21847 \SpecialChar ~
21848 mov a,r2
21849 \layout Standard
21850
21851
21852 \size footnotesize
21853 \SpecialChar ~
21854 \SpecialChar ~
21855 orl a,r3
21856 \layout Standard
21857
21858
21859 \size footnotesize
21860 \SpecialChar ~
21861 \SpecialChar ~
21862 jz 00103$
21863 \layout Standard
21864
21865
21866 \size footnotesize
21867 00114$:
21868 \layout Standard
21869
21870
21871 \size footnotesize
21872 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
21873 \layout Standard
21874
21875
21876 \size footnotesize
21877 \SpecialChar ~
21878 \SpecialChar ~
21879 mov dpl,_p
21880 \layout Standard
21881
21882
21883 \size footnotesize
21884 \SpecialChar ~
21885 \SpecialChar ~
21886 mov dph,(_p + 1)
21887 \layout Standard
21888
21889
21890 \size footnotesize
21891 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
21892 \layout Standard
21893
21894
21895 \size footnotesize
21896 \SpecialChar ~
21897 \SpecialChar ~
21898 mov a,#0x02
21899 \layout Standard
21900
21901
21902 \size footnotesize
21903 \SpecialChar ~
21904 \SpecialChar ~
21905 add a,_p
21906 \layout Standard
21907
21908
21909 \size footnotesize
21910 \SpecialChar ~
21911 \SpecialChar ~
21912 mov _p,a
21913 \layout Standard
21914
21915
21916 \size footnotesize
21917 \SpecialChar ~
21918 \SpecialChar ~
21919 clr a
21920 \layout Standard
21921
21922
21923 \size footnotesize
21924 \SpecialChar ~
21925 \SpecialChar ~
21926 addc a,(_p + 1)
21927 \layout Standard
21928
21929
21930 \size footnotesize
21931 \SpecialChar ~
21932 \SpecialChar ~
21933 mov (_p + 1),a
21934 \layout Standard
21935
21936
21937 \size footnotesize
21938 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
21939 \layout Standard
21940
21941
21942 \size footnotesize
21943 \SpecialChar ~
21944 \SpecialChar ~
21945 movx a,@dptr
21946 \layout Standard
21947
21948
21949 \size footnotesize
21950 \SpecialChar ~
21951 \SpecialChar ~
21952 mov r2,a
21953 \layout Standard
21954
21955
21956 \size footnotesize
21957 \SpecialChar ~
21958 \SpecialChar ~
21959 inc dptr
21960 \layout Standard
21961
21962
21963 \size footnotesize
21964 \SpecialChar ~
21965 \SpecialChar ~
21966 movx a,@dptr
21967 \layout Standard
21968
21969
21970 \size footnotesize
21971 \SpecialChar ~
21972 \SpecialChar ~
21973 mov r3,a
21974 \layout Standard
21975
21976
21977 \size footnotesize
21978 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
21979 \layout Standard
21980
21981
21982 \size footnotesize
21983 \SpecialChar ~
21984 \SpecialChar ~
21985 mov @r0,ar2
21986 \layout Standard
21987
21988
21989 \size footnotesize
21990 \SpecialChar ~
21991 \SpecialChar ~
21992 inc r0
21993 \layout Standard
21994
21995
21996 \size footnotesize
21997 \SpecialChar ~
21998 \SpecialChar ~
21999 mov @r0,ar3
22000 \layout Standard
22001
22002
22003 \size footnotesize
22004 ; iTemp6 [lr5:16]{_near * int}[r0] =
22005 \layout Standard
22006
22007
22008 \size footnotesize
22009 ; iTemp6 [lr5:16]{_near * int}[r0] +
22010 \layout Standard
22011
22012
22013 \size footnotesize
22014 ; 0x2 {short}
22015 \layout Standard
22016
22017
22018 \size footnotesize
22019 \SpecialChar ~
22020 \SpecialChar ~
22021 inc r0
22022 \layout Standard
22023
22024
22025 \size footnotesize
22026 ; goto _whilecontinue_0($1)
22027 \layout Standard
22028
22029
22030 \size footnotesize
22031 \SpecialChar ~
22032 \SpecialChar ~
22033 sjmp 00101$
22034 \layout Standard
22035
22036
22037 \size footnotesize
22038 ; _whilebreak_0($3) :
22039 \layout Standard
22040
22041
22042 \size footnotesize
22043 00103$:
22044 \layout Standard
22045
22046
22047 \size footnotesize
22048 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
22049 \layout Standard
22050
22051
22052 \size footnotesize
22053 \SpecialChar ~
22054 \SpecialChar ~
22055 mov r2,#0x00
22056 \layout Standard
22057
22058
22059 \size footnotesize
22060 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
22061 \layout Standard
22062
22063
22064 \size footnotesize
22065 \SpecialChar ~
22066 \SpecialChar ~
22067 mov r3,#0x00
22068 \layout Standard
22069
22070
22071 \size footnotesize
22072 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
22073 \layout Standard
22074
22075
22076 \size footnotesize
22077 \SpecialChar ~
22078 \SpecialChar ~
22079 mov r4,#0x00
22080 \layout Standard
22081
22082
22083 \size footnotesize
22084 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
22085 \layout Standard
22086
22087
22088 \size footnotesize
22089 \SpecialChar ~
22090 \SpecialChar ~
22091 mov r5,#0x0A
22092 \layout Standard
22093
22094
22095 \size footnotesize
22096 \SpecialChar ~
22097 \SpecialChar ~
22098 mov r6,#0x00
22099 \layout Standard
22100
22101
22102 \size footnotesize
22103 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
22104 \layout Standard
22105
22106
22107 \size footnotesize
22108 \SpecialChar ~
22109 \SpecialChar ~
22110 mov r7,#0x1E
22111 \layout Standard
22112
22113
22114 \size footnotesize
22115 \SpecialChar ~
22116 \SpecialChar ~
22117 mov r0,#0x00
22118 \layout Standard
22119
22120
22121 \size footnotesize
22122 ; _forcond_0($4) :
22123 \layout Standard
22124
22125
22126 \size footnotesize
22127 00104$:
22128 \layout Standard
22129
22130
22131 \size footnotesize
22132 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
22133 \layout Standard
22134
22135
22136 \size footnotesize
22137 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
22138 \layout Standard
22139
22140
22141 \size footnotesize
22142 \SpecialChar ~
22143 \SpecialChar ~
22144 clr c
22145 \layout Standard
22146
22147
22148 \size footnotesize
22149 \SpecialChar ~
22150 \SpecialChar ~
22151 mov a,r4
22152 \layout Standard
22153
22154
22155 \size footnotesize
22156 \SpecialChar ~
22157 \SpecialChar ~
22158 xrl a,#0x80
22159 \layout Standard
22160
22161
22162 \size footnotesize
22163 \SpecialChar ~
22164 \SpecialChar ~
22165 subb a,#0x8a
22166 \layout Standard
22167
22168
22169 \size footnotesize
22170 \SpecialChar ~
22171 \SpecialChar ~
22172 jnc 00107$
22173 \layout Standard
22174
22175
22176 \size footnotesize
22177 00115$:
22178 \layout Standard
22179
22180
22181 \size footnotesize
22182 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
22183 \layout Standard
22184
22185
22186 \size footnotesize
22187 ; iTemp21 [lr21:38]{short}[r4]
22188 \layout Standard
22189
22190
22191 \size footnotesize
22192 \SpecialChar ~
22193 \SpecialChar ~
22194 mov a,r4
22195 \layout Standard
22196
22197
22198 \size footnotesize
22199 \SpecialChar ~
22200 \SpecialChar ~
22201 add a,r2
22202 \layout Standard
22203
22204
22205 \size footnotesize
22206 \SpecialChar ~
22207 \SpecialChar ~
22208 mov r2,a
22209 \layout Standard
22210
22211
22212 \size footnotesize
22213 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
22214 \layout Standard
22215
22216
22217 \size footnotesize
22218 \SpecialChar ~
22219 \SpecialChar ~
22220 mov b,#0x03
22221 \layout Standard
22222
22223
22224 \size footnotesize
22225 \SpecialChar ~
22226 \SpecialChar ~
22227 mov a,r4
22228 \layout Standard
22229
22230
22231 \size footnotesize
22232 \SpecialChar ~
22233 \SpecialChar ~
22234 mul ab
22235 \layout Standard
22236
22237
22238 \size footnotesize
22239 \SpecialChar ~
22240 \SpecialChar ~
22241 mov r1,a
22242 \layout Standard
22243
22244
22245 \size footnotesize
22246 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
22247 \layout Standard
22248
22249
22250 \size footnotesize
22251 ; iTemp15 [lr29:30]{short}[r1]
22252 \layout Standard
22253
22254
22255 \size footnotesize
22256 \SpecialChar ~
22257 \SpecialChar ~
22258 add a,r3
22259 \layout Standard
22260
22261
22262 \size footnotesize
22263 \SpecialChar ~
22264 \SpecialChar ~
22265 mov r3,a
22266 \layout Standard
22267
22268
22269 \size footnotesize
22270 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
22271 \layout Standard
22272
22273
22274 \size footnotesize
22275 \SpecialChar ~
22276 \SpecialChar ~
22277 mov a,r7
22278 \layout Standard
22279
22280
22281 \size footnotesize
22282 \SpecialChar ~
22283 \SpecialChar ~
22284 add a,#0xfd
22285 \layout Standard
22286
22287
22288 \size footnotesize
22289 \SpecialChar ~
22290 \SpecialChar ~
22291 mov r7,a
22292 \layout Standard
22293
22294
22295 \size footnotesize
22296 \SpecialChar ~
22297 \SpecialChar ~
22298 mov a,r0
22299 \layout Standard
22300
22301
22302 \size footnotesize
22303 \SpecialChar ~
22304 \SpecialChar ~
22305 addc a,#0xff
22306 \layout Standard
22307
22308
22309 \size footnotesize
22310 \SpecialChar ~
22311 \SpecialChar ~
22312 mov r0,a
22313 \layout Standard
22314
22315
22316 \size footnotesize
22317 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
22318 \layout Standard
22319
22320
22321 \size footnotesize
22322 \SpecialChar ~
22323 \SpecialChar ~
22324 mov a,r7
22325 \layout Standard
22326
22327
22328 \size footnotesize
22329 \SpecialChar ~
22330 \SpecialChar ~
22331 add a,_gint
22332 \layout Standard
22333
22334
22335 \size footnotesize
22336 \SpecialChar ~
22337 \SpecialChar ~
22338 mov _gint,a
22339 \layout Standard
22340
22341
22342 \size footnotesize
22343 \SpecialChar ~
22344 \SpecialChar ~
22345 mov a,r0
22346 \layout Standard
22347
22348
22349 \size footnotesize
22350 \SpecialChar ~
22351 \SpecialChar ~
22352 addc a,(_gint + 1)
22353 \layout Standard
22354
22355
22356 \size footnotesize
22357 \SpecialChar ~
22358 \SpecialChar ~
22359 mov (_gint + 1),a
22360 \layout Standard
22361
22362
22363 \size footnotesize
22364 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
22365 \layout Standard
22366
22367
22368 \size footnotesize
22369 \SpecialChar ~
22370 \SpecialChar ~
22371 inc r4
22372 \layout Standard
22373
22374
22375 \size footnotesize
22376 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
22377 \layout Standard
22378
22379
22380 \size footnotesize
22381 \SpecialChar ~
22382 \SpecialChar ~
22383 dec r5
22384 \layout Standard
22385
22386
22387 \size footnotesize
22388 \SpecialChar ~
22389 \SpecialChar ~
22390 cjne r5,#0xff,00104$
22391 \layout Standard
22392
22393
22394 \size footnotesize
22395 \SpecialChar ~
22396 \SpecialChar ~
22397 dec r6
22398 \layout Standard
22399
22400
22401 \size footnotesize
22402 ; goto _forcond_0($4)
22403 \layout Standard
22404
22405
22406 \size footnotesize
22407 \SpecialChar ~
22408 \SpecialChar ~
22409 sjmp 00104$
22410 \layout Standard
22411
22412
22413 \size footnotesize
22414 ; _forbreak_0($7) :
22415 \layout Standard
22416
22417
22418 \size footnotesize
22419 00107$:
22420 \layout Standard
22421
22422
22423 \size footnotesize
22424 ; ret iTemp24 [lr40:41]{short}
22425 \layout Standard
22426
22427
22428 \size footnotesize
22429 \SpecialChar ~
22430 \SpecialChar ~
22431 mov a,r3
22432 \layout Standard
22433
22434
22435 \size footnotesize
22436 \SpecialChar ~
22437 \SpecialChar ~
22438 add a,r2
22439 \layout Standard
22440
22441
22442 \size footnotesize
22443 \SpecialChar ~
22444 \SpecialChar ~
22445 mov dpl,a
22446 \layout Standard
22447
22448
22449 \size footnotesize
22450 ; _return($8) :
22451 \layout Standard
22452
22453
22454 \size footnotesize
22455 00108$:
22456 \layout Standard
22457
22458
22459 \size footnotesize
22460 \SpecialChar ~
22461 \SpecialChar ~
22462 ret
22463 \newline
22464
22465 \layout Section
22466
22467 A few words about basic block successors, predecessors and dominators
22468 \layout Standard
22469
22470 Successors are basic blocks
22471 \begin_inset LatexCommand \index{Basic blocks}
22472
22473 \end_inset
22474
22475  that might execute after this basic block.
22476 \newline
22477 Predecessors are basic blocks that might execute before reaching this basic
22478  block.
22479 \newline
22480 Dominators are basic blocks that WILL execute before reaching this basic
22481  block.
22482 \newline
22483
22484 \layout Standard
22485
22486 [basic block 1]
22487 \layout Standard
22488
22489 if (something)
22490 \layout Standard
22491
22492 \SpecialChar ~
22493 \SpecialChar ~
22494 \SpecialChar ~
22495 \SpecialChar ~
22496 [basic block 2]
22497 \layout Standard
22498
22499 else
22500 \layout Standard
22501
22502 \SpecialChar ~
22503 \SpecialChar ~
22504 \SpecialChar ~
22505 \SpecialChar ~
22506 [basic block 3]
22507 \layout Standard
22508
22509 [basic block 4]
22510 \newline
22511
22512 \layout Standard
22513
22514 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
22515 \layout Standard
22516
22517 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
22518 \layout Standard
22519
22520 c) domVect of [BB4] = BB1 ...
22521  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
22522  was executed.
22523 \layout Chapter
22524
22525 Acknowledgments
22526 \layout Standard
22527
22528
22529 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
22530
22531 \end_inset
22532
22533
22534 \newline
22535
22536 \newline
22537
22538 \emph on
22539 Thanks to all the other volunteer developers who have helped with coding,
22540  testing, web-page creation, distribution sets, etc.
22541  You know who you are :-)
22542 \emph default
22543
22544 \newline
22545
22546 \layout Standard
22547
22548 This document was initially written by Sandeep Dutta
22549 \layout Standard
22550
22551 All product names mentioned herein may be trademarks
22552 \begin_inset LatexCommand \index{Trademarks}
22553
22554 \end_inset
22555
22556  of their respective companies.
22557
22558 \layout Section*
22559
22560 Alphabetical index
22561 \layout Standard
22562
22563 To avoid confusion, the installation and building options for SDCC itself
22564  (chapter 2) are not part of the index.
22565 \layout Standard
22566
22567
22568 \begin_inset LatexCommand \printindex{}
22569
22570 \end_inset
22571
22572
22573 \the_end