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 \pdfoptionpdfminorversion=3
   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 microcontroller 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.5.6
  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 Subversion
  95 \layout Standard
  96
  97
  98 \begin_inset LatexCommand \tableofcontents{}
  99
 100 \end_inset
 101
 102
 103 \layout Chapter
 104
 105 Introduction
 106 \layout Section
 107
 108 About SDCC
 109 \layout Standard
 110
 111
 112 \series bold
 113 SDCC
 114 \series default
 115  (
 116 \emph on
 117 S
 118 \emph default
 119 mall
 120 \emph on
 121 D
 122 \emph default
 123 evice
 124 \emph on
 125 C
 126 \emph default
 127
 128 \emph on
 129 C
 130 \emph default
 131 ompiler) is an open source, retargettable, optimizing ANSI-C compiler by
 132
 133 \series bold
 134 Sandeep Dutta
 135 \series default
 136  designed for 8 bit Microprocessors.
 137  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 138  8051, 8052
 139 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
 140
 141 \end_inset
 142
 143 , etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
 144  Zilog Z80 based MCUs.
 145  It can be retargetted for other microprocessors, support for Microchip
 146  PIC, Atmel AVR is under development.
 147  The entire source code for the compiler is distributed under GPL.
 148  SDCC uses ASXXXX
 149 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
 150
 151 \end_inset
 152
 153  & ASLINK
 154 \begin_inset LatexCommand \index{aslink}
 155
 156 \end_inset
 157
 158 , an open source retargettable assembler & linker.
 159  SDCC has extensive language extensions suitable for utilizing various microcont
 160 rollers and underlying hardware effectively.
 161
 162 \newline
 163
 164 \newline
 165 In addition to the MCU specific optimizations SDCC also does a host of standard
 166  optimizations like:
 167 \layout Itemize
 168
 169 global sub expression elimination,
 170 \layout Itemize
 171
 172 loop optimizations (loop invariant, strength reduction of induction variables
 173  and loop reversing),
 174 \layout Itemize
 175
 176 constant folding & propagation,
 177 \layout Itemize
 178
 179 copy propagation,
 180 \layout Itemize
 181
 182 dead code elimination
 183 \layout Itemize
 184
 185 jump tables for
 186 \emph on
 187 switch
 188 \emph default
 189  statements.
 190 \layout Standard
 191
 192 For the back-end SDCC uses a global register allocation scheme which should
 193  be well suited for other 8 bit MCUs.
 194
 195 \newline
 196
 197 \newline
 198 The peep hole optimizer uses a rule based substitution mechanism which is
 199  MCU independent.
 200
 201 \newline
 202
 203 \newline
 204 Supported data-types are:
 205 \layout Itemize
 206
 207 char (8 bits, 1 byte),
 208 \layout Itemize
 209
 210 short and int (16 bits, 2 bytes),
 211 \layout Itemize
 212
 213 long (32 bit, 4 bytes)
 214 \layout Itemize
 215
 216 float (4 byte IEEE).
 217
 218 \layout Standard
 219
 220 The compiler also allows
 221 \emph on
 222 inline assembler code
 223 \emph default
 224  to be embedded anywhere in a function.
 225  In addition, routines developed in assembly can also be called.
 226 \newline
 227
 228 \newline
 229 SDCC also provides an option (-
 230 \begin_inset ERT
 231 status Collapsed
 232
 233 \layout Standard
 234
 235 \backslash
 236 /
 237 \end_inset
 238
 239 -cyclomatic) to report the relative complexity of a function.
 240  These functions can then be further optimized, or hand coded in assembly
 241  if needed.
 242
 243 \newline
 244
 245 \newline
 246 SDCC also comes with a companion source level debugger SDCDB, the debugger
 247  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 248  SDCDB and ucSim are currently not available on Win32 platforms.
 249
 250 \newline
 251
 252 \newline
 253 The latest version can be downloaded from
 254 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 255
 256 \end_inset
 257
 258 .
 259
 260 \series bold
 261
 262 \series default
 263 \emph on
 264 Please note: the compiler will probably always be some steps ahead of this
 265  documentation
 266 \series bold
 267 \emph default
 268
 269 \begin_inset LatexCommand \index{Status of documentation}
 270
 271 \end_inset
 272
 273
 274 \begin_inset Foot
 275 collapsed false
 276
 277 \layout Standard
 278
 279 Obviously this has pros and cons
 280 \end_inset
 281
 282 .
 283 \layout Section
 284
 285 Open Source
 286 \layout Standard
 287
 288 All packages used in this compiler system are
 289 \emph on
 290 open source
 291 \emph default
 292  and
 293 \emph on
 294 freeware
 295 \emph default
 296 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 297  etc) is distributed with the package.
 298  This documentation is maintained using a freeware word processor (LyX).
 299 \newline
 300 This program is free software; you can redistribute it and/or modify it
 301  under the terms of the GNU General Public License
 302 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 303
 304 \end_inset
 305
 306  as published by the Free Software Foundation; either version 2, or (at
 307  your option) any later version.
 308  This program is distributed in the hope that it will be useful, but WITHOUT
 309  ANY WARRANTY; without even the implied warranty
 310 \begin_inset LatexCommand \index{warranty}
 311
 312 \end_inset
 313
 314  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 315  See the GNU General Public License for more details.
 316  You should have received a copy of the GNU General Public License along
 317  with this program; if not, write to the Free Software Foundation, 59 Temple
 318  Place - Suite 330, Boston, MA 02111-1307, USA.
 319  In other words, you are welcome to use, share and improve this program.
 320  You are forbidden to forbid anyone else to use, share and improve what
 321  you give them.
 322  Help stamp out software-hoarding!
 323 \layout Section
 324
 325 Typographic conventions
 326 \begin_inset LatexCommand \index{Typographic conventions}
 327
 328 \end_inset
 329
 330
 331 \layout Standard
 332
 333 Throughout this manual, we will use the following convention.
 334  Commands you have to type in are printed in
 335 \family sans
 336 \series bold
 337 "sans serif"
 338 \series default
 339 .
 340
 341 \family default
 342  Code samples are printed in
 343 \family typewriter
 344 typewriter font.
 345
 346 \family default
 347  Interesting items and new terms are printed in
 348 \emph on
 349 italic.
 350 \layout Section
 351
 352 Compatibility with previous versions
 353 \begin_inset LatexCommand \index{Compatibility with previous versions}
 354
 355 \end_inset
 356
 357
 358 \layout Standard
 359
 360 This version has numerous bug fixes compared with the previous version.
 361  But we also introduced some incompatibilities with older versions.
 362  Not just for the fun of it, but to make the compiler more stable, efficient
 363  and ANSI compliant
 364 \begin_inset LatexCommand \index{ANSI-compliance}
 365
 366 \end_inset
 367
 368  (see section
 369 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 370
 371 \end_inset
 372
 373  for ANSI-Compliance).
 374
 375 \newline
 376
 377 \layout Itemize
 378
 379 short is now equivalent to int (16 bits), it used to be equivalent to char
 380  (8 bits) which is not ANSI compliant.
 381 \layout Itemize
 382
 383 the default directory for gcc-builds where include, library and documentation
 384  files are stored is now in /usr/local/share.
 385 \layout Itemize
 386
 387 char type parameters to vararg functions are casted to int unless explicitly
 388  casted, e.g.:
 389 \newline
 390
 391 \family typewriter
 392 \SpecialChar ~
 393 \SpecialChar ~
 394 char a=3;
 395 \newline
 396 \SpecialChar ~
 397 \SpecialChar ~
 398 printf ("%d %c
 399 \backslash
 400 n", a, (char)a);
 401 \family default
 402
 403 \newline
 404  will push a as an int and as a char resp.
 405 \layout Itemize
 406
 407 option -
 408 \begin_inset ERT
 409 status Collapsed
 410
 411 \layout Standard
 412
 413 \backslash
 414 /
 415 \end_inset
 416
 417 -regextend has been removed.
 418 \layout Itemize
 419
 420 option -
 421 \begin_inset ERT
 422 status Collapsed
 423
 424 \layout Standard
 425
 426 \backslash
 427 /
 428 \end_inset
 429
 430 -noregparms has been removed.
 431 \layout Itemize
 432
 433 option -
 434 \begin_inset ERT
 435 status Collapsed
 436
 437 \layout Standard
 438
 439 \backslash
 440 /
 441 \end_inset
 442
 443 -stack-after-data has been removed.
 444 \layout Itemize
 445
 446 bit
 447 \begin_inset LatexCommand \index{bit}
 448
 449 \end_inset
 450
 451  and sbit
 452 \begin_inset LatexCommand \index{sbit}
 453
 454 \end_inset
 455
 456
 457 \begin_inset LatexCommand \index{\_\_sbit}
 458
 459 \end_inset
 460
 461  types now consistently behave like the C99 _Bool type with respect to type
 462  conversion
 463 \begin_inset LatexCommand \index{type conversion}
 464
 465 \end_inset
 466
 467
 468 \begin_inset LatexCommand \index{type promotion}
 469
 470 \end_inset
 471
 472 .
 473  The most common incompatibility resulting from this change is related to
 474  bit toggling
 475 \begin_inset LatexCommand \index{Bit toggling}
 476
 477 \end_inset
 478
 479  idioms, e.g.:
 480 \newline
 481
 482 \family typewriter
 483 \SpecialChar ~
 484 \SpecialChar ~
 485 bit b;
 486 \newline
 487 \SpecialChar ~
 488 \SpecialChar ~
 489 b = ~b; /* equivalent to b=1 instead of toggling b */
 490 \newline
 491 \SpecialChar ~
 492 \SpecialChar ~
 493 b = !b; /* toggles b */
 494 \newline
 495
 496 \family default
 497 In previous versions, both forms would have toggled the bit.
 498 \layout Standard
 499
 500
 501 \emph on
 502 <pending: more incompatibilities?>
 503 \layout Section
 504
 505 System Requirements
 506 \layout Standard
 507
 508 What do you need before you start installation of SDCC? A computer, and
 509  a desire to compute.
 510  The preferred method of installation is to compile SDCC from source using
 511  GNU gcc and make.
 512  For Windows some pre-compiled binary distributions are available for your
 513  convenience.
 514  You should have some experience with command line tools and compiler use.
 515 \layout Section
 516
 517 Other Resources
 518 \layout Standard
 519
 520 The SDCC home page at
 521 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 522
 523 \end_inset
 524
 525  is a great place to find distribution sets.
 526  You can also find links to the user mailing lists that offer help or discuss
 527  SDCC with other SDCC users.
 528  Web links to other SDCC related sites can also be found here.
 529  This document can be found in the DOC directory of the source package as
 530  a text or HTML file.
 531  A pdf version of this document is available at
 532 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 533
 534 \end_inset
 535
 536 .
 537  Some of the other tools (simulator and assembler) included with SDCC contain
 538  their own documentation and can be found in the source distribution.
 539  If you want the latest unreleased software, the complete source package
 540  is available directly from Subversion on https://svn.sourceforge.net/svnroot/sdcc
 541 /trunk/sdcc.
 542 \layout Section
 543
 544 Wishes for the future
 545 \layout Standard
 546
 547 There are (and always will be) some things that could be done.
 548  Here are some I can think of:
 549 \newline
 550
 551 \layout Standard
 552
 553
 554 \family typewriter
 555 char KernelFunction3(char p) at 0x340;
 556 \newline
 557
 558 \layout Standard
 559
 560
 561 \family typewriter
 562 better code banking
 563 \begin_inset LatexCommand \index{code banking (limited support)}
 564
 565 \end_inset
 566
 567  support for mcs51
 568 \newline
 569
 570 \newline
 571
 572 \family default
 573 If you can think of some more, please see the section
 574 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 575
 576 \end_inset
 577
 578  about filing feature requests
 579 \begin_inset LatexCommand \index{Requesting features}
 580
 581 \end_inset
 582
 583
 584 \begin_inset LatexCommand \index{Feature request}
 585
 586 \end_inset
 587
 588 .
 589 \newline
 590
 591 \layout Chapter
 592
 593 Installing SDCC
 594 \begin_inset LatexCommand \index{Installation}
 595
 596 \end_inset
 597
 598
 599 \layout Standard
 600
 601 For most users it is sufficient to skip to either section
 602 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 603
 604 \end_inset
 605
 606  or section
 607 \begin_inset LatexCommand \ref{sub:Windows-Install}
 608
 609 \end_inset
 610
 611 .
 612  More detailled instructions follow below.
 613 \layout Section
 614
 615 Configure Options
 616 \begin_inset LatexCommand \index{Options SDCC configuration}
 617
 618 \end_inset
 619
 620
 621 \layout Standard
 622
 623 The install paths, search paths and other options are defined when running
 624  'configure'.
 625  The defaults can be overridden by:
 626 \layout List
 627 \labelwidthstring 00.00.0000
 628
 629 -
 630 \begin_inset ERT
 631 status Collapsed
 632
 633 \layout Standard
 634
 635 \backslash
 636 /
 637 \end_inset
 638
 639 -prefix see table below
 640 \layout List
 641 \labelwidthstring 00.00.0000
 642
 643 -
 644 \begin_inset ERT
 645 status Collapsed
 646
 647 \layout Standard
 648
 649 \backslash
 650 /
 651 \end_inset
 652
 653 -exec_prefix see table below
 654 \layout List
 655 \labelwidthstring 00.00.0000
 656
 657 -
 658 \begin_inset ERT
 659 status Collapsed
 660
 661 \layout Standard
 662
 663 \backslash
 664 /
 665 \end_inset
 666
 667 -bindir see table below
 668 \layout List
 669 \labelwidthstring 00.00.0000
 670
 671 -
 672 \begin_inset ERT
 673 status Collapsed
 674
 675 \layout Standard
 676
 677 \backslash
 678 /
 679 \end_inset
 680
 681 -datadir see table below
 682 \layout List
 683 \labelwidthstring 00.00.0000
 684
 685 docdir environment variable, see table below
 686 \layout List
 687 \labelwidthstring 00.00.0000
 688
 689 include_dir_suffix environment variable, see table below
 690 \layout List
 691 \labelwidthstring 00.00.0000
 692
 693 lib_dir_suffix environment variable, see table below
 694 \layout List
 695 \labelwidthstring 00.00.0000
 696
 697 sdccconf_h_dir_separator environment variable, either / or
 698 \backslash
 699
 700 \backslash
 701  makes sense here.
 702  This character will only be used in sdccconf.h; don't forget it's a C-header,
 703  therefore a double-backslash is needed there.
 704 \layout List
 705 \labelwidthstring 00.00.0000
 706
 707 -
 708 \begin_inset ERT
 709 status Collapsed
 710
 711 \layout Standard
 712
 713 \backslash
 714 /
 715 \end_inset
 716
 717 -disable-mcs51-port Excludes the Intel mcs51 port
 718 \layout List
 719 \labelwidthstring 00.00.0000
 720
 721 -
 722 \begin_inset ERT
 723 status Collapsed
 724
 725 \layout Standard
 726
 727 \backslash
 728 /
 729 \end_inset
 730
 731 -disable-gbz80-port Excludes the Gameboy gbz80 port
 732 \layout List
 733 \labelwidthstring 00.00.0000
 734
 735 -
 736 \begin_inset ERT
 737 status Collapsed
 738
 739 \layout Standard
 740
 741 \backslash
 742 /
 743 \end_inset
 744
 745 -disable-z80-port Excludes the z80 port
 746 \layout List
 747 \labelwidthstring 00.00.0000
 748
 749 -
 750 \begin_inset ERT
 751 status Collapsed
 752
 753 \layout Standard
 754
 755 \backslash
 756 /
 757 \end_inset
 758
 759 -disable-avr-port Excludes the AVR port
 760 \layout List
 761 \labelwidthstring 00.00.0000
 762
 763 -
 764 \begin_inset ERT
 765 status Collapsed
 766
 767 \layout Standard
 768
 769 \backslash
 770 /
 771 \end_inset
 772
 773 -disable-ds390-port Excludes the DS390 port
 774 \layout List
 775 \labelwidthstring 00.00.0000
 776
 777 -
 778 \begin_inset ERT
 779 status Collapsed
 780
 781 \layout Standard
 782
 783 \backslash
 784 /
 785 \end_inset
 786
 787 -disable-hc08-port Excludes the HC08 port
 788 \layout List
 789 \labelwidthstring 00.00.0000
 790
 791 -
 792 \begin_inset ERT
 793 status Collapsed
 794
 795 \layout Standard
 796
 797 \backslash
 798 /
 799 \end_inset
 800
 801 -disable-pic-port Excludes the PIC port
 802 \layout List
 803 \labelwidthstring 00.00.0000
 804
 805 -
 806 \begin_inset ERT
 807 status Collapsed
 808
 809 \layout Standard
 810
 811 \backslash
 812 /
 813 \end_inset
 814
 815 -disable-xa51-port Excludes the XA51 port
 816 \layout List
 817 \labelwidthstring 00.00.0000
 818
 819 -
 820 \begin_inset ERT
 821 status Collapsed
 822
 823 \layout Standard
 824
 825 \backslash
 826 /
 827 \end_inset
 828
 829 -disable-ucsim Disables configuring and building of ucsim
 830 \layout List
 831 \labelwidthstring 00.00.0000
 832
 833 -
 834 \begin_inset ERT
 835 status Collapsed
 836
 837 \layout Standard
 838
 839 \backslash
 840 /
 841 \end_inset
 842
 843 -disable-device-lib Disables automatically building device libraries
 844 \layout List
 845 \labelwidthstring 00.00.0000
 846
 847 -
 848 \begin_inset ERT
 849 status Collapsed
 850
 851 \layout Standard
 852
 853 \backslash
 854 /
 855 \end_inset
 856
 857 -disable-packihx Disables building packihx
 858 \layout List
 859 \labelwidthstring 00.00.0000
 860
 861 -
 862 \begin_inset ERT
 863 status Collapsed
 864
 865 \layout Standard
 866
 867 \backslash
 868 /
 869 \end_inset
 870
 871 -enable-doc Build pdf, html and txt files from the lyx sources
 872 \layout List
 873 \labelwidthstring 00.00.0000
 874
 875 -
 876 \begin_inset ERT
 877 status Collapsed
 878
 879 \layout Standard
 880
 881 \backslash
 882 /
 883 \end_inset
 884
 885 -enable-libgc Use the Bohem memory allocator.
 886  Lower runtime footprint.
 887 \layout Standard
 888
 889 Furthermore the environment variables CC, CFLAGS, ...
 890  the tools and their arguments can be influenced.
 891  Please see `configure -
 892 \begin_inset ERT
 893 status Collapsed
 894
 895 \layout Standard
 896
 897 \backslash
 898 /
 899 \end_inset
 900
 901 -help` and the man/info pages of `configure` for details.
 902 \newline
 903
 904 \newline
 905 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 906  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 907 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 908  At the moment it's not possible to change the default settings (it was
 909  simply never required).
 910 \newline
 911
 912 \newline
 913 These configure options are compiled into the binaries, and can only be
 914  changed by rerunning 'configure' and recompiling SDCC.
 915  The configure options are written in
 916 \emph on
 917 italics
 918 \emph default
 919  to distinguish them from run time environment variables (see section search
 920  paths).
 921 \newline
 922
 923 \newline
 924 The settings for
 925 \begin_inset Quotes sld
 926 \end_inset
 927
 928 Win32 builds
 929 \begin_inset Quotes srd
 930 \end_inset
 931
 932  are used by the SDCC team to build the official Win32 binaries.
 933  The SDCC team uses Mingw32 to build the official Windows binaries, because
 934  it's
 935 \layout Enumerate
 936
 937 open source,
 938 \layout Enumerate
 939
 940 a gcc compiler and last but not least
 941 \layout Enumerate
 942
 943 the binaries can be built by cross compiling on Sourceforge's compile farm.
 944 \layout Standard
 945
 946 See the examples, how to pass the Win32 settings to 'configure'.
 947  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 948  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 949  for Win32.
 950 \newline
 951
 952 \newline
 953 These defaults are:
 954 \newline
 955
 956 \layout Standard
 957 \align center
 958
 959 \begin_inset  Tabular
 960 <lyxtabular version="3" rows="8" columns="3">
 961 <features>
 962 <column alignment="block" valignment="top" leftline="true" width="0in">
 963 <column alignment="block" valignment="top" leftline="true" width="0in">
 964 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 965 <row topline="true" bottomline="true">
 966 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 967 \begin_inset Text
 968
 969 \layout Standard
 970
 971 Variable
 972 \end_inset
 973 </cell>
 974 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 975 \begin_inset Text
 976
 977 \layout Standard
 978
 979 default
 980 \end_inset
 981 </cell>
 982 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 983 \begin_inset Text
 984
 985 \layout Standard
 986
 987 Win32 builds
 988 \end_inset
 989 </cell>
 990 </row>
 991 <row topline="true">
 992 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 993 \begin_inset Text
 994
 995 \layout Standard
 996
 997
 998 \emph on
 999 PREFIX
1000 \end_inset
1001 </cell>
1002 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1003 \begin_inset Text
1004
1005 \layout Standard
1006
1007 /usr/local
1008 \end_inset
1009 </cell>
1010 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1011 \begin_inset Text
1012
1013 \layout Standard
1014
1015
1016 \backslash
1017 sdcc
1018 \end_inset
1019 </cell>
1020 </row>
1021 <row topline="true">
1022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1023 \begin_inset Text
1024
1025 \layout Standard
1026
1027
1028 \emph on
1029 EXEC_PREFIX
1030 \end_inset
1031 </cell>
1032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1033 \begin_inset Text
1034
1035 \layout Standard
1036
1037
1038 \emph on
1039 $PREFIX
1040 \end_inset
1041 </cell>
1042 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1043 \begin_inset Text
1044
1045 \layout Standard
1046
1047
1048 \emph on
1049 $PREFIX
1050 \end_inset
1051 </cell>
1052 </row>
1053 <row topline="true">
1054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1055 \begin_inset Text
1056
1057 \layout Standard
1058
1059
1060 \emph on
1061 BINDIR
1062 \end_inset
1063 </cell>
1064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1065 \begin_inset Text
1066
1067 \layout Standard
1068
1069
1070 \emph on
1071 $EXECPREFIX
1072 \emph default
1073 /bin
1074 \end_inset
1075 </cell>
1076 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1077 \begin_inset Text
1078
1079 \layout Standard
1080
1081
1082 \emph on
1083 $EXECPREFIX
1084 \emph default
1085
1086 \backslash
1087 bin
1088 \end_inset
1089 </cell>
1090 </row>
1091 <row topline="true">
1092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1093 \begin_inset Text
1094
1095 \layout Standard
1096
1097
1098 \emph on
1099 DATADIR
1100 \end_inset
1101 </cell>
1102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1103 \begin_inset Text
1104
1105 \layout Standard
1106
1107
1108 \emph on
1109 $PREFIX
1110 \emph default
1111 /share
1112 \end_inset
1113 </cell>
1114 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1115 \begin_inset Text
1116
1117 \layout Standard
1118
1119
1120 \emph on
1121 $PREFIX
1122 \end_inset
1123 </cell>
1124 </row>
1125 <row topline="true">
1126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1127 \begin_inset Text
1128
1129 \layout Standard
1130
1131
1132 \emph on
1133 DOCDIR
1134 \end_inset
1135 </cell>
1136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1137 \begin_inset Text
1138
1139 \layout Standard
1140
1141
1142 \emph on
1143 $DATADIR
1144 \emph default
1145 /sdcc/doc
1146 \end_inset
1147 </cell>
1148 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1149 \begin_inset Text
1150
1151 \layout Standard
1152
1153
1154 \emph on
1155 $DATADIR
1156 \emph default
1157
1158 \backslash
1159 doc
1160 \end_inset
1161 </cell>
1162 </row>
1163 <row topline="true">
1164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1165 \begin_inset Text
1166
1167 \layout Standard
1168
1169
1170 \emph on
1171 INCLUDE_DIR_SUFFIX
1172 \end_inset
1173 </cell>
1174 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1175 \begin_inset Text
1176
1177 \layout Standard
1178
1179 sdcc/include
1180 \end_inset
1181 </cell>
1182 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1183 \begin_inset Text
1184
1185 \layout Standard
1186
1187 include
1188 \end_inset
1189 </cell>
1190 </row>
1191 <row topline="true" bottomline="true">
1192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1193 \begin_inset Text
1194
1195 \layout Standard
1196
1197
1198 \emph on
1199 LIB_DIR_SUFFIX
1200 \end_inset
1201 </cell>
1202 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1203 \begin_inset Text
1204
1205 \layout Standard
1206
1207 sdcc/lib
1208 \end_inset
1209 </cell>
1210 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1211 \begin_inset Text
1212
1213 \layout Standard
1214
1215 lib
1216 \end_inset
1217 </cell>
1218 </row>
1219 </lyxtabular>
1220
1221 \end_inset
1222
1223
1224 \newline
1225
1226 \layout Standard
1227 \noindent
1228 'configure' also computes relative paths.
1229  This is needed for full relocatability of a binary package and to complete
1230  search paths (see section search paths below):
1231 \newline
1232
1233 \layout Standard
1234 \align center
1235
1236 \begin_inset  Tabular
1237 <lyxtabular version="3" rows="4" columns="3">
1238 <features>
1239 <column alignment="block" valignment="top" leftline="true" width="0in">
1240 <column alignment="block" valignment="top" leftline="true" width="0in">
1241 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1242 <row topline="true" bottomline="true">
1243 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1244 \begin_inset Text
1245
1246 \layout Standard
1247
1248 Variable (computed)
1249 \end_inset
1250 </cell>
1251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1252 \begin_inset Text
1253
1254 \layout Standard
1255
1256 default
1257 \end_inset
1258 </cell>
1259 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1260 \begin_inset Text
1261
1262 \layout Standard
1263
1264 Win32 builds
1265 \end_inset
1266 </cell>
1267 </row>
1268 <row topline="true" bottomline="true">
1269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1270 \begin_inset Text
1271
1272 \layout Standard
1273
1274
1275 \emph on
1276 BIN2DATA_DIR
1277 \end_inset
1278 </cell>
1279 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1280 \begin_inset Text
1281
1282 \layout Standard
1283
1284 ../share
1285 \end_inset
1286 </cell>
1287 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1288 \begin_inset Text
1289
1290 \layout Standard
1291
1292 ..
1293 \end_inset
1294 </cell>
1295 </row>
1296 <row bottomline="true">
1297 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1298 \begin_inset Text
1299
1300 \layout Standard
1301
1302
1303 \emph on
1304 PREFIX2BIN_DIR
1305 \end_inset
1306 </cell>
1307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1308 \begin_inset Text
1309
1310 \layout Standard
1311
1312 bin
1313 \end_inset
1314 </cell>
1315 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1316 \begin_inset Text
1317
1318 \layout Standard
1319
1320 bin
1321 \end_inset
1322 </cell>
1323 </row>
1324 <row bottomline="true">
1325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1326 \begin_inset Text
1327
1328 \layout Standard
1329
1330
1331 \emph on
1332 PREFIX2DATA_DIR
1333 \end_inset
1334 </cell>
1335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1336 \begin_inset Text
1337
1338 \layout Standard
1339
1340 share/sdcc
1341 \end_inset
1342 </cell>
1343 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1344 \begin_inset Text
1345
1346 \layout Standard
1347
1348 \end_inset
1349 </cell>
1350 </row>
1351 </lyxtabular>
1352
1353 \end_inset
1354
1355
1356 \newline
1357
1358 \layout Standard
1359 \noindent
1360 Examples:
1361 \layout LyX-Code
1362
1363 ./configure
1364 \newline
1365 ./configure -
1366 \begin_inset ERT
1367 status Collapsed
1368
1369 \layout Standard
1370
1371 \backslash
1372 /
1373 \end_inset
1374
1375 -prefix=
1376 \begin_inset Quotes srd
1377 \end_inset
1378
1379 /usr/bin
1380 \begin_inset Quotes srd
1381 \end_inset
1382
1383  -
1384 \begin_inset ERT
1385 status Collapsed
1386
1387 \layout Standard
1388
1389 \backslash
1390 /
1391 \end_inset
1392
1393 -datadir=
1394 \begin_inset Quotes srd
1395 \end_inset
1396
1397 /usr/share
1398 \begin_inset Quotes srd
1399 \end_inset
1400
1401
1402 \newline
1403 ./configure -
1404 \begin_inset ERT
1405 status Collapsed
1406
1407 \layout Standard
1408
1409 \backslash
1410 /
1411 \end_inset
1412
1413 -disable-avr-port -
1414 \begin_inset ERT
1415 status Collapsed
1416
1417 \layout Standard
1418
1419 \backslash
1420 /
1421 \end_inset
1422
1423 -disable-xa51-port
1424 \layout Standard
1425
1426 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1427 32'):
1428 \layout LyX-Code
1429
1430 ./configure
1431 \backslash
1432
1433 \newline
1434 CC=
1435 \begin_inset Quotes srd
1436 \end_inset
1437
1438 i586-mingw32msvc-gcc
1439 \begin_inset Quotes srd
1440 \end_inset
1441
1442  CXX=
1443 \begin_inset Quotes srd
1444 \end_inset
1445
1446 i586-mingw32msvc-g++
1447 \begin_inset Quotes srd
1448 \end_inset
1449
1450
1451 \backslash
1452
1453 \newline
1454 RANLIB=
1455 \begin_inset Quotes srd
1456 \end_inset
1457
1458 i586-mingw32msvc-ranlib
1459 \begin_inset Quotes srd
1460 \end_inset
1461
1462
1463 \backslash
1464
1465 \newline
1466 STRIP=
1467 \begin_inset Quotes srd
1468 \end_inset
1469
1470 i586-mingw32msvc-strip
1471 \begin_inset Quotes srd
1472 \end_inset
1473
1474
1475 \backslash
1476
1477 \newline
1478 -
1479 \begin_inset ERT
1480 status Collapsed
1481
1482 \layout Standard
1483
1484 \backslash
1485 /
1486 \end_inset
1487
1488 -prefix=
1489 \begin_inset Quotes srd
1490 \end_inset
1491
1492 /sdcc
1493 \begin_inset Quotes srd
1494 \end_inset
1495
1496
1497 \backslash
1498
1499 \newline
1500 -
1501 \begin_inset ERT
1502 status Collapsed
1503
1504 \layout Standard
1505
1506 \backslash
1507 /
1508 \end_inset
1509
1510 -datadir=
1511 \begin_inset Quotes srd
1512 \end_inset
1513
1514 /sdcc
1515 \begin_inset Quotes srd
1516 \end_inset
1517
1518
1519 \backslash
1520
1521 \newline
1522 docdir=
1523 \begin_inset Quotes srd
1524 \end_inset
1525
1526 /sdcc/doc
1527 \begin_inset Quotes srd
1528 \end_inset
1529
1530
1531 \backslash
1532
1533 \newline
1534 include_dir_suffix=
1535 \begin_inset Quotes srd
1536 \end_inset
1537
1538 include
1539 \begin_inset Quotes srd
1540 \end_inset
1541
1542
1543 \backslash
1544
1545 \newline
1546 lib_dir_suffix=
1547 \begin_inset Quotes srd
1548 \end_inset
1549
1550 lib
1551 \begin_inset Quotes srd
1552 \end_inset
1553
1554
1555 \backslash
1556
1557 \newline
1558 sdccconf_h_dir_separator=
1559 \begin_inset Quotes srd
1560 \end_inset
1561
1562
1563 \backslash
1564
1565 \backslash
1566
1567 \backslash
1568
1569 \backslash
1570
1571 \begin_inset Quotes srd
1572 \end_inset
1573
1574
1575 \backslash
1576
1577 \newline
1578 -
1579 \begin_inset ERT
1580 status Collapsed
1581
1582 \layout Standard
1583
1584 \backslash
1585 /
1586 \end_inset
1587
1588 -disable-device-lib
1589 \backslash
1590
1591 \newline
1592 -
1593 \begin_inset ERT
1594 status Collapsed
1595
1596 \layout Standard
1597
1598 \backslash
1599 /
1600 \end_inset
1601
1602 -disable-ucsim
1603 \backslash
1604
1605 \newline
1606 -
1607 \begin_inset ERT
1608 status Collapsed
1609
1610 \layout Standard
1611
1612 \backslash
1613 /
1614 \end_inset
1615
1616 -host=i586-mingw32msvc -
1617 \begin_inset ERT
1618 status Collapsed
1619
1620 \layout Standard
1621
1622 \backslash
1623 /
1624 \end_inset
1625
1626 -build=unknown-unknown-linux-gnu
1627 \layout Standard
1628
1629 To
1630 \begin_inset Quotes sld
1631 \end_inset
1632
1633 cross
1634 \begin_inset Quotes srd
1635 \end_inset
1636
1637 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1638 ):
1639 \layout LyX-Code
1640
1641 ./configure -C
1642 \backslash
1643
1644 \newline
1645 CFLAGS=
1646 \begin_inset Quotes srd
1647 \end_inset
1648
1649 -mno-cygwin -O2
1650 \begin_inset Quotes srd
1651 \end_inset
1652
1653
1654 \backslash
1655
1656 \newline
1657 LDFLAGS=
1658 \begin_inset Quotes srd
1659 \end_inset
1660
1661 -mno-cygwin
1662 \begin_inset Quotes srd
1663 \end_inset
1664
1665
1666 \backslash
1667
1668 \newline
1669 -
1670 \begin_inset ERT
1671 status Collapsed
1672
1673 \layout Standard
1674
1675 \backslash
1676 /
1677 \end_inset
1678
1679 -prefix=
1680 \begin_inset Quotes srd
1681 \end_inset
1682
1683 /sdcc
1684 \begin_inset Quotes srd
1685 \end_inset
1686
1687
1688 \backslash
1689
1690 \newline
1691 -
1692 \begin_inset ERT
1693 status Collapsed
1694
1695 \layout Standard
1696
1697 \backslash
1698 /
1699 \end_inset
1700
1701 -datadir=
1702 \begin_inset Quotes srd
1703 \end_inset
1704
1705 /sdcc
1706 \begin_inset Quotes srd
1707 \end_inset
1708
1709
1710 \backslash
1711
1712 \newline
1713 docdir=
1714 \begin_inset Quotes srd
1715 \end_inset
1716
1717 /sdcc/doc
1718 \begin_inset Quotes srd
1719 \end_inset
1720
1721
1722 \backslash
1723
1724 \newline
1725 include_dir_suffix=
1726 \begin_inset Quotes srd
1727 \end_inset
1728
1729 include
1730 \begin_inset Quotes srd
1731 \end_inset
1732
1733
1734 \backslash
1735
1736 \newline
1737 lib_dir_suffix=
1738 \begin_inset Quotes srd
1739 \end_inset
1740
1741 lib
1742 \begin_inset Quotes srd
1743 \end_inset
1744
1745
1746 \backslash
1747
1748 \newline
1749 sdccconf_h_dir_separator=
1750 \begin_inset Quotes srd
1751 \end_inset
1752
1753
1754 \backslash
1755
1756 \backslash
1757
1758 \backslash
1759
1760 \backslash
1761
1762 \begin_inset Quotes srd
1763 \end_inset
1764
1765
1766 \backslash
1767
1768 \newline
1769 -
1770 \begin_inset ERT
1771 status Collapsed
1772
1773 \layout Standard
1774
1775 \backslash
1776 /
1777 \end_inset
1778
1779 -disable-ucsim
1780 \layout Standard
1781
1782 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1783  The option '-
1784 \begin_inset ERT
1785 status Collapsed
1786
1787 \layout Standard
1788
1789 \backslash
1790 /
1791 \end_inset
1792
1793 -C' turns on caching, which gives a little bit extra speed.
1794  However if options are changed, it can be necessary to delete the config.cache
1795  file.
1796 \layout Section
1797
1798 Install paths
1799 \begin_inset LatexCommand \label{sub:Install-paths}
1800
1801 \end_inset
1802
1803
1804 \begin_inset LatexCommand \index{Install paths}
1805
1806 \end_inset
1807
1808
1809 \layout Standard
1810 \added_space_top medskip \align center
1811
1812 \begin_inset  Tabular
1813 <lyxtabular version="3" rows="5" columns="4">
1814 <features>
1815 <column alignment="center" valignment="top" leftline="true" width="0">
1816 <column alignment="center" valignment="top" leftline="true" width="0">
1817 <column alignment="center" valignment="top" leftline="true" width="0">
1818 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1819 <row topline="true" bottomline="true">
1820 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1821 \begin_inset Text
1822
1823 \layout Standard
1824
1825
1826 \series bold
1827 Description
1828 \end_inset
1829 </cell>
1830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1831 \begin_inset Text
1832
1833 \layout Standard
1834
1835
1836 \series bold
1837 Path
1838 \end_inset
1839 </cell>
1840 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1841 \begin_inset Text
1842
1843 \layout Standard
1844
1845
1846 \series bold
1847 Default
1848 \end_inset
1849 </cell>
1850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1851 \begin_inset Text
1852
1853 \layout Standard
1854
1855
1856 \series bold
1857 Win32 builds
1858 \end_inset
1859 </cell>
1860 </row>
1861 <row topline="true">
1862 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1863 \begin_inset Text
1864
1865 \layout Standard
1866
1867 Binary files*
1868 \end_inset
1869 </cell>
1870 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1871 \begin_inset Text
1872
1873 \layout Standard
1874
1875
1876 \emph on
1877 $EXEC_PREFIX
1878 \end_inset
1879 </cell>
1880 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1881 \begin_inset Text
1882
1883 \layout Standard
1884
1885 /usr/local/bin
1886 \end_inset
1887 </cell>
1888 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1889 \begin_inset Text
1890
1891 \layout Standard
1892
1893
1894 \backslash
1895 sdcc
1896 \backslash
1897 bin
1898 \end_inset
1899 </cell>
1900 </row>
1901 <row topline="true">
1902 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1903 \begin_inset Text
1904
1905 \layout Standard
1906
1907 Include files
1908 \end_inset
1909 </cell>
1910 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1911 \begin_inset Text
1912
1913 \layout Standard
1914
1915
1916 \emph on
1917 $DATADIR/ $INCLUDE_DIR_SUFFIX
1918 \end_inset
1919 </cell>
1920 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1921 \begin_inset Text
1922
1923 \layout Standard
1924
1925 /usr/local/share/sdcc/include
1926 \end_inset
1927 </cell>
1928 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1929 \begin_inset Text
1930
1931 \layout Standard
1932
1933
1934 \backslash
1935 sdcc
1936 \backslash
1937 include
1938 \end_inset
1939 </cell>
1940 </row>
1941 <row topline="true">
1942 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1943 \begin_inset Text
1944
1945 \layout Standard
1946
1947 Library file**
1948 \end_inset
1949 </cell>
1950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1951 \begin_inset Text
1952
1953 \layout Standard
1954
1955
1956 \emph on
1957 $DATADIR/$LIB_DIR_SUFFIX
1958 \end_inset
1959 </cell>
1960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1961 \begin_inset Text
1962
1963 \layout Standard
1964
1965 /usr/local/share/sdcc/lib
1966 \end_inset
1967 </cell>
1968 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1969 \begin_inset Text
1970
1971 \layout Standard
1972
1973
1974 \backslash
1975 sdcc
1976 \backslash
1977 lib
1978 \end_inset
1979 </cell>
1980 </row>
1981 <row topline="true" bottomline="true">
1982 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1983 \begin_inset Text
1984
1985 \layout Standard
1986
1987 Documentation
1988 \end_inset
1989 </cell>
1990 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1991 \begin_inset Text
1992
1993 \layout Standard
1994
1995
1996 \emph on
1997 $DOCDIR
1998 \end_inset
1999 </cell>
2000 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2001 \begin_inset Text
2002
2003 \layout Standard
2004
2005 /usr/local/share/sdcc/doc
2006 \end_inset
2007 </cell>
2008 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2009 \begin_inset Text
2010
2011 \layout Standard
2012
2013
2014 \backslash
2015 sdcc
2016 \backslash
2017 doc
2018 \end_inset
2019 </cell>
2020 </row>
2021 </lyxtabular>
2022
2023 \end_inset
2024
2025
2026 \layout Verse
2027
2028
2029 \size footnotesize
2030 *compiler, preprocessor, assembler, and linker
2031 \newline
2032 **the
2033 \shape italic
2034 model
2035 \shape default
2036  is auto-appended by the compiler, e.g.
2037  small, large, z80, ds390 etc
2038 \layout Standard
2039 \noindent
2040 The install paths can still be changed during `make install` with e.g.:
2041 \layout LyX-Code
2042
2043 make install prefix=$(HOME)/local/sdcc
2044 \layout Standard
2045
2046 Of course this doesn't change the search paths compiled into the binaries.
2047 \newline
2048
2049 \newline
2050 Moreover the install path can be changed by defining DESTDIR
2051 \begin_inset LatexCommand \index{DESTDIR}
2052
2053 \end_inset
2054
2055 :
2056 \layout LyX-Code
2057
2058 make install DESTDIR=$(HOME)/sdcc.rpm/
2059 \layout Standard
2060
2061 Please note that DESTDIR must have a trailing slash!
2062 \layout Section
2063
2064 Search Paths
2065 \begin_inset LatexCommand \label{sub:Search-Paths}
2066
2067 \end_inset
2068
2069
2070 \begin_inset LatexCommand \index{Search path}
2071
2072 \end_inset
2073
2074
2075 \layout Standard
2076
2077 Some search paths or parts of them are determined by configure variables
2078  (in
2079 \emph on
2080 italics
2081 \emph default
2082 , see section above).
2083  Further search paths are determined by environment variables during runtime.
2084
2085 \newline
2086 The paths searched when running the compiler are as follows (the first catch
2087  wins):
2088 \newline
2089
2090 \newline
2091 1.
2092  Binary files (preprocessor, assembler and linker)
2093 \newline
2094
2095 \layout Standard
2096 \align center
2097
2098 \begin_inset  Tabular
2099 <lyxtabular version="3" rows="4" columns="3">
2100 <features>
2101 <column alignment="block" valignment="top" leftline="true" width="0in">
2102 <column alignment="block" valignment="top" leftline="true" width="0in">
2103 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2104 <row topline="true" bottomline="true">
2105 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2106 \begin_inset Text
2107
2108 \layout Standard
2109
2110 Search path
2111 \end_inset
2112 </cell>
2113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2114 \begin_inset Text
2115
2116 \layout Standard
2117
2118 default
2119 \end_inset
2120 </cell>
2121 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2122 \begin_inset Text
2123
2124 \layout Standard
2125
2126 Win32 builds
2127 \end_inset
2128 </cell>
2129 </row>
2130 <row topline="true">
2131 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2132 \begin_inset Text
2133
2134 \layout Standard
2135
2136 $SDCC_HOME/
2137 \emph on
2138 $PPREFIX2BIN_DIR
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 $SDCC_HOME/bin
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 $SDCC_HOME
2155 \backslash
2156 bin
2157 \end_inset
2158 </cell>
2159 </row>
2160 <row topline="true">
2161 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2162 \begin_inset Text
2163
2164 \layout Standard
2165
2166 Path of argv[0] (if available)
2167 \end_inset
2168 </cell>
2169 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2170 \begin_inset Text
2171
2172 \layout Standard
2173
2174 Path of argv[0]
2175 \end_inset
2176 </cell>
2177 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2178 \begin_inset Text
2179
2180 \layout Standard
2181
2182 Path of argv[0]
2183 \end_inset
2184 </cell>
2185 </row>
2186 <row topline="true" bottomline="true">
2187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2188 \begin_inset Text
2189
2190 \layout Standard
2191
2192 $PATH
2193 \end_inset
2194 </cell>
2195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2196 \begin_inset Text
2197
2198 \layout Standard
2199
2200 $PATH
2201 \end_inset
2202 </cell>
2203 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2204 \begin_inset Text
2205
2206 \layout Standard
2207
2208 $PATH
2209 \end_inset
2210 </cell>
2211 </row>
2212 </lyxtabular>
2213
2214 \end_inset
2215
2216
2217 \newline
2218
2219 \layout Standard
2220 \noindent
2221 2.
2222  Include files
2223 \newline
2224
2225 \layout Standard
2226 \align center
2227
2228 \begin_inset  Tabular
2229 <lyxtabular version="3" rows="6" columns="3">
2230 <features>
2231 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2232 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2233 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2234 <row topline="true" bottomline="true">
2235 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2236 \begin_inset Text
2237
2238 \layout Standard
2239
2240 Search path
2241 \end_inset
2242 </cell>
2243 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2244 \begin_inset Text
2245
2246 \layout Standard
2247
2248 default
2249 \end_inset
2250 </cell>
2251 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2252 \begin_inset Text
2253
2254 \layout Standard
2255
2256 Win32 builds
2257 \end_inset
2258 </cell>
2259 </row>
2260 <row topline="true">
2261 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2262 \begin_inset Text
2263
2264 \layout Standard
2265
2266 -
2267 \begin_inset ERT
2268 status Collapsed
2269
2270 \layout Standard
2271
2272 \backslash
2273 /
2274 \end_inset
2275
2276 -I dir
2277 \end_inset
2278 </cell>
2279 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2280 \begin_inset Text
2281
2282 \layout Standard
2283
2284 -
2285 \begin_inset ERT
2286 status Collapsed
2287
2288 \layout Standard
2289
2290 \backslash
2291 /
2292 \end_inset
2293
2294 -I dir
2295 \end_inset
2296 </cell>
2297 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2298 \begin_inset Text
2299
2300 \layout Standard
2301
2302 -
2303 \begin_inset ERT
2304 status Collapsed
2305
2306 \layout Standard
2307
2308 \backslash
2309 /
2310 \end_inset
2311
2312 -I dir
2313 \end_inset
2314 </cell>
2315 </row>
2316 <row topline="true">
2317 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2318 \begin_inset Text
2319
2320 \layout Standard
2321
2322 $SDCC_INCLUDE
2323 \end_inset
2324 </cell>
2325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2326 \begin_inset Text
2327
2328 \layout Standard
2329
2330 $SDCC_INCLUDE
2331 \end_inset
2332 </cell>
2333 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2334 \begin_inset Text
2335
2336 \layout Standard
2337
2338 $SDCC_INCLUDE
2339 \end_inset
2340 </cell>
2341 </row>
2342 <row topline="true">
2343 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2344 \begin_inset Text
2345
2346 \layout Standard
2347
2348 $SDCC_HOME/
2349 \newline
2350
2351 \emph on
2352 $PREFIX2DATA_DIR/
2353 \newline
2354 $INCLUDE_DIR_SUFFIX
2355 \end_inset
2356 </cell>
2357 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2358 \begin_inset Text
2359
2360 \layout Standard
2361
2362 $SDCC_ HOME/
2363 \newline
2364 share/sdcc/
2365 \newline
2366 include
2367 \end_inset
2368 </cell>
2369 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2370 \begin_inset Text
2371
2372 \layout Standard
2373
2374 $SDCC_HOME
2375 \backslash
2376 include
2377 \end_inset
2378 </cell>
2379 </row>
2380 <row topline="true">
2381 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2382 \begin_inset Text
2383
2384 \layout Standard
2385
2386 path(argv[0])/
2387 \newline
2388
2389 \emph on
2390 $BIN2DATADIR/
2391 \emph default
2392
2393 \newline
2394
2395 \emph on
2396 $INCLUDE_DIR_SUFFIX
2397 \end_inset
2398 </cell>
2399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2400 \begin_inset Text
2401
2402 \layout Standard
2403
2404 path(argv[0])/
2405 \newline
2406 ../sdcc/include
2407 \newline
2408 \SpecialChar ~
2409 \SpecialChar ~
2410 \SpecialChar ~
2411 \SpecialChar ~
2412 \SpecialChar ~
2413 \SpecialChar ~
2414 \SpecialChar ~
2415 \SpecialChar ~
2416 \SpecialChar ~
2417 \SpecialChar ~
2418 \SpecialChar ~
2419 \SpecialChar ~
2420 \SpecialChar ~
2421 \SpecialChar ~
2422 \SpecialChar ~
2423 \SpecialChar ~
2424 \SpecialChar ~
2425 \SpecialChar ~
2426 \SpecialChar ~
2427 \SpecialChar ~
2428 \SpecialChar ~
2429 \SpecialChar ~
2430 \SpecialChar ~
2431 \SpecialChar ~
2432 \SpecialChar ~
2433 \SpecialChar ~
2434 \SpecialChar ~
2435 \SpecialChar ~
2436 \SpecialChar ~
2437 \SpecialChar ~
2438 \SpecialChar ~
2439 \SpecialChar ~
2440 \SpecialChar ~
2441 \SpecialChar ~
2442 \SpecialChar ~
2443 \SpecialChar ~
2444 \SpecialChar ~
2445 \SpecialChar ~
2446
2447 \end_inset
2448 </cell>
2449 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2450 \begin_inset Text
2451
2452 \layout Standard
2453
2454 path(argv[0])
2455 \backslash
2456 ..
2457 \backslash
2458 include
2459 \end_inset
2460 </cell>
2461 </row>
2462 <row topline="true" bottomline="true">
2463 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2464 \begin_inset Text
2465
2466 \layout Standard
2467
2468
2469 \emph on
2470 $DATADIR/
2471 \emph default
2472
2473 \newline
2474
2475 \emph on
2476 $INCLUDE_DIR_SUFFIX
2477 \end_inset
2478 </cell>
2479 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2480 \begin_inset Text
2481
2482 \layout Standard
2483
2484 /usr/local/share/sdcc/
2485 \newline
2486 include
2487 \end_inset
2488 </cell>
2489 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2490 \begin_inset Text
2491
2492 \layout Standard
2493
2494 (not on Win32)
2495 \end_inset
2496 </cell>
2497 </row>
2498 </lyxtabular>
2499
2500 \end_inset
2501
2502
2503 \newline
2504
2505 \layout Standard
2506 \noindent
2507 The option -
2508 \begin_inset ERT
2509 status Collapsed
2510
2511 \layout Standard
2512
2513 \backslash
2514 /
2515 \end_inset
2516
2517 -nostdinc disables the last two search paths.
2518 \newline
2519
2520 \newline
2521 3.
2522  Library files
2523 \newline
2524
2525 \layout Standard
2526
2527 With the exception of
2528 \begin_inset Quotes sld
2529 \end_inset
2530
2531 -
2532 \begin_inset ERT
2533 status Collapsed
2534
2535 \layout Standard
2536
2537 \backslash
2538 /
2539 \end_inset
2540
2541 -L dir
2542 \begin_inset Quotes srd
2543 \end_inset
2544
2545  the
2546 \shape italic
2547 model
2548 \shape default
2549  is auto-appended by the compiler (e.g.
2550  small, large, z80, ds390 etc.).
2551
2552 \newline
2553
2554 \layout Standard
2555 \align center
2556
2557 \begin_inset  Tabular
2558 <lyxtabular version="3" rows="6" columns="3">
2559 <features>
2560 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2561 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2562 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2563 <row topline="true" bottomline="true">
2564 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2565 \begin_inset Text
2566
2567 \layout Standard
2568
2569 Search path
2570 \end_inset
2571 </cell>
2572 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2573 \begin_inset Text
2574
2575 \layout Standard
2576
2577 default
2578 \end_inset
2579 </cell>
2580 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2581 \begin_inset Text
2582
2583 \layout Standard
2584
2585 Win32 builds
2586 \end_inset
2587 </cell>
2588 </row>
2589 <row topline="true">
2590 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2591 \begin_inset Text
2592
2593 \layout Standard
2594
2595 -
2596 \begin_inset ERT
2597 status Collapsed
2598
2599 \layout Standard
2600
2601 \backslash
2602 /
2603 \end_inset
2604
2605 -L dir
2606 \end_inset
2607 </cell>
2608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2609 \begin_inset Text
2610
2611 \layout Standard
2612
2613 -
2614 \begin_inset ERT
2615 status Collapsed
2616
2617 \layout Standard
2618
2619 \backslash
2620 /
2621 \end_inset
2622
2623 -L dir
2624 \end_inset
2625 </cell>
2626 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2627 \begin_inset Text
2628
2629 \layout Standard
2630
2631 -
2632 \begin_inset ERT
2633 status Collapsed
2634
2635 \layout Standard
2636
2637 \backslash
2638 /
2639 \end_inset
2640
2641 -L dir
2642 \end_inset
2643 </cell>
2644 </row>
2645 <row topline="true">
2646 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2647 \begin_inset Text
2648
2649 \layout Standard
2650
2651 $SDCC_LIB/
2652 \newline
2653
2654 \emph on
2655 <model>
2656 \end_inset
2657 </cell>
2658 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2659 \begin_inset Text
2660
2661 \layout Standard
2662
2663 $SDCC_LIB/
2664 \newline
2665
2666 \emph on
2667 <model>
2668 \end_inset
2669 </cell>
2670 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2671 \begin_inset Text
2672
2673 \layout Standard
2674
2675 $SDCC_LIB
2676 \backslash
2677
2678 \newline
2679
2680 \emph on
2681 <model>
2682 \end_inset
2683 </cell>
2684 </row>
2685 <row topline="true">
2686 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2687 \begin_inset Text
2688
2689 \layout Standard
2690
2691 $SDCC_HOME/
2692 \newline
2693
2694 \emph on
2695 $PREFIX2DATA_DIR/
2696 \newline
2697 $LIB_DIR_SUFFIX/<model>
2698 \end_inset
2699 </cell>
2700 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2701 \begin_inset Text
2702
2703 \layout Standard
2704
2705 $SDCC_HOME/
2706 \newline
2707 share/sdcc/
2708 \newline
2709 lib/
2710 \emph on
2711 <model>
2712 \end_inset
2713 </cell>
2714 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2715 \begin_inset Text
2716
2717 \layout Standard
2718
2719 $SDCC_HOME
2720 \backslash
2721 lib
2722 \backslash
2723
2724 \emph on
2725
2726 \newline
2727 <model>
2728 \end_inset
2729 </cell>
2730 </row>
2731 <row topline="true">
2732 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2733 \begin_inset Text
2734
2735 \layout Standard
2736
2737 path(argv[0])/
2738 \newline
2739
2740 \emph on
2741 $BIN2DATADIR/
2742 \emph default
2743
2744 \newline
2745
2746 \emph on
2747 $LIB_DIR_SUFFIX/<model>
2748 \end_inset
2749 </cell>
2750 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2751 \begin_inset Text
2752
2753 \layout Standard
2754
2755 path(argv[0])/
2756 \newline
2757 ../sdcc/lib/
2758 \emph on
2759 <model>
2760 \newline
2761 \SpecialChar ~
2762 \SpecialChar ~
2763 \SpecialChar ~
2764 \SpecialChar ~
2765 \SpecialChar ~
2766 \SpecialChar ~
2767 \SpecialChar ~
2768 \SpecialChar ~
2769 \SpecialChar ~
2770 \SpecialChar ~
2771 \SpecialChar ~
2772 \SpecialChar ~
2773 \SpecialChar ~
2774 \SpecialChar ~
2775 \SpecialChar ~
2776 \SpecialChar ~
2777 \SpecialChar ~
2778 \SpecialChar ~
2779 \SpecialChar ~
2780 \SpecialChar ~
2781 \SpecialChar ~
2782 \SpecialChar ~
2783 \SpecialChar ~
2784 \SpecialChar ~
2785 \SpecialChar ~
2786 \SpecialChar ~
2787 \SpecialChar ~
2788 \SpecialChar ~
2789 \SpecialChar ~
2790 \SpecialChar ~
2791 \SpecialChar ~
2792 \SpecialChar ~
2793 \SpecialChar ~
2794 \SpecialChar ~
2795 \SpecialChar ~
2796 \SpecialChar ~
2797 \SpecialChar ~
2798 \SpecialChar ~
2799 \SpecialChar ~
2800
2801 \end_inset
2802 </cell>
2803 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2804 \begin_inset Text
2805
2806 \layout Standard
2807
2808 path(argv[0])
2809 \backslash
2810
2811 \newline
2812 ..
2813 \backslash
2814 lib
2815 \backslash
2816
2817 \emph on
2818 <model>
2819 \newline
2820 \SpecialChar ~
2821 \SpecialChar ~
2822 \SpecialChar ~
2823 \SpecialChar ~
2824 \SpecialChar ~
2825 \SpecialChar ~
2826 \SpecialChar ~
2827 \SpecialChar ~
2828 \SpecialChar ~
2829 \SpecialChar ~
2830 \SpecialChar ~
2831 \SpecialChar ~
2832 \SpecialChar ~
2833 \SpecialChar ~
2834 \SpecialChar ~
2835 \SpecialChar ~
2836 \SpecialChar ~
2837 \SpecialChar ~
2838 \SpecialChar ~
2839 \SpecialChar ~
2840 \SpecialChar ~
2841 \SpecialChar ~
2842 \SpecialChar ~
2843 \SpecialChar ~
2844 \SpecialChar ~
2845 \SpecialChar ~
2846 \SpecialChar ~
2847 \SpecialChar ~
2848 \SpecialChar ~
2849 \SpecialChar ~
2850 \SpecialChar ~
2851 \SpecialChar ~
2852 \SpecialChar ~
2853 \SpecialChar ~
2854 \SpecialChar ~
2855
2856 \end_inset
2857 </cell>
2858 </row>
2859 <row topline="true" bottomline="true">
2860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2861 \begin_inset Text
2862
2863 \layout Standard
2864
2865
2866 \emph on
2867 $DATADIR/
2868 \newline
2869 $LIB_DIR_SUFFIX/<model>
2870 \end_inset
2871 </cell>
2872 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2873 \begin_inset Text
2874
2875 \layout Standard
2876
2877 /usr/local/share/sdcc/
2878 \newline
2879 lib/
2880 \emph on
2881 <model>
2882 \end_inset
2883 </cell>
2884 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2885 \begin_inset Text
2886
2887 \layout Standard
2888
2889 (not on Win32)
2890 \end_inset
2891 </cell>
2892 </row>
2893 </lyxtabular>
2894
2895 \end_inset
2896
2897
2898 \newline
2899
2900 \layout Comment
2901
2902 Don't delete any of the stray spaces in the table above without checking
2903  the HTML output (last line)!
2904 \layout Standard
2905
2906 \SpecialChar ~
2907
2908 \newline
2909 The option -
2910 \begin_inset ERT
2911 status Collapsed
2912
2913 \layout Standard
2914
2915 \backslash
2916 /
2917 \end_inset
2918
2919 -nostdlib disables the last two search paths.
2920 \layout Section
2921
2922 Building SDCC
2923 \begin_inset LatexCommand \index{Building SDCC}
2924
2925 \end_inset
2926
2927
2928 \layout Subsection
2929
2930 Building SDCC on Linux
2931 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2932
2933 \end_inset
2934
2935
2936 \layout Enumerate
2937
2938
2939 \series medium
2940 Download the source package
2941 \series default
2942  either from the SDCC Subversion repository or from the nightly snapshots
2943 \series medium
2944 , it will be named something like sdcc
2945 \series default
2946 .src
2947 \series medium
2948 .t
2949 \series default
2950 ar.
2951 \series medium
2952 gz
2953 \series default
2954
2955 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2956
2957 \end_inset
2958
2959 .
2960 \layout Enumerate
2961
2962
2963 \series medium
2964 Bring up a command line terminal, such as xterm.
2965 \layout Enumerate
2966
2967
2968 \series medium
2969 Unpack the file using a command like:
2970 \family sans
2971 \series bold
2972 "tar -xvzf sdcc.src.tar.gz
2973 \family default
2974 \series default
2975 "
2976 \series medium
2977 , this will create a sub-directory called sdcc with all of the sources.
2978 \layout Enumerate
2979
2980 Change directory into the main SDCC directory, for example type:
2981 \family sans
2982 \series bold
2983 "cd sdcc
2984 \series default
2985 ".
2986 \layout Enumerate
2987
2988
2989 \series medium
2990 Type
2991 \family sans
2992 \series bold
2993 "./configure
2994 \family default
2995 \series default
2996 ".
2997  This configures the package for compilation on your system.
2998 \layout Enumerate
2999
3000
3001 \series medium
3002 Type
3003 \family sans
3004 \series bold
3005 "make
3006 \family default
3007 \series default
3008 "
3009 \series medium
3010 .
3011
3012 \series default
3013  All of the source packages will compile, this can take a while.
3014 \layout Enumerate
3015
3016
3017 \series medium
3018 Type
3019 \family sans
3020 \series bold
3021 "make install"
3022 \family default
3023 \series default
3024  as root
3025 \series medium
3026 .
3027
3028 \series default
3029  This copies the binary executables, the include files, the libraries and
3030  the documentation to the install directories.
3031  Proceed with section
3032 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
3033
3034 \end_inset
3035
3036 .
3037 \layout Subsection
3038
3039 Building SDCC on OSX 2.x
3040 \layout Standard
3041
3042 Follow the instruction for Linux.
3043 \newline
3044
3045 \newline
3046 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
3047 )) fails to compile SDCC.
3048  Fortunately there's also gcc 2.9.x installed, which works fine.
3049  This compiler can be selected by running 'configure' with:
3050 \layout LyX-Code
3051
3052 ./configure CC=gcc2 CXX=g++2
3053 \layout Subsection
3054
3055 Cross compiling SDCC on Linux for Windows
3056 \layout Standard
3057
3058 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
3059  See section 'Configure Options'.
3060 \layout Subsection
3061
3062 Building SDCC on Windows
3063 \layout Standard
3064
3065 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
3066  built on Windows.
3067  They use Unix-sockets, which are not available on Win32.
3068 \layout Subsection
3069
3070 Building SDCC using Cygwin and Mingw32
3071 \layout Standard
3072
3073 For building and installing a Cygwin executable follow the instructions
3074  for Linux.
3075 \newline
3076
3077 \newline
3078 On Cygwin a
3079 \begin_inset Quotes sld
3080 \end_inset
3081
3082 native
3083 \begin_inset Quotes srd
3084 \end_inset
3085
3086  Win32-binary can be built, which will not need the Cygwin-DLL.
3087  For the necessary 'configure' options see section 'configure options' or
3088  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3089 \newline
3090
3091 \newline
3092 In order to install Cygwin on Windows download setup.exe from
3093 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3094
3095 \end_inset
3096
3097 .
3098  Run it, set the
3099 \begin_inset Quotes sld
3100 \end_inset
3101
3102 default text file type
3103 \begin_inset Quotes srd
3104 \end_inset
3105
3106  to
3107 \begin_inset Quotes sld
3108 \end_inset
3109
3110 unix
3111 \begin_inset Quotes srd
3112 \end_inset
3113
3114  and download/install at least the following packages.
3115  Some packages are selected by default, others will be automatically selected
3116  because of dependencies with the manually selected packages.
3117  Never deselect these packages!
3118 \layout Itemize
3119
3120 flex
3121 \layout Itemize
3122
3123 bison
3124 \layout Itemize
3125
3126 gcc ; version 3.x is fine, no need to use the old 2.9x
3127 \layout Itemize
3128
3129 binutils ; selected with gcc
3130 \layout Itemize
3131
3132 make
3133 \layout Itemize
3134
3135 rxvt ; a nice console, which makes life much easier under windoze (see below)
3136 \layout Itemize
3137
3138 man ; not really needed for building SDCC, but you'll miss it sooner or
3139  later
3140 \layout Itemize
3141
3142 less ; not really needed for building SDCC, but you'll miss it sooner or
3143  later
3144 \layout Itemize
3145
3146 svn ; only if you use Subversion access
3147 \layout Standard
3148
3149 If you want to develop something you'll need:
3150 \layout Itemize
3151
3152 python ; for the regression tests
3153 \layout Itemize
3154
3155 gdb ; the gnu debugger, together with the nice GUI
3156 \begin_inset Quotes sld
3157 \end_inset
3158
3159 insight
3160 \begin_inset Quotes srd
3161 \end_inset
3162
3163
3164 \layout Itemize
3165
3166 openssh ; to access the CF or commit changes
3167 \layout Itemize
3168
3169 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3170  use autoconf-stable!
3171 \layout Standard
3172
3173 rxvt is a nice console with history.
3174  Replace in your cygwin.bat the line
3175 \layout LyX-Code
3176
3177 bash -
3178 \begin_inset ERT
3179 status Collapsed
3180
3181 \layout Standard
3182
3183 \backslash
3184 /
3185 \end_inset
3186
3187 -login -i
3188 \layout Standard
3189
3190 with (one line):
3191 \layout LyX-Code
3192
3193 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3194 \layout LyX-Code
3195
3196      -bg black -fg white -geometry 100x65 -e bash -
3197 \begin_inset ERT
3198 status Collapsed
3199
3200 \layout Standard
3201
3202 \backslash
3203 /
3204 \end_inset
3205
3206 -login
3207 \layout Standard
3208
3209 Text selected with the mouse is automatically copied to the clipboard, pasting
3210  works with shift-insert.
3211 \newline
3212
3213 \newline
3214 The other good tip is to make sure you have no //c/-style paths anywhere,
3215  use /cygdrive/c/ instead.
3216  Using // invokes a network lookup which is very slow.
3217  If you think
3218 \begin_inset Quotes sld
3219 \end_inset
3220
3221 cygdrive
3222 \begin_inset Quotes srd
3223 \end_inset
3224
3225  is too long, you can change it with e.g.
3226 \layout LyX-Code
3227
3228 mount -s -u -c /mnt
3229 \layout Standard
3230
3231 SDCC sources use the unix line ending LF.
3232  Life is much easier, if you store the source tree on a drive which is mounted
3233  in binary mode.
3234  And use an editor which can handle LF-only line endings.
3235  Make sure not to commit files with windows line endings.
3236  The tabulator spacing
3237 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3238
3239 \end_inset
3240
3241  used in the project is 8.
3242  Although a tabulator spacing of 8 is a sensible choice for programmers
3243  (it's a power of 2 and allows to display 8/16 bit signed variables without
3244  loosing columns) the plan is to move towards using only spaces in the source.
3245 \layout Subsection
3246
3247 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3248 \layout Standard
3249
3250
3251 \series medium
3252 Download the source package
3253 \series default
3254  either from the SDCC Subversion repository or from the
3255 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3256
3257 \end_inset
3258
3259
3260 \series medium
3261 , it will be named something like sdcc
3262 \series default
3263 .src
3264 \series medium
3265 .tgz.
3266
3267 \series default
3268  SDCC is distributed with all the projects, workspaces, and files you need
3269  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3270  doesn't build under MSVC).
3271  The workspace name is 'sdcc.dsw'.
3272  Please note that as it is now, all the executables are created in a folder
3273  called sdcc
3274 \backslash
3275 bin_vc.
3276  Once built you need to copy the executables from sdcc
3277 \backslash
3278 bin_vc to sdcc
3279 \backslash
3280 bin before running SDCC.
3281
3282 \newline
3283
3284 \newline
3285 WARNING: Visual studio is very picky with line terminations; it expects
3286  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3287  When using the Subversion repository it's easiest to configure the svn
3288  client to convert automatically for you.
3289  If however you are getting a message such as "This makefile was not generated
3290  by Developer Studio etc.
3291  etc.
3292 \begin_inset Quotes srd
3293 \end_inset
3294
3295  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3296  need to convert the Unix style line endings to DOS style line endings.
3297  To do so you can use the
3298 \begin_inset Quotes sld
3299 \end_inset
3300
3301 unix2dos
3302 \begin_inset Quotes srd
3303 \end_inset
3304
3305  utility freely available on the internet.
3306  Doug Hawkins reported in the sdcc-user list that this works:
3307 \newline
3308
3309 \newline
3310 C:
3311 \backslash
3312 Programming
3313 \backslash
3314 SDCC> unix2dos sdcc.dsw
3315 \newline
3316 C:
3317 \backslash
3318 Programming
3319 \backslash
3320 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3321 \newline
3322
3323 \newline
3324 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3325  flex.exe, and gawk.exe.
3326  One good place to get them is
3327 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3328
3329 \end_inset
3330
3331
3332 \newline
3333
3334 \newline
3335 Download the file UnxUtils
3336 \begin_inset LatexCommand \index{UnxUtils}
3337
3338 \end_inset
3339
3340 .zip.
3341  Now you have to install the utilities and setup MSVC so it can locate the
3342  required programs.
3343  Here there are two alternatives (choose one!):
3344 \layout Enumerate
3345
3346 The easy way:
3347 \newline
3348
3349 \newline
3350 a) Extract UnxUtils.zip to your C:
3351 \backslash
3352  hard disk PRESERVING the original paths, otherwise bison won't work.
3353  (If you are using WinZip make certain that 'Use folder names' is selected)
3354 \newline
3355
3356 \newline
3357 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3358  in 'Show directories for:' select 'Executable files', and in the directories
3359  window add a new path: 'C:
3360 \backslash
3361 user
3362 \backslash
3363 local
3364 \backslash
3365 wbin', click ok.
3366 \newline
3367
3368 \newline
3369 (As a side effect, you get a bunch of Unix utilities that could be useful,
3370  such as diff and patch.)
3371 \layout Enumerate
3372
3373 A more compact way:
3374 \newline
3375
3376 \newline
3377 This one avoids extracting a bunch of files you may not use, but requires
3378  some extra work:
3379 \newline
3380
3381 \newline
3382 a) Create a directory were to put the tools needed, or use a directory already
3383  present.
3384  Say for example 'C:
3385 \backslash
3386 util'.
3387 \newline
3388
3389 \newline
3390 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3391  to such directory WITHOUT preserving the original paths.
3392  (If you are using WinZip make certain that 'Use folder names' is not selected)
3393 \newline
3394
3395 \newline
3396 c) Rename bison.exe to '_bison.exe'.
3397 \newline
3398
3399 \newline
3400 d) Create a batch file 'bison.bat' in 'C:
3401 \backslash
3402 util
3403 \backslash
3404 ' and add these lines:
3405 \newline
3406 \SpecialChar ~
3407 \SpecialChar ~
3408 set BISON_SIMPLE=C:
3409 \backslash
3410 util
3411 \backslash
3412 bison.simple
3413 \newline
3414 \SpecialChar ~
3415 \SpecialChar ~
3416 set BISON_HAIRY=C:
3417 \backslash
3418 util
3419 \backslash
3420 bison.hairy
3421 \newline
3422 \SpecialChar ~
3423 \SpecialChar ~
3424 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3425 \newline
3426
3427 \newline
3428 Steps 'c' and 'd' are needed because bison requires by default that the
3429  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3430  '/usr/local/share/' I think.
3431  So it is necessary to tell bison where those files are located if they
3432  are not in such directory.
3433  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3434 \newline
3435
3436 \newline
3437 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3438  in 'Show directories for:' select 'Executable files', and in the directories
3439  window add a new path: 'c:
3440 \backslash
3441 util', click ok.
3442  Note that you can use any other path instead of 'c:
3443 \backslash
3444 util', even the path where the Visual C++ tools are, probably: 'C:
3445 \backslash
3446 Program Files
3447 \backslash
3448 Microsoft Visual Studio
3449 \backslash
3450 Common
3451 \backslash
3452 Tools'.
3453  So you don't have to execute step 'e' :)
3454 \layout Standard
3455
3456 That is it.
3457  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3458  the executables from sdcc
3459 \backslash
3460 bin_vc to sdcc
3461 \backslash
3462 bin, and you can compile using SDCC.
3463 \layout Subsection
3464
3465 Building SDCC Using Borland
3466 \layout Enumerate
3467
3468 From the sdcc directory, run the command "make -f Makefile.bcc".
3469  This should regenerate all the .exe files in the bin directory except for
3470  sdcdb.exe (which currently doesn't build under Borland C++).
3471 \layout Enumerate
3472
3473 If you modify any source files and need to rebuild, be aware that the dependenci
3474 es may not be correctly calculated.
3475  The safest option is to delete all .obj files and run the build again.
3476  From a Cygwin BASH prompt, this can easily be done with the command (be
3477  sure you are in the sdcc directory):
3478 \newline
3479
3480 \newline
3481
3482 \family sans
3483 \series bold
3484 find .
3485
3486 \backslash
3487 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3488 \backslash
3489 ) -print -exec rm {}
3490 \backslash
3491 ;
3492 \family default
3493 \series default
3494
3495 \newline
3496
3497 \newline
3498 or on Windows NT/2000/XP from the command prompt with the command:
3499 \newline
3500
3501 \family sans
3502 \series bold
3503
3504 \newline
3505 del /s *.obj *.lib *.rul
3506 \family default
3507 \series default
3508  from the sdcc directory.
3509 \layout Subsection
3510
3511 Windows Install Using a ZIP Package
3512 \layout Enumerate
3513
3514 Download the binary zip package from
3515 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3516
3517 \end_inset
3518
3519  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3520  This should unpack to a group of sub-directories.
3521  An example directory structure after unpacking the mingw32 package is:
3522  c:
3523 \backslash
3524 sdcc
3525 \backslash
3526 bin for the executables, c:
3527 \backslash
3528 sdcc
3529 \backslash
3530 include and c:
3531 \backslash
3532 sdcc
3533 \backslash
3534 lib for the include and libraries.
3535 \layout Enumerate
3536
3537 Adjust your environment variable PATH to include the location of the bin
3538  directory or start sdcc using the full path.
3539 \layout Subsection
3540
3541 Windows Install Using the Setup Program
3542 \begin_inset LatexCommand \label{sub:Windows-Install}
3543
3544 \end_inset
3545
3546
3547 \layout Standard
3548
3549 Download the setup program
3550 \emph on
3551 sdcc-x.y.z-setup.exe
3552 \emph default
3553  for an official release from
3554 \newline
3555
3556 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3557
3558 \end_inset
3559
3560  or a setup program for one of the snapshots
3561 \emph on
3562 sdcc_yyyymmdd_setup.exe
3563 \emph default
3564  from
3565 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3566
3567 \end_inset
3568
3569  and execute it.
3570  A windows typical installer will guide you through the installation process.
3571 \layout Subsection
3572
3573 VPATH
3574 \begin_inset LatexCommand \index{VPATH}
3575
3576 \end_inset
3577
3578  feature
3579 \layout Standard
3580
3581 SDCC supports the VPATH feature provided by configure and make.
3582  It allows to separate the source and build trees.
3583  Here's an example:
3584 \layout Standard
3585
3586
3587 \family typewriter
3588 cd ~\SpecialChar ~
3589 \SpecialChar ~
3590 \SpecialChar ~
3591 \SpecialChar ~
3592 \SpecialChar ~
3593 \SpecialChar ~
3594 \SpecialChar ~
3595 \SpecialChar ~
3596 \SpecialChar ~
3597 \SpecialChar ~
3598 \SpecialChar ~
3599 \SpecialChar ~
3600 \SpecialChar ~
3601 \SpecialChar ~
3602 \SpecialChar ~
3603 \SpecialChar ~
3604 \SpecialChar ~
3605 \SpecialChar ~
3606 \SpecialChar ~
3607 \SpecialChar ~
3608 \SpecialChar ~
3609 # cd $HOME
3610 \layout Standard
3611
3612
3613 \family typewriter
3614 tar -xzf sdcc.src.tar.gz\SpecialChar ~
3615 # extract source to directory sdcc
3616 \layout Standard
3617
3618
3619 \family typewriter
3620 mkdir sdcc.build\SpecialChar ~
3621 \SpecialChar ~
3622 \SpecialChar ~
3623 \SpecialChar ~
3624 \SpecialChar ~
3625 \SpecialChar ~
3626 \SpecialChar ~
3627 \SpecialChar ~
3628 \SpecialChar ~
3629 # put output in sdcc.build
3630 \layout Standard
3631
3632
3633 \family typewriter
3634 cd sdcc.build
3635 \layout Standard
3636
3637
3638 \family typewriter
3639 ../sdcc/configure\SpecialChar ~
3640 \SpecialChar ~
3641 \SpecialChar ~
3642 \SpecialChar ~
3643 \SpecialChar ~
3644 \SpecialChar ~
3645 \SpecialChar ~
3646 \SpecialChar ~
3647 # configure is doing all the magic!
3648 \layout Standard
3649
3650
3651 \family typewriter
3652 make
3653 \layout Standard
3654 \noindent
3655 That's it!
3656 \series bold
3657 configure
3658 \series default
3659  will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
3660  It automagically computes the variables srcdir, top_srcdir and top_buildir
3661  for each directory.
3662  After running
3663 \series bold
3664 make
3665 \series default
3666  the generated files will be in ~/sdcc.build, while the source files stay
3667  in ~/sdcc.
3668 \newline
3669 This is not only usefull for building different binaries, e.g.
3670  when cross compiling.
3671  It also gives you a much better overview in the source tree when all the
3672  generated files are not scattered between the source files.
3673  And the best thing is: if you want to change a file you can leave the original
3674  file untouched in the source directory.
3675  Simply copy it to the build directory, edit it, enter `make clean`, `rm
3676  Makefile.dep` and `make`.
3677
3678 \series bold
3679 make
3680 \series default
3681  will do the rest for you!
3682 \layout Section
3683
3684 Building the Documentation
3685 \layout Standard
3686
3687 Add -
3688 \begin_inset ERT
3689 status Collapsed
3690
3691 \layout Standard
3692
3693 \backslash
3694 /
3695 \end_inset
3696
3697 -enable-doc to the configure arguments to build the documentation together
3698  with all the other stuff.
3699  You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
3700  dvips and makeindex) to get the job done.
3701  Another possibility is to change to the doc directory and to type
3702 \family sans
3703 \series bold
3704
3705 \begin_inset Quotes srd
3706 \end_inset
3707
3708 make
3709 \begin_inset Quotes srd
3710 \end_inset
3711
3712
3713 \family default
3714 \series default
3715  there.
3716  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3717 x).
3718  Using LyX
3719 \begin_inset LatexCommand \url{http://www.lyx.org}
3720
3721 \end_inset
3722
3723  as editor is straightforward.
3724  Prebuilt documentation in html and pdf format is available from
3725 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3726
3727 \end_inset
3728
3729 .
3730 \layout Section
3731
3732 Reading the Documentation
3733 \layout Standard
3734
3735 Currently reading the document in pdf format is recommended, as for unknown
3736  reason the hyperlinks are working there whereas in the html version they
3737  are not
3738 \begin_inset Foot
3739 collapsed false
3740
3741 \layout Standard
3742
3743 If you should know why please drop us a note
3744 \end_inset
3745
3746 .
3747
3748 \newline
3749 You'll find the pdf version
3750 \begin_inset LatexCommand \index{PDF version of this document}
3751
3752 \end_inset
3753
3754  at
3755 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
3756
3757 \end_inset
3758
3759 .
3760
3761 \newline
3762 A html version
3763 \begin_inset LatexCommand \index{HTML version of this document}
3764
3765 \end_inset
3766
3767  should be online at
3768 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
3769
3770 \end_inset
3771
3772 .
3773 \newline
3774 This documentation is in some aspects different from a commercial documentation:
3775
3776 \layout Itemize
3777
3778 It tries to document SDCC for several processor architectures in one document
3779  (commercially these probably would be separate documents/products).
3780  This document
3781 \begin_inset LatexCommand \index{Status of documentation}
3782
3783 \end_inset
3784
3785  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3786 on about f.e.
3787  Z80, PIC14, PIC16 and HC08.
3788 \layout Itemize
3789
3790 There are many references pointing away from this documentation.
3791  Don't let this distract you.
3792  If there f.e.
3793  was a reference like
3794 \begin_inset LatexCommand \url{http://www.opencores.org}
3795
3796 \end_inset
3797
3798  together with a statement
3799 \begin_inset Quotes sld
3800 \end_inset
3801
3802 some processors which are targetted by SDCC can be implemented in a
3803 \emph on
3804 f
3805 \emph default
3806 ield
3807 \emph on
3808 p
3809 \emph default
3810 rogrammable
3811 \emph on
3812 g
3813 \emph default
3814 ate
3815 \emph on
3816 a
3817 \emph default
3818 rray
3819 \begin_inset LatexCommand \index{FPGA (field programmable gate array)}
3820
3821 \end_inset
3822
3823
3824 \begin_inset Quotes srd
3825 \end_inset
3826
3827  or
3828 \begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
3829
3830 \end_inset
3831
3832
3833 \begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
3834
3835 \end_inset
3836
3837
3838 \begin_inset Quotes sld
3839 \end_inset
3840
3841 have you ever heard of an open source compiler that compiles a subset of
3842  C for an FPGA?
3843 \begin_inset Quotes srd
3844 \end_inset
3845
3846  we expect you to have a quick look there and come back.
3847  If you read this you are on the right track.
3848 \layout Itemize
3849
3850 Some sections attribute more space to problems, restrictions and warnings
3851  than to the solution.
3852 \layout Itemize
3853
3854 The installation section and the section about the debugger is intimidating.
3855 \layout Itemize
3856
3857 There are still lots of typos and there are more different writing styles
3858  than pictures.
3859 \layout Section
3860
3861 Testing the SDCC Compiler
3862 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3863
3864 \end_inset
3865
3866
3867 \layout Standard
3868
3869 The first thing you should do after installing your SDCC compiler is to
3870  see if it runs.
3871  Type
3872 \family sans
3873 \series bold
3874 "sdcc -
3875 \begin_inset ERT
3876 status Collapsed
3877
3878 \layout Standard
3879
3880 \backslash
3881 /
3882 \end_inset
3883
3884 -version"
3885 \begin_inset LatexCommand \index{version}
3886
3887 \end_inset
3888
3889
3890 \family default
3891 \series default
3892  at the prompt, and the program should run and tell you the version.
3893  If it doesn't run, or gives a message about not finding sdcc program, then
3894  you need to check over your installation.
3895  Make sure that the sdcc bin directory is in your executable search path
3896  defined by the PATH environment setting (
3897 \series medium
3898 see
3899 \series default
3900 section
3901 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3902
3903 \end_inset
3904
3905 \SpecialChar ~
3906
3907 \series medium
3908 Install trouble-shooting for suggestions
3909 \series default
3910 ).
3911  Make sure that the sdcc program is in the bin folder, if not perhaps something
3912  did not install correctly.
3913 \newline
3914
3915 \newline
3916
3917 \series medium
3918 SDCC
3919 \series default
3920 is commonly installed as described in section
3921 \begin_inset Quotes sld
3922 \end_inset
3923
3924 Install and search paths
3925 \begin_inset Quotes srd
3926 \end_inset
3927
3928 .
3929 \newline
3930
3931 \newline
3932
3933 \series medium
3934 Make sure the compiler works on a very simple example.
3935  Type in the following test.c program using your favorite
3936 \series default
3937 ASCII
3938 \series medium
3939 editor:
3940 \layout Verse
3941
3942
3943 \family typewriter
3944 char test;
3945 \newline
3946
3947 \newline
3948 void main(void) {
3949 \newline
3950 \SpecialChar ~
3951 \SpecialChar ~
3952 \SpecialChar ~
3953 \SpecialChar ~
3954 test=0;
3955 \newline
3956 }
3957 \layout Standard
3958
3959
3960 \series medium
3961 Compile this using the following command:
3962 \family sans
3963 \series bold
3964 "sdcc -c test.c".
3965
3966 \family default
3967 \series default
3968
3969 \series medium
3970 If all goes well, the compiler will generate a test.asm and test.rel file.
3971  Congratulations, you've just compiled your first program with SDCC.
3972  We used the -c option to tell SDCC not to link the generated code, just
3973  to keep things simple for this step.
3974 \series default
3975
3976 \newline
3977
3978 \newline
3979
3980 \series medium
3981 The next step is to try it with the linker.
3982  Type in
3983 \family sans
3984 \series bold
3985 "sdcc test.c
3986 \family default
3987 \series default
3988 "
3989 \series medium
3990 .
3991  If all goes well the compiler will link with the libraries and produce
3992  a test.ihx output file.
3993  If this step fails
3994 \series default
3995
3996 \series medium
3997 (no test.ihx, and the linker generates warnings), then the problem is most
3998  likely that
3999 \series default
4000 SDCC
4001 \series medium
4002  cannot find the
4003 \series default
4004 /
4005 \series medium
4006 usr/local/share/sdcc/lib directory
4007 \series default
4008
4009 \series medium
4010 (see
4011 \series default
4012 section
4013 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4014
4015 \end_inset
4016
4017 \SpecialChar ~
4018
4019 \series medium
4020 Install trouble-shooting for suggestions).
4021 \series default
4022
4023 \newline
4024
4025 \newline
4026
4027 \series medium
4028 The final test is to ensure
4029 \series default
4030 SDCC
4031 \series medium
4032  can use the
4033 \series default
4034 standard
4035 \series medium
4036  header files and libraries.
4037  Edit test.c and change it to the following:
4038 \layout Verse
4039
4040
4041 \family typewriter
4042 #include <string.h>
4043 \newline
4044
4045 \newline
4046 char str1[10];
4047 \newline
4048
4049 \newline
4050 void main(void) {
4051 \newline
4052 \SpecialChar ~
4053 \SpecialChar ~
4054 strcpy(str1, "testing");
4055 \newline
4056 }
4057 \layout Standard
4058
4059
4060 \series medium
4061 Compile this by typing
4062 \family sans
4063 \series bold
4064 "sdcc test.c"
4065 \family default
4066 \series medium
4067 .
4068  This should generate a test.ihx output file, and it should give no warnings
4069  such as not finding the string.h file.
4070  If it cannot find the string.h file, then the problem is that
4071 \series default
4072 SDCC
4073 \series medium
4074  cannot find the /usr/local/share/sdcc/include directory
4075 \series default
4076
4077 \series medium
4078 (see the
4079 \series default
4080 section
4081 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4082
4083 \end_inset
4084
4085 \SpecialChar ~
4086
4087 \series medium
4088 Install trouble-shooting section for suggestions).
4089
4090 \series default
4091  Use option
4092 \series bold
4093 -
4094 \begin_inset ERT
4095 status Collapsed
4096
4097 \layout Standard
4098
4099 \backslash
4100 /
4101 \end_inset
4102
4103 -print-search-dirs
4104 \series default
4105
4106 \begin_inset LatexCommand \index{-\/-print-search-dirs}
4107
4108 \end_inset
4109
4110  to find exactly where SDCC is looking for the include and lib files.
4111 \layout Section
4112
4113 Install Trouble-shooting
4114 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
4115
4116 \end_inset
4117
4118
4119 \begin_inset LatexCommand \index{Install trouble-shooting}
4120
4121 \end_inset
4122
4123
4124 \layout Subsection
4125
4126 If SDCC does not build correctly
4127 \layout Standard
4128
4129 A thing to try is starting from scratch by unpacking the .tgz source package
4130  again in an empty directory.
4131  Configure it like:
4132 \newline
4133
4134 \newline
4135
4136 \family sans
4137 \series bold
4138 ./configure 2>&1 | tee configure.log
4139 \family default
4140 \series default
4141
4142 \newline
4143
4144 \newline
4145 and build it like:
4146 \newline
4147
4148 \newline
4149
4150 \family sans
4151 \series bold
4152 make 2>&1 | tee make.log
4153 \family default
4154 \series default
4155
4156 \newline
4157
4158 \newline
4159 If anything goes wrong, you can review the log files to locate the problem.
4160  Or a relevant part of this can be attached to an email that could be helpful
4161  when requesting help from the mailing list.
4162 \layout Subsection
4163
4164 What the
4165 \begin_inset Quotes sld
4166 \end_inset
4167
4168 ./configure
4169 \begin_inset Quotes srd
4170 \end_inset
4171
4172  does
4173 \layout Standard
4174
4175 The
4176 \begin_inset Quotes sld
4177 \end_inset
4178
4179 ./configure
4180 \begin_inset Quotes srd
4181 \end_inset
4182
4183  command is a script that analyzes your system and performs some configuration
4184  to ensure the source package compiles on your system.
4185  It will take a few minutes to run, and will compile a few tests to determine
4186  what compiler features are installed.
4187 \layout Subsection
4188
4189 What the
4190 \begin_inset Quotes sld
4191 \end_inset
4192
4193 make
4194 \begin_inset Quotes srd
4195 \end_inset
4196
4197  does
4198 \layout Standard
4199
4200 This runs the GNU make tool, which automatically compiles all the source
4201  packages into the final installed binary executables.
4202 \layout Subsection
4203
4204 What the
4205 \begin_inset Quotes sld
4206 \end_inset
4207
4208 make install
4209 \begin_inset Quotes erd
4210 \end_inset
4211
4212  command does.
4213 \layout Standard
4214
4215 This will install the compiler, other executables libraries and include
4216  files into the appropriate directories.
4217  See sections
4218 \begin_inset LatexCommand \ref{sub:Install-paths}
4219
4220 \end_inset
4221
4222 ,\SpecialChar ~
4223
4224 \begin_inset LatexCommand \ref{sub:Search-Paths}
4225
4226 \end_inset
4227
4228 \SpecialChar ~
4229 about install and search paths.
4230 \newline
4231 On most systems you will need super-user privileges to do this.
4232 \layout Section
4233
4234 Components of SDCC
4235 \layout Standard
4236
4237 SDCC is not just a compiler, but a collection of tools by various developers.
4238  These include linkers, assemblers, simulators and other components.
4239  Here is a summary of some of the components.
4240  Note that the included simulator and assembler have separate documentation
4241  which you can find in the source package in their respective directories.
4242  As SDCC grows to include support for other processors, other packages from
4243  various developers are included and may have their own sets of documentation.
4244 \newline
4245
4246 \newline
4247 You might want to look at the files which are installed in <installdir>.
4248  At the time of this writing, we find the following programs for gcc-builds:
4249 \newline
4250
4251 \newline
4252 In <installdir>/bin:
4253 \layout Itemize
4254
4255 sdcc - The compiler.
4256 \layout Itemize
4257
4258 sdcpp - The C preprocessor.
4259 \layout Itemize
4260
4261 asx8051 - The assembler for 8051 type processors.
4262 \layout Itemize
4263
4264 as-z80
4265 \series bold
4266 ,
4267 \series default
4268 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4269 \layout Itemize
4270
4271 aslink -The linker for 8051 type processors.
4272 \layout Itemize
4273
4274 link-z80
4275 \series bold
4276 ,
4277 \series default
4278 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4279 \layout Itemize
4280
4281 s51 - The ucSim 8051 simulator.
4282  Not available on Win32 platforms.
4283 \layout Itemize
4284
4285 sdcdb - The source debugger.
4286  Not available on Win32 platforms.
4287 \layout Itemize
4288
4289 packihx - A tool to pack (compress) Intel hex files.
4290 \layout Standard
4291
4292 In <installdir>/share/sdcc/include
4293 \layout Itemize
4294
4295 the include files
4296 \layout Standard
4297
4298 In <installdir>/share/sdcc/lib
4299 \layout Itemize
4300
4301 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4302  relocatables.
4303 \layout Standard
4304
4305 In <installdir>/share/sdcc/doc
4306 \layout Itemize
4307
4308 the documentation
4309 \layout Standard
4310
4311 As development for other processors proceeds, this list will expand to include
4312  executables to support processors like AVR, PIC, etc.
4313 \layout Subsection
4314
4315 sdcc - The Compiler
4316 \layout Standard
4317
4318 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4319  the assembler and linkage editor.
4320 \layout Subsection
4321
4322 sdcpp - The C-Preprocessor
4323 \layout Standard
4324
4325 The preprocessor
4326 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4327
4328 \end_inset
4329
4330  is a modified version of the GNU preprocessor.
4331  The C preprocessor is used to pull in #include sources, process #ifdef
4332  statements, #defines and so on.
4333 \layout Subsection
4334
4335 as
4336 \emph on
4337 xxxx
4338 \emph default
4339 , aslink, link-
4340 \emph on
4341 xxx
4342 \emph default
4343  - The Assemblers and Linkage Editors
4344 \layout Standard
4345
4346 This is retargettable assembler & linkage editor, it was developed by Alan
4347  Baldwin.
4348  John Hartman created the version for 8051, and I (Sandeep) have made some
4349  enhancements and bug fixes for it to work properly with SDCC.
4350 \layout Subsection
4351
4352 s51 - The Simulator
4353 \layout Standard
4354
4355 S51
4356 \begin_inset LatexCommand \index{s51}
4357
4358 \end_inset
4359
4360  is a freeware, opensource simulator developed by Daniel Drotos.
4361  The simulator is built as part of the build process.
4362  For more information visit Daniel's web site at:
4363 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4364
4365 \end_inset
4366
4367 .
4368  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4369  XA51 family.
4370  S51 is currently not available on Win32 platfors.
4371 \layout Subsection
4372
4373 sdcdb - Source Level Debugger
4374 \layout Standard
4375
4376 Sdcdb
4377 \begin_inset LatexCommand \index{sdcdb (debugger)}
4378
4379 \end_inset
4380
4381  is the companion source level debugger.
4382  More about sdcdb in section
4383 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4384
4385 \end_inset
4386
4387 .
4388  The current version of the debugger uses Daniel's Simulator S51
4389 \begin_inset LatexCommand \index{s51}
4390
4391 \end_inset
4392
4393 , but can be easily changed to use other simulators.
4394  Sdcdb is currently not available on Win32 platfors.
4395 \layout Chapter
4396
4397 Using SDCC
4398 \layout Section
4399
4400 Compiling
4401 \layout Subsection
4402
4403 Single Source File Projects
4404 \layout Standard
4405
4406 For single source file 8051 projects the process is very simple.
4407  Compile your programs with the following command
4408 \family sans
4409 \series bold
4410 "sdcc sourcefile.c".
4411
4412 \family default
4413 \series default
4414  This will compile, assemble and link your source file.
4415  Output files are as follows:
4416 \layout Itemize
4417
4418 sourcefile.asm
4419 \begin_inset LatexCommand \index{<file>.asm}
4420
4421 \end_inset
4422
4423  - Assembler source
4424 \begin_inset LatexCommand \index{Assembler source}
4425
4426 \end_inset
4427
4428  file created by the compiler
4429 \layout Itemize
4430
4431 sourcefile.lst
4432 \begin_inset LatexCommand \index{<file>.lst}
4433
4434 \end_inset
4435
4436  - Assembler listing
4437 \begin_inset LatexCommand \index{Assembler listing}
4438
4439 \end_inset
4440
4441  file created by the Assembler
4442 \layout Itemize
4443
4444 sourcefile.rst
4445 \begin_inset LatexCommand \index{<file>.rst}
4446
4447 \end_inset
4448
4449  - Assembler listing
4450 \begin_inset LatexCommand \index{Assembler listing}
4451
4452 \end_inset
4453
4454  file updated with linkedit information, created by linkage editor
4455 \layout Itemize
4456
4457 sourcefile.sym
4458 \begin_inset LatexCommand \index{<file>.sym}
4459
4460 \end_inset
4461
4462  - symbol listing
4463 \begin_inset LatexCommand \index{Symbol listing}
4464
4465 \end_inset
4466
4467  for the sourcefile, created by the assembler
4468 \layout Itemize
4469
4470 sourcefile.rel
4471 \begin_inset LatexCommand \index{<file>.rel}
4472
4473 \end_inset
4474
4475  or sourcefile.o
4476 \begin_inset LatexCommand \index{<file>.o}
4477
4478 \end_inset
4479
4480  - Object file
4481 \begin_inset LatexCommand \index{Object file}
4482
4483 \end_inset
4484
4485  created by the assembler, input to Linkage editor
4486 \layout Itemize
4487
4488 sourcefile.map
4489 \begin_inset LatexCommand \index{<file>.map}
4490
4491 \end_inset
4492
4493  - The memory map
4494 \begin_inset LatexCommand \index{Memory map}
4495
4496 \end_inset
4497
4498  for the load module, created by the Linker
4499 \layout Itemize
4500
4501 sourcefile.mem
4502 \begin_inset LatexCommand \index{<file>.mem}
4503
4504 \end_inset
4505
4506  - A file with a summary of the memory usage
4507 \layout Itemize
4508
4509 sourcefile.ihx
4510 \begin_inset LatexCommand \index{<file>.ihx}
4511
4512 \end_inset
4513
4514  - The load module in Intel hex format
4515 \begin_inset LatexCommand \index{Intel hex format}
4516
4517 \end_inset
4518
4519  (you can select the Motorola S19 format
4520 \begin_inset LatexCommand \index{Motorola S19 format}
4521
4522 \end_inset
4523
4524  with -
4525 \begin_inset ERT
4526 status Collapsed
4527
4528 \layout Standard
4529
4530 \backslash
4531 /
4532 \end_inset
4533
4534 -out-fmt-s19
4535 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4536
4537 \end_inset
4538
4539 .
4540  If you need another format you might want to use
4541 \family sans
4542 \shape italic
4543 objdump
4544 \family default
4545 \shape default
4546
4547 \begin_inset LatexCommand \index{objdump (tool)}
4548
4549 \end_inset
4550
4551  or
4552 \family sans
4553 \shape italic
4554  srecord
4555 \family default
4556 \shape default
4557
4558 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4559
4560 \end_inset
4561
4562 ).
4563  Both formats are documented in the documentation of srecord
4564 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4565
4566 \end_inset
4567
4568
4569 \layout Itemize
4570
4571 sourcefile.adb
4572 \begin_inset LatexCommand \index{<file>.adb}
4573
4574 \end_inset
4575
4576  - An intermediate file containing debug information needed to create the
4577  .cdb file (with -
4578 \begin_inset ERT
4579 status Open
4580
4581 \layout Standard
4582
4583 \backslash
4584 /
4585 \end_inset
4586
4587 -debug
4588 \begin_inset LatexCommand \index{-\/-debug}
4589
4590 \end_inset
4591
4592 )
4593 \layout Itemize
4594
4595 sourcefile.cdb
4596 \begin_inset LatexCommand \index{<file>.cdb}
4597
4598 \end_inset
4599
4600  - An optional file (with -
4601 \begin_inset ERT
4602 status Collapsed
4603
4604 \layout Standard
4605
4606 \backslash
4607 /
4608 \end_inset
4609
4610 -debug) containing debug information.
4611  The format is documented in cdbfileformat.pdf
4612 \layout Itemize
4613
4614 sourcefile.
4615  - (no extension)
4616 \begin_inset LatexCommand \index{<file> (no extension)}
4617
4618 \end_inset
4619
4620  An optional AOMF or AOMF51
4621 \begin_inset LatexCommand \index{AOMF, AOMF51}
4622
4623 \end_inset
4624
4625  file containing debug information (generated with option -
4626 \begin_inset ERT
4627 status Collapsed
4628
4629 \layout Standard
4630
4631 \backslash
4632 /
4633 \end_inset
4634
4635 -debug).
4636  The (Intel)
4637 \emph on
4638  a
4639 \emph default
4640 bsolute
4641 \emph on
4642 o
4643 \emph default
4644 bject
4645 \emph on
4646 m
4647 \emph default
4648 odule
4649 \emph on
4650 f
4651 \emph default
4652 ormat is commonly used by third party tools (debuggers
4653 \begin_inset LatexCommand \index{Debugger}
4654
4655 \end_inset
4656
4657 , simulators, emulators)
4658 \layout Itemize
4659
4660 sourcefile.dump*
4661 \begin_inset LatexCommand \index{<file>.dump*}
4662
4663 \end_inset
4664
4665  - Dump file to debug the compiler it self (generated with option -
4666 \begin_inset ERT
4667 status Collapsed
4668
4669 \layout Standard
4670
4671 \backslash
4672 /
4673 \end_inset
4674
4675 -dumpall) (see section
4676 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4677
4678 \end_inset
4679
4680 \SpecialChar ~
4681  and section
4682 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4683
4684 \end_inset
4685
4686 \SpecialChar ~
4687
4688 \begin_inset Quotes sld
4689 \end_inset
4690
4691 Anatomy of the compiler
4692 \begin_inset Quotes srd
4693 \end_inset
4694
4695 ).
4696 \layout Subsection
4697
4698 Projects with Multiple Source Files
4699 \layout Standard
4700
4701 SDCC can compile only ONE file at a time.
4702  Let us for example assume that you have a project containing the following
4703  files:
4704 \newline
4705
4706 \newline
4707 foo1.c (contains some functions)
4708 \newline
4709 foo2.c (contains some more functions)
4710 \newline
4711 foomain.c (contains more functions and the function main)
4712 \newline
4713
4714 \size footnotesize
4715
4716 \newline
4717
4718 \size default
4719 The first two files will need to be compiled separately with the commands:
4720 \size footnotesize
4721
4722 \size default
4723
4724 \newline
4725
4726 \newline
4727
4728 \family sans
4729 \series bold
4730 sdcc\SpecialChar ~
4731 -c\SpecialChar ~
4732 foo1.c
4733 \family default
4734 \series default
4735 \size footnotesize
4736
4737 \newline
4738
4739 \family sans
4740 \series bold
4741 \size default
4742 sdcc\SpecialChar ~
4743 -c\SpecialChar ~
4744 foo2.c
4745 \family default
4746 \series default
4747
4748 \newline
4749
4750 \newline
4751 Then compile the source file containing the
4752 \emph on
4753 main()
4754 \emph default
4755  function and link
4756 \begin_inset LatexCommand \index{Linker}
4757
4758 \end_inset
4759
4760  the files together with the following command:
4761 \newline
4762
4763 \newline
4764
4765 \family sans
4766 \series bold
4767 sdcc\SpecialChar ~
4768 foomain.c\SpecialChar ~
4769 foo1.rel\SpecialChar ~
4770 foo2.rel
4771 \family default
4772 \series default
4773
4774 \begin_inset LatexCommand \index{<file>.rel}
4775
4776 \end_inset
4777
4778
4779 \newline
4780
4781 \newline
4782 Alternatively,
4783 \emph on
4784 foomain.c
4785 \emph default
4786 can be separately compiled as well:
4787 \family sans
4788 \series bold
4789
4790 \newline
4791
4792 \newline
4793 sdcc\SpecialChar ~
4794 -c\SpecialChar ~
4795 foomain.c
4796 \newline
4797 sdcc foomain.rel foo1.rel foo2.rel
4798 \newline
4799
4800 \newline
4801
4802 \family default
4803 \series default
4804 The file containing the
4805 \emph on
4806 main()
4807 \emph default
4808  function
4809 \emph on
4810
4811 \emph default
4812 \noun on
4813 must
4814 \noun default
4815  be the
4816 \noun on
4817 first
4818 \noun default
4819  file specified in the command line, since the linkage editor processes
4820  file in the order they are presented to it.
4821  The linker is invoked from SDCC using a script file with extension .lnk
4822 \begin_inset LatexCommand \index{<file>.lnk}
4823
4824 \end_inset
4825
4826 .
4827  You can view this file to troubleshoot linking problems such as those arising
4828  from missing libraries.
4829 \layout Subsection
4830
4831 Projects with Additional Libraries
4832 \begin_inset LatexCommand \index{Libraries}
4833
4834 \end_inset
4835
4836
4837 \layout Standard
4838
4839 Some reusable routines may be compiled into a library, see the documentation
4840  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4841  for how to create a
4842 \emph on
4843 .lib
4844 \begin_inset LatexCommand \index{<file>.lib}
4845
4846 \end_inset
4847
4848
4849 \emph default
4850  library file.
4851  Libraries created in this manner can be included in the command line.
4852  Make sure you include the -L <library-path> option to tell the linker where
4853  to look for these files if they are not in the current directory.
4854  Here is an example, assuming you have the source file
4855 \emph on
4856 foomain.c
4857 \emph default
4858  and a library
4859 \emph on
4860  foolib.lib
4861 \emph default
4862  in the directory
4863 \emph on
4864 mylib
4865 \emph default
4866  (if that is not the same as your current project):
4867 \newline
4868
4869 \newline
4870
4871 \family sans
4872 \series bold
4873 sdcc foomain.c foolib.lib -L mylib
4874 \newline
4875
4876 \newline
4877
4878 \family default
4879 \series default
4880 Note here that
4881 \emph on
4882  mylib
4883 \emph default
4884  must be an absolute path name.
4885 \newline
4886
4887 \newline
4888 The most efficient way to use libraries is to keep separate modules in separate
4889  source files.
4890  The lib file now should name all the modules.rel
4891 \begin_inset LatexCommand \index{<file>.rel}
4892
4893 \end_inset
4894
4895  files.
4896  For an example see the standard library file
4897 \emph on
4898 libsdcc.lib
4899 \emph default
4900  in the directory <installdir>/share/lib/small.
4901 \layout Subsection
4902
4903 Using sdcclib to Create and Manage Libraries
4904 \begin_inset LatexCommand \index{sdcclib}
4905
4906 \end_inset
4907
4908
4909 \layout Standard
4910
4911 Alternatively, instead of having a .rel file for each entry on the library
4912  file as described in the preceding section, sdcclib can be used to embed
4913  all the modules belonging to such library in the library file itself.
4914  This results in a larger library file, but it greatly reduces the number
4915  of disk files accessed by the linker.
4916   Additionally, the packed library file contains an index of all include
4917  modules and symbols that significantly speeds up the linking process.
4918  To display a list of options supported by sdcclib type:
4919 \newline
4920
4921 \layout Standard
4922
4923
4924 \family sans
4925 \series bold
4926 sdcclib -?
4927 \begin_inset LatexCommand \index{sdcclib}
4928
4929 \end_inset
4930
4931
4932 \newline
4933
4934 \newline
4935
4936 \family default
4937 \series default
4938 To create a new library file, start by compiling all the required modules.
4939  For example:
4940 \newline
4941
4942 \layout Standard
4943
4944
4945 \family sans
4946 \series bold
4947 sdcc -c _divsint.c
4948 \layout Standard
4949
4950
4951 \family sans
4952 \series bold
4953 sdcc -c _divuint.c
4954 \layout Standard
4955
4956
4957 \family sans
4958 \series bold
4959 sdcc -c _modsint.c
4960 \layout Standard
4961
4962
4963 \family sans
4964 \series bold
4965 sdcc -c _moduint.c
4966 \layout Standard
4967
4968
4969 \family sans
4970 \series bold
4971 sdcc -c _mulint.c
4972 \newline
4973
4974 \layout Standard
4975
4976 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4977  and _mulint.rel.
4978  The next step is to add the .rel files to the library file:
4979 \newline
4980
4981 \layout Standard
4982
4983
4984 \family sans
4985 \series bold
4986 sdcclib libint.lib _divsint.rel
4987 \family default
4988
4989 \begin_inset LatexCommand \index{sdcclib}
4990
4991 \end_inset
4992
4993
4994 \layout Standard
4995
4996
4997 \family sans
4998 \series bold
4999 sdcclib libint.lib _divuint.rel
5000 \layout Standard
5001
5002
5003 \family sans
5004 \series bold
5005 sdcclib libint.lib _modsint.rel
5006 \layout Standard
5007
5008
5009 \family sans
5010 \series bold
5011 sdcclib libint.lib _moduint.rel
5012 \layout Standard
5013
5014
5015 \family sans
5016 \series bold
5017 sdcclib libint.lib _mulint.rel
5018 \series default
5019
5020 \newline
5021
5022 \layout Standard
5023
5024 If the file already exists in the library, it will be replaced.
5025  To see what modules and symbols are included in the library, options -s
5026  and -m are available.
5027  For example:
5028 \newline
5029
5030 \newline
5031
5032 \family sans
5033 \series bold
5034 sdcclib -s libint.lib
5035 \family default
5036
5037 \begin_inset LatexCommand \index{sdcclib}
5038
5039 \end_inset
5040
5041
5042 \newline
5043
5044 \family typewriter
5045 \series default
5046 _divsint.rel:
5047 \layout Standard
5048
5049
5050 \family typewriter
5051 __divsint_a_1_1
5052 \layout Standard
5053
5054
5055 \family typewriter
5056 __divsint_PARM_2
5057 \layout Standard
5058
5059
5060 \family typewriter
5061 __divsint
5062 \newline
5063 _divuint.rel:
5064 \layout Standard
5065
5066
5067 \family typewriter
5068 __divuint_a_1_1
5069 \layout Standard
5070
5071
5072 \family typewriter
5073 __divuint_PARM_2
5074 \layout Standard
5075
5076
5077 \family typewriter
5078 __divuint_reste_1_1
5079 \layout Standard
5080
5081
5082 \family typewriter
5083 __divuint_count_1_1
5084 \layout Standard
5085
5086
5087 \family typewriter
5088 __divuint
5089 \newline
5090 _modsint.rel:
5091 \layout Standard
5092
5093
5094 \family typewriter
5095 __modsint_a_1_1
5096 \layout Standard
5097
5098
5099 \family typewriter
5100 __modsint_PARM_2
5101 \layout Standard
5102
5103
5104 \family typewriter
5105 __modsint
5106 \newline
5107 _moduint.rel:
5108 \layout Standard
5109
5110
5111 \family typewriter
5112 __moduint_a_1_1
5113 \layout Standard
5114
5115
5116 \family typewriter
5117 __moduint_PARM_2
5118 \layout Standard
5119
5120
5121 \family typewriter
5122 __moduint_count_1_1
5123 \layout Standard
5124
5125
5126 \family typewriter
5127 __moduint
5128 \newline
5129 _mulint.rel:
5130 \layout Standard
5131
5132
5133 \family typewriter
5134 __mulint_PARM_2
5135 \layout Standard
5136
5137
5138 \family typewriter
5139 __mulint
5140 \family default
5141 \series bold
5142
5143 \newline
5144
5145 \layout Standard
5146
5147 If the source files are compiled using -
5148 \begin_inset ERT
5149 status Open
5150
5151 \layout Standard
5152
5153 \backslash
5154 /
5155 \end_inset
5156
5157 -debug
5158 \begin_inset LatexCommand \index{-\/-debug}
5159
5160 \end_inset
5161
5162 , the corresponding debug information file .adb will be include in the library
5163  file as well.
5164  The library files created with sdcclib are plain text files, so they can
5165  be viewed with a text editor.
5166  It is not recomended to modify a library file created with sdcclib using
5167  a text editor, as there are file indexes numbers located accross the file
5168  used by the linker to quickly locate the required module to link.
5169  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5170  it can be safely deleted, since all the information required for linking
5171  is embedded in the library file itself.
5172  Library files created using sdcclib are used as described in the preceding
5173  sections.
5174 \layout Section
5175
5176 Command Line Options
5177 \begin_inset LatexCommand \index{Command Line Options}
5178
5179 \end_inset
5180
5181
5182 \layout Subsection
5183
5184 Processor Selection Options
5185 \begin_inset LatexCommand \index{Options processor selection}
5186
5187 \end_inset
5188
5189
5190 \begin_inset LatexCommand \index{Processor selection options}
5191
5192 \end_inset
5193
5194
5195 \layout List
5196 \labelwidthstring 00.00.0000
5197
5198
5199 \series bold
5200 -mmcs51
5201 \begin_inset LatexCommand \index{-mmcs51}
5202
5203 \end_inset
5204
5205
5206 \series default
5207  Generate code for the Intel MCS51
5208 \begin_inset LatexCommand \index{MCS51}
5209
5210 \end_inset
5211
5212  family of processors.
5213  This is the default processor target.
5214 \layout List
5215 \labelwidthstring 00.00.0000
5216
5217
5218 \series bold
5219 -mds390
5220 \begin_inset LatexCommand \index{-mds390}
5221
5222 \end_inset
5223
5224
5225 \series default
5226  Generate code for the Dallas DS80C390
5227 \begin_inset LatexCommand \index{DS80C390}
5228
5229 \end_inset
5230
5231  processor.
5232 \layout List
5233 \labelwidthstring 00.00.0000
5234
5235
5236 \series bold
5237 -mds400
5238 \begin_inset LatexCommand \index{-mds400}
5239
5240 \end_inset
5241
5242
5243 \series default
5244  Generate code for the Dallas DS80C400
5245 \begin_inset LatexCommand \index{DS80C400}
5246
5247 \end_inset
5248
5249  processor.
5250 \layout List
5251 \labelwidthstring 00.00.0000
5252
5253
5254 \series bold
5255 -mhc08
5256 \begin_inset LatexCommand \index{-mhc08}
5257
5258 \end_inset
5259
5260
5261 \series default
5262  Generate code for the Freescale/Motorola HC08
5263 \begin_inset LatexCommand \index{HC08}
5264
5265 \end_inset
5266
5267  family of processors.
5268 \layout List
5269 \labelwidthstring 00.00.0000
5270
5271
5272 \series bold
5273 -mz80
5274 \begin_inset LatexCommand \index{-mz80}
5275
5276 \end_inset
5277
5278
5279 \series default
5280  Generate code for the Zilog Z80
5281 \begin_inset LatexCommand \index{Z80}
5282
5283 \end_inset
5284
5285  family of processors.
5286 \layout List
5287 \labelwidthstring 00.00.0000
5288
5289
5290 \series bold
5291 -mgbz80
5292 \begin_inset LatexCommand \index{-mgbz80}
5293
5294 \end_inset
5295
5296
5297 \series default
5298  Generate code for the GameBoy Z80
5299 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5300
5301 \end_inset
5302
5303  processor (Not actively maintained).
5304 \layout List
5305 \labelwidthstring 00.00.0000
5306
5307
5308 \series bold
5309 -mavr
5310 \begin_inset LatexCommand \index{-mavr}
5311
5312 \end_inset
5313
5314
5315 \series default
5316  Generate code for the Atmel AVR
5317 \begin_inset LatexCommand \index{AVR}
5318
5319 \end_inset
5320
5321  processor (In development, not complete).
5322  AVR users should probably have a look at winavr
5323 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5324
5325 \end_inset
5326
5327  or
5328 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5329
5330 \end_inset
5331
5332 .
5333 \layout Comment
5334
5335 I think it is fair to direct users there for now.
5336  Open source is also about avoiding unnecessary work .
5337  But I didn't find the 'official' link.
5338 \layout List
5339 \labelwidthstring 00.00.0000
5340
5341
5342 \series bold
5343 -mpic14
5344 \begin_inset LatexCommand \index{-mpic14}
5345
5346 \end_inset
5347
5348
5349 \series default
5350  Generate code for the Microchip PIC 14
5351 \begin_inset LatexCommand \index{PIC14}
5352
5353 \end_inset
5354
5355 -bit processors (p16f84 and variants.
5356  In development, not complete).
5357 \layout Comment
5358
5359 p16f627 p16f628 p16f84 p16f873 p16f877?
5360 \layout List
5361 \labelwidthstring 00.00.0000
5362
5363
5364 \series bold
5365 -mpic16
5366 \begin_inset LatexCommand \index{-mpic16}
5367
5368 \end_inset
5369
5370
5371 \series default
5372  Generate code for the Microchip PIC 16
5373 \begin_inset LatexCommand \index{PIC16}
5374
5375 \end_inset
5376
5377 -bit processors (p18f452 and variants.
5378  In development, not complete).
5379 \layout List
5380 \labelwidthstring 00.00.0000
5381
5382
5383 \series bold
5384 -mtlcs900h
5385 \series default
5386  Generate code for the Toshiba TLCS-900H
5387 \begin_inset LatexCommand \index{TLCS-900H}
5388
5389 \end_inset
5390
5391  processor (Not maintained, not complete).
5392 \layout List
5393 \labelwidthstring 00.00.0000
5394
5395
5396 \series bold
5397 -mxa51
5398 \begin_inset LatexCommand \index{-mxa51}
5399
5400 \end_inset
5401
5402
5403 \series default
5404  Generate code for the Phillips XA51
5405 \begin_inset LatexCommand \index{XA51}
5406
5407 \end_inset
5408
5409  processor (Not maintained, not complete).
5410 \layout Subsection
5411
5412 Preprocessor Options
5413 \begin_inset LatexCommand \index{Options preprocessor}
5414
5415 \end_inset
5416
5417
5418 \begin_inset LatexCommand \index{Preprocessor options}
5419
5420 \end_inset
5421
5422
5423 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5424
5425 \end_inset
5426
5427
5428 \layout List
5429 \labelwidthstring 00.00.0000
5430
5431
5432 \series bold
5433 -I<path>
5434 \begin_inset LatexCommand \index{-I<path>}
5435
5436 \end_inset
5437
5438
5439 \series default
5440  The additional location where the pre processor will look for <..h> or
5441 \begin_inset Quotes eld
5442 \end_inset
5443
5444 ..h
5445 \begin_inset Quotes erd
5446 \end_inset
5447
5448  files.
5449 \layout List
5450 \labelwidthstring 00.00.0000
5451
5452
5453 \series bold
5454 -D<macro[=value]>
5455 \begin_inset LatexCommand \index{-D<macro[=value]>}
5456
5457 \end_inset
5458
5459
5460 \series default
5461  Command line definition of macros.
5462  Passed to the preprocessor.
5463 \layout List
5464 \labelwidthstring 00.00.0000
5465
5466
5467 \series bold
5468 -M
5469 \begin_inset LatexCommand \index{-M}
5470
5471 \end_inset
5472
5473
5474 \series default
5475  Tell the preprocessor to output a rule suitable for make describing the
5476  dependencies of each object file.
5477  For each source file, the preprocessor outputs one make-rule whose target
5478  is the object file name for that source file and whose dependencies are
5479  all the files `#include'd in it.
5480  This rule may be a single line or may be continued with `
5481 \backslash
5482 '-newline if it is long.
5483  The list of rules is printed on standard output instead of the preprocessed
5484  C program.
5485  `-M' implies `-E
5486 \begin_inset LatexCommand \index{-E}
5487
5488 \end_inset
5489
5490 '.
5491 \layout List
5492 \labelwidthstring 00.00.0000
5493
5494
5495 \series bold
5496 -C
5497 \begin_inset LatexCommand \index{-C}
5498
5499 \end_inset
5500
5501
5502 \series default
5503  Tell the preprocessor not to discard comments.
5504  Used with the `-E' option.
5505 \layout List
5506 \labelwidthstring 00.00.0000
5507
5508
5509 \series bold
5510 -MM
5511 \begin_inset LatexCommand \index{-MM}
5512
5513 \end_inset
5514
5515
5516 \size large
5517 \bar under
5518
5519 \series default
5520 \size default
5521 \bar default
5522 Like `-M' but the output mentions only the user header files included with
5523  `#include
5524 \begin_inset Quotes eld
5525 \end_inset
5526
5527 file"'.
5528  System header files included with `#include <file>' are omitted.
5529 \layout List
5530 \labelwidthstring 00.00.0000
5531
5532
5533 \series bold
5534 -Aquestion(answer)
5535 \begin_inset LatexCommand \index{-Aquestion(answer)}
5536
5537 \end_inset
5538
5539
5540 \series default
5541  Assert the answer answer for question, in case it is tested with a preprocessor
5542  conditional such as `#if #question(answer)'.
5543  `-A-' disables the standard assertions that normally describe the target
5544  machine.
5545 \layout List
5546 \labelwidthstring 00.00.0000
5547
5548
5549 \series bold
5550 -Umacro
5551 \begin_inset LatexCommand \index{-Umacro}
5552
5553 \end_inset
5554
5555
5556 \series default
5557  Undefine macro macro.
5558  `-U' options are evaluated after all `-D' options, but before any `-include'
5559  and `-imacros' options.
5560 \layout List
5561 \labelwidthstring 00.00.0000
5562
5563
5564 \series bold
5565 -dM
5566 \begin_inset LatexCommand \index{-dM}
5567
5568 \end_inset
5569
5570
5571 \series default
5572  Tell the preprocessor to output only a list of the macro definitions that
5573  are in effect at the end of preprocessing.
5574  Used with the `-E' option.
5575 \layout List
5576 \labelwidthstring 00.00.0000
5577
5578
5579 \series bold
5580 -dD
5581 \begin_inset LatexCommand \index{-dD}
5582
5583 \end_inset
5584
5585
5586 \series default
5587  Tell the preprocessor to pass all macro definitions into the output, in
5588  their proper sequence in the rest of the output.
5589 \layout List
5590 \labelwidthstring 00.00.0000
5591
5592
5593 \series bold
5594 -dN
5595 \begin_inset LatexCommand \index{-dN}
5596
5597 \end_inset
5598
5599
5600 \size large
5601 \bar under
5602
5603 \series default
5604 \size default
5605 \bar default
5606 Like `-dD' except that the macro arguments and contents are omitted.
5607  Only `#define name' is included in the output.
5608 \layout List
5609 \labelwidthstring 00.00.0000
5610
5611
5612 \series bold
5613 -Wp\SpecialChar ~
5614 preprocessorOption[,preprocessorOption]
5615 \series default
5616
5617 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5618
5619 \end_inset
5620
5621 ...
5622  Pass the preprocessorOption to the preprocessor
5623 \family typewriter
5624 sdcpp
5625 \family default
5626
5627 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5628
5629 \end_inset
5630
5631 .
5632  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5633  Collection (gcc), if you need more dedicated options please refer to the
5634  documentation at
5635 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5636
5637 \end_inset
5638
5639 .
5640 \layout Subsection
5641
5642 Linker Options
5643 \begin_inset LatexCommand \index{Options linker}
5644
5645 \end_inset
5646
5647
5648 \begin_inset LatexCommand \index{Linker options}
5649
5650 \end_inset
5651
5652
5653 \layout List
5654 \labelwidthstring 00.00.0000
5655
5656
5657 \series bold
5658 -L\SpecialChar ~
5659 -
5660 \series default
5661
5662 \begin_inset ERT
5663 status Collapsed
5664
5665 \layout Standard
5666
5667 \backslash
5668 /
5669 \end_inset
5670
5671
5672 \series bold
5673 -lib-path
5674 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5675
5676 \end_inset
5677
5678
5679 \begin_inset LatexCommand \index{-L -\/-lib-path}
5680
5681 \end_inset
5682
5683
5684 \series default
5685 \SpecialChar ~
5686 <absolute path to additional libraries> This option is passed to the linkage
5687  editor's additional libraries
5688 \begin_inset LatexCommand \index{Libraries}
5689
5690 \end_inset
5691
5692  search path.
5693  The path name must be absolute.
5694  Additional library files may be specified in the command line.
5695  See section Compiling programs for more details.
5696 \layout List
5697 \labelwidthstring 00.00.0000
5698
5699
5700 \series bold
5701 -
5702 \begin_inset ERT
5703 status Collapsed
5704
5705 \layout Standard
5706
5707 \backslash
5708 /
5709 \end_inset
5710
5711 -xram-loc
5712 \series default
5713
5714 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5715
5716 \end_inset
5717
5718 \SpecialChar ~
5719 <Value> The start location of the external ram
5720 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5721
5722 \end_inset
5723
5724 , default value is 0.
5725  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5726 \begin_inset ERT
5727 status Collapsed
5728
5729 \layout Standard
5730
5731 \backslash
5732 /
5733 \end_inset
5734
5735 -xram-loc 0x8000 or -
5736 \begin_inset ERT
5737 status Collapsed
5738
5739 \layout Standard
5740
5741 \backslash
5742 /
5743 \end_inset
5744
5745 -xram-loc 32768.
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 -code-loc
5762 \series default
5763
5764 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5765
5766 \end_inset
5767
5768 \SpecialChar ~
5769 <Value> The start location of the code
5770 \begin_inset LatexCommand \index{code}
5771
5772 \end_inset
5773
5774  segment, default value 0.
5775  Note when this option is used the interrupt vector table is also relocated
5776  to the given address.
5777  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5778 \begin_inset ERT
5779 status Collapsed
5780
5781 \layout Standard
5782
5783 \backslash
5784 /
5785 \end_inset
5786
5787 -code-loc 0x8000 or -
5788 \begin_inset ERT
5789 status Collapsed
5790
5791 \layout Standard
5792
5793 \backslash
5794 /
5795 \end_inset
5796
5797 -code-loc 32768.
5798 \layout List
5799 \labelwidthstring 00.00.0000
5800
5801
5802 \series bold
5803 -
5804 \begin_inset ERT
5805 status Collapsed
5806
5807 \layout Standard
5808
5809 \backslash
5810 /
5811 \end_inset
5812
5813 -stack-loc
5814 \series default
5815
5816 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5817
5818 \end_inset
5819
5820 \SpecialChar ~
5821 <Value> By default the stack
5822 \begin_inset LatexCommand \index{stack}
5823
5824 \end_inset
5825
5826  is placed after the data segment.
5827  Using this option the stack can be placed anywhere in the internal memory
5828  space of the 8051.
5829  The value entered can be in Hexadecimal or Decimal format, e.g.
5830  -
5831 \begin_inset ERT
5832 status Collapsed
5833
5834 \layout Standard
5835
5836 \backslash
5837 /
5838 \end_inset
5839
5840 -stack-loc 0x20 or -
5841 \begin_inset ERT
5842 status Collapsed
5843
5844 \layout Standard
5845
5846 \backslash
5847 /
5848 \end_inset
5849
5850 -stack-loc 32.
5851  Since the sp register is incremented before a push or call, the initial
5852  sp will be set to one byte prior the provided value.
5853  The provided value should not overlap any other memory areas such as used
5854  register banks or the data segment and with enough space for the current
5855  application.
5856  The
5857 \series bold
5858 -
5859 \begin_inset ERT
5860 status Collapsed
5861
5862 \layout Standard
5863
5864 \backslash
5865 /
5866 \end_inset
5867
5868 -pack-iram
5869 \series default
5870 \SpecialChar ~
5871
5872 \begin_inset LatexCommand \index{-\/-pack-iram}
5873
5874 \end_inset
5875
5876  option (which is now a default setting) will override this setting, so
5877  you should also specify the
5878 \series bold
5879 -
5880 \begin_inset ERT
5881 status Collapsed
5882
5883 \layout Standard
5884
5885 \backslash
5886 /
5887 \end_inset
5888
5889 -no-pack-iram
5890 \series default
5891 \SpecialChar ~
5892
5893 \begin_inset LatexCommand \index{-\/-no-pack-iram}
5894
5895 \end_inset
5896
5897  option if you need to manually place the stack.
5898 \layout List
5899 \labelwidthstring 00.00.0000
5900
5901
5902 \series bold
5903 -
5904 \begin_inset ERT
5905 status Collapsed
5906
5907 \layout Standard
5908
5909 \backslash
5910 /
5911 \end_inset
5912
5913 -xstack-loc
5914 \series default
5915
5916 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
5917
5918 \end_inset
5919
5920 \SpecialChar ~
5921 <Value> By default the external stack
5922 \begin_inset LatexCommand \index{xstack}
5923
5924 \end_inset
5925
5926  is placed after the pdata segment.
5927  Using this option the xstack can be placed anywhere in the external memory
5928  space of the 8051.
5929  The value entered can be in Hexadecimal or Decimal format, e.g.
5930  -
5931 \begin_inset ERT
5932 status Collapsed
5933
5934 \layout Standard
5935
5936 \backslash
5937 /
5938 \end_inset
5939
5940 -xstack-loc 0x8000 or -
5941 \begin_inset ERT
5942 status Collapsed
5943
5944 \layout Standard
5945
5946 \backslash
5947 /
5948 \end_inset
5949
5950 -stack-loc 32768.
5951  The provided value should not overlap any other memory areas such as the
5952  pdata or xdata segment and with enough space for the current application.
5953 \layout List
5954 \labelwidthstring 00.00.0000
5955
5956
5957 \series bold
5958 -
5959 \begin_inset ERT
5960 status Collapsed
5961
5962 \layout Standard
5963
5964 \backslash
5965 /
5966 \end_inset
5967
5968 -data-loc
5969 \series default
5970
5971 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5972
5973 \end_inset
5974
5975 \SpecialChar ~
5976 <Value> The start location of the internal ram data
5977 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5978
5979 \end_inset
5980
5981  segment.
5982  The value entered can be in Hexadecimal or Decimal format, eg.
5983  -
5984 \begin_inset ERT
5985 status Collapsed
5986
5987 \layout Standard
5988
5989 \backslash
5990 /
5991 \end_inset
5992
5993 -data-loc 0x20 or -
5994 \begin_inset ERT
5995 status Collapsed
5996
5997 \layout Standard
5998
5999 \backslash
6000 /
6001 \end_inset
6002
6003 -data-loc 32.
6004  (By default, the start location of the internal ram data segment  is set
6005  as low as possible in memory, taking into account the used register banks
6006  and the bit segment at address 0x20.
6007  For example if register banks 0 and 1 are used without bit variables, the
6008  data segment will be set, if -
6009 \begin_inset ERT
6010 status Collapsed
6011
6012 \layout Standard
6013
6014 \backslash
6015 /
6016 \end_inset
6017
6018 -data-loc is not used, to location 0x10.)
6019 \layout List
6020 \labelwidthstring 00.00.0000
6021
6022
6023 \series bold
6024 -
6025 \begin_inset ERT
6026 status Collapsed
6027
6028 \layout Standard
6029
6030 \backslash
6031 /
6032 \end_inset
6033
6034 -idata-loc
6035 \series default
6036
6037 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
6038
6039 \end_inset
6040
6041 \SpecialChar ~
6042 <Value> The start location of the indirectly addressable internal ram
6043 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
6044
6045 \end_inset
6046
6047  of the 8051, default value is 0x80.
6048  The value entered can be in Hexadecimal or Decimal format, eg.
6049  -
6050 \begin_inset ERT
6051 status Collapsed
6052
6053 \layout Standard
6054
6055 \backslash
6056 /
6057 \end_inset
6058
6059 -idata-loc 0x88 or -
6060 \begin_inset ERT
6061 status Collapsed
6062
6063 \layout Standard
6064
6065 \backslash
6066 /
6067 \end_inset
6068
6069 -idata-loc 136.
6070 \layout List
6071 \labelwidthstring 00.00.0000
6072
6073
6074 \series bold
6075 -
6076 \begin_inset ERT
6077 status Collapsed
6078
6079 \layout Standard
6080
6081 \backslash
6082 /
6083 \end_inset
6084
6085 -bit-loc
6086 \series default
6087 \SpecialChar ~
6088 <Value> The start location of the bit
6089 \begin_inset LatexCommand \index{bit}
6090
6091 \end_inset
6092
6093  addressable internal ram of the 8051.
6094  This is
6095 \emph on
6096 not
6097 \emph default
6098  implemented yet.
6099  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
6100 -bBSEG=<Value>.
6101 \layout List
6102 \labelwidthstring 00.00.0000
6103
6104
6105 \series bold
6106 -
6107 \begin_inset ERT
6108 status Collapsed
6109
6110 \layout Standard
6111
6112 \backslash
6113 /
6114 \end_inset
6115
6116 -out-fmt-ihx
6117 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
6118
6119 \end_inset
6120
6121
6122 \bar under
6123
6124 \series default
6125 \bar default
6126 The linker output (final object code) is in Intel Hex format.
6127 \begin_inset LatexCommand \index{Intel hex format}
6128
6129 \end_inset
6130
6131  This is the default option.
6132  The format itself is documented in the documentation of srecord
6133 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
6134
6135 \end_inset
6136
6137 .
6138 \layout List
6139 \labelwidthstring 00.00.0000
6140
6141
6142 \series bold
6143 -
6144 \begin_inset ERT
6145 status Collapsed
6146
6147 \layout Standard
6148
6149 \backslash
6150 /
6151 \end_inset
6152
6153 -out-fmt-s19
6154 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6155
6156 \end_inset
6157
6158
6159 \bar under
6160
6161 \series default
6162 \bar default
6163 The linker output (final object code) is in Motorola S19 format
6164 \begin_inset LatexCommand \index{Motorola S19 format}
6165
6166 \end_inset
6167
6168 .
6169  The format itself is documented in the documentation of srecord.
6170 \layout List
6171 \labelwidthstring 00.00.0000
6172
6173
6174 \series bold
6175 -
6176 \begin_inset ERT
6177 status Collapsed
6178
6179 \layout Standard
6180
6181 \backslash
6182 /
6183 \end_inset
6184
6185 -out-fmt-elf
6186 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6187
6188 \end_inset
6189
6190
6191 \bar under
6192
6193 \series default
6194 \bar default
6195 The linker output (final object code) is in ELF format
6196 \begin_inset LatexCommand \index{ELF format}
6197
6198 \end_inset
6199
6200 .
6201  (Currently only supported for the HC08 processors)
6202 \layout List
6203 \labelwidthstring 00.00.0000
6204
6205
6206 \series bold
6207 -Wl\SpecialChar ~
6208 linkOption[,linkOption]
6209 \series default
6210
6211 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
6212
6213 \end_inset
6214
6215 ...
6216  Pass the linkOption to the linker.
6217  See file sdcc/as/doc/asxhtm.html for more on linker options.
6218 \layout Subsection
6219
6220 MCS51 Options
6221 \begin_inset LatexCommand \index{Options MCS51}
6222
6223 \end_inset
6224
6225
6226 \begin_inset LatexCommand \index{MCS51 options}
6227
6228 \end_inset
6229
6230
6231 \layout List
6232 \labelwidthstring 00.00.0000
6233
6234
6235 \series bold
6236 -
6237 \begin_inset ERT
6238 status Collapsed
6239
6240 \layout Standard
6241
6242 \backslash
6243 /
6244 \end_inset
6245
6246 -model-small
6247 \begin_inset LatexCommand \index{-\/-model-small}
6248
6249 \end_inset
6250
6251
6252 \series default
6253 \size large
6254 \emph on
6255
6256 \size default
6257 \emph default
6258 Generate code for Small Model programs, see section Memory Models for more
6259  details.
6260  This is the default model.
6261 \layout List
6262 \labelwidthstring 00.00.0000
6263
6264
6265 \series bold
6266 -
6267 \begin_inset ERT
6268 status Collapsed
6269
6270 \layout Standard
6271
6272 \backslash
6273 /
6274 \end_inset
6275
6276 -model-medium
6277 \begin_inset LatexCommand \index{-\/-model-medium}
6278
6279 \end_inset
6280
6281
6282 \series default
6283  Generate code for Medium model programs, see section Memory Models for
6284  more details.
6285  If this option is used all source files in the project have to be compiled
6286  with this option.
6287  It must also be used when invoking the linker.
6288 \layout List
6289 \labelwidthstring 00.00.0000
6290
6291
6292 \series bold
6293 -
6294 \begin_inset ERT
6295 status Collapsed
6296
6297 \layout Standard
6298
6299 \backslash
6300 /
6301 \end_inset
6302
6303 -model-large
6304 \begin_inset LatexCommand \index{-\/-model-large}
6305
6306 \end_inset
6307
6308
6309 \series default
6310  Generate code for Large model programs, see section Memory Models for more
6311  details.
6312  If this option is used all source files in the project have to be compiled
6313  with this option.
6314  It must also be used when invoking the linker.
6315 \layout List
6316 \labelwidthstring 00.00.0000
6317
6318
6319 \series bold
6320 -
6321 \begin_inset ERT
6322 status Collapsed
6323
6324 \layout Standard
6325
6326 \backslash
6327 /
6328 \end_inset
6329
6330 -xstack
6331 \begin_inset LatexCommand \index{-\/-xstack}
6332
6333 \end_inset
6334
6335
6336 \series default
6337  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6338  variables and passing parameters.
6339  See section
6340 \begin_inset LatexCommand \ref{sub:External-Stack}
6341
6342 \end_inset
6343
6344 \SpecialChar ~
6345  External Stack for more details.
6346 \layout List
6347 \labelwidthstring 00.00.0000
6348
6349
6350 \series bold
6351 -
6352 \begin_inset ERT
6353 status Collapsed
6354
6355 \layout Standard
6356
6357 \backslash
6358 /
6359 \end_inset
6360
6361 -iram-size
6362 \series default
6363 \SpecialChar ~
6364 <Value>
6365 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6366
6367 \end_inset
6368
6369  Causes the linker to check if the internal ram usage is within limits of
6370  the given value.
6371 \layout List
6372 \labelwidthstring 00.00.0000
6373
6374
6375 \series bold
6376 -
6377 \begin_inset ERT
6378 status Collapsed
6379
6380 \layout Standard
6381
6382 \backslash
6383 /
6384 \end_inset
6385
6386 -xram-size
6387 \series default
6388 \SpecialChar ~
6389 <Value>
6390 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6391
6392 \end_inset
6393
6394  Causes the linker to check if the external ram usage is within limits of
6395  the given value.
6396 \layout List
6397 \labelwidthstring 00.00.0000
6398
6399
6400 \series bold
6401 -
6402 \begin_inset ERT
6403 status Collapsed
6404
6405 \layout Standard
6406
6407 \backslash
6408 /
6409 \end_inset
6410
6411 -code-size
6412 \series default
6413 \SpecialChar ~
6414 <Value>
6415 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6416
6417 \end_inset
6418
6419  Causes the linker to check if the code memory usage is within limits of
6420  the given value.
6421 \layout List
6422 \labelwidthstring 00.00.0000
6423
6424
6425 \series bold
6426 -
6427 \begin_inset ERT
6428 status Collapsed
6429
6430 \layout Standard
6431
6432 \backslash
6433 /
6434 \end_inset
6435
6436 -stack-size
6437 \series default
6438 \SpecialChar ~
6439 <Value>
6440 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6441
6442 \end_inset
6443
6444  Causes the linker to check if there is at minimum <Value> bytes for stack.
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 -pack-iram
6461 \series default
6462 \SpecialChar ~
6463
6464 \begin_inset LatexCommand \index{-\/-pack-iram}
6465
6466 \end_inset
6467
6468  Causes the linker to use unused register banks for data variables and pack
6469  data, idata and stack together.
6470  This is the default now.
6471 \layout List
6472 \labelwidthstring 00.00.0000
6473
6474
6475 \series bold
6476 -
6477 \begin_inset ERT
6478 status Collapsed
6479
6480 \layout Standard
6481
6482 \backslash
6483 /
6484 \end_inset
6485
6486 -no-pack-iram
6487 \series default
6488 \SpecialChar ~
6489
6490 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6491
6492 \end_inset
6493
6494  Causes the linker to use old style for allocating memory areas.
6495 \layout Subsection
6496
6497 DS390 / DS400 Options
6498 \begin_inset LatexCommand \index{Options DS390}
6499
6500 \end_inset
6501
6502
6503 \begin_inset LatexCommand \index{DS390 options}
6504
6505 \end_inset
6506
6507
6508 \layout List
6509 \labelwidthstring 00.00.0000
6510
6511
6512 \series bold
6513 -
6514 \begin_inset ERT
6515 status Collapsed
6516
6517 \layout Standard
6518
6519 \backslash
6520 /
6521 \end_inset
6522
6523 -model-flat24
6524 \series default
6525
6526 \begin_inset LatexCommand \index{-\/-model-flat24}
6527
6528 \end_inset
6529
6530
6531 \size large
6532 \emph on
6533
6534 \size default
6535 \emph default
6536 Generate 24-bit flat mode code.
6537  This is the one and only that the ds390 code generator supports right now
6538  and is default when using
6539 \emph on
6540 -mds390
6541 \emph default
6542 .
6543  See section Memory Models for more details.
6544 \layout List
6545 \labelwidthstring 00.00.0000
6546
6547
6548 \series bold
6549 -
6550 \begin_inset ERT
6551 status Collapsed
6552
6553 \layout Standard
6554
6555 \backslash
6556 /
6557 \end_inset
6558
6559 -protect-sp-update
6560 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6561
6562 \end_inset
6563
6564
6565 \series default
6566  disable interrupts during ESP:SP updates.
6567 \layout List
6568 \labelwidthstring 00.00.0000
6569
6570
6571 \series bold
6572 -
6573 \begin_inset ERT
6574 status Collapsed
6575
6576 \layout Standard
6577
6578 \backslash
6579 /
6580 \end_inset
6581
6582 -stack-10bit
6583 \series default
6584
6585 \begin_inset LatexCommand \index{-\/-stack-10bit}
6586
6587 \end_inset
6588
6589  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6590  This is the one and only that the ds390 code generator supports right now
6591  and is default when using
6592 \emph on
6593 -mds390
6594 \emph default
6595 .
6596  In this mode, the stack is located in the lower 1K of the internal RAM,
6597  which is mapped to 0x400000.
6598  Note that the support is incomplete, since it still uses a single byte
6599  as the stack pointer.
6600  This means that only the lower 256 bytes of the potential 1K stack space
6601  will actually be used.
6602  However, this does allow you to reclaim the precious 256 bytes of low RAM
6603  for use for the DATA and IDATA segments.
6604  The compiler will not generate any code to put the processor into 10 bit
6605  stack mode.
6606  It is important to ensure that the processor is in this mode before calling
6607  any re-entrant functions compiled with this option.
6608  In principle, this should work with the
6609 \emph on
6610 -
6611 \begin_inset ERT
6612 status Collapsed
6613
6614 \layout Standard
6615
6616 \backslash
6617 /
6618 \end_inset
6619
6620 -stack-auto
6621 \begin_inset LatexCommand \index{-\/-stack-auto}
6622
6623 \end_inset
6624
6625
6626 \emph default
6627  option, but that has not been tested.
6628  It is incompatible with the
6629 \emph on
6630 -
6631 \begin_inset ERT
6632 status Collapsed
6633
6634 \layout Standard
6635
6636 \backslash
6637 /
6638 \end_inset
6639
6640 -xstack
6641 \begin_inset LatexCommand \index{-\/-xstack}
6642
6643 \end_inset
6644
6645
6646 \emph default
6647  option.
6648  It also only makes sense if the processor is in 24 bit contiguous addressing
6649  mode (see the
6650 \emph on
6651 -
6652 \begin_inset ERT
6653 status Collapsed
6654
6655 \layout Standard
6656
6657 \backslash
6658 /
6659 \end_inset
6660
6661 -model-flat24 option
6662 \emph default
6663 ).
6664 \layout List
6665 \labelwidthstring 00.00.0000
6666
6667
6668 \series bold
6669 -
6670 \begin_inset ERT
6671 status Collapsed
6672
6673 \layout Standard
6674
6675 \backslash
6676 /
6677 \end_inset
6678
6679 -stack-probe
6680 \begin_inset LatexCommand \index{-\/-stack-probe}
6681
6682 \end_inset
6683
6684
6685 \series default
6686  insert call to function __stack_probe at each function prologue.
6687 \layout List
6688 \labelwidthstring 00.00.0000
6689
6690
6691 \series bold
6692 -
6693 \begin_inset ERT
6694 status Collapsed
6695
6696 \layout Standard
6697
6698 \backslash
6699 /
6700 \end_inset
6701
6702 -tini-libid
6703 \begin_inset LatexCommand \index{-\/-tini-libid}
6704
6705 \end_inset
6706
6707
6708 \series default
6709  <nnnn> LibraryID used in -mTININative.
6710
6711 \layout List
6712 \labelwidthstring 00.00.0000
6713
6714
6715 \series bold
6716 -
6717 \begin_inset ERT
6718 status Collapsed
6719
6720 \layout Standard
6721
6722 \backslash
6723 /
6724 \end_inset
6725
6726 -use-accelerator
6727 \begin_inset LatexCommand \index{-\/-use-accelerator}
6728
6729 \end_inset
6730
6731
6732 \series default
6733  generate code for DS390 Arithmetic Accelerator.
6734
6735 \layout Subsection
6736
6737 Z80 Options
6738 \begin_inset LatexCommand \index{Options Z80}
6739
6740 \end_inset
6741
6742
6743 \begin_inset LatexCommand \index{Z80 options}
6744
6745 \end_inset
6746
6747
6748 \layout List
6749 \labelwidthstring 00.00.0000
6750
6751
6752 \series bold
6753 -
6754 \begin_inset ERT
6755 status Collapsed
6756
6757 \layout Standard
6758
6759 \backslash
6760 /
6761 \end_inset
6762
6763 -callee-saves-bc
6764 \series default
6765
6766 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6767
6768 \end_inset
6769
6770
6771 \size large
6772 \emph on
6773
6774 \size default
6775 \emph default
6776 Force a called function to always save BC.
6777 \layout List
6778 \labelwidthstring 00.00.0000
6779
6780
6781 \series bold
6782 -
6783 \begin_inset ERT
6784 status Collapsed
6785
6786 \layout Standard
6787
6788 \backslash
6789 /
6790 \end_inset
6791
6792 -no-std-crt0
6793 \series default
6794
6795 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6796
6797 \end_inset
6798
6799  When linking, skip the standard crt0.o object file.
6800  You must provide your own crt0.o for your system when linking.
6801
6802 \layout Subsection
6803
6804 Optimization Options
6805 \begin_inset LatexCommand \index{Options optimization}
6806
6807 \end_inset
6808
6809
6810 \begin_inset LatexCommand \index{Optimization options}
6811
6812 \end_inset
6813
6814
6815 \layout List
6816 \labelwidthstring 00.00.0000
6817
6818
6819 \series bold
6820 -
6821 \begin_inset ERT
6822 status Collapsed
6823
6824 \layout Standard
6825
6826 \backslash
6827 /
6828 \end_inset
6829
6830 -nogcse
6831 \begin_inset LatexCommand \index{-\/-nogcse}
6832
6833 \end_inset
6834
6835
6836 \series default
6837  Will not do global subexpression elimination, this option may be used when
6838  the compiler creates undesirably large stack/data spaces to store compiler
6839  temporaries (
6840 \emph on
6841 s
6842 \emph default
6843 pill
6844 \emph on
6845 loc
6846 \emph default
6847 ations, sloc
6848 \begin_inset LatexCommand \index{sloc (spill location)}
6849
6850 \end_inset
6851
6852 ).
6853  A warning message will be generated when this happens and the compiler
6854  will indicate the number of extra bytes it allocated.
6855  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6856 nogcse
6857 \begin_inset LatexCommand \index{\#pragma nogcse}
6858
6859 \end_inset
6860
6861  can be used to turn off global subexpression elimination
6862 \begin_inset LatexCommand \index{Subexpression elimination}
6863
6864 \end_inset
6865
6866  for a given function only.
6867 \layout List
6868 \labelwidthstring 00.00.0000
6869
6870
6871 \series bold
6872 -
6873 \begin_inset ERT
6874 status Collapsed
6875
6876 \layout Standard
6877
6878 \backslash
6879 /
6880 \end_inset
6881
6882 -noinvariant
6883 \begin_inset LatexCommand \index{-\/-noinvariant}
6884
6885 \end_inset
6886
6887
6888 \series default
6889  Will not do loop invariant optimizations, this may be turned off for reasons
6890  explained for the previous option.
6891  For more details of loop optimizations performed see Loop Invariants in
6892  section
6893 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6894
6895 \end_inset
6896
6897 .
6898  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6899 noinvariant
6900 \begin_inset LatexCommand \index{\#pragma noinvariant}
6901
6902 \end_inset
6903
6904  can be used to turn off invariant optimizations for a given function only.
6905 \layout List
6906 \labelwidthstring 00.00.0000
6907
6908
6909 \series bold
6910 -
6911 \begin_inset ERT
6912 status Collapsed
6913
6914 \layout Standard
6915
6916 \backslash
6917 /
6918 \end_inset
6919
6920 -noinduction
6921 \begin_inset LatexCommand \index{-\/-noinduction}
6922
6923 \end_inset
6924
6925
6926 \series default
6927  Will not do loop induction optimizations, see section strength reduction
6928  for more details.
6929  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6930 noinduction
6931 \begin_inset LatexCommand \index{\#pragma noinduction}
6932
6933 \end_inset
6934
6935  can be used to turn off induction optimizations for a given function only.
6936 \layout List
6937 \labelwidthstring 00.00.0000
6938
6939
6940 \series bold
6941 -
6942 \begin_inset ERT
6943 status Collapsed
6944
6945 \layout Standard
6946
6947 \backslash
6948 /
6949 \end_inset
6950
6951 -nojtbound
6952 \begin_inset LatexCommand \index{-\/-nojtbound}
6953
6954 \end_inset
6955
6956
6957 \size large
6958 \bar under
6959
6960 \series default
6961 \size default
6962 \bar default
6963  Will not generate boundary condition check when switch statements
6964 \begin_inset LatexCommand \index{switch statement}
6965
6966 \end_inset
6967
6968  are implemented using jump-tables.
6969  See section
6970 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6971
6972 \end_inset
6973
6974 \SpecialChar ~
6975 Switch Statements for more details.
6976  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6977 nojtbound
6978 \begin_inset LatexCommand \index{\#pragma nojtbound}
6979
6980 \end_inset
6981
6982  can be used to turn off boundary checking for jump tables for a given function
6983  only.
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 -noloopreverse
7000 \begin_inset LatexCommand \index{-\/-noloopreverse}
7001
7002 \end_inset
7003
7004
7005 \series default
7006 \size large
7007
7008 \size default
7009 Will not do loop reversal
7010 \begin_inset LatexCommand \index{Loop reversing}
7011
7012 \end_inset
7013
7014 optimization.
7015 \layout List
7016 \labelwidthstring 00.00.0000
7017
7018 -
7019 \begin_inset ERT
7020 status Collapsed
7021
7022 \layout Standard
7023
7024 \backslash
7025 /
7026 \end_inset
7027
7028 -
7029 \series bold
7030 nolabelopt
7031 \series default
7032
7033 \begin_inset LatexCommand \index{-\/-nolabelopt }
7034
7035 \end_inset
7036
7037 Will not optimize labels (makes the dumpfiles more readable).
7038 \layout List
7039 \labelwidthstring 00.00.0000
7040
7041
7042 \series bold
7043 -
7044 \begin_inset ERT
7045 status Collapsed
7046
7047 \layout Standard
7048
7049 \backslash
7050 /
7051 \end_inset
7052
7053 -no-xinit-opt
7054 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
7055
7056 \end_inset
7057
7058
7059 \series default
7060  Will not memcpy initialized data from code space into xdata space.
7061  This saves a few bytes in code space if you don't have initialized data
7062 \begin_inset LatexCommand \index{Variable initialization}
7063
7064 \end_inset
7065
7066 .
7067 \layout List
7068 \labelwidthstring 00.00.0000
7069
7070
7071 \series bold
7072 -
7073 \begin_inset ERT
7074 status Collapsed
7075
7076 \layout Standard
7077
7078 \backslash
7079 /
7080 \end_inset
7081
7082 -nooverlay
7083 \begin_inset LatexCommand \index{-\/-nooverlay}
7084
7085 \end_inset
7086
7087
7088 \series default
7089   The compiler will not overlay parameters and local variables of any function,
7090  see section Parameters and local variables for more details.
7091 \layout List
7092 \labelwidthstring 00.00.0000
7093
7094
7095 \series bold
7096 -
7097 \begin_inset ERT
7098 status Collapsed
7099
7100 \layout Standard
7101
7102 \backslash
7103 /
7104 \end_inset
7105
7106 -no-peep
7107 \begin_inset LatexCommand \index{-\/-no-peep}
7108
7109 \end_inset
7110
7111
7112 \series default
7113  Disable peep-hole optimization with built-in rules.
7114 \layout List
7115 \labelwidthstring 00.00.0000
7116
7117
7118 \series bold
7119 -
7120 \begin_inset ERT
7121 status Collapsed
7122
7123 \layout Standard
7124
7125 \backslash
7126 /
7127 \end_inset
7128
7129 -peep-file
7130 \series default
7131
7132 \begin_inset LatexCommand \index{-\/-peep-file}
7133
7134 \end_inset
7135
7136 \SpecialChar ~
7137 <filename> This option can be used to use additional rules to be used by
7138  the peep hole optimizer.
7139  See section
7140 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
7141
7142 \end_inset
7143
7144 \SpecialChar ~
7145 Peep Hole optimizations for details on how to write these rules.
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 -peep-asm
7162 \begin_inset LatexCommand \index{-\/-peep-asm}
7163
7164 \end_inset
7165
7166
7167 \series default
7168  Pass the inline assembler code through the peep hole optimizer.
7169  This can cause unexpected changes to inline assembler code, please go through
7170  the peephole optimizer
7171 \begin_inset LatexCommand \index{Peephole optimizer}
7172
7173 \end_inset
7174
7175  rules defined in the source file tree '<target>/peeph.def' before using
7176  this option.
7177 \layout List
7178 \labelwidthstring 00.00.0000
7179
7180
7181 \series bold
7182 -
7183 \begin_inset ERT
7184 status Collapsed
7185
7186 \layout Standard
7187
7188 \backslash
7189 /
7190 \end_inset
7191
7192 -opt-code-speed
7193 \begin_inset LatexCommand \index{-\/-opt-code-speed}
7194
7195 \end_inset
7196
7197
7198 \series default
7199  The compiler will optimize code generation towards fast code, possibly
7200  at the expense of code size.
7201 \layout List
7202 \labelwidthstring 00.00.0000
7203
7204
7205 \series bold
7206 -
7207 \begin_inset ERT
7208 status Collapsed
7209
7210 \layout Standard
7211
7212 \backslash
7213 /
7214 \end_inset
7215
7216 -opt-code-size
7217 \begin_inset LatexCommand \index{-\/-opt-code-size}
7218
7219 \end_inset
7220
7221
7222 \series default
7223  The compiler will optimize code generation towards compact code, possibly
7224  at the expense of code speed.
7225 \layout Subsection
7226
7227 Other Options
7228 \begin_inset LatexCommand \index{Options other}
7229
7230 \end_inset
7231
7232
7233 \layout List
7234 \labelwidthstring 00.00.0000
7235
7236
7237 \series bold
7238 -c\SpecialChar ~
7239 -
7240 \begin_inset ERT
7241 status Collapsed
7242
7243 \layout Standard
7244
7245 \backslash
7246 /
7247 \end_inset
7248
7249 -compile-only
7250 \begin_inset LatexCommand \index{-\/-compile-only}
7251
7252 \end_inset
7253
7254
7255 \begin_inset LatexCommand \index{-c -\/-compile-only}
7256
7257 \end_inset
7258
7259
7260 \series default
7261  will compile and assemble the source, but will not call the linkage editor.
7262 \layout List
7263 \labelwidthstring 00.00.0000
7264
7265
7266 \series bold
7267 -
7268 \series default
7269
7270 \begin_inset ERT
7271 status Collapsed
7272
7273 \layout Standard
7274
7275 \backslash
7276 /
7277 \end_inset
7278
7279
7280 \series bold
7281 -c1mode
7282 \begin_inset LatexCommand \index{-\/-c1mode}
7283
7284 \end_inset
7285
7286
7287 \series default
7288  reads the preprocessed source from standard input and compiles it.
7289  The file name for the assembler output must be specified using the -o option.
7290 \layout List
7291 \labelwidthstring 00.00.0000
7292
7293
7294 \series bold
7295 -E
7296 \begin_inset LatexCommand \index{-E}
7297
7298 \end_inset
7299
7300
7301 \series default
7302  Run only the C preprocessor.
7303  Preprocess all the C source files specified and output the results to standard
7304  output.
7305 \layout List
7306 \labelwidthstring 00.00.0000
7307
7308
7309 \series bold
7310 -o\SpecialChar ~
7311 <path/file>
7312 \begin_inset LatexCommand \index{-o <path/file>}
7313
7314 \end_inset
7315
7316
7317 \series default
7318 The output path resp.
7319  file where everything will be placed.
7320  If the parameter is a path, it must have a trailing slash (or backslash
7321  for the Windows binaries) to be recognized as a path.
7322
7323 \layout List
7324 \labelwidthstring 00.00.0000
7325
7326
7327 \series bold
7328 -
7329 \begin_inset ERT
7330 status Collapsed
7331
7332 \layout Standard
7333
7334 \backslash
7335 /
7336 \end_inset
7337
7338 -stack-auto
7339 \begin_inset LatexCommand \index{-\/-stack-auto}
7340
7341 \end_inset
7342
7343
7344 \series default
7345 \size large
7346 \emph on
7347
7348 \size default
7349 \emph default
7350 All functions in the source file will be compiled as
7351 \emph on
7352 reentrant
7353 \emph default
7354
7355 \begin_inset LatexCommand \index{reentrant}
7356
7357 \end_inset
7358
7359 , i.e.
7360  the parameters and local variables will be allocated on the stack
7361 \begin_inset LatexCommand \index{stack}
7362
7363 \end_inset
7364
7365 .
7366  See section
7367 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7368
7369 \end_inset
7370
7371  Parameters and Local Variables for more details.
7372  If this option is used all source files in the project should be compiled
7373  with this option.
7374  It automatically implies --int-long-reent and --float-reent.
7375
7376 \layout List
7377 \labelwidthstring 00.00.0000
7378
7379
7380 \series bold
7381 -
7382 \begin_inset ERT
7383 status Collapsed
7384
7385 \layout Standard
7386
7387 \backslash
7388 /
7389 \end_inset
7390
7391 -callee-saves
7392 \begin_inset LatexCommand \index{-\/-callee-saves}
7393
7394 \end_inset
7395
7396  function1[,function2][,function3]....
7397
7398 \series default
7399  The compiler by default uses a caller saves convention for register saving
7400  across function calls, however this can cause unnecessary register pushing
7401  & popping when calling small functions from larger functions.
7402  This option can be used to switch the register saving convention for the
7403  function names specified.
7404  The compiler will not save registers when calling these functions, no extra
7405  code will be generated at the entry & exit (function prologue
7406 \series bold
7407
7408 \begin_inset LatexCommand \index{function prologue}
7409
7410 \end_inset
7411
7412
7413 \series default
7414  & epilogue
7415 \series bold
7416
7417 \begin_inset LatexCommand \index{function epilogue}
7418
7419 \end_inset
7420
7421
7422 \series default
7423 ) for these functions to save & restore the registers used by these functions,
7424  this can SUBSTANTIALLY reduce code & improve run time performance of the
7425  generated code.
7426  In the future the compiler (with inter procedural analysis) will be able
7427  to determine the appropriate scheme to use for each function call.
7428  DO NOT use this option for built-in functions such as _mulint..., if this
7429  option is used for a library function the appropriate library function
7430  needs to be recompiled with the same option.
7431  If the project consists of multiple source files then all the source file
7432  should be compiled with the same -
7433 \begin_inset ERT
7434 status Collapsed
7435
7436 \layout Standard
7437
7438 \backslash
7439 /
7440 \end_inset
7441
7442 -callee-saves option string.
7443  Also see #pragma\SpecialChar ~
7444 callee_saves
7445 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7446
7447 \end_inset
7448
7449 .
7450 \layout List
7451 \labelwidthstring 00.00.0000
7452
7453
7454 \series bold
7455 -
7456 \begin_inset ERT
7457 status Collapsed
7458
7459 \layout Standard
7460
7461 \backslash
7462 /
7463 \end_inset
7464
7465 -debug
7466 \begin_inset LatexCommand \index{-\/-debug}
7467
7468 \end_inset
7469
7470
7471 \bar under
7472
7473 \series default
7474 \bar default
7475 When this option is used the compiler will generate debug information.
7476  The debug information collected in a file with .cdb extension can be used
7477  with the SDCDB.
7478  For more information see documentation for SDCDB.
7479  Another file with no extension contains debug information in AOMF or AOMF51
7480 \begin_inset LatexCommand \index{AOMF, AOMF51}
7481
7482 \end_inset
7483
7484  format which is commonly used by third party tools.
7485 \layout List
7486 \labelwidthstring 00.00.0000
7487
7488
7489 \series bold
7490 -S
7491 \begin_inset LatexCommand \index{-S}
7492
7493 \end_inset
7494
7495
7496 \size large
7497 \bar under
7498
7499 \series default
7500 \size default
7501 \bar default
7502 Stop after the stage of compilation proper; do not assemble.
7503  The output is an assembler code file for the input file specified.
7504 \layout List
7505 \labelwidthstring 00.00.0000
7506
7507
7508 \series bold
7509 -
7510 \begin_inset ERT
7511 status Collapsed
7512
7513 \layout Standard
7514
7515 \backslash
7516 /
7517 \end_inset
7518
7519 -int-long-reent
7520 \begin_inset LatexCommand \index{-\/-int-long-reent}
7521
7522 \end_inset
7523
7524
7525 \series default
7526  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7527  Note by default these libraries are compiled as non-reentrant.
7528  See section Installation for more details.
7529 \layout List
7530 \labelwidthstring 00.00.0000
7531
7532
7533 \series bold
7534 -
7535 \begin_inset ERT
7536 status Collapsed
7537
7538 \layout Standard
7539
7540 \backslash
7541 /
7542 \end_inset
7543
7544 -cyclomatic
7545 \begin_inset LatexCommand \index{-\/-cyclomatic}
7546
7547 \end_inset
7548
7549
7550 \bar under
7551
7552 \series default
7553 \bar default
7554 This option will cause the compiler to generate an information message for
7555  each function in the source file.
7556  The message contains some
7557 \emph on
7558 important
7559 \emph default
7560  information about the function.
7561  The number of edges and nodes the compiler detected in the control flow
7562  graph of the function, and most importantly the
7563 \emph on
7564 cyclomatic complexity
7565 \begin_inset LatexCommand \index{Cyclomatic complexity}
7566
7567 \end_inset
7568
7569
7570 \emph default
7571  see section on Cyclomatic Complexity for more details.
7572 \layout List
7573 \labelwidthstring 00.00.0000
7574
7575
7576 \series bold
7577 -
7578 \begin_inset ERT
7579 status Collapsed
7580
7581 \layout Standard
7582
7583 \backslash
7584 /
7585 \end_inset
7586
7587 -float-reent
7588 \begin_inset LatexCommand \index{-\/-float-reent}
7589
7590 \end_inset
7591
7592
7593 \series default
7594  Floating point library is compiled as reentrant
7595 \begin_inset LatexCommand \index{reentrant}
7596
7597 \end_inset
7598
7599 .
7600  See section Installation for more details.
7601 \layout List
7602 \labelwidthstring 00.00.0000
7603
7604
7605 \series bold
7606 -
7607 \begin_inset ERT
7608 status Collapsed
7609
7610 \layout Standard
7611
7612 \backslash
7613 /
7614 \end_inset
7615
7616 -main-return
7617 \begin_inset LatexCommand \index{-\/-main-return}
7618
7619 \end_inset
7620
7621
7622 \series default
7623  This option can be used if the code generated is called by a monitor program
7624  or if the main routine includes an endless loop.
7625  This option might result in slightly smaller code and save two bytes of
7626  stack space.
7627  The return from the 'main'
7628 \begin_inset LatexCommand \index{main return}
7629
7630 \end_inset
7631
7632  function will return to the function calling main.
7633  The default setting is to lock up i.e.
7634  generate a '
7635 \family typewriter
7636 sjmp .
7637 \family default
7638 '.
7639 \layout List
7640 \labelwidthstring 00.00.0000
7641
7642
7643 \series bold
7644 -
7645 \begin_inset ERT
7646 status Collapsed
7647
7648 \layout Standard
7649
7650 \backslash
7651 /
7652 \end_inset
7653
7654 -nostdinc
7655 \begin_inset LatexCommand \index{-\/-nostdinc}
7656
7657 \end_inset
7658
7659
7660 \series default
7661  This will prevent the compiler from passing on the default include path
7662  to the preprocessor.
7663 \layout List
7664 \labelwidthstring 00.00.0000
7665
7666
7667 \series bold
7668 -
7669 \begin_inset ERT
7670 status Collapsed
7671
7672 \layout Standard
7673
7674 \backslash
7675 /
7676 \end_inset
7677
7678 -nostdlib
7679 \begin_inset LatexCommand \index{-\/-nostdlib}
7680
7681 \end_inset
7682
7683
7684 \series default
7685  This will prevent the compiler from passing on the default library
7686 \begin_inset LatexCommand \index{Libraries}
7687
7688 \end_inset
7689
7690  path to the linker.
7691 \layout List
7692 \labelwidthstring 00.00.0000
7693
7694
7695 \series bold
7696 -
7697 \begin_inset ERT
7698 status Collapsed
7699
7700 \layout Standard
7701
7702 \backslash
7703 /
7704 \end_inset
7705
7706 -verbose
7707 \begin_inset LatexCommand \index{-\/-verbose}
7708
7709 \end_inset
7710
7711
7712 \series default
7713  Shows the various actions the compiler is performing.
7714 \layout List
7715 \labelwidthstring 00.00.0000
7716
7717
7718 \series bold
7719 -V
7720 \begin_inset LatexCommand \index{-V}
7721
7722 \end_inset
7723
7724
7725 \series default
7726  Shows the actual commands the compiler is executing.
7727 \layout List
7728 \labelwidthstring 00.00.0000
7729
7730
7731 \series bold
7732 -
7733 \begin_inset ERT
7734 status Collapsed
7735
7736 \layout Standard
7737
7738 \backslash
7739 /
7740 \end_inset
7741
7742 -no-c-code-in-asm
7743 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7744
7745 \end_inset
7746
7747
7748 \series default
7749  Hides your ugly and inefficient c-code from the asm file, so you can always
7750  blame the compiler :)
7751 \layout List
7752 \labelwidthstring 00.00.0000
7753
7754
7755 \series bold
7756 -
7757 \begin_inset ERT
7758 status Collapsed
7759
7760 \layout Standard
7761
7762 \backslash
7763 /
7764 \end_inset
7765
7766 -no-peep-comments
7767 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7768
7769 \end_inset
7770
7771
7772 \series default
7773  Will not include peep-hole comments in the generated files.
7774 \layout List
7775 \labelwidthstring 00.00.0000
7776
7777
7778 \series bold
7779 -
7780 \begin_inset ERT
7781 status Collapsed
7782
7783 \layout Standard
7784
7785 \backslash
7786 /
7787 \end_inset
7788
7789 -i-code-in-asm
7790 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7791
7792 \end_inset
7793
7794
7795 \series default
7796  Include i-codes in the asm file.
7797  Sounds like noise but is most helpful for debugging the compiler itself.
7798 \layout List
7799 \labelwidthstring 00.00.0000
7800
7801
7802 \series bold
7803 -
7804 \begin_inset ERT
7805 status Collapsed
7806
7807 \layout Standard
7808
7809 \backslash
7810 /
7811 \end_inset
7812
7813 -less-pedantic
7814 \begin_inset LatexCommand \index{-\/-less-pedantic}
7815
7816 \end_inset
7817
7818
7819 \series default
7820  Disable some of the more pedantic warnings
7821 \begin_inset LatexCommand \index{Warnings}
7822
7823 \end_inset
7824
7825  (jwk burps: please be more specific here, please!).
7826 \layout List
7827 \labelwidthstring 00.00.0000
7828
7829
7830 \series bold
7831 -
7832 \begin_inset ERT
7833 status Collapsed
7834
7835 \layout Standard
7836
7837 \backslash
7838 /
7839 \end_inset
7840
7841 -disable-warning\SpecialChar ~
7842 <nnnn>
7843 \begin_inset LatexCommand \index{-\/-disable-warning}
7844
7845 \end_inset
7846
7847
7848 \series default
7849  Disable specific warning with number <nnnn>.
7850 \layout List
7851 \labelwidthstring 00.00.0000
7852
7853
7854 \series bold
7855 -
7856 \begin_inset ERT
7857 status Collapsed
7858
7859 \layout Standard
7860
7861 \backslash
7862 /
7863 \end_inset
7864
7865 -print-search-dirs
7866 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7867
7868 \end_inset
7869
7870
7871 \series default
7872  Display the directories in the compiler's search path
7873 \layout List
7874 \labelwidthstring 00.00.0000
7875
7876
7877 \series bold
7878 -
7879 \begin_inset ERT
7880 status Collapsed
7881
7882 \layout Standard
7883
7884 \backslash
7885 /
7886 \end_inset
7887
7888 -vc
7889 \begin_inset LatexCommand \index{-\/-vc}
7890
7891 \end_inset
7892
7893
7894 \series default
7895  Display errors and warnings using MSVC style, so you can use SDCC with
7896  visual studio.
7897 \layout List
7898 \labelwidthstring 00.00.0000
7899
7900
7901 \series bold
7902 -
7903 \begin_inset ERT
7904 status Collapsed
7905
7906 \layout Standard
7907
7908 \backslash
7909 /
7910 \end_inset
7911
7912 -use-stdout
7913 \begin_inset LatexCommand \index{-\/-use-stdout}
7914
7915 \end_inset
7916
7917
7918 \series default
7919  Send errors and warnings to stdout instead of stderr.
7920 \layout List
7921 \labelwidthstring 00.00.0000
7922
7923
7924 \series bold
7925 -Wa\SpecialChar ~
7926 asmOption[,asmOption]
7927 \series default
7928
7929 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7930
7931 \end_inset
7932
7933 ...
7934  Pass the asmOption to the assembler
7935 \begin_inset LatexCommand \index{Options assembler}
7936
7937 \end_inset
7938
7939
7940 \begin_inset LatexCommand \index{Assembler options}
7941
7942 \end_inset
7943
7944 .
7945  See file sdcc/as/doc/asxhtm.html for assembler options.cd
7946 \layout List
7947 \labelwidthstring 00.00.0000
7948
7949
7950 \series bold
7951 -
7952 \begin_inset ERT
7953 status Collapsed
7954
7955 \layout Standard
7956
7957 \backslash
7958 /
7959 \end_inset
7960
7961 -std-sdcc89
7962 \begin_inset LatexCommand \index{-\/-std-sdcc89}
7963
7964 \end_inset
7965
7966
7967 \series default
7968  Generally follow the C89 standard, but allow SDCC features that conflict
7969  with the standard (default).
7970 \layout List
7971 \labelwidthstring 00.00.0000
7972
7973
7974 \series bold
7975 -
7976 \begin_inset ERT
7977 status Collapsed
7978
7979 \layout Standard
7980
7981 \backslash
7982 /
7983 \end_inset
7984
7985 -std-c89
7986 \begin_inset LatexCommand \index{-\/-std-c89}
7987
7988 \end_inset
7989
7990
7991 \series default
7992  Follow the C89 standard and disable SDCC features that conflict with the
7993  standard.
7994 \layout List
7995 \labelwidthstring 00.00.0000
7996
7997
7998 \series bold
7999 -
8000 \begin_inset ERT
8001 status Collapsed
8002
8003 \layout Standard
8004
8005 \backslash
8006 /
8007 \end_inset
8008
8009 -std-sdcc99
8010 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8011
8012 \end_inset
8013
8014
8015 \series default
8016  Generally follow the C99 standard, but allow SDCC features that conflict
8017  with the standard (incomplete support).
8018 \layout List
8019 \labelwidthstring 00.00.0000
8020
8021
8022 \series bold
8023 -
8024 \begin_inset ERT
8025 status Collapsed
8026
8027 \layout Standard
8028
8029 \backslash
8030 /
8031 \end_inset
8032
8033 -std-c99
8034 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8035
8036 \end_inset
8037
8038
8039 \series default
8040  Follow the C99 standard and disable SDCC features that conflict with the
8041  standard (incomplete support).
8042 \layout List
8043 \labelwidthstring 00.00.0000
8044
8045
8046 \series bold
8047 -
8048 \begin_inset ERT
8049 status Collapsed
8050
8051 \layout Standard
8052
8053 \backslash
8054 /
8055 \end_inset
8056
8057 -codeseg
8058 \series default
8059
8060 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
8061
8062 \end_inset
8063
8064 \SpecialChar ~
8065 <Name> The name to be used for the code
8066 \begin_inset LatexCommand \index{code}
8067
8068 \end_inset
8069
8070  segment, default CSEG.
8071  This is useful if you need to tell the compiler to put the code in a special
8072  segment so you can later on tell the linker to put this segment in a special
8073  place in memory.
8074  Can be used for instance when using bank switching to put the code in a
8075  bank.
8076 \layout List
8077 \labelwidthstring 00.00.0000
8078
8079
8080 \series bold
8081 -
8082 \begin_inset ERT
8083 status Collapsed
8084
8085 \layout Standard
8086
8087 \backslash
8088 /
8089 \end_inset
8090
8091 -constseg
8092 \series default
8093
8094 \begin_inset LatexCommand \index{-\/-constseg <Value>}
8095
8096 \end_inset
8097
8098 \SpecialChar ~
8099 <Name> The name to be used for the const
8100 \begin_inset LatexCommand \index{code}
8101
8102 \end_inset
8103
8104  segment, default CONST.
8105  This is useful if you need to tell the compiler to put the const data in
8106  a special segment so you can later on tell the linker to put this segment
8107  in a special place in memory.
8108  Can be used for instance when using bank switching to put the const data
8109  in a bank.
8110 \layout List
8111 \labelwidthstring 00.00.0000
8112
8113
8114 \series bold
8115 more-pedantic
8116 \series default
8117  Actually this is
8118 \series bold
8119 \emph on
8120 not
8121 \series default
8122 \emph default
8123  a SDCC compiler option but if you want
8124 \emph on
8125 more
8126 \emph default
8127  warnings you can use a separate tool dedicated to syntax checking like
8128  splint
8129 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
8130
8131 \end_inset
8132
8133
8134 \begin_inset LatexCommand \index{lint (syntax checking tool)}
8135
8136 \end_inset
8137
8138
8139 \begin_inset LatexCommand \url{http://www.splint.org}
8140
8141 \end_inset
8142
8143 .
8144  To make your source files parseable by splint you will have to include
8145
8146 \family sans
8147 lint.h
8148 \family default
8149
8150 \begin_inset LatexCommand \index{splint (syntax checking tool)}
8151
8152 \end_inset
8153
8154  in your source file and add brackets around extended keywords (like
8155 \family sans
8156
8157 \begin_inset Quotes sld
8158 \end_inset
8159
8160 __at\SpecialChar ~
8161
8162 \series bold
8163 (
8164 \series default
8165 0xab
8166 \series bold
8167 )
8168 \series default
8169
8170 \begin_inset Quotes srd
8171 \end_inset
8172
8173
8174 \family default
8175  and
8176 \family sans
8177
8178 \begin_inset Quotes sld
8179 \end_inset
8180
8181 __interrupt\SpecialChar ~
8182 (2)
8183 \begin_inset Quotes srd
8184 \end_inset
8185
8186
8187 \family default
8188 ).
8189
8190 \newline
8191 Splint has an excellent on line manual at
8192 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
8193
8194 \end_inset
8195
8196  and it's capabilities go beyond pure syntax checking.
8197  You'll need to tell splint the location of SDCC's include files so a typical
8198  command line could look like this:
8199 \newline
8200
8201 \family sans
8202 splint\SpecialChar ~
8203 -I\SpecialChar ~
8204 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
8205 \SpecialChar ~
8206 myprogram.c
8207 \layout Subsection
8208
8209 Intermediate Dump Options
8210 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
8211
8212 \end_inset
8213
8214
8215 \begin_inset LatexCommand \index{Options intermediate dump}
8216
8217 \end_inset
8218
8219
8220 \begin_inset LatexCommand \index{Intermediate dump options}
8221
8222 \end_inset
8223
8224
8225 \layout Standard
8226
8227 The following options are provided for the purpose of retargetting and debugging
8228  the compiler.
8229  They provide a means to dump the intermediate code (iCode
8230 \begin_inset LatexCommand \index{iCode}
8231
8232 \end_inset
8233
8234 ) generated by the compiler in human readable form at various stages of
8235  the compilation process.
8236  More on iCodes see chapter
8237 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8238
8239 \end_inset
8240
8241
8242 \begin_inset Quotes srd
8243 \end_inset
8244
8245 The anatomy of the compiler
8246 \begin_inset Quotes srd
8247 \end_inset
8248
8249 .
8250 \layout List
8251 \labelwidthstring 00.00.0000
8252
8253
8254 \series bold
8255 -
8256 \begin_inset ERT
8257 status Collapsed
8258
8259 \layout Standard
8260
8261 \backslash
8262 /
8263 \end_inset
8264
8265 -dumpraw
8266 \begin_inset LatexCommand \index{-\/-dumpraw}
8267
8268 \end_inset
8269
8270
8271 \series default
8272  This option will cause the compiler to dump the intermediate code into
8273  a file of named
8274 \emph on
8275 <source filename>.dumpraw
8276 \emph default
8277  just after the intermediate code has been generated for a function, i.e.
8278  before any optimizations are done.
8279  The basic blocks
8280 \begin_inset LatexCommand \index{Basic blocks}
8281
8282 \end_inset
8283
8284  at this stage ordered in the depth first number, so they may not be in
8285  sequence of execution.
8286 \layout List
8287 \labelwidthstring 00.00.0000
8288
8289
8290 \series bold
8291 -
8292 \begin_inset ERT
8293 status Collapsed
8294
8295 \layout Standard
8296
8297 \backslash
8298 /
8299 \end_inset
8300
8301 -dumpgcse
8302 \begin_inset LatexCommand \index{-\/-dumpgcse}
8303
8304 \end_inset
8305
8306
8307 \series default
8308  Will create a dump of iCode's, after global subexpression elimination
8309 \begin_inset LatexCommand \index{Global subexpression elimination}
8310
8311 \end_inset
8312
8313 , into a file named
8314 \emph on
8315 <source filename>.dumpgcse.
8316 \layout List
8317 \labelwidthstring 00.00.0000
8318
8319
8320 \series bold
8321 -
8322 \begin_inset ERT
8323 status Collapsed
8324
8325 \layout Standard
8326
8327 \backslash
8328 /
8329 \end_inset
8330
8331 -dumpdeadcode
8332 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8333
8334 \end_inset
8335
8336
8337 \series default
8338  Will create a dump of iCode's, after deadcode elimination
8339 \begin_inset LatexCommand \index{Dead-code elimination}
8340
8341 \end_inset
8342
8343 , into a file named
8344 \emph on
8345 <source filename>.dumpdeadcode.
8346 \layout List
8347 \labelwidthstring 00.00.0000
8348
8349
8350 \series bold
8351 -
8352 \begin_inset ERT
8353 status Collapsed
8354
8355 \layout Standard
8356
8357 \backslash
8358 /
8359 \end_inset
8360
8361 -dumploop
8362 \begin_inset LatexCommand \index{-\/-dumploop}
8363
8364 \end_inset
8365
8366
8367 \series default
8368 \size large
8369
8370 \size default
8371 Will create a dump of iCode's, after loop optimizations
8372 \begin_inset LatexCommand \index{Loop optimization}
8373
8374 \end_inset
8375
8376 , into a file named
8377 \emph on
8378 <source filename>.dumploop.
8379 \layout List
8380 \labelwidthstring 00.00.0000
8381
8382
8383 \series bold
8384 -
8385 \begin_inset ERT
8386 status Collapsed
8387
8388 \layout Standard
8389
8390 \backslash
8391 /
8392 \end_inset
8393
8394 -dumprange
8395 \begin_inset LatexCommand \index{-\/-dumprange}
8396
8397 \end_inset
8398
8399
8400 \series default
8401 \size large
8402
8403 \size default
8404 Will create a dump of iCode's, after live range analysis
8405 \begin_inset LatexCommand \index{Live range analysis}
8406
8407 \end_inset
8408
8409 , into a file named
8410 \emph on
8411 <source filename>.dumprange.
8412 \layout List
8413 \labelwidthstring 00.00.0000
8414
8415
8416 \series bold
8417 -
8418 \begin_inset ERT
8419 status Collapsed
8420
8421 \layout Standard
8422
8423 \backslash
8424 /
8425 \end_inset
8426
8427 -dumlrange
8428 \begin_inset LatexCommand \index{-\/-dumlrange}
8429
8430 \end_inset
8431
8432
8433 \series default
8434  Will dump the life ranges
8435 \begin_inset LatexCommand \index{Live range analysis}
8436
8437 \end_inset
8438
8439  for all symbols.
8440 \layout List
8441 \labelwidthstring 00.00.0000
8442
8443
8444 \series bold
8445 -
8446 \begin_inset ERT
8447 status Collapsed
8448
8449 \layout Standard
8450
8451 \backslash
8452 /
8453 \end_inset
8454
8455 -dumpregassign
8456 \begin_inset LatexCommand \index{-\/-dumpregassign}
8457
8458 \end_inset
8459
8460
8461 \bar under
8462
8463 \series default
8464 \bar default
8465 Will create a dump of iCode's, after register assignment
8466 \begin_inset LatexCommand \index{Register assignment}
8467
8468 \end_inset
8469
8470 , into a file named
8471 \emph on
8472 <source filename>.dumprassgn.
8473 \layout List
8474 \labelwidthstring 00.00.0000
8475
8476
8477 \series bold
8478 -
8479 \begin_inset ERT
8480 status Collapsed
8481
8482 \layout Standard
8483
8484 \backslash
8485 /
8486 \end_inset
8487
8488 -dumplrange
8489 \begin_inset LatexCommand \index{-\/-dumplrange}
8490
8491 \end_inset
8492
8493
8494 \series default
8495  Will create a dump of the live ranges of iTemp's
8496 \layout List
8497 \labelwidthstring 00.00.0000
8498
8499
8500 \series bold
8501 -
8502 \begin_inset ERT
8503 status Collapsed
8504
8505 \layout Standard
8506
8507 \backslash
8508 /
8509 \end_inset
8510
8511 -dumpall
8512 \begin_inset LatexCommand \index{-\/-dumpall}
8513
8514 \end_inset
8515
8516
8517 \size large
8518 \bar under
8519
8520 \series default
8521 \size default
8522 \bar default
8523 Will cause all the above mentioned dumps to be created.
8524 \layout Subsection
8525
8526 Redirecting output on Windows Shells
8527 \layout Standard
8528
8529 By default SDCC writes it's error messages to
8530 \begin_inset Quotes sld
8531 \end_inset
8532
8533 standard error
8534 \begin_inset Quotes srd
8535 \end_inset
8536
8537 .
8538  To force all messages to
8539 \begin_inset Quotes sld
8540 \end_inset
8541
8542 standard output
8543 \begin_inset Quotes srd
8544 \end_inset
8545
8546  use
8547 \series bold
8548 -
8549 \series default
8550 \emph on
8551
8552 \begin_inset ERT
8553 status Collapsed
8554
8555 \layout Standard
8556
8557 \backslash
8558 /
8559 \end_inset
8560
8561
8562 \series bold
8563 \emph default
8564 -
8565 \series default
8566 use-stdout
8567 \begin_inset LatexCommand \index{-\/-use-stdout}
8568
8569 \end_inset
8570
8571 .
8572  Additionally, if you happen to have visual studio installed in your windows
8573  machine, you can use it to compile your sources using a custom build and
8574  the SDCC -
8575 \emph on
8576
8577 \begin_inset ERT
8578 status Collapsed
8579
8580 \layout Standard
8581
8582 \backslash
8583 /
8584 \end_inset
8585
8586
8587 \emph default
8588 -vc
8589 \begin_inset LatexCommand \index{-\/-vc}
8590
8591 \end_inset
8592
8593  option.
8594  Something like this should work:
8595 \newline
8596
8597 \newline
8598
8599 \series bold
8600 c:
8601 \backslash
8602 sdcc
8603 \backslash
8604 bin
8605 \backslash
8606 sdcc.exe -
8607 \series default
8608 \emph on
8609
8610 \begin_inset ERT
8611 status Collapsed
8612
8613 \layout Standard
8614
8615 \backslash
8616 /
8617 \end_inset
8618
8619
8620 \series bold
8621 \emph default
8622 -vc -
8623 \series default
8624 \emph on
8625
8626 \begin_inset ERT
8627 status Collapsed
8628
8629 \layout Standard
8630
8631 \backslash
8632 /
8633 \end_inset
8634
8635
8636 \series bold
8637 \emph default
8638 -model-large -c $(InputPath)
8639 \layout Section
8640
8641 Environment variables
8642 \begin_inset LatexCommand \index{Environment variables}
8643
8644 \end_inset
8645
8646
8647 \layout Standard
8648
8649 SDCC recognizes the following environment variables:
8650 \layout List
8651 \labelwidthstring 00.00.0000
8652
8653
8654 \series bold
8655 SDCC_LEAVE_SIGNALS
8656 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
8657
8658 \end_inset
8659
8660
8661 \series default
8662  SDCC installs a signal handler
8663 \begin_inset LatexCommand \index{signal handler}
8664
8665 \end_inset
8666
8667  to be able to delete temporary files after an user break (^C) or an exception.
8668  If this environment variable is set, SDCC won't install the signal handler
8669  in order to be able to debug SDCC.
8670 \layout List
8671 \labelwidthstring 00.00.0000
8672
8673
8674 \series bold
8675 TMP,\SpecialChar ~
8676 TEMP,\SpecialChar ~
8677 TMPDIR
8678 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
8679
8680 \end_inset
8681
8682
8683 \series default
8684  Path, where temporary files will be created.
8685  The order of the variables is the search order.
8686  In a standard *nix environment these variables are not set, and there's
8687  no need to set them.
8688  On Windows it's recommended to set one of them.
8689 \layout List
8690 \labelwidthstring 00.00.0000
8691
8692
8693 \series bold
8694 SDCC_HOME
8695 \begin_inset LatexCommand \index{SDCC\_HOME}
8696
8697 \end_inset
8698
8699
8700 \series default
8701  Path, see section
8702 \begin_inset LatexCommand \ref{sub:Install-paths}
8703
8704 \end_inset
8705
8706 \SpecialChar ~
8707
8708 \begin_inset Quotes sld
8709 \end_inset
8710
8711  Install Paths
8712 \begin_inset Quotes srd
8713 \end_inset
8714
8715 .
8716 \layout List
8717 \labelwidthstring 00.00.0000
8718
8719
8720 \series bold
8721 SDCC_INCLUDE
8722 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8723
8724 \end_inset
8725
8726
8727 \series default
8728  Path, see section
8729 \begin_inset LatexCommand \ref{sub:Search-Paths}
8730
8731 \end_inset
8732
8733 \SpecialChar ~
8734
8735 \begin_inset Quotes sld
8736 \end_inset
8737
8738 Search Paths
8739 \begin_inset Quotes srd
8740 \end_inset
8741
8742 .
8743 \layout List
8744 \labelwidthstring 00.00.0000
8745
8746
8747 \series bold
8748 SDCC_LIB
8749 \begin_inset LatexCommand \index{SDCC\_LIB}
8750
8751 \end_inset
8752
8753
8754 \series default
8755  Path, see section
8756 \begin_inset LatexCommand \ref{sub:Search-Paths}
8757
8758 \end_inset
8759
8760 \SpecialChar ~
8761
8762 \begin_inset Quotes sld
8763 \end_inset
8764
8765 Search Paths
8766 \begin_inset Quotes srd
8767 \end_inset
8768
8769 ..
8770 \layout Standard
8771
8772 There are some more environment variables recognized by SDCC, but these
8773  are solely used for debugging purposes.
8774  They can change or disappear very quickly, and will never be documented.
8775 \layout Section
8776
8777 Storage Class Language Extensions
8778 \layout Subsection
8779
8780 MCS51/DS390 Storage Class
8781 \begin_inset LatexCommand \index{Storage class}
8782
8783 \end_inset
8784
8785  Language Extensions
8786 \layout Standard
8787
8788 In addition to the ANSI storage classes SDCC allows the following MCS51
8789  specific storage classes:
8790 \layout Subsubsection
8791
8792 data
8793 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8794
8795 \end_inset
8796
8797
8798 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
8799
8800 \end_inset
8801
8802  / near
8803 \begin_inset LatexCommand \index{near (storage class)}
8804
8805 \end_inset
8806
8807
8808 \begin_inset LatexCommand \index{\_\_near (storage class)}
8809
8810 \end_inset
8811
8812
8813 \layout Standard
8814
8815 This is the
8816 \series bold
8817 default
8818 \series default
8819  storage class for the Small Memory model (
8820 \emph on
8821 data
8822 \emph default
8823  and
8824 \emph on
8825 near
8826 \emph default
8827  can be used synonymously).
8828  Variables declared with this storage class will be allocated in the directly
8829  addressable portion of the internal RAM of a 8051, e.g.:
8830 \layout Verse
8831
8832
8833 \family typewriter
8834 data unsigned char test_data;
8835 \layout Standard
8836
8837 Writing 0x01 to this variable generates the assembly code:
8838 \layout Verse
8839
8840
8841 \family typewriter
8842 75*00 01\SpecialChar ~
8843 \SpecialChar ~
8844 \SpecialChar ~
8845 mov\SpecialChar ~
8846 \SpecialChar ~
8847 _test_data,#0x01
8848 \layout Subsubsection
8849
8850 xdata
8851 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8852
8853 \end_inset
8854
8855
8856 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
8857
8858 \end_inset
8859
8860  / far
8861 \begin_inset LatexCommand \index{far (storage class)}
8862
8863 \end_inset
8864
8865
8866 \begin_inset LatexCommand \index{\_\_far (storage class)}
8867
8868 \end_inset
8869
8870
8871 \layout Standard
8872
8873 Variables declared with this storage class will be placed in the external
8874  RAM.
8875  This is the
8876 \series bold
8877 default
8878 \series default
8879  storage class for the Large Memory model, e.g.:
8880 \layout Verse
8881
8882
8883 \family typewriter
8884 xdata unsigned char test_xdata;
8885 \layout Standard
8886
8887 Writing 0x01 to this variable generates the assembly code:
8888 \layout Verse
8889
8890
8891 \family typewriter
8892 90s00r00\SpecialChar ~
8893 \SpecialChar ~
8894 \SpecialChar ~
8895 mov\SpecialChar ~
8896 \SpecialChar ~
8897 dptr,#_test_xdata
8898 \newline
8899 74\SpecialChar ~
8900 01\SpecialChar ~
8901 \SpecialChar ~
8902 \SpecialChar ~
8903 \SpecialChar ~
8904 \SpecialChar ~
8905 \SpecialChar ~
8906 mov\SpecialChar ~
8907 \SpecialChar ~
8908 a,#0x01
8909 \newline
8910 F0\SpecialChar ~
8911 \SpecialChar ~
8912 \SpecialChar ~
8913 \SpecialChar ~
8914 \SpecialChar ~
8915 \SpecialChar ~
8916 \SpecialChar ~
8917 \SpecialChar ~
8918 \SpecialChar ~
8919 movx\SpecialChar ~
8920 @dptr,a
8921 \layout Subsubsection
8922
8923 idata
8924 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8925
8926 \end_inset
8927
8928
8929 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
8930
8931 \end_inset
8932
8933
8934 \layout Standard
8935
8936 Variables declared with this storage class will be allocated into the indirectly
8937  addressable portion of the internal ram of a 8051, e.g.:
8938 \layout Verse
8939
8940
8941 \family typewriter
8942 idata unsigned char test_idata;
8943 \layout Standard
8944
8945 Writing 0x01 to this variable generates the assembly code:
8946 \layout Verse
8947
8948
8949 \family typewriter
8950 78r00\SpecialChar ~
8951 \SpecialChar ~
8952 \SpecialChar ~
8953 \SpecialChar ~
8954 \SpecialChar ~
8955 \SpecialChar ~
8956 \SpecialChar ~
8957 mov\SpecialChar ~
8958 \SpecialChar ~
8959 r0,#_test_idata
8960 \newline
8961 76\SpecialChar ~
8962 01\SpecialChar ~
8963 \SpecialChar ~
8964 \SpecialChar ~
8965 \SpecialChar ~
8966 \SpecialChar ~
8967 \SpecialChar ~
8968 \SpecialChar ~
8969 mov\SpecialChar ~
8970 \SpecialChar ~
8971 @r0,#0x01
8972 \layout Standard
8973
8974 Please note, the first 128 byte of idata physically access the same RAM
8975  as the data memory.
8976  The original 8051 had 128 byte idata memory, nowadays most devices have
8977  256 byte idata memory.
8978  The stack
8979 \begin_inset LatexCommand \index{stack}
8980
8981 \end_inset
8982
8983  is located in idata memory.
8984 \layout Subsubsection
8985
8986 pdata
8987 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8988
8989 \end_inset
8990
8991
8992 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
8993
8994 \end_inset
8995
8996
8997 \layout Standard
8998
8999 Paged xdata access is just as straightforward as using the other addressing
9000  modes of a 8051.
9001  It is typically located at the start of xdata and has a maximum size of
9002  256 bytes.
9003  The following example writes 0x01 to the pdata variable.
9004  Please note, pdata access physically accesses xdata memory.
9005  The high byte of the address is determined by port P2
9006 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
9007
9008 \end_inset
9009
9010 (or in case of some 8051 variants by a separate Special Function Register,
9011  see section
9012 \begin_inset LatexCommand \ref{sub:MCS51-variants}
9013
9014 \end_inset
9015
9016 ).
9017  This is the
9018 \series bold
9019 default
9020 \series default
9021  storage class for the Medium Memory model, e.g.:
9022 \layout Verse
9023
9024
9025 \family typewriter
9026 pdata unsigned char test_pdata;
9027 \layout Standard
9028
9029 Writing 0x01 to this variable generates the assembly code:
9030 \layout Verse
9031
9032
9033 \family typewriter
9034 78r00\SpecialChar ~
9035 \SpecialChar ~
9036 \SpecialChar ~
9037 \SpecialChar ~
9038 \SpecialChar ~
9039 \SpecialChar ~
9040 mov r0,#_test_pdata
9041 \newline
9042 74 01\SpecialChar ~
9043 \SpecialChar ~
9044 \SpecialChar ~
9045 \SpecialChar ~
9046 \SpecialChar ~
9047 \SpecialChar ~
9048 mov a,#0x01
9049 \newline
9050 F2\SpecialChar ~
9051 \SpecialChar ~
9052 \SpecialChar ~
9053 \SpecialChar ~
9054 \SpecialChar ~
9055 \SpecialChar ~
9056 \SpecialChar ~
9057 \SpecialChar ~
9058 \SpecialChar ~
9059 movx @r0,a
9060 \layout Standard
9061
9062 If the -
9063 \begin_inset ERT
9064 status Collapsed
9065
9066 \layout Standard
9067
9068 \backslash
9069 /
9070 \end_inset
9071
9072 -xstack
9073 \begin_inset LatexCommand \index{-\/-xstack}
9074
9075 \end_inset
9076
9077  option is used the pdata memory area is followed by the xstack memory area
9078  and the sum of their sizes is limited to 256 bytes.
9079 \layout Subsubsection
9080
9081 code
9082 \begin_inset LatexCommand \index{code}
9083
9084 \end_inset
9085
9086
9087 \begin_inset LatexCommand \index{\_\_code}
9088
9089 \end_inset
9090
9091
9092 \layout Standard
9093
9094 'Variables' declared with this storage class will be placed in the code
9095  memory:
9096 \layout Verse
9097
9098
9099 \family typewriter
9100 code unsigned char test_code;
9101 \layout Standard
9102
9103 Read access to this variable generates the assembly code:
9104 \layout Verse
9105
9106
9107 \family typewriter
9108 90s00r6F\SpecialChar ~
9109 \SpecialChar ~
9110 \SpecialChar ~
9111 mov dptr,#_test_code
9112 \newline
9113 E4\SpecialChar ~
9114 \SpecialChar ~
9115 \SpecialChar ~
9116 \SpecialChar ~
9117 \SpecialChar ~
9118 \SpecialChar ~
9119 \SpecialChar ~
9120 \SpecialChar ~
9121 \SpecialChar ~
9122 clr a
9123 \newline
9124 93\SpecialChar ~
9125 \SpecialChar ~
9126 \SpecialChar ~
9127 \SpecialChar ~
9128 \SpecialChar ~
9129 \SpecialChar ~
9130 \SpecialChar ~
9131 \SpecialChar ~
9132 \SpecialChar ~
9133 movc a,@a+dptr
9134 \layout Standard
9135
9136
9137 \family typewriter
9138 char
9139 \family default
9140  indexed arrays of characters in code memory can be accessed efficiently:
9141 \layout Verse
9142
9143
9144 \family typewriter
9145 code char test_array[] = {'c','h','e','a','p'};
9146 \layout Standard
9147
9148 Read access to this array using an 8-bit unsigned index generates the assembly
9149  code:
9150 \layout Verse
9151
9152
9153 \family typewriter
9154 E5*00\SpecialChar ~
9155 \SpecialChar ~
9156 \SpecialChar ~
9157 \SpecialChar ~
9158 \SpecialChar ~
9159 \SpecialChar ~
9160 mov a,_index
9161 \layout Verse
9162
9163
9164 \family typewriter
9165 90s00r41\SpecialChar ~
9166 \SpecialChar ~
9167 \SpecialChar ~
9168 mov dptr,#_test_array
9169 \layout Verse
9170
9171
9172 \family typewriter
9173 93\SpecialChar ~
9174 \SpecialChar ~
9175 \SpecialChar ~
9176 \SpecialChar ~
9177 \SpecialChar ~
9178 \SpecialChar ~
9179 \SpecialChar ~
9180 \SpecialChar ~
9181 \SpecialChar ~
9182 movc a,@a+dptr
9183 \layout Subsubsection
9184
9185 bit
9186 \begin_inset LatexCommand \index{bit}
9187
9188 \end_inset
9189
9190
9191 \begin_inset LatexCommand \index{\_\_bit}
9192
9193 \end_inset
9194
9195
9196 \layout Standard
9197
9198 This is a data-type and a storage class specifier.
9199  When a variable is declared as a bit, it is allocated into the bit addressable
9200  memory of 8051, e.g.:
9201 \layout Verse
9202
9203
9204 \family typewriter
9205 bit test_bit;
9206 \layout Standard
9207
9208 Writing 1 to this variable generates the assembly code:
9209 \layout Verse
9210
9211
9212 \family typewriter
9213 D2*00\SpecialChar ~
9214 \SpecialChar ~
9215 \SpecialChar ~
9216 \SpecialChar ~
9217 \SpecialChar ~
9218 \SpecialChar ~
9219 \SpecialChar ~
9220 setb\SpecialChar ~
9221 _test_bit
9222 \layout Standard
9223
9224 The bit addressable memory consists of 128 bits which are located from 0x20
9225  to 0x2f in data memory.
9226
9227 \newline
9228 Apart from this 8051 specific storage class most architectures support ANSI-C
9229  bitfields
9230 \begin_inset LatexCommand \index{bitfields}
9231
9232 \end_inset
9233
9234
9235 \begin_inset Foot
9236 collapsed false
9237
9238 \layout Standard
9239
9240 Not really meant as examples, but nevertheless showing what bitfields are
9241  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9242 \end_inset
9243
9244 .
9245  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9246  signed modifier are implemented as unsigned.
9247 \layout Subsubsection
9248
9249 sfr
9250 \begin_inset LatexCommand \index{sfr}
9251
9252 \end_inset
9253
9254
9255 \begin_inset LatexCommand \index{\_\_sfr}
9256
9257 \end_inset
9258
9259  / sfr16
9260 \begin_inset LatexCommand \index{sfr16}
9261
9262 \end_inset
9263
9264
9265 \begin_inset LatexCommand \index{\_\_sfr16}
9266
9267 \end_inset
9268
9269  / sfr32
9270 \begin_inset LatexCommand \index{sfr32}
9271
9272 \end_inset
9273
9274
9275 \begin_inset LatexCommand \index{\_\_sfr32}
9276
9277 \end_inset
9278
9279  / sbit
9280 \begin_inset LatexCommand \index{\_\_sbit}
9281
9282 \end_inset
9283
9284
9285 \layout Standard
9286
9287 Like the bit keyword,
9288 \emph on
9289 sfr / sfr16 / sfr32 / sbit
9290 \emph default
9291 signify both a data-type and storage class, they are used to describe the
9292
9293 \emph on
9294 s
9295 \emph default
9296 pecial
9297 \emph on
9298 f
9299 \emph default
9300 unction
9301 \emph on
9302 r
9303 \emph default
9304 egisters and
9305 \emph on
9306 s
9307 \emph default
9308 pecial
9309 \emph on
9310 bit
9311 \emph default
9312  variables of a 8051, eg:
9313 \layout Verse
9314
9315
9316 \family typewriter
9317 sfr at
9318 \begin_inset LatexCommand \index{at}
9319
9320 \end_inset
9321
9322
9323 \begin_inset LatexCommand \index{\_\_at}
9324
9325 \end_inset
9326
9327  0x80 P0;\SpecialChar ~
9328  /* special function register P0 at location 0x80 */
9329 \newline
9330 /* 16 bit special function register combination for timer 0 */
9331 \newline
9332 /* with the high byte at location 0x8C and the low byte at location 0x8A
9333  */
9334 \newline
9335 sfr16 at
9336 \begin_inset LatexCommand \index{at}
9337
9338 \end_inset
9339
9340
9341 \begin_inset LatexCommand \index{\_\_at}
9342
9343 \end_inset
9344
9345  0x8C8A TMR0;
9346 \newline
9347 sbit at 0xd7 CY; /* CY (Carry Flag
9348 \begin_inset LatexCommand \index{Flags}
9349
9350 \end_inset
9351
9352
9353 \begin_inset LatexCommand \index{Carry flag}
9354
9355 \end_inset
9356
9357 ) */
9358 \layout Standard
9359
9360 Special function registers which are located on an address dividable by
9361  8 are bit-addressable, an
9362 \emph on
9363  sbit
9364 \emph default
9365  addresses a specific bit within these sfr.
9366 \newline
9367 16 Bit and 32 bit special function register combinations which require a
9368  certain access order are better not declared using
9369 \emph on
9370 sfr16
9371 \emph default
9372  or
9373 \emph on
9374 sfr32.
9375
9376 \emph default
9377  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9378  this is not guaranteed.
9379 \layout Subsubsection
9380
9381 Pointers
9382 \begin_inset LatexCommand \index{Pointer}
9383
9384 \end_inset
9385
9386  to MCS51/DS390 specific memory spaces
9387 \layout Standard
9388
9389 SDCC allows (via language extensions) pointers to explicitly point to any
9390  of the memory spaces
9391 \begin_inset LatexCommand \index{Memory model}
9392
9393 \end_inset
9394
9395  of the 8051.
9396  In addition to the explicit pointers, the compiler uses (by default) generic
9397  pointers which can be used to point to any of the memory spaces.
9398 \newline
9399
9400 \newline
9401 Pointer declaration examples:
9402 \layout Verse
9403
9404
9405 \family typewriter
9406 /* pointer physically in internal ram pointing to object in external ram
9407  */
9408 \newline
9409 xdata unsigned char * data p;
9410 \newline
9411
9412 \newline
9413 /* pointer physically in external ram pointing to object in internal ram
9414  */
9415 \newline
9416 data unsigned char * xdata p;
9417 \newline
9418
9419 \newline
9420 /* pointer physically in code rom pointing to data in xdata space */
9421 \newline
9422 xdata unsigned char * code p;
9423 \newline
9424
9425 \newline
9426 /* pointer physically in code space pointing to data in code space */
9427 \newline
9428 code unsigned char * code p;
9429 \newline
9430
9431 \newline
9432 /* the following is a generic pointer physically located in xdata space
9433  */
9434 \newline
9435 char * xdata p;
9436 \newline
9437
9438 \newline
9439 /* the following is a function pointer physically located in data space
9440  */
9441 \newline
9442 char (* data fp)(void);
9443 \layout Standard
9444
9445 Well you get the idea.
9446
9447 \newline
9448
9449 \newline
9450 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9451 \emph on
9452 generic
9453 \emph default
9454  pointers.
9455
9456 \size small
9457
9458 \newline
9459
9460 \newline
9461
9462 \size default
9463 The highest order byte of the
9464 \emph on
9465 generic
9466 \emph default
9467  pointers contains the data space information.
9468  Assembler support routines are called whenever data is stored or retrieved
9469  using
9470 \emph on
9471 generic
9472 \emph default
9473  pointers.
9474  These are useful for developing reusable library
9475 \begin_inset LatexCommand \index{Libraries}
9476
9477 \end_inset
9478
9479  routines.
9480  Explicitly specifying the pointer type will generate the most efficient
9481  code.
9482 \layout Subsubsection
9483
9484 Notes on MCS51 memory
9485 \begin_inset LatexCommand \index{MCS51 memory}
9486
9487 \end_inset
9488
9489  layout
9490 \layout Standard
9491
9492 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9493  RAM memory which is structured as follows:
9494 \newline
9495
9496 \newline
9497 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9498
9499 \newline
9500 - Bytes 20-2F - 16 bytes to hold 128 bit
9501 \begin_inset LatexCommand \index{bit}
9502
9503 \end_inset
9504
9505  variables and,
9506 \newline
9507 - Bytes 30-7F - 80 bytes for general purpose use.
9508 \newline
9509
9510 \layout Standard
9511
9512 Additionally some members of the MCS51 family may have up to 128 bytes of
9513  additional, indirectly addressable, internal RAM memory (
9514 \emph on
9515 idata
9516 \emph default
9517
9518 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9519
9520 \end_inset
9521
9522
9523 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9524
9525 \end_inset
9526
9527 ).
9528  Furthermore, some chips may have some built in external memory (
9529 \emph on
9530 xdata
9531 \emph default
9532
9533 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9534
9535 \end_inset
9536
9537
9538 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9539
9540 \end_inset
9541
9542 ) which should not be confused with the internal, directly addressable RAM
9543  memory (
9544 \emph on
9545 data
9546 \emph default
9547
9548 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9549
9550 \end_inset
9551
9552
9553 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9554
9555 \end_inset
9556
9557 ).
9558  Sometimes this built in
9559 \emph on
9560 xdata
9561 \emph default
9562  memory has to be activated before using it (you can probably find this
9563  information on the datasheet of the microcontroller your are using, see
9564  also section
9565 \begin_inset LatexCommand \ref{sub:Startup-Code}
9566
9567 \end_inset
9568
9569 \SpecialChar ~
9570 Startup-Code).
9571 \layout Standard
9572
9573 Normally SDCC will only use the first bank
9574 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9575
9576 \end_inset
9577
9578  of registers (register bank 0), but it is possible to specify that other
9579  banks of registers (keyword
9580 \emph on
9581 using
9582 \emph default
9583
9584 \emph on
9585
9586 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9587
9588 \end_inset
9589
9590
9591 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9592
9593 \end_inset
9594
9595
9596 \emph default
9597 ) should be used in interrupt
9598 \begin_inset LatexCommand \index{interrupt}
9599
9600 \end_inset
9601
9602
9603 \begin_inset LatexCommand \index{\_\_interrupt}
9604
9605 \end_inset
9606
9607  routines.
9608  By default, the compiler will place the stack after the last byte of allocated
9609  memory for variables.
9610  For example, if the first 2 banks of registers are used, and only four
9611  bytes are used for
9612 \emph on
9613 data
9614 \emph default
9615  variables, it will position the base of the internal stack at address 20
9616  (0x14).
9617  This implies that as the stack
9618 \begin_inset LatexCommand \index{stack}
9619
9620 \end_inset
9621
9622  grows, it will use up the remaining register banks, and the 16 bytes used
9623  by the 128 bit variables, and 80 bytes for general purpose use.
9624  If any bit variables are used, the data variables will be placed in unused
9625  register banks and after the byte holding the last bit variable.
9626  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9627  (two bytes used),
9628 \emph on
9629 data
9630 \emph default
9631  variables will be placed starting from address 0x10 to 0x20 and continue
9632  at address 0x22.
9633  You can also use -
9634 \begin_inset ERT
9635 status Collapsed
9636
9637 \layout Standard
9638
9639 \backslash
9640 /
9641 \end_inset
9642
9643 -data-loc
9644 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
9645
9646 \end_inset
9647
9648  to specify the start address of the
9649 \emph on
9650 data
9651 \emph default
9652  and -
9653 \begin_inset ERT
9654 status Collapsed
9655
9656 \layout Standard
9657
9658 \backslash
9659 /
9660 \end_inset
9661
9662 -iram-size
9663 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
9664
9665 \end_inset
9666
9667  to specify the size of the total internal RAM (
9668 \emph on
9669 data
9670 \emph default
9671 +
9672 \emph on
9673 idata
9674 \emph default
9675 ).
9676
9677 \layout Standard
9678
9679 By default the 8051 linker will place the stack after the last byte of (i)data
9680  variables.
9681  Option -
9682 \begin_inset ERT
9683 status Collapsed
9684
9685 \layout Standard
9686
9687 \backslash
9688 /
9689 \end_inset
9690
9691 -stack-loc
9692 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
9693
9694 \end_inset
9695
9696  allows you to specify the start of the stack, i.e.
9697  you could start it after any data in the general purpose area.
9698  If your microcontroller has additional indirectly addressable internal
9699  RAM (
9700 \emph on
9701 idata
9702 \emph default
9703 ) you can place the stack on it.
9704  You may also need to use -
9705 \begin_inset ERT
9706 status Collapsed
9707
9708 \layout Standard
9709
9710 \backslash
9711 /
9712 \end_inset
9713
9714 -xdata-loc
9715 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
9716
9717 \end_inset
9718
9719  to set the start address of the external RAM (
9720 \emph on
9721 xdata
9722 \emph default
9723 ) and -
9724 \begin_inset ERT
9725 status Collapsed
9726
9727 \layout Standard
9728
9729 \backslash
9730 /
9731 \end_inset
9732
9733 -xram-size
9734 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
9735
9736 \end_inset
9737
9738  to specify its size.
9739  Same goes for the code memory, using -
9740 \begin_inset ERT
9741 status Collapsed
9742
9743 \layout Standard
9744
9745 \backslash
9746 /
9747 \end_inset
9748
9749 -code-loc
9750 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
9751
9752 \end_inset
9753
9754  and -
9755 \begin_inset ERT
9756 status Collapsed
9757
9758 \layout Standard
9759
9760 \backslash
9761 /
9762 \end_inset
9763
9764 -code-size
9765 \begin_inset LatexCommand \index{-\/-code-size <Value>}
9766
9767 \end_inset
9768
9769 .
9770  If in doubt, don't specify any options and see if the resulting memory
9771  layout is appropriate, then you can adjust it.
9772 \layout Standard
9773
9774 The linker generates two files with memory allocation information.
9775  The first, with extension .map
9776 \begin_inset LatexCommand \index{<file>.map}
9777
9778 \end_inset
9779
9780  shows all the variables and segments.
9781  The second with extension .mem
9782 \begin_inset LatexCommand \index{<file>.mem}
9783
9784 \end_inset
9785
9786  shows the final memory layout.
9787  The linker will complain either if memory segments overlap, there is not
9788  enough memory, or there is not enough space for stack.
9789  If you get any linking warnings and/or errors related to stack or segments
9790  allocation, take a look at either the .map or .mem files to find out what
9791  the problem is.
9792  The .mem file may even suggest a solution to the problem.
9793 \layout Subsection
9794
9795 Z80/Z180 Storage Class
9796 \begin_inset LatexCommand \index{Storage class}
9797
9798 \end_inset
9799
9800  Language Extensions
9801 \layout Subsubsection
9802
9803 sfr
9804 \begin_inset LatexCommand \index{sfr}
9805
9806 \end_inset
9807
9808
9809 \begin_inset LatexCommand \index{\_\_sfr}
9810
9811 \end_inset
9812
9813  (in/out to 8-bit addresses)
9814 \layout Standard
9815
9816 The Z80
9817 \begin_inset LatexCommand \index{Z80}
9818
9819 \end_inset
9820
9821  family has separate address spaces for memory and
9822 \emph on
9823 i
9824 \emph default
9825 nput/
9826 \emph on
9827 o
9828 \emph default
9829 utput memory.
9830  I/O memory
9831 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9832
9833 \end_inset
9834
9835  is accessed with special instructions, e.g.:
9836 \layout Verse
9837
9838
9839 \family typewriter
9840 sfr at 0x78 IoPort;\SpecialChar ~
9841 \SpecialChar ~
9842 /* define a var in I/O space at 78h called IoPort */
9843
9844 \layout Standard
9845
9846 Writing 0x01 to this variable generates the assembly code:
9847 \layout Verse
9848
9849
9850 \family typewriter
9851 3E 01\SpecialChar ~
9852 \SpecialChar ~
9853 \SpecialChar ~
9854 \SpecialChar ~
9855 \SpecialChar ~
9856 \SpecialChar ~
9857 ld a,#0x01
9858 \newline
9859 D3 78\SpecialChar ~
9860 \SpecialChar ~
9861 \SpecialChar ~
9862 \SpecialChar ~
9863 \SpecialChar ~
9864 \SpecialChar ~
9865 out (_IoPort),a
9866 \layout Subsubsection
9867
9868 banked sfr
9869 \begin_inset LatexCommand \index{sfr}
9870
9871 \end_inset
9872
9873
9874 \begin_inset LatexCommand \index{\_\_sfr}
9875
9876 \end_inset
9877
9878  (in/out to 16-bit addresses)
9879 \layout Standard
9880
9881 The keyword
9882 \emph on
9883 banked
9884 \emph default
9885  is used to support 16 bit addresses in I/O memory e.g.:
9886 \layout Verse
9887
9888
9889 \family typewriter
9890 sfr banked at
9891 \begin_inset LatexCommand \index{at}
9892
9893 \end_inset
9894
9895
9896 \begin_inset LatexCommand \index{\_\_at}
9897
9898 \end_inset
9899
9900  0x123 IoPort;
9901 \layout Standard
9902
9903 Writing 0x01 to this variable generates the assembly code:
9904 \layout Verse
9905
9906
9907 \family typewriter
9908 01 23 01\SpecialChar ~
9909 \SpecialChar ~
9910 \SpecialChar ~
9911 ld bc,#_IoPort
9912 \newline
9913 3E 01\SpecialChar ~
9914 \SpecialChar ~
9915 \SpecialChar ~
9916 \SpecialChar ~
9917 \SpecialChar ~
9918 \SpecialChar ~
9919 ld a,#0x01
9920 \newline
9921 ED 79\SpecialChar ~
9922 \SpecialChar ~
9923 \SpecialChar ~
9924 \SpecialChar ~
9925 \SpecialChar ~
9926 \SpecialChar ~
9927 out (c),a
9928 \layout Subsubsection
9929
9930 sfr
9931 \begin_inset LatexCommand \index{sfr}
9932
9933 \end_inset
9934
9935
9936 \begin_inset LatexCommand \index{\_\_sfr}
9937
9938 \end_inset
9939
9940  (in0/out0 to 8 bit addresses on Z180
9941 \begin_inset LatexCommand \index{Z180}
9942
9943 \end_inset
9944
9945 /HD64180
9946 \begin_inset LatexCommand \index{HD64180}
9947
9948 \end_inset
9949
9950 )
9951 \layout Standard
9952
9953 The compiler option -
9954 \begin_inset ERT
9955 status Collapsed
9956
9957 \layout Standard
9958
9959 \backslash
9960 /
9961 \end_inset
9962
9963 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9964 portmode
9965 \begin_inset LatexCommand \index{\#pragma portmode}
9966
9967 \end_inset
9968
9969 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9970 ns
9971 \family typewriter
9972 in0/out0
9973 \family default
9974  instead of
9975 \family typewriter
9976 in/out
9977 \family default
9978 .
9979  If you include the file z180.h this will be set automatically.
9980 \layout Subsection
9981
9982 HC08 Storage Class
9983 \begin_inset LatexCommand \index{Storage class}
9984
9985 \end_inset
9986
9987  Language Extensions
9988 \layout Subsubsection
9989
9990 data
9991 \begin_inset LatexCommand \index{data (hc08 storage class)}
9992
9993 \end_inset
9994
9995
9996 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
9997
9998 \end_inset
9999
10000
10001 \layout Standard
10002
10003 The data storage class declares a variable that resides in the first 256
10004  bytes of memory (the direct page).
10005  The HC08 is most efficient at accessing variables (especially pointers)
10006  stored here.
10007 \layout Subsubsection
10008
10009 xdata
10010 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
10011
10012 \end_inset
10013
10014
10015 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
10016
10017 \end_inset
10018
10019
10020 \layout Standard
10021
10022 The xdata storage class declares a variable that can reside anywhere in
10023  memory.
10024  This is the default if no storage class is specified.
10025
10026 \layout Section
10027
10028 Absolute Addressing
10029 \begin_inset LatexCommand \index{Absolute addressing}
10030
10031 \end_inset
10032
10033
10034 \layout Standard
10035
10036 Data items can be assigned an absolute address with the
10037 \emph on
10038 at
10039 \begin_inset LatexCommand \index{at}
10040
10041 \end_inset
10042
10043
10044 \begin_inset LatexCommand \index{\_\_at}
10045
10046 \end_inset
10047
10048  <address>
10049 \emph default
10050  keyword, in addition to a storage class, e.g.:
10051 \layout Verse
10052
10053
10054 \family typewriter
10055 xdata
10056 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10057
10058 \end_inset
10059
10060
10061 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
10062
10063 \end_inset
10064
10065  at
10066 \begin_inset LatexCommand \index{at}
10067
10068 \end_inset
10069
10070
10071 \begin_inset LatexCommand \index{\_\_at}
10072
10073 \end_inset
10074
10075  0x7ffe unsigned int chksum;
10076 \layout Standard
10077
10078 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
10079  of the external ram.
10080  The compiler does
10081 \emph on
10082 not
10083 \emph default
10084  reserve any space for variables declared in this way (they are implemented
10085  with an equate in the assembler).
10086  Thus it is left to the programmer to make sure there are no overlaps with
10087  other variables that are declared without the absolute address.
10088  The assembler listing file (.lst
10089 \begin_inset LatexCommand \index{<file>.lst}
10090
10091 \end_inset
10092
10093 ) and the linker output files (.rst
10094 \begin_inset LatexCommand \index{<file>.rst}
10095
10096 \end_inset
10097
10098 ) and (.map
10099 \begin_inset LatexCommand \index{<file>.map}
10100
10101 \end_inset
10102
10103 ) are good places to look for such overlaps.
10104  Variables with an absolute address are
10105 \emph on
10106 not
10107 \emph default
10108  initialized
10109 \begin_inset LatexCommand \index{Variable initialization}
10110
10111 \end_inset
10112
10113 .
10114 \layout Standard
10115
10116 In case of memory mapped I/O devices the keyword
10117 \emph on
10118 volatile
10119 \emph default
10120  has to be used to tell the compiler that accesses might not be removed:
10121 \layout Verse
10122
10123
10124 \family typewriter
10125 volatile
10126 \begin_inset LatexCommand \index{volatile}
10127
10128 \end_inset
10129
10130  xdata
10131 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10132
10133 \end_inset
10134
10135  at
10136 \begin_inset LatexCommand \index{at}
10137
10138 \end_inset
10139
10140  0x8000 unsigned char PORTA_8255;
10141 \layout Standard
10142
10143 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
10144 r) array
10145 \family typewriter
10146 \size footnotesize
10147
10148 \begin_inset LatexCommand \index{Aligned array}
10149
10150 \end_inset
10151
10152
10153 \family default
10154 \size default
10155  starts at a block (256 byte) boundary
10156 \begin_inset LatexCommand \index{block boundary}
10157
10158 \end_inset
10159
10160  (section
10161 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
10162
10163 \end_inset
10164
10165  has an example).
10166 \newline
10167 Absolute addresses can be specified for variables in all storage classes,
10168  e.g.:
10169 \layout Verse
10170
10171
10172 \family typewriter
10173 bit
10174 \begin_inset LatexCommand \index{bit}
10175
10176 \end_inset
10177
10178  at
10179 \begin_inset LatexCommand \index{at}
10180
10181 \end_inset
10182
10183  0x02 bvar;
10184 \layout Standard
10185
10186 The above example will allocate the variable at offset 0x02 in the bit-addressab
10187 le space.
10188  There is no real advantage to assigning absolute addresses to variables
10189  in this manner, unless you want strict control over all the variables allocated.
10190  One possible use would be to write hardware portable code.
10191  For example, if you have a routine that uses one or more of the microcontroller
10192  I/O pins, and such pins are different for two different hardwares, you
10193  can declare the I/O pins in your routine using:
10194 \layout Verse
10195
10196
10197 \family typewriter
10198 extern volatile
10199 \begin_inset LatexCommand \index{volatile}
10200
10201 \end_inset
10202
10203  bit MOSI;\SpecialChar ~
10204 \SpecialChar ~
10205 \SpecialChar ~
10206 \SpecialChar ~
10207 /* master out, slave in */
10208 \newline
10209 extern volatile bit MISO;\SpecialChar ~
10210 \SpecialChar ~
10211 \SpecialChar ~
10212 \SpecialChar ~
10213 /* master in, slave out */
10214 \newline
10215 extern volatile bit MCLK;\SpecialChar ~
10216 \SpecialChar ~
10217 \SpecialChar ~
10218 \SpecialChar ~
10219 /* master clock */
10220 \newline
10221
10222 \newline
10223 /* Input and Output of a byte on a 3-wire serial bus.
10224 \newline
10225 \SpecialChar ~
10226 \SpecialChar ~
10227 \SpecialChar ~
10228 If needed adapt polarity of clock, polarity of data and bit order
10229 \newline
10230 \SpecialChar ~
10231 */
10232 \newline
10233 unsigned char spi_io(unsigned char out_byte)
10234 \newline
10235 {
10236 \newline
10237 \SpecialChar ~
10238 \SpecialChar ~
10239 \SpecialChar ~
10240 \SpecialChar ~
10241 unsigned char i=8;
10242 \newline
10243 \SpecialChar ~
10244 \SpecialChar ~
10245 \SpecialChar ~
10246 \SpecialChar ~
10247 do {
10248 \newline
10249 \SpecialChar ~
10250 \SpecialChar ~
10251 \SpecialChar ~
10252 \SpecialChar ~
10253 \SpecialChar ~
10254 \SpecialChar ~
10255 \SpecialChar ~
10256 \SpecialChar ~
10257 MOSI = out_byte & 0x80;
10258 \newline
10259 \SpecialChar ~
10260 \SpecialChar ~
10261 \SpecialChar ~
10262 \SpecialChar ~
10263 \SpecialChar ~
10264 \SpecialChar ~
10265 \SpecialChar ~
10266 \SpecialChar ~
10267 out_byte <<= 1;
10268 \newline
10269 \SpecialChar ~
10270 \SpecialChar ~
10271 \SpecialChar ~
10272 \SpecialChar ~
10273 \SpecialChar ~
10274 \SpecialChar ~
10275 \SpecialChar ~
10276 \SpecialChar ~
10277 MCLK = 1;
10278 \newline
10279 \SpecialChar ~
10280 \SpecialChar ~
10281 \SpecialChar ~
10282 \SpecialChar ~
10283 \SpecialChar ~
10284 \SpecialChar ~
10285 \SpecialChar ~
10286 \SpecialChar ~
10287 /* _asm nop _endasm; */\SpecialChar ~
10288 \SpecialChar ~
10289 \SpecialChar ~
10290 \SpecialChar ~
10291 \SpecialChar ~
10292 \SpecialChar ~
10293 \SpecialChar ~
10294 \SpecialChar ~
10295 /* for slow peripherals */
10296 \newline
10297 \SpecialChar ~
10298 \SpecialChar ~
10299 \SpecialChar ~
10300 \SpecialChar ~
10301 \SpecialChar ~
10302 \SpecialChar ~
10303 \SpecialChar ~
10304 \SpecialChar ~
10305 if(MISO)
10306 \newline
10307 \SpecialChar ~
10308 \SpecialChar ~
10309 \SpecialChar ~
10310 \SpecialChar ~
10311 \SpecialChar ~
10312 \SpecialChar ~
10313 \SpecialChar ~
10314 \SpecialChar ~
10315 \SpecialChar ~
10316 \SpecialChar ~
10317 \SpecialChar ~
10318 \SpecialChar ~
10319 out_byte += 1;
10320 \newline
10321 \SpecialChar ~
10322 \SpecialChar ~
10323 \SpecialChar ~
10324 \SpecialChar ~
10325 \SpecialChar ~
10326 \SpecialChar ~
10327 \SpecialChar ~
10328 \SpecialChar ~
10329 MCLK = 0;
10330 \newline
10331 \SpecialChar ~
10332 \SpecialChar ~
10333 \SpecialChar ~
10334 \SpecialChar ~
10335 } while(--i);
10336 \newline
10337 \SpecialChar ~
10338 \SpecialChar ~
10339 \SpecialChar ~
10340 \SpecialChar ~
10341 return out_byte;
10342 \newline
10343 }
10344 \layout Standard
10345
10346 Then, someplace in the code for the first hardware you would use
10347 \layout Verse
10348
10349
10350 \family typewriter
10351 bit at
10352 \begin_inset LatexCommand \index{at}
10353
10354 \end_inset
10355
10356
10357 \begin_inset LatexCommand \index{\_\_at}
10358
10359 \end_inset
10360
10361  0x80 MOSI;\SpecialChar ~
10362 \SpecialChar ~
10363 \SpecialChar ~
10364 \SpecialChar ~
10365 /* I/O port 0, bit 0 */
10366 \newline
10367 bit at 0x81 MISO;\SpecialChar ~
10368 \SpecialChar ~
10369 \SpecialChar ~
10370 \SpecialChar ~
10371 /* I/O port 0, bit 1 */
10372 \newline
10373 bit at 0x82 MCLK;\SpecialChar ~
10374 \SpecialChar ~
10375 \SpecialChar ~
10376 \SpecialChar ~
10377 /* I/O port 0, bit 2 */
10378 \layout Standard
10379
10380 Similarly, for the second hardware you would use
10381 \layout Verse
10382
10383
10384 \family typewriter
10385 bit at 0x83 MOSI;\SpecialChar ~
10386 \SpecialChar ~
10387 \SpecialChar ~
10388 \SpecialChar ~
10389 /* I/O port 0, bit 3 */
10390 \newline
10391 bit at 0x91 MISO;\SpecialChar ~
10392 \SpecialChar ~
10393 \SpecialChar ~
10394 \SpecialChar ~
10395 /* I/O port 1, bit 1 */
10396 \newline
10397 bit
10398 \begin_inset LatexCommand \index{bit}
10399
10400 \end_inset
10401
10402  at 0x92 MCLK;\SpecialChar ~
10403 \SpecialChar ~
10404 \SpecialChar ~
10405 \SpecialChar ~
10406 /* I/O port 1, bit 2 */
10407 \layout Standard
10408
10409 and you can use the same hardware dependent routine without changes, as
10410  for example in a library.
10411  This is somehow similar to sbit, but only one absolute address has to be
10412  specified in the whole project.
10413 \layout Section
10414
10415 Parameters
10416 \begin_inset LatexCommand \index{Parameters}
10417
10418 \end_inset
10419
10420
10421 \begin_inset LatexCommand \index{function parameter}
10422
10423 \end_inset
10424
10425  & Local Variables
10426 \begin_inset LatexCommand \index{local variables}
10427
10428 \end_inset
10429
10430
10431 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10432
10433 \end_inset
10434
10435
10436 \layout Standard
10437
10438 Automatic (local) variables and parameters to functions can either be placed
10439  on the stack or in data-space.
10440  The default action of the compiler is to place these variables in the internal
10441  RAM (for small model) or external RAM (for large model).
10442  This in fact makes them similar to
10443 \emph on
10444 static
10445 \begin_inset LatexCommand \index{static}
10446
10447 \end_inset
10448
10449
10450 \emph default
10451  so by default functions are non-reentrant
10452 \begin_inset LatexCommand \index{reentrant}
10453
10454 \end_inset
10455
10456 .
10457
10458 \newline
10459
10460 \newline
10461 They can be placed on the stack
10462 \begin_inset LatexCommand \index{stack}
10463
10464 \end_inset
10465
10466  by using the
10467 \emph on
10468  -
10469 \begin_inset ERT
10470 status Collapsed
10471
10472 \layout Standard
10473
10474 \backslash
10475 /
10476 \end_inset
10477
10478 -stack-auto
10479 \begin_inset LatexCommand \index{-\/-stack-auto}
10480
10481 \end_inset
10482
10483
10484 \emph default
10485  option, by using
10486 \emph on
10487 #pragma\SpecialChar ~
10488 stackauto
10489 \emph default
10490
10491 \begin_inset LatexCommand \index{\#pragma stackauto}
10492
10493 \end_inset
10494
10495  or by using the
10496 \emph on
10497 reentrant
10498 \begin_inset LatexCommand \index{reentrant}
10499
10500 \end_inset
10501
10502
10503 \emph default
10504  keyword in the function declaration, e.g.:
10505 \layout Verse
10506
10507
10508 \family typewriter
10509 unsigned char foo(char i) reentrant
10510 \newline
10511 {
10512 \newline
10513 \SpecialChar ~
10514 \SpecialChar ~
10515 \SpecialChar ~
10516 \SpecialChar ~
10517 ...
10518
10519 \newline
10520 }
10521 \layout Standard
10522
10523 Since stack space on 8051 is limited, the
10524 \emph on
10525 reentrant
10526 \emph default
10527 keyword or the
10528 \emph on
10529  -
10530 \begin_inset ERT
10531 status Collapsed
10532
10533 \layout Standard
10534
10535 \backslash
10536 /
10537 \end_inset
10538
10539 -stack-auto
10540 \emph default
10541  option should be used sparingly.
10542  Note that the reentrant keyword just means that the parameters & local
10543  variables will be allocated to the stack, it
10544 \emph on
10545 does not
10546 \emph default
10547  mean that the function is register bank
10548 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10549
10550 \end_inset
10551
10552  independent.
10553 \newline
10554
10555 \newline
10556 Local variables
10557 \begin_inset LatexCommand \index{local variables}
10558
10559 \end_inset
10560
10561  can be assigned storage classes and absolute
10562 \begin_inset LatexCommand \index{Absolute addressing}
10563
10564 \end_inset
10565
10566  addresses, e.g.:
10567 \layout Verse
10568
10569
10570 \family typewriter
10571 unsigned char foo()
10572 \newline
10573 {
10574 \newline
10575 \SpecialChar ~
10576 \SpecialChar ~
10577 \SpecialChar ~
10578 \SpecialChar ~
10579 xdata unsigned char i;
10580 \newline
10581 \SpecialChar ~
10582 \SpecialChar ~
10583 \SpecialChar ~
10584 \SpecialChar ~
10585 bit bvar;
10586 \newline
10587 \SpecialChar ~
10588 \SpecialChar ~
10589 \SpecialChar ~
10590 \SpecialChar ~
10591 data at
10592 \begin_inset LatexCommand \index{at}
10593
10594 \end_inset
10595
10596  0x31 unsigned char j;
10597 \newline
10598 \SpecialChar ~
10599 \SpecialChar ~
10600 \SpecialChar ~
10601 \SpecialChar ~
10602 ...
10603
10604 \newline
10605 }
10606 \layout Standard
10607
10608 In the above example the variable
10609 \emph on
10610 i
10611 \emph default
10612  will be allocated in the external ram,
10613 \emph on
10614 bvar
10615 \emph default
10616  in bit addressable space and
10617 \emph on
10618  j
10619 \emph default
10620  in internal ram.
10621  When compiled with
10622 \emph on
10623 -
10624 \begin_inset ERT
10625 status Collapsed
10626
10627 \layout Standard
10628
10629 \backslash
10630 /
10631 \end_inset
10632
10633 -stack-auto
10634 \emph default
10635  or when a function is declared as
10636 \emph on
10637 reentrant
10638 \emph default
10639  this should only be done for static variables.
10640 \layout Standard
10641
10642 Parameters
10643 \begin_inset LatexCommand \index{function parameter}
10644
10645 \end_inset
10646
10647  however are not allowed any storage class
10648 \begin_inset LatexCommand \index{Storage class}
10649
10650 \end_inset
10651
10652 , (storage classes for parameters will be ignored), their allocation is
10653  governed by the memory model in use, and the reentrancy options.
10654 \layout Standard
10655
10656 It is however allowed to use bit parameters in reentrant functions and also
10657  non-static local bit variables are supported.
10658  Efficient use is limited to 8 semi-bitregisters in bit space.
10659  They are pushed and popped to stack as a single byte just like the normal
10660  registers.
10661 \layout Section
10662
10663 Overlaying
10664 \begin_inset LatexCommand \label{sub:Overlaying}
10665
10666 \end_inset
10667
10668
10669 \begin_inset LatexCommand \index{Overlaying}
10670
10671 \end_inset
10672
10673
10674 \layout Standard
10675
10676 For non-reentrant
10677 \begin_inset LatexCommand \index{reentrant}
10678
10679 \end_inset
10680
10681  functions SDCC will try to reduce internal ram space usage by overlaying
10682  parameters and local variables of a function (if possible).
10683  Parameters and local variables
10684 \begin_inset LatexCommand \index{local variables}
10685
10686 \end_inset
10687
10688  of a function will be allocated to an overlayable segment if the function
10689  has
10690 \emph on
10691 no other function calls and the function is non-reentrant and the memory
10692  model
10693 \begin_inset LatexCommand \index{Memory model}
10694
10695 \end_inset
10696
10697  is small.
10698
10699 \emph default
10700  If an explicit storage class
10701 \begin_inset LatexCommand \index{Storage class}
10702
10703 \end_inset
10704
10705  is specified for a local variable, it will NOT be overlayed.
10706 \layout Standard
10707
10708 Note that the compiler (not the linkage editor) makes the decision for overlayin
10709 g the data items.
10710  Functions that are called from an interrupt service routine should be preceded
10711  by a #pragma\SpecialChar ~
10712 nooverlay
10713 \begin_inset LatexCommand \index{\#pragma nooverlay}
10714
10715 \end_inset
10716
10717  if they are not reentrant.
10718 \layout Standard
10719
10720 Also note that the compiler does not do any processing of inline assembler
10721  code, so the compiler might incorrectly assign local variables and parameters
10722  of a function into the overlay segment if the inline assembler code calls
10723  other c-functions that might use the overlay.
10724  In that case the #pragma\SpecialChar ~
10725 nooverlay should be used.
10726 \layout Standard
10727
10728 Parameters and local variables of functions that contain 16 or 32 bit multiplica
10729 tion
10730 \begin_inset LatexCommand \index{Multiplication}
10731
10732 \end_inset
10733
10734  or division
10735 \begin_inset LatexCommand \index{Division}
10736
10737 \end_inset
10738
10739  will NOT be overlayed since these are implemented using external functions,
10740  e.g.:
10741 \layout Verse
10742
10743
10744 \family typewriter
10745 #pragma save
10746 \newline
10747 #pragma nooverlay
10748 \begin_inset LatexCommand \index{\#pragma nooverlay}
10749
10750 \end_inset
10751
10752
10753 \newline
10754 void set_error(unsigned char errcd)
10755 \newline
10756 {
10757 \newline
10758 \SpecialChar ~
10759 \SpecialChar ~
10760 \SpecialChar ~
10761 \SpecialChar ~
10762 P3 = errcd;
10763 \newline
10764 }
10765 \newline
10766 #pragma restore
10767 \newline
10768
10769 \newline
10770 void some_isr () interrupt
10771 \begin_inset LatexCommand \index{interrupt}
10772
10773 \end_inset
10774
10775  2
10776 \newline
10777 {
10778 \newline
10779 \SpecialChar ~
10780 \SpecialChar ~
10781 \SpecialChar ~
10782 \SpecialChar ~
10783 ...
10784 \newline
10785 \SpecialChar ~
10786 \SpecialChar ~
10787 \SpecialChar ~
10788 \SpecialChar ~
10789 set_error(10);
10790 \newline
10791 \SpecialChar ~
10792 \SpecialChar ~
10793 \SpecialChar ~
10794 \SpecialChar ~
10795 ...
10796
10797 \newline
10798 }
10799 \layout Standard
10800
10801 In the above example the parameter
10802 \emph on
10803 errcd
10804 \emph default
10805  for the function
10806 \emph on
10807 set_error
10808 \emph default
10809  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
10810 nooverlay was
10811  not present, this could cause unpredictable runtime behavior when called
10812  from an interrupt service routine.
10813  The #pragma\SpecialChar ~
10814 nooverlay ensures that the parameters and local variables for
10815  the function are NOT overlayed.
10816 \layout Section
10817
10818 Interrupt Service Routines
10819 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
10820
10821 \end_inset
10822
10823
10824 \layout Subsection
10825
10826 General Information
10827 \layout Standard
10828
10829 SDCC allows
10830 \emph on
10831 i
10832 \emph default
10833 nterrupt
10834 \emph on
10835 s
10836 \emph default
10837 ervice
10838 \emph on
10839 r
10840 \emph default
10841 outines to be coded in C, with some extended keywords.
10842 \layout Verse
10843
10844
10845 \family typewriter
10846 void timer_isr (void) interrupt 1 using 1
10847 \newline
10848 {
10849 \newline
10850 \SpecialChar ~
10851 \SpecialChar ~
10852 \SpecialChar ~
10853 \SpecialChar ~
10854 ...
10855
10856 \newline
10857 }
10858 \layout Standard
10859
10860 The optional number following the
10861 \emph on
10862 interrupt
10863 \begin_inset LatexCommand \index{interrupt}
10864
10865 \end_inset
10866
10867
10868 \begin_inset LatexCommand \index{\_\_interrupt}
10869
10870 \end_inset
10871
10872
10873 \emph default
10874  keyword is the interrupt number this routine will service.
10875  When present, the compiler will insert a call to this routine in the interrupt
10876  vector table for the interrupt number specified.
10877  If you have multiple source files in your project, interrupt service routines
10878  can be present in any of them, but a prototype of the isr MUST be present
10879  or included in the file that contains the function
10880 \emph on
10881 main
10882 \emph default
10883 .
10884  The optional
10885 \emph on
10886 using
10887 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10888
10889 \end_inset
10890
10891
10892 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10893
10894 \end_inset
10895
10896
10897 \emph default
10898  keyword can be used to tell the compiler to use the specified register
10899  bank (8051 specific) when generating code for this function.
10900
10901 \newline
10902
10903 \layout Standard
10904
10905 Interrupt service routines open the door for some very interesting bugs:
10906 \newline
10907 If an interrupt service routine changes variables which are accessed by
10908  other functions these variables have to be declared
10909 \emph on
10910 volatile
10911 \emph default
10912
10913 \begin_inset LatexCommand \index{volatile}
10914
10915 \end_inset
10916
10917 .
10918
10919 \layout Standard
10920
10921 If the access to these variables is not
10922 \emph on
10923 atomic
10924 \begin_inset LatexCommand \index{atomic}
10925
10926 \end_inset
10927
10928
10929 \emph default
10930  (i.e.
10931  the processor needs more than one instruction for the access and could
10932  be interrupted while accessing the variable) the interrupt must be disabled
10933  during the access to avoid inconsistent data.
10934  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10935  and should be protected by disabling interrupts.
10936  You're not automatically on the safe side if you use 8 bit variables though.
10937  We need an example here: f.e.
10938  on the 8051 the harmless looking
10939 \begin_inset Quotes srd
10940 \end_inset
10941
10942
10943 \family typewriter
10944 flags\SpecialChar ~
10945 |=\SpecialChar ~
10946 0x80;
10947 \family default
10948
10949 \begin_inset Quotes sld
10950 \end_inset
10951
10952  is not atomic if
10953 \family typewriter
10954 flags
10955 \family default
10956  resides in xdata.
10957  Setting
10958 \begin_inset Quotes srd
10959 \end_inset
10960
10961
10962 \family typewriter
10963 flags\SpecialChar ~
10964 |=\SpecialChar ~
10965 0x40;
10966 \family default
10967
10968 \begin_inset Quotes sld
10969 \end_inset
10970
10971  from within an interrupt routine might get lost if the interrupt occurs
10972  at the wrong time.
10973
10974 \begin_inset Quotes sld
10975 \end_inset
10976
10977
10978 \family typewriter
10979 counter\SpecialChar ~
10980 +=\SpecialChar ~
10981 8;
10982 \family default
10983
10984 \begin_inset Quotes srd
10985 \end_inset
10986
10987  is not atomic on the 8051 even if
10988 \family typewriter
10989 counter
10990 \family default
10991  is located in data memory.
10992  Bugs like these are hard to reproduce and can cause a lot of trouble.
10993
10994 \layout Standard
10995
10996 The return address and the registers used in the interrupt service routine
10997  are saved on the stack
10998 \begin_inset LatexCommand \index{stack}
10999
11000 \end_inset
11001
11002  so there must be sufficient stack space.
11003  If there isn't variables or registers (or even the return address itself)
11004  will be corrupted.
11005  This
11006 \emph on
11007 stack overflow
11008 \emph default
11009
11010 \begin_inset LatexCommand \index{stack overflow}
11011
11012 \end_inset
11013
11014  is most likely to happen if the interrupt occurs during the
11015 \begin_inset Quotes sld
11016 \end_inset
11017
11018 deepest
11019 \begin_inset Quotes srd
11020 \end_inset
11021
11022  subroutine when the stack is already in use for f.e.
11023  many return addresses.
11024 \layout Standard
11025
11026 A special note here, int (16 bit) and long (32 bit) integer division
11027 \begin_inset LatexCommand \index{Division}
11028
11029 \end_inset
11030
11031 , multiplication
11032 \begin_inset LatexCommand \index{Multiplication}
11033
11034 \end_inset
11035
11036  & modulus
11037 \begin_inset LatexCommand \index{Modulus}
11038
11039 \end_inset
11040
11041  and floating-point
11042 \begin_inset LatexCommand \index{Floating point support}
11043
11044 \end_inset
11045
11046  operations are implemented using external support routines developed in
11047  ANSI-C.
11048  If an interrupt service routine needs to do any of these operations then
11049  the support routines (as mentioned in a following section) will have to
11050  be recompiled using the
11051 \emph on
11052  -
11053 \begin_inset ERT
11054 status Collapsed
11055
11056 \layout Standard
11057
11058 \backslash
11059 /
11060 \end_inset
11061
11062 -stack-auto
11063 \begin_inset LatexCommand \index{-\/-stack-auto}
11064
11065 \end_inset
11066
11067
11068 \emph default
11069  option and the source file will need to be compiled using the
11070 \emph on
11071 -
11072 \begin_inset ERT
11073 status Collapsed
11074
11075 \layout Standard
11076
11077 \backslash
11078 /
11079 \end_inset
11080
11081 -int-long-reent
11082 \emph default
11083
11084 \begin_inset LatexCommand \index{-\/-int-long-reent}
11085
11086 \end_inset
11087
11088  compiler option.
11089 \layout Standard
11090
11091 Calling other functions from an interrupt service routine is not recommended,
11092  avoid it if possible.
11093  Note that when some function is called from an interrupt service routine
11094  it should be preceded by a #pragma\SpecialChar ~
11095 nooverlay
11096 \begin_inset LatexCommand \index{\#pragma nooverlay}
11097
11098 \end_inset
11099
11100  if it is not reentrant.
11101  Furthermore nonreentrant functions should not be called from the main program
11102  while the interrupt service routine might be active.
11103  They also must not be called from low priority interrupt service routines
11104  while a high priority interrupt service routine might be active.
11105  You could use semaphores or make the function
11106 \emph on
11107  critical
11108 \emph default
11109  if all parameters are passed in registers.
11110 \newline
11111
11112 \newline
11113 Also see section
11114 \begin_inset LatexCommand \ref{sub:Overlaying}
11115
11116 \end_inset
11117
11118 \SpecialChar ~
11119 about Overlaying and section
11120 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
11121
11122 \end_inset
11123
11124 \SpecialChar ~
11125 about Functions using private register banks.
11126 \layout Subsection
11127
11128 MCS51/DS390 Interrupt Service Routines
11129 \layout Standard
11130
11131 Interrupt numbers and the corresponding address & descriptions for the Standard
11132  8051/8052 are listed below.
11133  SDCC will automatically adjust the interrupt vector table to the maximum
11134  interrupt number specified.
11135 \newline
11136
11137 \layout Standard
11138 \align center
11139
11140 \begin_inset  Tabular
11141 <lyxtabular version="3" rows="7" columns="3">
11142 <features>
11143 <column alignment="center" valignment="top" leftline="true" width="0in">
11144 <column alignment="center" valignment="top" leftline="true" width="0in">
11145 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
11146 <row topline="true" bottomline="true">
11147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11148 \begin_inset Text
11149
11150 \layout Standard
11151
11152 Interrupt #
11153 \end_inset
11154 </cell>
11155 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11156 \begin_inset Text
11157
11158 \layout Standard
11159
11160 Description
11161 \end_inset
11162 </cell>
11163 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11164 \begin_inset Text
11165
11166 \layout Standard
11167
11168 Vector Address
11169 \end_inset
11170 </cell>
11171 </row>
11172 <row topline="true">
11173 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11174 \begin_inset Text
11175
11176 \layout Standard
11177
11178 0
11179 \end_inset
11180 </cell>
11181 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11182 \begin_inset Text
11183
11184 \layout Standard
11185
11186 External 0
11187 \end_inset
11188 </cell>
11189 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11190 \begin_inset Text
11191
11192 \layout Standard
11193
11194 0x0003
11195 \end_inset
11196 </cell>
11197 </row>
11198 <row topline="true">
11199 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11200 \begin_inset Text
11201
11202 \layout Standard
11203
11204 1
11205 \end_inset
11206 </cell>
11207 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11208 \begin_inset Text
11209
11210 \layout Standard
11211
11212 Timer 0
11213 \end_inset
11214 </cell>
11215 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11216 \begin_inset Text
11217
11218 \layout Standard
11219
11220 0x000B
11221 \end_inset
11222 </cell>
11223 </row>
11224 <row topline="true">
11225 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11226 \begin_inset Text
11227
11228 \layout Standard
11229
11230 2
11231 \end_inset
11232 </cell>
11233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11234 \begin_inset Text
11235
11236 \layout Standard
11237
11238 External 1
11239 \end_inset
11240 </cell>
11241 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11242 \begin_inset Text
11243
11244 \layout Standard
11245
11246 0x0013
11247 \end_inset
11248 </cell>
11249 </row>
11250 <row topline="true">
11251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11252 \begin_inset Text
11253
11254 \layout Standard
11255
11256 3
11257 \end_inset
11258 </cell>
11259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11260 \begin_inset Text
11261
11262 \layout Standard
11263
11264 Timer 1
11265 \end_inset
11266 </cell>
11267 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11268 \begin_inset Text
11269
11270 \layout Standard
11271
11272 0x001B
11273 \end_inset
11274 </cell>
11275 </row>
11276 <row topline="true">
11277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11278 \begin_inset Text
11279
11280 \layout Standard
11281
11282 4
11283 \end_inset
11284 </cell>
11285 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11286 \begin_inset Text
11287
11288 \layout Standard
11289
11290 Serial
11291 \end_inset
11292 </cell>
11293 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11294 \begin_inset Text
11295
11296 \layout Standard
11297
11298 0x0023
11299 \end_inset
11300 </cell>
11301 </row>
11302 <row topline="true" bottomline="true">
11303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11304 \begin_inset Text
11305
11306 \layout Standard
11307
11308 5
11309 \end_inset
11310 </cell>
11311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11312 \begin_inset Text
11313
11314 \layout Standard
11315
11316 Timer 2 (8052)
11317 \end_inset
11318 </cell>
11319 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11320 \begin_inset Text
11321
11322 \layout Standard
11323
11324 0x002B
11325 \end_inset
11326 </cell>
11327 </row>
11328 </lyxtabular>
11329
11330 \end_inset
11331
11332
11333 \newline
11334
11335 \layout Standard
11336
11337 If the interrupt service routine is defined without
11338 \emph on
11339 using
11340 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11341
11342 \end_inset
11343
11344
11345 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11346
11347 \end_inset
11348
11349
11350 \emph default
11351  a register bank or with register bank 0 (
11352 \emph on
11353 using
11354 \emph default
11355  0), the compiler will save the registers used by itself on the stack upon
11356  entry and restore them at exit, however if such an interrupt service routine
11357  calls another function then the entire register bank will be saved on the
11358  stack.
11359  This scheme may be advantageous for small interrupt service routines which
11360  have low register usage.
11361 \layout Standard
11362
11363 If the interrupt service routine is defined to be using a specific register
11364  bank then only
11365 \emph on
11366 a, b, dptr
11367 \emph default
11368  & psw are saved and restored, if such an interrupt service routine calls
11369  another function (using another register bank) then the entire register
11370  bank of the called function will be saved on the stack.
11371  This scheme is recommended for larger interrupt service routines.
11372 \layout Subsection
11373
11374 HC08 Interrupt Service Routines
11375 \layout Standard
11376
11377 Since the number of interrupts available is chip specific and the interrupt
11378  vector table always ends at the last byte of memory, the interrupt numbers
11379  corresponds to the interrupt vectors in reverse order of address.
11380  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11381  2 will use the interrupt vector at 0xfffa, and so on.
11382  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11383  this way; instead see section
11384 \begin_inset LatexCommand \ref{sub:Startup-Code}
11385
11386 \end_inset
11387
11388  for details on customizing startup.
11389 \layout Subsection
11390
11391 Z80 Interrupt Service Routines
11392 \layout Standard
11393
11394 The Z80 uses several different methods for determining the correct interrupt
11395  vector depending on the hardware implementation.
11396  Therefore, SDCC ignores the optional interrupt number and does not attempt
11397  to generate an interrupt vector table.
11398 \layout Standard
11399
11400 By default, SDCC generates code for a maskable interrupt, which uses a RETI
11401  instruction to return from the interrupt.
11402  To write an interrupt handler for the non-maskable interrupt, which needs
11403  a RETN instruction instead, add the
11404 \emph on
11405 critical
11406 \emph default
11407  keyword:
11408 \layout Verse
11409
11410
11411 \family typewriter
11412 void nmi_isr (void) critical interrupt
11413 \newline
11414 {
11415 \newline
11416 \SpecialChar ~
11417 \SpecialChar ~
11418 \SpecialChar ~
11419 \SpecialChar ~
11420 ...
11421
11422 \newline
11423 }
11424 \layout Standard
11425
11426 However if you need to create a non-interruptable interrupt service routine
11427  you would also require the
11428 \emph on
11429 critical
11430 \emph default
11431  keyword.
11432  To distinguish between this and an nmi_isr you must provide an interrupt
11433  number.
11434 \layout Section
11435
11436 Enabling and Disabling Interrupts
11437 \layout Subsection
11438
11439 Critical Functions and Critical Statements
11440 \layout Standard
11441
11442 A special keyword may be associated with a block or a function declaring
11443  it as
11444 \emph on
11445 critical
11446 \emph default
11447 .
11448  SDCC will generate code to disable all interrupts
11449 \begin_inset LatexCommand \index{interrupt}
11450
11451 \end_inset
11452
11453  upon entry to a critical function and restore the interrupt enable to the
11454  previous state before returning.
11455  Nesting critical functions will need one additional byte on the stack
11456 \begin_inset LatexCommand \index{stack}
11457
11458 \end_inset
11459
11460  for each call.
11461 \layout Verse
11462
11463
11464 \family typewriter
11465 int foo () critical
11466 \begin_inset LatexCommand \index{critical}
11467
11468 \end_inset
11469
11470
11471 \begin_inset LatexCommand \index{\_\_critical}
11472
11473 \end_inset
11474
11475
11476 \newline
11477 {
11478 \newline
11479 \SpecialChar ~
11480 \SpecialChar ~
11481 \SpecialChar ~
11482 \SpecialChar ~
11483 ...
11484
11485 \newline
11486 \SpecialChar ~
11487 \SpecialChar ~
11488 \SpecialChar ~
11489 \SpecialChar ~
11490 ...
11491
11492 \newline
11493 }
11494 \layout Standard
11495
11496 The critical attribute maybe used with other attributes like
11497 \emph on
11498 reentrant.
11499 \emph default
11500
11501 \newline
11502 The keyword
11503 \emph on
11504 critical
11505 \emph default
11506  may also be used to disable interrupts more locally:
11507 \layout Verse
11508
11509
11510 \family typewriter
11511 critical{ i++; }
11512 \layout Standard
11513
11514 More than one statement could have been included in the block.
11515 \layout Subsection
11516
11517 Enabling and Disabling Interrupts directly
11518 \layout Standard
11519
11520 Interrupts
11521 \begin_inset LatexCommand \index{interrupt}
11522
11523 \end_inset
11524
11525  can also be disabled and enabled directly (8051):
11526 \layout Verse
11527
11528
11529 \family typewriter
11530 EA = 0;\SpecialChar ~
11531 \SpecialChar ~
11532 \SpecialChar ~
11533 \SpecialChar ~
11534 \SpecialChar ~
11535 \SpecialChar ~
11536 \SpecialChar ~
11537 \SpecialChar ~
11538 \SpecialChar ~
11539 \SpecialChar ~
11540 \SpecialChar ~
11541 \SpecialChar ~
11542 or:\SpecialChar ~
11543 \SpecialChar ~
11544 \SpecialChar ~
11545 \SpecialChar ~
11546 \SpecialChar ~
11547 \SpecialChar ~
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 \SpecialChar ~
11551 \SpecialChar ~
11552 \SpecialChar ~
11553 EA_SAVE = EA;
11554 \layout Verse
11555
11556
11557 \family typewriter
11558 ...\SpecialChar ~
11559 \SpecialChar ~
11560 \SpecialChar ~
11561 \SpecialChar ~
11562 \SpecialChar ~
11563 \SpecialChar ~
11564 \SpecialChar ~
11565 \SpecialChar ~
11566 \SpecialChar ~
11567 \SpecialChar ~
11568 \SpecialChar ~
11569 \SpecialChar ~
11570 \SpecialChar ~
11571 \SpecialChar ~
11572 \SpecialChar ~
11573 \SpecialChar ~
11574 \SpecialChar ~
11575 \SpecialChar ~
11576 \SpecialChar ~
11577 \SpecialChar ~
11578 \SpecialChar ~
11579 \SpecialChar ~
11580 \SpecialChar ~
11581 \SpecialChar ~
11582 \SpecialChar ~
11583 \SpecialChar ~
11584 \SpecialChar ~
11585 \SpecialChar ~
11586 \SpecialChar ~
11587 \SpecialChar ~
11588 EA = 0;
11589 \layout Verse
11590
11591
11592 \family typewriter
11593 EA = 1;\SpecialChar ~
11594 \SpecialChar ~
11595 \SpecialChar ~
11596 \SpecialChar ~
11597 \SpecialChar ~
11598 \SpecialChar ~
11599 \SpecialChar ~
11600 \SpecialChar ~
11601 \SpecialChar ~
11602 \SpecialChar ~
11603 \SpecialChar ~
11604 \SpecialChar ~
11605 \SpecialChar ~
11606 \SpecialChar ~
11607 \SpecialChar ~
11608 \SpecialChar ~
11609 \SpecialChar ~
11610 \SpecialChar ~
11611 \SpecialChar ~
11612 \SpecialChar ~
11613 \SpecialChar ~
11614 \SpecialChar ~
11615 \SpecialChar ~
11616 \SpecialChar ~
11617 \SpecialChar ~
11618 \SpecialChar ~
11619 ...
11620 \layout Verse
11621
11622
11623 \family typewriter
11624 \SpecialChar ~
11625 \SpecialChar ~
11626 \SpecialChar ~
11627 \SpecialChar ~
11628 \SpecialChar ~
11629 \SpecialChar ~
11630 \SpecialChar ~
11631 \SpecialChar ~
11632 \SpecialChar ~
11633 \SpecialChar ~
11634 \SpecialChar ~
11635 \SpecialChar ~
11636 \SpecialChar ~
11637 \SpecialChar ~
11638 \SpecialChar ~
11639 \SpecialChar ~
11640 \SpecialChar ~
11641 \SpecialChar ~
11642 \SpecialChar ~
11643 \SpecialChar ~
11644 \SpecialChar ~
11645 \SpecialChar ~
11646 \SpecialChar ~
11647 \SpecialChar ~
11648 \SpecialChar ~
11649 \SpecialChar ~
11650 \SpecialChar ~
11651 \SpecialChar ~
11652 \SpecialChar ~
11653 \SpecialChar ~
11654 \SpecialChar ~
11655 \SpecialChar ~
11656 \SpecialChar ~
11657 EA = EA_SAVE;
11658 \layout Standard
11659
11660 On other architectures which have seperate opcodes for enabling and disabling
11661  interrupts you might want to make use of defines with inline assembly
11662 \begin_inset LatexCommand \index{Assembler routines}
11663
11664 \end_inset
11665
11666  (HC08):
11667 \layout Verse
11668
11669
11670 \family typewriter
11671 #define CLI _asm
11672 \begin_inset LatexCommand \index{\_asm}
11673
11674 \end_inset
11675
11676 \SpecialChar ~
11677 \SpecialChar ~
11678 cli\SpecialChar ~
11679 \SpecialChar ~
11680 _endasm
11681 \begin_inset LatexCommand \index{\_endasm}
11682
11683 \end_inset
11684
11685 ;
11686 \layout Verse
11687
11688
11689 \family typewriter
11690 #define SEI _asm\SpecialChar ~
11691 \SpecialChar ~
11692 sei\SpecialChar ~
11693 \SpecialChar ~
11694 _endasm;
11695 \layout Verse
11696
11697
11698 \family typewriter
11699 ...
11700 \layout Standard
11701
11702 Note: it is sometimes sufficient to disable only a specific interrupt source
11703  like f.e.
11704  a timer or serial interrupt by manipulating an
11705 \emph on
11706 interrupt mask
11707 \begin_inset LatexCommand \index{interrupt mask}
11708
11709 \end_inset
11710
11711
11712 \emph default
11713  register.
11714
11715 \layout Standard
11716
11717 Usually the time during which interrupts are disabled should be kept as
11718  short as possible.
11719  This minimizes both
11720 \emph on
11721 interrupt latency
11722 \emph default
11723
11724 \begin_inset LatexCommand \index{interrupt latency}
11725
11726 \end_inset
11727
11728  (the time between the occurrence of the interrupt and the execution of
11729  the first code in the interrupt routine) and
11730 \emph on
11731 interrupt jitter
11732 \emph default
11733
11734 \begin_inset LatexCommand \index{interrupt jitter}
11735
11736 \end_inset
11737
11738  (the difference between the shortest and the longest interrupt latency).
11739  These really are something different, f.e.
11740  a serial interrupt has to be served before its buffer overruns so it cares
11741  for the maximum interrupt latency, whereas it does not care about jitter.
11742  On a loudspeaker driven via a digital to analog converter which is fed
11743  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11744  a much smaller jitter will be very audible.
11745 \layout Standard
11746
11747 You can reenable interrupts within an interrupt routine and on some architecture
11748 s you can make use of two (or more) levels of
11749 \emph on
11750 interrupt priorities
11751 \emph default
11752
11753 \begin_inset LatexCommand \index{interrupt priority}
11754
11755 \end_inset
11756
11757 .
11758  On some architectures which don't support interrupt priorities these can
11759  be implemented by manipulating the interrupt mask and reenabling interrupts
11760  within the interrupt routine.
11761  Check there is sufficient space on the stack
11762 \begin_inset LatexCommand \index{stack}
11763
11764 \end_inset
11765
11766  and don't add complexity unless you have to.
11767
11768 \layout Subsection
11769
11770 Semaphore
11771 \begin_inset LatexCommand \index{semaphore}
11772
11773 \end_inset
11774
11775  locking (mcs51/ds390)
11776 \layout Standard
11777
11778 Some architectures (mcs51/ds390) have an atomic
11779 \begin_inset LatexCommand \index{atomic}
11780
11781 \end_inset
11782
11783  bit test and
11784 \emph on
11785
11786 \emph default
11787 clear
11788 \emph on
11789
11790 \emph default
11791 instruction.
11792  These type of instructions are typically used in preemptive multitasking
11793  systems, where a routine f.e.
11794  claims the use of a data structure ('acquires a lock
11795 \begin_inset LatexCommand \index{lock}
11796
11797 \end_inset
11798
11799  on it'), makes some modifications and then releases the lock when the data
11800  structure is consistent again.
11801  The instruction may also be used if interrupt and non-interrupt code have
11802  to compete for a resource.
11803  With the atomic bit test and clear instruction interrupts
11804 \begin_inset LatexCommand \index{interrupt}
11805
11806 \end_inset
11807
11808  don't have to be disabled for the locking operation.
11809
11810 \layout Standard
11811
11812 SDCC generates this instruction if the source follows this pattern:
11813 \layout Verse
11814
11815
11816 \family typewriter
11817 volatile
11818 \begin_inset LatexCommand \index{volatile}
11819
11820 \end_inset
11821
11822  bit resource_is_free;
11823 \newline
11824
11825 \newline
11826 if (resource_is_free)
11827 \newline
11828 \SpecialChar ~
11829 \SpecialChar ~
11830 {
11831 \newline
11832 \SpecialChar ~
11833 \SpecialChar ~
11834 \SpecialChar ~
11835 \SpecialChar ~
11836 resource_is_free=0;
11837 \newline
11838 \SpecialChar ~
11839 \SpecialChar ~
11840 \SpecialChar ~
11841 \SpecialChar ~
11842 ...
11843
11844 \newline
11845 \SpecialChar ~
11846 \SpecialChar ~
11847 \SpecialChar ~
11848 \SpecialChar ~
11849 resource_is_free=1;
11850 \newline
11851 \SpecialChar ~
11852 \SpecialChar ~
11853 }
11854 \layout Standard
11855
11856 Note, mcs51 and ds390 support only an atomic
11857 \begin_inset LatexCommand \index{atomic}
11858
11859 \end_inset
11860
11861  bit test and
11862 \emph on
11863 clear
11864 \emph default
11865  instruction (as opposed to atomic bit test and
11866 \emph on
11867 set).
11868 \layout Section
11869
11870 Functions using private register banks
11871 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11872
11873 \end_inset
11874
11875  (mcs51/ds390)
11876 \layout Standard
11877
11878 Some architectures have support for quickly changing register sets.
11879  SDCC supports this feature with the
11880 \emph on
11881 using
11882 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11883
11884 \end_inset
11885
11886
11887 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11888
11889 \end_inset
11890
11891
11892 \emph default
11893  attribute (which tells the compiler to use a register bank
11894 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11895
11896 \end_inset
11897
11898  other than the default bank zero).
11899  It should only be applied to
11900 \emph on
11901 interrupt
11902 \begin_inset LatexCommand \index{interrupt}
11903
11904 \end_inset
11905
11906
11907 \emph default
11908  functions (see footnote below).
11909  This will in most circumstances make the generated ISR code more efficient
11910  since it will not have to save registers on the stack.
11911 \layout Standard
11912
11913 The
11914 \emph on
11915 using
11916 \emph default
11917  attribute will have no effect on the generated code for a
11918 \emph on
11919 non-interrupt
11920 \emph default
11921  function (but may occasionally be useful anyway
11922 \begin_inset Foot
11923 collapsed false
11924
11925 \layout Standard
11926
11927 possible exception: if a function is called ONLY from 'interrupt' functions
11928  using a particular bank, it can be declared with the same 'using' attribute
11929  as the calling 'interrupt' functions.
11930  For instance, if you have several ISRs using bank one, and all of them
11931  call memcpy(), it might make sense to create a specialized version of memcpy()
11932  'using 1', since this would prevent the ISR from having to save bank zero
11933  to the stack on entry and switch to bank zero before calling the function
11934 \end_inset
11935
11936 ).
11937 \newline
11938
11939 \emph on
11940 (pending: I don't think this has been done yet)
11941 \layout Standard
11942
11943 An
11944 \emph on
11945 interrupt
11946 \emph default
11947  function using a non-zero bank will assume that it can trash that register
11948  bank, and will not save it.
11949  Since high-priority interrupts
11950 \begin_inset LatexCommand \index{interrupts}
11951
11952 \end_inset
11953
11954
11955 \begin_inset LatexCommand \index{interrupt priority}
11956
11957 \end_inset
11958
11959  can interrupt low-priority ones on the 8051 and friends, this means that
11960  if a high-priority ISR
11961 \emph on
11962 using
11963 \emph default
11964  a particular bank occurs while processing a low-priority ISR
11965 \emph on
11966 using
11967 \emph default
11968  the same bank, terrible and bad things can happen.
11969  To prevent this, no single register bank should be
11970 \emph on
11971 used
11972 \emph default
11973  by both a high priority and a low priority ISR.
11974  This is probably most easily done by having all high priority ISRs use
11975  one bank and all low priority ISRs use another.
11976  If you have an ISR which can change priority at runtime, you're on your
11977  own: I suggest using the default bank zero and taking the small performance
11978  hit.
11979 \layout Standard
11980
11981 It is most efficient if your ISR calls no other functions.
11982  If your ISR must call other functions, it is most efficient if those functions
11983  use the same bank as the ISR (see note 1 below); the next best is if the
11984  called functions use bank zero.
11985  It is very inefficient to call a function using a different, non-zero bank
11986  from an ISR.
11987
11988 \layout Section
11989
11990 Startup Code
11991 \begin_inset LatexCommand \label{sub:Startup-Code}
11992
11993 \end_inset
11994
11995
11996 \begin_inset LatexCommand \index{Startup code}
11997
11998 \end_inset
11999
12000
12001 \layout Subsection
12002
12003 MCS51/DS390 Startup Code
12004 \layout Standard
12005
12006 The compiler inserts a call to the C routine
12007 \emph on
12008 _sdcc_external_startup()
12009 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
12010
12011 \end_inset
12012
12013
12014 \series bold
12015 \emph default
12016
12017 \series default
12018 at the start of the CODE area.
12019  This routine is in the runtime library
12020 \begin_inset LatexCommand \index{Runtime library}
12021
12022 \end_inset
12023
12024 .
12025  By default this routine returns 0, if this routine returns a non-zero value,
12026  the static & global variable initialization will be skipped and the function
12027  main will be invoked.
12028  Otherwise static & global variables will be initialized before the function
12029  main is invoked.
12030  You could add a
12031 \emph on
12032 _sdcc_external_startup()
12033 \emph default
12034  routine to your program to override the default if you need to setup hardware
12035  or perform some other critical operation prior to static & global variable
12036  initialization
12037 \begin_inset LatexCommand \index{Variable initialization}
12038
12039 \end_inset
12040
12041 .
12042  On some mcs51 variants xdata
12043 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
12044
12045 \end_inset
12046
12047  memory has to be explicitly enabled before it can be accessed or if the
12048  watchdog needs to be disabled, this is the place to do it.
12049  The startup code clears all internal data memory, 256 bytes by default,
12050  but from 0 to n-1 if
12051 \emph on
12052 -
12053 \begin_inset ERT
12054 status Collapsed
12055
12056 \layout Standard
12057
12058 \backslash
12059 /
12060 \end_inset
12061
12062 -iram-size
12063 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
12064
12065 \end_inset
12066
12067 n
12068 \emph default
12069  is used.
12070  (recommended for Chipcon CC1010).
12071 \layout Standard
12072
12073 See also the compiler option
12074 \emph on
12075 -
12076 \begin_inset ERT
12077 status Collapsed
12078
12079 \layout Standard
12080
12081 \backslash
12082 /
12083 \end_inset
12084
12085 -no-xinit
12086 \emph default
12087 -
12088 \emph on
12089 opt
12090 \emph default
12091
12092 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
12093
12094 \end_inset
12095
12096  and section
12097 \begin_inset LatexCommand \ref{sub:MCS51-variants}
12098
12099 \end_inset
12100
12101 \SpecialChar ~
12102 about MCS51-variants.
12103 \layout Subsection
12104
12105 HC08 Startup Code
12106 \layout Standard
12107
12108 The HC08 startup code follows the same scheme as the MCS51 startup code.
12109 \layout Subsection
12110
12111 Z80 Startup Code
12112 \layout Standard
12113
12114 On the Z80 the startup code is inserted by linking with crt0.o which is generated
12115  from sdcc/device/lib/z80/crt0.s.
12116  If you need a different startup code you can use the compiler option
12117 \emph on
12118 -
12119 \series bold
12120 \emph default
12121
12122 \begin_inset ERT
12123 status Collapsed
12124
12125 \layout Standard
12126
12127 \backslash
12128 /
12129 \end_inset
12130
12131
12132 \series default
12133 \emph on
12134 -no-std-crt0
12135 \emph default
12136
12137 \begin_inset LatexCommand \index{-\/-no-std-crt0}
12138
12139 \end_inset
12140
12141  and provide your own crt0.o.
12142
12143 \layout Section
12144
12145 Inline Assembler Code
12146 \begin_inset LatexCommand \index{Assembler routines}
12147
12148 \end_inset
12149
12150
12151 \layout Subsection
12152
12153 A Step by Step Introduction
12154 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
12155
12156 \end_inset
12157
12158
12159 \layout Standard
12160
12161 Starting from a small snippet of c-code this example shows for the MCS51
12162  how to use inline assembly, access variables, a function parameter and
12163  an array in xdata memory.
12164  The example uses an MCS51 here but is easily adapted for other architectures.
12165  This is a buffer routine which should be optimized:
12166 \layout Verse
12167
12168
12169 \family typewriter
12170 \size footnotesize
12171 unsigned char far
12172 \begin_inset LatexCommand \index{far (storage class)}
12173
12174 \end_inset
12175
12176
12177 \begin_inset LatexCommand \index{\_\_far (storage class)}
12178
12179 \end_inset
12180
12181  at
12182 \begin_inset LatexCommand \index{at}
12183
12184 \end_inset
12185
12186
12187 \begin_inset LatexCommand \index{\_\_at}
12188
12189 \end_inset
12190
12191  0x7f00 buf[0x100];
12192 \begin_inset LatexCommand \index{Aligned array}
12193
12194 \end_inset
12195
12196
12197 \newline
12198 unsigned char head,tail;
12199 \newline
12200
12201 \newline
12202 void to_buffer( unsigned char c )
12203 \newline
12204 {
12205 \newline
12206 \SpecialChar ~
12207 \SpecialChar ~
12208 \SpecialChar ~
12209 \SpecialChar ~
12210 if( head != tail-1 )
12211 \newline
12212 \SpecialChar ~
12213 \SpecialChar ~
12214 \SpecialChar ~
12215 \SpecialChar ~
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 \SpecialChar ~
12219 \SpecialChar ~
12220 buf[ head++ ] = c;\SpecialChar ~
12221 \SpecialChar ~
12222 \SpecialChar ~
12223 \SpecialChar ~
12224 /* access to a 256 byte aligned array */
12225 \newline
12226 }
12227 \layout Standard
12228
12229 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
12230  then a corresponding buffer.asm file is generated.
12231  We define a new function
12232 \family typewriter
12233 to_buffer_asm()
12234 \family default
12235  in file buffer.c in which we cut and paste the generated code, removing
12236  unwanted comments and some ':'.
12237  Then add
12238 \begin_inset Quotes sld
12239 \end_inset
12240
12241 _asm
12242 \begin_inset Quotes srd
12243 \end_inset
12244
12245  and
12246 \begin_inset Quotes sld
12247 \end_inset
12248
12249 _endasm;
12250 \begin_inset Quotes srd
12251 \end_inset
12252
12253  to the beginning and the end of the function body:
12254 \layout Verse
12255
12256
12257 \family typewriter
12258 \size footnotesize
12259 /* With a cut and paste from the .asm file, we have something to start with.
12260 \newline
12261 \SpecialChar ~
12262 \SpecialChar ~
12263 \SpecialChar ~
12264 The function is not yet OK! (registers aren't saved) */
12265 \newline
12266 void to_buffer_asm( unsigned char c )
12267 \newline
12268 {
12269 \newline
12270 \SpecialChar ~
12271 \SpecialChar ~
12272 \SpecialChar ~
12273 \SpecialChar ~
12274 _asm
12275 \begin_inset LatexCommand \index{\_asm}
12276
12277 \end_inset
12278
12279
12280 \begin_inset LatexCommand \index{\_\_asm}
12281
12282 \end_inset
12283
12284
12285 \newline
12286 \SpecialChar ~
12287 \SpecialChar ~
12288 \SpecialChar ~
12289 \SpecialChar ~
12290 mov\SpecialChar ~
12291 \SpecialChar ~
12292 r2,dpl
12293 \newline
12294 ;buffer.c if( head != tail-1 )
12295 \newline
12296 \SpecialChar ~
12297 \SpecialChar ~
12298 \SpecialChar ~
12299 \SpecialChar ~
12300 mov\SpecialChar ~
12301 \SpecialChar ~
12302 a,_tail
12303 \newline
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 \SpecialChar ~
12308 dec\SpecialChar ~
12309 \SpecialChar ~
12310 a
12311 \newline
12312 \SpecialChar ~
12313 \SpecialChar ~
12314 \SpecialChar ~
12315 \SpecialChar ~
12316 mov\SpecialChar ~
12317 \SpecialChar ~
12318 r3,a
12319 \newline
12320 \SpecialChar ~
12321 \SpecialChar ~
12322 \SpecialChar ~
12323 \SpecialChar ~
12324 mov\SpecialChar ~
12325 \SpecialChar ~
12326 a,_head
12327 \newline
12328 \SpecialChar ~
12329 \SpecialChar ~
12330 \SpecialChar ~
12331 \SpecialChar ~
12332 cjne a,ar3,00106$
12333 \newline
12334 \SpecialChar ~
12335 \SpecialChar ~
12336 \SpecialChar ~
12337 \SpecialChar ~
12338 ret
12339 \newline
12340 00106$:
12341 \newline
12342 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12343 \begin_inset LatexCommand \index{Aligned array}
12344
12345 \end_inset
12346
12347
12348 \newline
12349 \SpecialChar ~
12350 \SpecialChar ~
12351 \SpecialChar ~
12352 \SpecialChar ~
12353 mov\SpecialChar ~
12354 \SpecialChar ~
12355 r3,_head
12356 \newline
12357 \SpecialChar ~
12358 \SpecialChar ~
12359 \SpecialChar ~
12360 \SpecialChar ~
12361 inc\SpecialChar ~
12362 \SpecialChar ~
12363 _head
12364 \newline
12365 \SpecialChar ~
12366 \SpecialChar ~
12367 \SpecialChar ~
12368 \SpecialChar ~
12369 mov\SpecialChar ~
12370 \SpecialChar ~
12371 dpl,r3
12372 \newline
12373 \SpecialChar ~
12374 \SpecialChar ~
12375 \SpecialChar ~
12376 \SpecialChar ~
12377 mov\SpecialChar ~
12378 \SpecialChar ~
12379 dph,#(_buf >> 8)
12380 \newline
12381 \SpecialChar ~
12382 \SpecialChar ~
12383 \SpecialChar ~
12384 \SpecialChar ~
12385 mov\SpecialChar ~
12386 \SpecialChar ~
12387 a,r2
12388 \newline
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 \SpecialChar ~
12392 \SpecialChar ~
12393 movx @dptr,a
12394 \newline
12395 00103$:
12396 \newline
12397 \SpecialChar ~
12398 \SpecialChar ~
12399 \SpecialChar ~
12400 \SpecialChar ~
12401 ret
12402 \newline
12403 \SpecialChar ~
12404 \SpecialChar ~
12405 \SpecialChar ~
12406 \SpecialChar ~
12407 _endasm
12408 \begin_inset LatexCommand \index{\_endasm}
12409
12410 \end_inset
12411
12412
12413 \begin_inset LatexCommand \index{\_\_endasm}
12414
12415 \end_inset
12416
12417 ;
12418 \newline
12419 }
12420 \layout Standard
12421
12422 The new file buffer.c should compile with only one warning about the unreferenced
12423  function argument 'c'.
12424  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12425  (1) and finally have:
12426 \layout Verse
12427
12428
12429 \family typewriter
12430 \size footnotesize
12431 unsigned char far at 0x7f00 buf[0x100];
12432 \newline
12433 unsigned char head,tail;
12434 \newline
12435 #define USE_ASSEMBLY (1)
12436 \newline
12437
12438 \newline
12439 #if !USE_ASSEMBLY
12440 \newline
12441
12442 \newline
12443 void to_buffer( unsigned char c )
12444 \newline
12445 {
12446 \newline
12447 \SpecialChar ~
12448 \SpecialChar ~
12449 \SpecialChar ~
12450 \SpecialChar ~
12451 if( head != tail-1 )
12452 \newline
12453 \SpecialChar ~
12454 \SpecialChar ~
12455 \SpecialChar ~
12456 \SpecialChar ~
12457 \SpecialChar ~
12458 \SpecialChar ~
12459 \SpecialChar ~
12460 \SpecialChar ~
12461 buf[ head++ ] = c;
12462 \newline
12463 }
12464 \newline
12465
12466 \newline
12467 #else
12468 \newline
12469
12470 \newline
12471 void to_buffer( unsigned char c )
12472 \newline
12473 {
12474 \newline
12475 \SpecialChar ~
12476 \SpecialChar ~
12477 \SpecialChar ~
12478 \SpecialChar ~
12479 c; // to avoid warning: unreferenced function argument
12480 \newline
12481 \SpecialChar ~
12482 \SpecialChar ~
12483 \SpecialChar ~
12484 \SpecialChar ~
12485 _asm
12486 \begin_inset LatexCommand \index{\_asm}
12487
12488 \end_inset
12489
12490
12491 \begin_inset LatexCommand \index{\_\_asm}
12492
12493 \end_inset
12494
12495
12496 \newline
12497 \SpecialChar ~
12498 \SpecialChar ~
12499 \SpecialChar ~
12500 \SpecialChar ~
12501 \SpecialChar ~
12502 \SpecialChar ~
12503 \SpecialChar ~
12504 \SpecialChar ~
12505 ; save used registers here.
12506
12507 \newline
12508 \SpecialChar ~
12509 \SpecialChar ~
12510 \SpecialChar ~
12511 \SpecialChar ~
12512 \SpecialChar ~
12513 \SpecialChar ~
12514 \SpecialChar ~
12515 \SpecialChar ~
12516 ; If we were still using r2,r3 we would have to push them here.
12517
12518 \newline
12519 ; if( head != tail-1 )
12520 \newline
12521 \SpecialChar ~
12522 \SpecialChar ~
12523 \SpecialChar ~
12524 \SpecialChar ~
12525 \SpecialChar ~
12526 \SpecialChar ~
12527 \SpecialChar ~
12528 \SpecialChar ~
12529 mov\SpecialChar ~
12530  a,_tail
12531 \newline
12532 \SpecialChar ~
12533 \SpecialChar ~
12534 \SpecialChar ~
12535 \SpecialChar ~
12536 \SpecialChar ~
12537 \SpecialChar ~
12538 \SpecialChar ~
12539 \SpecialChar ~
12540 dec\SpecialChar ~
12541  a
12542 \newline
12543 \SpecialChar ~
12544 \SpecialChar ~
12545 \SpecialChar ~
12546 \SpecialChar ~
12547 \SpecialChar ~
12548 \SpecialChar ~
12549 \SpecialChar ~
12550 \SpecialChar ~
12551 xrl\SpecialChar ~
12552  a,_head
12553 \newline
12554 \SpecialChar ~
12555 \SpecialChar ~
12556 \SpecialChar ~
12557 \SpecialChar ~
12558 \SpecialChar ~
12559 \SpecialChar ~
12560 \SpecialChar ~
12561 \SpecialChar ~
12562 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
12563 \newline
12564 \SpecialChar ~
12565 \SpecialChar ~
12566 \SpecialChar ~
12567 \SpecialChar ~
12568 \SpecialChar ~
12569 \SpecialChar ~
12570 \SpecialChar ~
12571 \SpecialChar ~
12572 jz\SpecialChar ~
12573 \SpecialChar ~
12574  t_b_end$
12575 \newline
12576 \SpecialChar ~
12577 \SpecialChar ~
12578 \SpecialChar ~
12579 \SpecialChar ~
12580 \SpecialChar ~
12581 \SpecialChar ~
12582 \SpecialChar ~
12583 \SpecialChar ~
12584 ;
12585 \newline
12586 ; buf[ head++ ] = c;
12587 \newline
12588 \SpecialChar ~
12589 \SpecialChar ~
12590 \SpecialChar ~
12591 \SpecialChar ~
12592 \SpecialChar ~
12593 \SpecialChar ~
12594 \SpecialChar ~
12595 \SpecialChar ~
12596 mov\SpecialChar ~
12597  a,dpl \SpecialChar ~
12598 \SpecialChar ~
12599 \SpecialChar ~
12600 \SpecialChar ~
12601 \SpecialChar ~
12602 \SpecialChar ~
12603 \SpecialChar ~
12604 ; dpl holds lower byte of function argument
12605 \newline
12606 \SpecialChar ~
12607 \SpecialChar ~
12608 \SpecialChar ~
12609 \SpecialChar ~
12610 \SpecialChar ~
12611 \SpecialChar ~
12612 \SpecialChar ~
12613 \SpecialChar ~
12614 mov\SpecialChar ~
12615  dpl,_head \SpecialChar ~
12616 \SpecialChar ~
12617 \SpecialChar ~
12618 ; buf is 0x100 byte aligned so head can be used directly
12619 \newline
12620 \SpecialChar ~
12621 \SpecialChar ~
12622 \SpecialChar ~
12623 \SpecialChar ~
12624 \SpecialChar ~
12625 \SpecialChar ~
12626 \SpecialChar ~
12627 \SpecialChar ~
12628 mov\SpecialChar ~
12629  dph,#(_buf>>8)
12630 \newline
12631 \SpecialChar ~
12632 \SpecialChar ~
12633 \SpecialChar ~
12634 \SpecialChar ~
12635 \SpecialChar ~
12636 \SpecialChar ~
12637 \SpecialChar ~
12638 \SpecialChar ~
12639 movx @dptr,a
12640 \newline
12641 \SpecialChar ~
12642 \SpecialChar ~
12643 \SpecialChar ~
12644 \SpecialChar ~
12645 \SpecialChar ~
12646 \SpecialChar ~
12647 \SpecialChar ~
12648 \SpecialChar ~
12649 inc \SpecialChar ~
12650 _head
12651 \newline
12652 \SpecialChar ~
12653 \SpecialChar ~
12654 \SpecialChar ~
12655 \SpecialChar ~
12656 \SpecialChar ~
12657 \SpecialChar ~
12658 \SpecialChar ~
12659 \SpecialChar ~
12660 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
12661 \newline
12662 t_b_end$:
12663 \newline
12664 \SpecialChar ~
12665 \SpecialChar ~
12666 \SpecialChar ~
12667 \SpecialChar ~
12668 \SpecialChar ~
12669 \SpecialChar ~
12670 \SpecialChar ~
12671 \SpecialChar ~
12672 ; restore used registers here
12673 \newline
12674 \SpecialChar ~
12675 \SpecialChar ~
12676 \SpecialChar ~
12677 \SpecialChar ~
12678 _endasm
12679 \begin_inset LatexCommand \index{\_endasm}
12680
12681 \end_inset
12682
12683
12684 \begin_inset LatexCommand \index{\_\_endasm}
12685
12686 \end_inset
12687
12688 ;
12689 \newline
12690 }
12691 \newline
12692 #endif
12693 \layout Standard
12694
12695 The inline assembler code can contain any valid code understood by the assembler
12696 , this includes any assembler directives and comment lines
12697 \begin_inset Foot
12698 collapsed false
12699
12700 \layout Standard
12701
12702 The assembler does not like some characters like ':' or ''' in comments.
12703  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
12704 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
12705
12706 \end_inset
12707
12708
12709 \begin_inset LatexCommand \index{Assembler documentation}
12710
12711 \end_inset
12712
12713
12714 \end_inset
12715
12716 .
12717  The compiler does not do any validation of the code within the
12718 \family typewriter
12719 _asm
12720 \begin_inset LatexCommand \index{\_asm}
12721
12722 \end_inset
12723
12724
12725 \begin_inset LatexCommand \index{\_\_asm}
12726
12727 \end_inset
12728
12729  ...
12730  _endasm
12731 \size footnotesize
12732
12733 \begin_inset LatexCommand \index{\_endasm}
12734
12735 \end_inset
12736
12737
12738 \begin_inset LatexCommand \index{\_\_endasm}
12739
12740 \end_inset
12741
12742
12743 \size default
12744 ;
12745 \family default
12746  keyword pair.
12747  Specifically it will not know which registers are used and thus register
12748  pushing/popping
12749 \begin_inset LatexCommand \index{push/pop}
12750
12751 \end_inset
12752
12753  has to be done manually.
12754
12755 \layout Standard
12756
12757 It is recommended that each assembly instruction (including labels) be placed
12758  in a separate line (as the example shows).
12759  When the -
12760 \begin_inset ERT
12761 status Collapsed
12762
12763 \layout Standard
12764
12765 \backslash
12766 /
12767 \end_inset
12768
12769 -
12770 \emph on
12771 peep-asm
12772 \begin_inset LatexCommand \index{-\/-peep-asm}
12773
12774 \end_inset
12775
12776
12777 \emph default
12778  command line option is used, the inline assembler code will be passed through
12779  the peephole optimizer
12780 \begin_inset LatexCommand \index{Peephole optimizer}
12781
12782 \end_inset
12783
12784 .
12785  There are only a few (if any) cases where this option makes sense, it might
12786  cause some unexpected changes in the inline assembler code.
12787  Please go through the peephole optimizer rules defined in file
12788 \emph on
12789 SDCCpeeph.def
12790 \emph default
12791  before using this option.
12792 \layout Subsection
12793
12794 Naked Functions
12795 \begin_inset LatexCommand \label{sub:Naked-Functions}
12796
12797 \end_inset
12798
12799
12800 \begin_inset LatexCommand \index{Naked functions}
12801
12802 \end_inset
12803
12804
12805 \layout Standard
12806
12807 A special keyword may be associated with a function declaring it as
12808 \emph on
12809 _naked
12810 \begin_inset LatexCommand \index{\_naked}
12811
12812 \end_inset
12813
12814
12815 \begin_inset LatexCommand \index{\_\_naked}
12816
12817 \end_inset
12818
12819 .
12820
12821 \emph default
12822 The
12823 \emph on
12824 _naked
12825 \emph default
12826  function modifier attribute prevents the compiler from generating prologue
12827 \begin_inset LatexCommand \index{function prologue}
12828
12829 \end_inset
12830
12831  and epilogue
12832 \begin_inset LatexCommand \index{function epilogue}
12833
12834 \end_inset
12835
12836  code for that function.
12837  This means that the user is entirely responsible for such things as saving
12838  any registers that may need to be preserved, selecting the proper register
12839  bank, generating the
12840 \emph on
12841 return
12842 \emph default
12843  instruction at the end, etc.
12844  Practically, this means that the contents of the function must be written
12845  in inline assembler.
12846  This is particularly useful for interrupt functions, which can have a large
12847  (and often unnecessary) prologue/epilogue.
12848  For example, compare the code generated by these two functions:
12849 \layout Verse
12850
12851
12852 \family typewriter
12853 volatile
12854 \begin_inset LatexCommand \index{volatile}
12855
12856 \end_inset
12857
12858  data unsigned char counter;
12859 \newline
12860
12861 \newline
12862 void simpleInterrupt(void) interrupt
12863 \begin_inset LatexCommand \index{interrupt}
12864
12865 \end_inset
12866
12867
12868 \begin_inset LatexCommand \index{\_\_interrupt}
12869
12870 \end_inset
12871
12872  1
12873 \newline
12874 {
12875 \newline
12876 \SpecialChar ~
12877 \SpecialChar ~
12878 \SpecialChar ~
12879 \SpecialChar ~
12880 counter++;
12881 \newline
12882 }
12883 \newline
12884
12885 \newline
12886 void nakedInterrupt(void) interrupt 2 _naked
12887 \newline
12888 {
12889 \newline
12890 \SpecialChar ~
12891 \SpecialChar ~
12892 \SpecialChar ~
12893 \SpecialChar ~
12894 _asm
12895 \begin_inset LatexCommand \index{\_asm}
12896
12897 \end_inset
12898
12899
12900 \begin_inset LatexCommand \index{\_\_asm}
12901
12902 \end_inset
12903
12904
12905 \newline
12906 \SpecialChar ~
12907 \SpecialChar ~
12908 \SpecialChar ~
12909 \SpecialChar ~
12910 \SpecialChar ~
12911 \SpecialChar ~
12912 inc\SpecialChar ~
12913 \SpecialChar ~
12914 \SpecialChar ~
12915 \SpecialChar ~
12916 \SpecialChar ~
12917 _counter ; does not change flags, no need to save psw
12918 \newline
12919 \SpecialChar ~
12920 \SpecialChar ~
12921 \SpecialChar ~
12922 \SpecialChar ~
12923 \SpecialChar ~
12924 \SpecialChar ~
12925 reti\SpecialChar ~
12926 \SpecialChar ~
12927 \SpecialChar ~
12928 \SpecialChar ~
12929 ; MUST explicitly include ret or reti in _naked function.
12930 \newline
12931 \SpecialChar ~
12932 \SpecialChar ~
12933 \SpecialChar ~
12934 \SpecialChar ~
12935 _endasm
12936 \begin_inset LatexCommand \index{\_endasm}
12937
12938 \end_inset
12939
12940
12941 \begin_inset LatexCommand \index{\_\_endasm}
12942
12943 \end_inset
12944
12945 ;
12946 \newline
12947 }
12948 \layout Standard
12949
12950 For an 8051 target, the generated simpleInterrupt looks like:
12951 \layout Verse
12952
12953
12954 \family typewriter
12955 _simpleInterrupt:
12956 \newline
12957 \SpecialChar ~
12958 \SpecialChar ~
12959 \SpecialChar ~
12960 \SpecialChar ~
12961 push\SpecialChar ~
12962 \SpecialChar ~
12963 \SpecialChar ~
12964 \SpecialChar ~
12965 acc
12966 \newline
12967 \SpecialChar ~
12968 \SpecialChar ~
12969 \SpecialChar ~
12970 \SpecialChar ~
12971 push\SpecialChar ~
12972 \SpecialChar ~
12973 \SpecialChar ~
12974 \SpecialChar ~
12975 b
12976 \newline
12977 \SpecialChar ~
12978 \SpecialChar ~
12979 \SpecialChar ~
12980 \SpecialChar ~
12981 push\SpecialChar ~
12982 \SpecialChar ~
12983 \SpecialChar ~
12984 \SpecialChar ~
12985 dpl
12986 \newline
12987 \SpecialChar ~
12988 \SpecialChar ~
12989 \SpecialChar ~
12990 \SpecialChar ~
12991 push\SpecialChar ~
12992 \SpecialChar ~
12993 \SpecialChar ~
12994 \SpecialChar ~
12995 dph
12996 \newline
12997 \SpecialChar ~
12998 \SpecialChar ~
12999 \SpecialChar ~
13000 \SpecialChar ~
13001 push\SpecialChar ~
13002 \SpecialChar ~
13003 \SpecialChar ~
13004 \SpecialChar ~
13005 psw
13006 \newline
13007 \SpecialChar ~
13008 \SpecialChar ~
13009 \SpecialChar ~
13010 \SpecialChar ~
13011 mov\SpecialChar ~
13012 \SpecialChar ~
13013 \SpecialChar ~
13014 \SpecialChar ~
13015 \SpecialChar ~
13016 psw,#0x00
13017 \newline
13018 \SpecialChar ~
13019 \SpecialChar ~
13020 \SpecialChar ~
13021 \SpecialChar ~
13022 inc\SpecialChar ~
13023 \SpecialChar ~
13024 \SpecialChar ~
13025 \SpecialChar ~
13026 \SpecialChar ~
13027 _counter
13028 \newline
13029 \SpecialChar ~
13030 \SpecialChar ~
13031 \SpecialChar ~
13032 \SpecialChar ~
13033 pop\SpecialChar ~
13034 \SpecialChar ~
13035 \SpecialChar ~
13036 \SpecialChar ~
13037 \SpecialChar ~
13038 psw
13039 \newline
13040 \SpecialChar ~
13041 \SpecialChar ~
13042 \SpecialChar ~
13043 \SpecialChar ~
13044 pop\SpecialChar ~
13045 \SpecialChar ~
13046 \SpecialChar ~
13047 \SpecialChar ~
13048 \SpecialChar ~
13049 dph
13050 \newline
13051 \SpecialChar ~
13052 \SpecialChar ~
13053 \SpecialChar ~
13054 \SpecialChar ~
13055 pop\SpecialChar ~
13056 \SpecialChar ~
13057 \SpecialChar ~
13058 \SpecialChar ~
13059 \SpecialChar ~
13060 dpl
13061 \newline
13062 \SpecialChar ~
13063 \SpecialChar ~
13064 \SpecialChar ~
13065 \SpecialChar ~
13066 pop\SpecialChar ~
13067 \SpecialChar ~
13068 \SpecialChar ~
13069 \SpecialChar ~
13070 \SpecialChar ~
13071 b
13072 \newline
13073 \SpecialChar ~
13074 \SpecialChar ~
13075 \SpecialChar ~
13076 \SpecialChar ~
13077 pop\SpecialChar ~
13078 \SpecialChar ~
13079 \SpecialChar ~
13080 \SpecialChar ~
13081 \SpecialChar ~
13082 acc
13083 \newline
13084 \SpecialChar ~
13085 \SpecialChar ~
13086 \SpecialChar ~
13087 \SpecialChar ~
13088 reti
13089 \layout Standard
13090
13091 whereas nakedInterrupt looks like:
13092 \layout Verse
13093
13094
13095 \family typewriter
13096 _nakedInterrupt:
13097 \newline
13098 \SpecialChar ~
13099 \SpecialChar ~
13100 \SpecialChar ~
13101 \SpecialChar ~
13102 inc\SpecialChar ~
13103 \SpecialChar ~
13104 \SpecialChar ~
13105 \SpecialChar ~
13106 _counter ; does not change flags, no need to save psw
13107 \newline
13108 \SpecialChar ~
13109 \SpecialChar ~
13110 \SpecialChar ~
13111 \SpecialChar ~
13112 reti\SpecialChar ~
13113 \SpecialChar ~
13114 \SpecialChar ~
13115 \SpecialChar ~
13116 \SpecialChar ~
13117 \SpecialChar ~
13118 \SpecialChar ~
13119 \SpecialChar ~
13120 \SpecialChar ~
13121 \SpecialChar ~
13122 \SpecialChar ~
13123 \SpecialChar ~
13124 ; MUST explicitly include ret or reti in _naked function
13125 \layout Standard
13126
13127 The related directive #pragma exclude
13128 \begin_inset LatexCommand \index{\#pragma exclude}
13129
13130 \end_inset
13131
13132  allows a more fine grained control over pushing & popping
13133 \begin_inset LatexCommand \index{push/pop}
13134
13135 \end_inset
13136
13137  the registers.
13138 \layout Standard
13139
13140 While there is nothing preventing you from writing C code inside a
13141 \family typewriter
13142 _naked
13143 \family default
13144  function, there are many ways to shoot yourself in the foot doing this,
13145  and it is recommended that you stick to inline assembler.
13146 \layout Subsection
13147
13148 Use of Labels within Inline Assembler
13149 \layout Standard
13150
13151 SDCC allows the use of in-line assembler with a few restrictions regarding
13152  labels.
13153  In older versions of the compiler all labels defined within inline assembler
13154  code
13155 \emph on
13156 had to be
13157 \emph default
13158  of the form
13159 \emph on
13160 nnnnn$
13161 \emph default
13162  where nnnn is a number less than 100 (which implies a limit of utmost 100
13163  inline assembler labels
13164 \emph on
13165 per function
13166 \emph default
13167 \noun on
13168 )
13169 \noun default
13170 .
13171
13172 \layout Verse
13173
13174
13175 \family typewriter
13176 _asm
13177 \begin_inset LatexCommand \index{\_asm}
13178
13179 \end_inset
13180
13181
13182 \begin_inset LatexCommand \index{\_\_asm}
13183
13184 \end_inset
13185
13186
13187 \newline
13188 \SpecialChar ~
13189 \SpecialChar ~
13190 \SpecialChar ~
13191 \SpecialChar ~
13192 mov\SpecialChar ~
13193 \SpecialChar ~
13194 \SpecialChar ~
13195 \SpecialChar ~
13196 \SpecialChar ~
13197 b,#10
13198 \newline
13199 00001$:
13200 \newline
13201 \SpecialChar ~
13202 \SpecialChar ~
13203 \SpecialChar ~
13204 \SpecialChar ~
13205 djnz\SpecialChar ~
13206 \SpecialChar ~
13207 \SpecialChar ~
13208 \SpecialChar ~
13209 b,00001$
13210 \newline
13211 _endasm
13212 \begin_inset LatexCommand \index{\_endasm}
13213
13214 \end_inset
13215
13216
13217 \begin_inset LatexCommand \index{\_\_endasm}
13218
13219 \end_inset
13220
13221  ;
13222 \layout Standard
13223
13224 Inline assembler code cannot reference any C-Labels, however it can reference
13225  labels
13226 \begin_inset LatexCommand \index{Labels}
13227
13228 \end_inset
13229
13230  defined by the inline assembler, e.g.:
13231 \layout Verse
13232
13233
13234 \family typewriter
13235 foo() {
13236 \newline
13237 \SpecialChar ~
13238 \SpecialChar ~
13239 \SpecialChar ~
13240 \SpecialChar ~
13241 /* some c code */
13242 \newline
13243 \SpecialChar ~
13244 \SpecialChar ~
13245 \SpecialChar ~
13246 \SpecialChar ~
13247 _asm
13248 \newline
13249 \SpecialChar ~
13250 \SpecialChar ~
13251 \SpecialChar ~
13252 \SpecialChar ~
13253 \SpecialChar ~
13254 \SpecialChar ~
13255 ; some assembler code
13256 \newline
13257 \SpecialChar ~
13258 \SpecialChar ~
13259 \SpecialChar ~
13260 \SpecialChar ~
13261 \SpecialChar ~
13262 \SpecialChar ~
13263 ljmp $0003
13264 \newline
13265 \SpecialChar ~
13266 \SpecialChar ~
13267 \SpecialChar ~
13268 \SpecialChar ~
13269 _endasm;
13270 \newline
13271 \SpecialChar ~
13272 \SpecialChar ~
13273 \SpecialChar ~
13274 \SpecialChar ~
13275 /* some more c code */
13276 \newline
13277 clabel:\SpecialChar ~
13278 \SpecialChar ~
13279 /* inline assembler cannot reference this label */
13280 \newline
13281 \SpecialChar ~
13282 \SpecialChar ~
13283 \SpecialChar ~
13284 \SpecialChar ~
13285 _asm
13286 \newline
13287 \SpecialChar ~
13288 \SpecialChar ~
13289 \SpecialChar ~
13290 \SpecialChar ~
13291 $0003: ;label (can be referenced by inline assembler only)
13292 \newline
13293 \SpecialChar ~
13294 \SpecialChar ~
13295 \SpecialChar ~
13296 \SpecialChar ~
13297 _endasm
13298 \begin_inset LatexCommand \index{\_endasm}
13299
13300 \end_inset
13301
13302
13303 \begin_inset LatexCommand \index{\_\_endasm}
13304
13305 \end_inset
13306
13307  ;
13308 \newline
13309 \SpecialChar ~
13310 \SpecialChar ~
13311 \SpecialChar ~
13312 \SpecialChar ~
13313 /* some more c code */
13314 \newline
13315 }
13316 \layout Standard
13317
13318 In other words inline assembly code can access labels defined in inline
13319  assembly within the scope of the function.
13320  The same goes the other way, i.e.
13321  labels defines in inline assembly can not be accessed by C statements.
13322 \layout Section
13323
13324 Interfacing with Assembler Code
13325 \begin_inset LatexCommand \index{Assembler routines}
13326
13327 \end_inset
13328
13329
13330 \layout Subsection
13331
13332 Global Registers used for Parameter Passing
13333 \begin_inset LatexCommand \index{Parameter passing}
13334
13335 \end_inset
13336
13337
13338 \layout Standard
13339
13340 The compiler always uses the global registers
13341 \emph on
13342 DPL, DPH
13343 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13344
13345 \end_inset
13346
13347
13348 \begin_inset LatexCommand \index{DPTR}
13349
13350 \end_inset
13351
13352 , B
13353 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13354
13355 \end_inset
13356
13357
13358 \emph default
13359 and
13360 \emph on
13361  ACC
13362 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13363
13364 \end_inset
13365
13366
13367 \emph default
13368  to pass the first parameter to a routine.
13369  The second parameter onwards is either allocated on the stack (for reentrant
13370  routines or if -
13371 \begin_inset ERT
13372 status Collapsed
13373
13374 \layout Standard
13375
13376 \backslash
13377 /
13378 \end_inset
13379
13380 -stack-auto is used) or in data / xdata memory (depending on the memory
13381  model).
13382
13383 \layout Subsection
13384
13385 Assembler Routine (non-reentrant)
13386 \layout Standard
13387
13388 In the following example
13389 \begin_inset LatexCommand \index{reentrant}
13390
13391 \end_inset
13392
13393
13394 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13395
13396 \end_inset
13397
13398  the function c_func calls an assembler routine asm_func, which takes two
13399  parameters
13400 \begin_inset LatexCommand \index{function parameter}
13401
13402 \end_inset
13403
13404 .
13405 \layout Verse
13406
13407
13408 \family typewriter
13409 extern int asm_func(unsigned char, unsigned char);
13410 \newline
13411
13412 \newline
13413 int c_func (unsigned char i, unsigned char j)
13414 \newline
13415 {
13416 \newline
13417 \SpecialChar ~
13418 \SpecialChar ~
13419 \SpecialChar ~
13420 \SpecialChar ~
13421 return asm_func(i,j);
13422 \newline
13423 }
13424 \newline
13425
13426 \newline
13427 int main()
13428 \newline
13429 {
13430 \newline
13431 \SpecialChar ~
13432 \SpecialChar ~
13433 \SpecialChar ~
13434 \SpecialChar ~
13435 return c_func(10,9);
13436 \newline
13437 }
13438 \layout Standard
13439
13440 The corresponding assembler function is:
13441 \layout Verse
13442
13443
13444 \family typewriter
13445 .globl _asm_func_PARM_2
13446 \newline
13447 \SpecialChar ~
13448 \SpecialChar ~
13449 \SpecialChar ~
13450 \SpecialChar ~
13451 \SpecialChar ~
13452 \SpecialChar ~
13453 \SpecialChar ~
13454 \SpecialChar ~
13455 .globl _asm_func
13456 \newline
13457 \SpecialChar ~
13458 \SpecialChar ~
13459 \SpecialChar ~
13460 \SpecialChar ~
13461 \SpecialChar ~
13462 \SpecialChar ~
13463 \SpecialChar ~
13464 \SpecialChar ~
13465 .area OSEG
13466 \newline
13467 _asm_func_PARM_2:
13468 \newline
13469 \SpecialChar ~
13470 \SpecialChar ~
13471 \SpecialChar ~
13472 \SpecialChar ~
13473 \SpecialChar ~
13474 \SpecialChar ~
13475 \SpecialChar ~
13476 \SpecialChar ~
13477 .ds    1
13478 \newline
13479 \SpecialChar ~
13480 \SpecialChar ~
13481 \SpecialChar ~
13482 \SpecialChar ~
13483 \SpecialChar ~
13484 \SpecialChar ~
13485 \SpecialChar ~
13486 \SpecialChar ~
13487 .area CSEG
13488 \newline
13489 _asm_func:
13490 \newline
13491 \SpecialChar ~
13492 \SpecialChar ~
13493 \SpecialChar ~
13494 \SpecialChar ~
13495 \SpecialChar ~
13496 \SpecialChar ~
13497 \SpecialChar ~
13498 \SpecialChar ~
13499 mov\SpecialChar ~
13500 \SpecialChar ~
13501 \SpecialChar ~
13502 \SpecialChar ~
13503 a,dpl
13504 \newline
13505 \SpecialChar ~
13506 \SpecialChar ~
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 \SpecialChar ~
13510 \SpecialChar ~
13511 \SpecialChar ~
13512 \SpecialChar ~
13513 add\SpecialChar ~
13514 \SpecialChar ~
13515 \SpecialChar ~
13516 \SpecialChar ~
13517 a,_asm_func_PARM_2
13518 \newline
13519 \SpecialChar ~
13520 \SpecialChar ~
13521 \SpecialChar ~
13522 \SpecialChar ~
13523 \SpecialChar ~
13524 \SpecialChar ~
13525 \SpecialChar ~
13526 \SpecialChar ~
13527 mov\SpecialChar ~
13528 \SpecialChar ~
13529 \SpecialChar ~
13530 \SpecialChar ~
13531 dpl,a
13532 \newline
13533 \SpecialChar ~
13534 \SpecialChar ~
13535 \SpecialChar ~
13536 \SpecialChar ~
13537 \SpecialChar ~
13538 \SpecialChar ~
13539 \SpecialChar ~
13540 \SpecialChar ~
13541 mov\SpecialChar ~
13542 \SpecialChar ~
13543 \SpecialChar ~
13544 \SpecialChar ~
13545 dph
13546 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13547
13548 \end_inset
13549
13550 ,#0x00
13551 \newline
13552 \SpecialChar ~
13553 \SpecialChar ~
13554 \SpecialChar ~
13555 \SpecialChar ~
13556 \SpecialChar ~
13557 \SpecialChar ~
13558 \SpecialChar ~
13559 \SpecialChar ~
13560 ret
13561 \layout Standard
13562
13563 Note here that the return values
13564 \begin_inset LatexCommand \index{return value}
13565
13566 \end_inset
13567
13568  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
13569  two byte values.
13570  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
13571 b' & 'acc' for four byte values.
13572 \layout Standard
13573
13574 The parameter naming convention is _<function_name>_PARM_<n>, where n is
13575  the parameter number starting from 1, and counting from the left.
13576  The first parameter is passed in
13577 \begin_inset Quotes eld
13578 \end_inset
13579
13580 dpl
13581 \begin_inset Quotes erd
13582 \end_inset
13583
13584  for a one byte parameter,
13585 \begin_inset Quotes eld
13586 \end_inset
13587
13588 dptr
13589 \begin_inset Quotes erd
13590 \end_inset
13591
13592  for two bytes,
13593 \begin_inset Quotes eld
13594 \end_inset
13595
13596 b,dptr
13597 \begin_inset Quotes erd
13598 \end_inset
13599
13600  for three bytes and
13601 \begin_inset Quotes eld
13602 \end_inset
13603
13604 acc,b,dptr
13605 \begin_inset Quotes erd
13606 \end_inset
13607
13608  for a four bytes parameter.
13609  The variable name for the second parameter will be _<function_name>_PARM_2.
13610 \newline
13611
13612 \newline
13613 Assemble the assembler routine with the following command:
13614 \newline
13615
13616 \newline
13617
13618 \family sans
13619 \series bold
13620 asx8051 -losg asmfunc.asm
13621 \newline
13622
13623 \newline
13624
13625 \family default
13626 \series default
13627 Then compile and link the assembler routine to the C source file with the
13628  following command:
13629 \newline
13630
13631 \newline
13632
13633 \family sans
13634 \series bold
13635 sdcc cfunc.c asmfunc.rel
13636 \layout Subsection
13637
13638 Assembler Routine (reentrant)
13639 \layout Standard
13640
13641 In this case
13642 \begin_inset LatexCommand \index{reentrant}
13643
13644 \end_inset
13645
13646
13647 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
13648
13649 \end_inset
13650
13651  the second parameter
13652 \begin_inset LatexCommand \index{function parameter}
13653
13654 \end_inset
13655
13656  onwards will be passed on the stack, the parameters are pushed from right
13657  to left i.e.
13658  after the call the leftmost parameter will be on the top of the stack.
13659  Here is an example:
13660 \layout Verse
13661
13662
13663 \family typewriter
13664 extern int asm_func(unsigned char, unsigned char);
13665 \newline
13666
13667 \newline
13668 int c_func (unsigned char i, unsigned char j) reentrant
13669 \newline
13670 {
13671 \newline
13672 \SpecialChar ~
13673 \SpecialChar ~
13674 \SpecialChar ~
13675 \SpecialChar ~
13676 return asm_func(i,j);
13677 \newline
13678 }
13679 \newline
13680
13681 \newline
13682 int main()
13683 \newline
13684 {
13685 \newline
13686 \SpecialChar ~
13687 \SpecialChar ~
13688 \SpecialChar ~
13689 \SpecialChar ~
13690 return c_func(10,9);
13691 \newline
13692 }
13693 \layout Standard
13694
13695 The corresponding assembler routine is:
13696 \layout Verse
13697
13698
13699 \family typewriter
13700 .globl _asm_func
13701 \newline
13702 _asm_func:
13703 \newline
13704 \SpecialChar ~
13705 \SpecialChar ~
13706 \SpecialChar ~
13707 \SpecialChar ~
13708 push  _bp
13709 \newline
13710 \SpecialChar ~
13711 \SpecialChar ~
13712 \SpecialChar ~
13713 \SpecialChar ~
13714 mov _bp,sp
13715 \newline
13716 \SpecialChar ~
13717 \SpecialChar ~
13718 \SpecialChar ~
13719 \SpecialChar ~
13720 mov r2,dpl
13721 \newline
13722 \SpecialChar ~
13723 \SpecialChar ~
13724 \SpecialChar ~
13725 \SpecialChar ~
13726 mov a,_bp
13727 \newline
13728 \SpecialChar ~
13729 \SpecialChar ~
13730 \SpecialChar ~
13731 \SpecialChar ~
13732 add a,#0xfd
13733 \newline
13734 \SpecialChar ~
13735 \SpecialChar ~
13736 \SpecialChar ~
13737 \SpecialChar ~
13738 mov r0,a
13739 \newline
13740 \SpecialChar ~
13741 \SpecialChar ~
13742 \SpecialChar ~
13743 \SpecialChar ~
13744 add  a,#0xfc ;?
13745 \newline
13746 \SpecialChar ~
13747 \SpecialChar ~
13748 \SpecialChar ~
13749 \SpecialChar ~
13750 mov  r1,a
13751 \newline
13752 \SpecialChar ~
13753 \SpecialChar ~
13754 \SpecialChar ~
13755 \SpecialChar ~
13756 mov  a,@r0
13757 \newline
13758 \SpecialChar ~
13759 \SpecialChar ~
13760 \SpecialChar ~
13761 \SpecialChar ~
13762 add  a,r2 ;?
13763 \newline
13764 \SpecialChar ~
13765 \SpecialChar ~
13766 \SpecialChar ~
13767 \SpecialChar ~
13768 mov  dpl,a
13769 \newline
13770 \SpecialChar ~
13771 \SpecialChar ~
13772 \SpecialChar ~
13773 \SpecialChar ~
13774 mov  dph,#0x00
13775 \newline
13776 \SpecialChar ~
13777 \SpecialChar ~
13778 \SpecialChar ~
13779 \SpecialChar ~
13780 mov  sp,_bp
13781 \newline
13782 \SpecialChar ~
13783 \SpecialChar ~
13784 \SpecialChar ~
13785 \SpecialChar ~
13786 pop  _bp
13787 \newline
13788 \SpecialChar ~
13789 \SpecialChar ~
13790 \SpecialChar ~
13791 \SpecialChar ~
13792 ret
13793 \layout Standard
13794
13795 The compiling and linking procedure remains the same, however note the extra
13796  entry & exit linkage required for the assembler code, _bp is the stack
13797  frame pointer and is used to compute the offset into the stack for parameters
13798  and local variables.
13799 \layout Section
13800
13801 int (16 bit)
13802 \begin_inset LatexCommand \index{int (16 bit)}
13803
13804 \end_inset
13805
13806  and long (32 bit)
13807 \begin_inset LatexCommand \index{long (32 bit)}
13808
13809 \end_inset
13810
13811  Support
13812 \layout Standard
13813
13814 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
13815  multiplication and modulus operations are implemented by support routines.
13816  These support routines are all developed in ANSI-C to facilitate porting
13817  to other MCUs, although some model specific assembler optimizations are
13818  used.
13819  The following files contain the described routines, all of them can be
13820  found in <installdir>/share/sdcc/lib.
13821 \newline
13822
13823 \layout Standard
13824 \align center
13825
13826 \begin_inset  Tabular
13827 <lyxtabular version="3" rows="11" columns="2">
13828 <features>
13829 <column alignment="center" valignment="top" leftline="true" width="0">
13830 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13831 <row topline="true" bottomline="true">
13832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13833 \begin_inset Text
13834
13835 \layout Standard
13836
13837
13838 \series bold
13839 Function
13840 \end_inset
13841 </cell>
13842 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13843 \begin_inset Text
13844
13845 \layout Standard
13846
13847
13848 \series bold
13849 Description
13850 \end_inset
13851 </cell>
13852 </row>
13853 <row topline="true">
13854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13855 \begin_inset Text
13856
13857 \layout Standard
13858
13859 _mulint.c
13860 \end_inset
13861 </cell>
13862 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13863 \begin_inset Text
13864
13865 \layout Standard
13866
13867 16 bit multiplication
13868 \end_inset
13869 </cell>
13870 </row>
13871 <row topline="true">
13872 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13873 \begin_inset Text
13874
13875 \layout Standard
13876
13877 _divsint.c
13878 \end_inset
13879 </cell>
13880 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13881 \begin_inset Text
13882
13883 \layout Standard
13884
13885  signed 16 bit division (calls _divuint)
13886 \end_inset
13887 </cell>
13888 </row>
13889 <row topline="true">
13890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13891 \begin_inset Text
13892
13893 \layout Standard
13894
13895 _divuint.c
13896 \end_inset
13897 </cell>
13898 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13899 \begin_inset Text
13900
13901 \layout Standard
13902
13903  unsigned 16 bit division
13904 \end_inset
13905 </cell>
13906 </row>
13907 <row topline="true">
13908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13909 \begin_inset Text
13910
13911 \layout Standard
13912
13913 _modsint.c
13914 \end_inset
13915 </cell>
13916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13917 \begin_inset Text
13918
13919 \layout Standard
13920
13921 signed 16 bit modulus (calls _moduint)
13922 \end_inset
13923 </cell>
13924 </row>
13925 <row topline="true">
13926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13927 \begin_inset Text
13928
13929 \layout Standard
13930
13931 _moduint.c
13932 \end_inset
13933 </cell>
13934 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13935 \begin_inset Text
13936
13937 \layout Standard
13938
13939 unsigned 16 bit modulus
13940 \end_inset
13941 </cell>
13942 </row>
13943 <row topline="true">
13944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13945 \begin_inset Text
13946
13947 \layout Standard
13948
13949 _mullong.c
13950 \end_inset
13951 </cell>
13952 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13953 \begin_inset Text
13954
13955 \layout Standard
13956
13957 32 bit multiplication
13958 \end_inset
13959 </cell>
13960 </row>
13961 <row topline="true">
13962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13963 \begin_inset Text
13964
13965 \layout Standard
13966
13967 _divslong.c
13968 \end_inset
13969 </cell>
13970 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13971 \begin_inset Text
13972
13973 \layout Standard
13974
13975  signed 32 division (calls _divulong)
13976 \end_inset
13977 </cell>
13978 </row>
13979 <row topline="true">
13980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13981 \begin_inset Text
13982
13983 \layout Standard
13984
13985 _divulong.c
13986 \end_inset
13987 </cell>
13988 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13989 \begin_inset Text
13990
13991 \layout Standard
13992
13993 unsigned 32 division
13994 \end_inset
13995 </cell>
13996 </row>
13997 <row topline="true">
13998 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13999 \begin_inset Text
14000
14001 \layout Standard
14002
14003 _modslong.c
14004 \end_inset
14005 </cell>
14006 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14007 \begin_inset Text
14008
14009 \layout Standard
14010
14011  signed 32 bit modulus (calls _modulong)
14012 \end_inset
14013 </cell>
14014 </row>
14015 <row topline="true" bottomline="true">
14016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14017 \begin_inset Text
14018
14019 \layout Standard
14020
14021 _modulong.c
14022 \end_inset
14023 </cell>
14024 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14025 \begin_inset Text
14026
14027 \layout Standard
14028
14029 unsigned 32 bit modulus
14030 \end_inset
14031 </cell>
14032 </row>
14033 </lyxtabular>
14034
14035 \end_inset
14036
14037
14038 \newline
14039
14040 \layout Standard
14041
14042 Since they are compiled as
14043 \emph on
14044 non-reentrant
14045 \emph default
14046
14047 \begin_inset LatexCommand \index{reentrant}
14048
14049 \end_inset
14050
14051 , interrupt
14052 \begin_inset LatexCommand \index{interrupt}
14053
14054 \end_inset
14055
14056  service routines should not do any of the above operations.
14057  If this is unavoidable then the above routines will need to be compiled
14058  with the
14059 \emph on
14060 -
14061 \begin_inset ERT
14062 status Collapsed
14063
14064 \layout Standard
14065
14066 \backslash
14067 /
14068 \end_inset
14069
14070 -stack-auto
14071 \begin_inset LatexCommand \index{-\/-stack-auto}
14072
14073 \end_inset
14074
14075
14076 \emph default
14077  option, after which the source program will have to be compiled with
14078 \emph on
14079 -
14080 \begin_inset ERT
14081 status Collapsed
14082
14083 \layout Standard
14084
14085 \backslash
14086 /
14087 \end_inset
14088
14089 -int-long-reent
14090 \begin_inset LatexCommand \index{-\/-int-long-reent}
14091
14092 \end_inset
14093
14094
14095 \emph default
14096  option.
14097  Notice that you don't have to call these routines directly.
14098  The compiler will use them automatically every time an integer operation
14099  is required.
14100 \layout Section
14101
14102 Floating Point Support
14103 \begin_inset LatexCommand \index{Floating point support}
14104
14105 \end_inset
14106
14107
14108 \layout Standard
14109
14110 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
14111  floating point support routines are derived from gcc's floatlib.c and consist
14112  of the following routines:
14113 \newline
14114
14115 \layout Standard
14116 \align center
14117
14118 \size footnotesize
14119
14120 \begin_inset  Tabular
14121 <lyxtabular version="3" rows="17" columns="2">
14122 <features>
14123 <column alignment="center" valignment="top" leftline="true" width="0">
14124 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
14125 <row topline="true" bottomline="true">
14126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14127 \begin_inset Text
14128
14129 \layout Standard
14130
14131
14132 \family roman
14133 \series medium
14134 \shape up
14135 \size normal
14136 \emph off
14137 \bar no
14138 \noun off
14139 \color none
14140 Function
14141 \end_inset
14142 </cell>
14143 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14144 \begin_inset Text
14145
14146 \layout Standard
14147
14148 Description
14149 \end_inset
14150 </cell>
14151 </row>
14152 <row topline="true">
14153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14154 \begin_inset Text
14155
14156 \layout Standard
14157
14158
14159 \family roman
14160 \series medium
14161 \shape up
14162 \size normal
14163 \emph off
14164 \bar no
14165 \noun off
14166 \color none
14167 _fsadd.c
14168 \end_inset
14169 </cell>
14170 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14171 \begin_inset Text
14172
14173 \layout Standard
14174
14175
14176 \family roman
14177 \series medium
14178 \shape up
14179 \size normal
14180 \emph off
14181 \bar no
14182 \noun off
14183 \color none
14184 add floating point numbers
14185 \end_inset
14186 </cell>
14187 </row>
14188 <row topline="true">
14189 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14190 \begin_inset Text
14191
14192 \layout Standard
14193
14194
14195 \family roman
14196 \series medium
14197 \shape up
14198 \size normal
14199 \emph off
14200 \bar no
14201 \noun off
14202 \color none
14203 _fssub.c
14204 \end_inset
14205 </cell>
14206 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14207 \begin_inset Text
14208
14209 \layout Standard
14210
14211
14212 \family roman
14213 \series medium
14214 \shape up
14215 \size normal
14216 \emph off
14217 \bar no
14218 \noun off
14219 \color none
14220 subtract floating point numbers
14221 \end_inset
14222 </cell>
14223 </row>
14224 <row topline="true">
14225 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14226 \begin_inset Text
14227
14228 \layout Standard
14229
14230
14231 \family roman
14232 \series medium
14233 \shape up
14234 \size normal
14235 \emph off
14236 \bar no
14237 \noun off
14238 \color none
14239 _fsdiv.c
14240 \end_inset
14241 </cell>
14242 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14243 \begin_inset Text
14244
14245 \layout Standard
14246
14247
14248 \family roman
14249 \series medium
14250 \shape up
14251 \size normal
14252 \emph off
14253 \bar no
14254 \noun off
14255 \color none
14256 divide floating point numbers
14257 \end_inset
14258 </cell>
14259 </row>
14260 <row topline="true">
14261 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14262 \begin_inset Text
14263
14264 \layout Standard
14265
14266
14267 \family roman
14268 \series medium
14269 \shape up
14270 \size normal
14271 \emph off
14272 \bar no
14273 \noun off
14274 \color none
14275 _fsmul.c
14276 \end_inset
14277 </cell>
14278 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14279 \begin_inset Text
14280
14281 \layout Standard
14282
14283
14284 \family roman
14285 \series medium
14286 \shape up
14287 \size normal
14288 \emph off
14289 \bar no
14290 \noun off
14291 \color none
14292 multiply floating point numbers
14293 \end_inset
14294 </cell>
14295 </row>
14296 <row topline="true">
14297 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14298 \begin_inset Text
14299
14300 \layout Standard
14301
14302
14303 \family roman
14304 \series medium
14305 \shape up
14306 \size normal
14307 \emph off
14308 \bar no
14309 \noun off
14310 \color none
14311 _fs2uchar.c
14312 \end_inset
14313 </cell>
14314 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14315 \begin_inset Text
14316
14317 \layout Standard
14318
14319
14320 \family roman
14321 \series medium
14322 \shape up
14323 \size normal
14324 \emph off
14325 \bar no
14326 \noun off
14327 \color none
14328 convert floating point to unsigned char
14329 \end_inset
14330 </cell>
14331 </row>
14332 <row topline="true">
14333 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14334 \begin_inset Text
14335
14336 \layout Standard
14337
14338
14339 \family roman
14340 \series medium
14341 \shape up
14342 \size normal
14343 \emph off
14344 \bar no
14345 \noun off
14346 \color none
14347 _fs2char.c
14348 \end_inset
14349 </cell>
14350 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14351 \begin_inset Text
14352
14353 \layout Standard
14354
14355
14356 \family roman
14357 \series medium
14358 \shape up
14359 \size normal
14360 \emph off
14361 \bar no
14362 \noun off
14363 \color none
14364 convert floating point to signed char
14365 \end_inset
14366 </cell>
14367 </row>
14368 <row topline="true">
14369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14370 \begin_inset Text
14371
14372 \layout Standard
14373
14374
14375 \family roman
14376 \series medium
14377 \shape up
14378 \size normal
14379 \emph off
14380 \bar no
14381 \noun off
14382 \color none
14383 _fs2uint.c
14384 \end_inset
14385 </cell>
14386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14387 \begin_inset Text
14388
14389 \layout Standard
14390
14391
14392 \family roman
14393 \series medium
14394 \shape up
14395 \size normal
14396 \emph off
14397 \bar no
14398 \noun off
14399 \color none
14400 convert floating point to unsigned int
14401 \end_inset
14402 </cell>
14403 </row>
14404 <row topline="true">
14405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14406 \begin_inset Text
14407
14408 \layout Standard
14409
14410
14411 \family roman
14412 \series medium
14413 \shape up
14414 \size normal
14415 \emph off
14416 \bar no
14417 \noun off
14418 \color none
14419 _fs2int.c
14420 \end_inset
14421 </cell>
14422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14423 \begin_inset Text
14424
14425 \layout Standard
14426
14427
14428 \family roman
14429 \series medium
14430 \shape up
14431 \size normal
14432 \emph off
14433 \bar no
14434 \noun off
14435 \color none
14436 convert floating point to signed int
14437 \end_inset
14438 </cell>
14439 </row>
14440 <row topline="true">
14441 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14442 \begin_inset Text
14443
14444 \layout Standard
14445
14446
14447 \family roman
14448 \series medium
14449 \shape up
14450 \size normal
14451 \emph off
14452 \bar no
14453 \noun off
14454 \color none
14455 _fs2ulong.
14456 \family default
14457 \series default
14458 \shape default
14459 \size default
14460 \emph default
14461 \bar default
14462 \noun default
14463 \color default
14464 c
14465 \end_inset
14466 </cell>
14467 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14468 \begin_inset Text
14469
14470 \layout Standard
14471
14472
14473 \family roman
14474 \series medium
14475 \shape up
14476 \size normal
14477 \emph off
14478 \bar no
14479 \noun off
14480 \color none
14481 convert floating point to unsigned long
14482 \end_inset
14483 </cell>
14484 </row>
14485 <row topline="true">
14486 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14487 \begin_inset Text
14488
14489 \layout Standard
14490
14491
14492 \family roman
14493 \series medium
14494 \shape up
14495 \size normal
14496 \emph off
14497 \bar no
14498 \noun off
14499 \color none
14500 _fs2long.c
14501 \end_inset
14502 </cell>
14503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14504 \begin_inset Text
14505
14506 \layout Standard
14507
14508
14509 \family roman
14510 \series medium
14511 \shape up
14512 \size normal
14513 \emph off
14514 \bar no
14515 \noun off
14516 \color none
14517 convert floating point to signed long
14518 \end_inset
14519 </cell>
14520 </row>
14521 <row topline="true">
14522 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14523 \begin_inset Text
14524
14525 \layout Standard
14526
14527
14528 \family roman
14529 \series medium
14530 \shape up
14531 \size normal
14532 \emph off
14533 \bar no
14534 \noun off
14535 \color none
14536 _uchar2fs.c
14537 \end_inset
14538 </cell>
14539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14540 \begin_inset Text
14541
14542 \layout Standard
14543
14544
14545 \family roman
14546 \series medium
14547 \shape up
14548 \size normal
14549 \emph off
14550 \bar no
14551 \noun off
14552 \color none
14553 convert unsigned char to floating point
14554 \end_inset
14555 </cell>
14556 </row>
14557 <row topline="true">
14558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14559 \begin_inset Text
14560
14561 \layout Standard
14562
14563
14564 \family roman
14565 \series medium
14566 \shape up
14567 \size normal
14568 \emph off
14569 \bar no
14570 \noun off
14571 \color none
14572 _char2fs.c
14573 \end_inset
14574 </cell>
14575 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14576 \begin_inset Text
14577
14578 \layout Standard
14579
14580
14581 \family roman
14582 \series medium
14583 \shape up
14584 \size normal
14585 \emph off
14586 \bar no
14587 \noun off
14588 \color none
14589 convert char to floating point number
14590 \end_inset
14591 </cell>
14592 </row>
14593 <row topline="true">
14594 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14595 \begin_inset Text
14596
14597 \layout Standard
14598
14599
14600 \family roman
14601 \series medium
14602 \shape up
14603 \size normal
14604 \emph off
14605 \bar no
14606 \noun off
14607 \color none
14608 _uint2fs.c
14609 \end_inset
14610 </cell>
14611 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14612 \begin_inset Text
14613
14614 \layout Standard
14615
14616
14617 \family roman
14618 \series medium
14619 \shape up
14620 \size normal
14621 \emph off
14622 \bar no
14623 \noun off
14624 \color none
14625 convert unsigned int to floating point
14626 \end_inset
14627 </cell>
14628 </row>
14629 <row topline="true">
14630 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14631 \begin_inset Text
14632
14633 \layout Standard
14634
14635
14636 \family roman
14637 \series medium
14638 \shape up
14639 \size normal
14640 \emph off
14641 \bar no
14642 \noun off
14643 \color none
14644 _int2fs.c
14645 \end_inset
14646 </cell>
14647 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14648 \begin_inset Text
14649
14650 \layout Standard
14651
14652
14653 \family roman
14654 \series medium
14655 \shape up
14656 \size normal
14657 \emph off
14658 \bar no
14659 \noun off
14660 \color none
14661 convert int to floating point numbers
14662 \end_inset
14663 </cell>
14664 </row>
14665 <row topline="true">
14666 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14667 \begin_inset Text
14668
14669 \layout Standard
14670
14671
14672 \family roman
14673 \series medium
14674 \shape up
14675 \size normal
14676 \emph off
14677 \bar no
14678 \noun off
14679 \color none
14680 _ulong2fs.c
14681 \end_inset
14682 </cell>
14683 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14684 \begin_inset Text
14685
14686 \layout Standard
14687
14688
14689 \family roman
14690 \series medium
14691 \shape up
14692 \size normal
14693 \emph off
14694 \bar no
14695 \noun off
14696 \color none
14697 convert unsigned long to floating point number
14698 \end_inset
14699 </cell>
14700 </row>
14701 <row topline="true" bottomline="true">
14702 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14703 \begin_inset Text
14704
14705 \layout Standard
14706
14707
14708 \family roman
14709 \series medium
14710 \shape up
14711 \size normal
14712 \emph off
14713 \bar no
14714 \noun off
14715 \color none
14716 _long2fs.c
14717 \end_inset
14718 </cell>
14719 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14720 \begin_inset Text
14721
14722 \layout Standard
14723
14724
14725 \family roman
14726 \series medium
14727 \shape up
14728 \size normal
14729 \emph off
14730 \bar no
14731 \noun off
14732 \color none
14733 convert long to floating point number
14734 \end_inset
14735 </cell>
14736 </row>
14737 </lyxtabular>
14738
14739 \end_inset
14740
14741
14742 \newline
14743
14744 \layout Standard
14745
14746 These support routines are developed in ANSI-C so there is room for space
14747  and speed improvement
14748 \begin_inset Foot
14749 collapsed false
14750
14751 \layout Standard
14752
14753 The floating point routines for the mcs51 are implemented in assembler
14754 \end_inset
14755
14756 .
14757  Note if all these routines are used simultaneously the data space might
14758  overflow.
14759  For serious floating point usage the large model might be needed.
14760  Also notice that you don't have to call this routines directly.
14761  The compiler will use them automatically every time a floating point operation
14762  is required.
14763 \layout Section
14764
14765 Library Routines
14766 \begin_inset LatexCommand \index{Libraries}
14767
14768 \end_inset
14769
14770
14771 \layout Standard
14772
14773
14774 \emph on
14775 <pending: this is messy and incomplete - a little more information is in
14776  sdcc/doc/libdoc.txt
14777 \emph default
14778  >
14779 \layout Subsection
14780
14781 Compiler support routines (_gptrget, _mulint etc.)
14782 \layout Subsection
14783
14784 Stdclib functions (puts, printf, strcat etc.)
14785 \layout Subsubsection
14786
14787 <stdio.h>
14788 \layout Standard
14789
14790
14791 \begin_inset LatexCommand \index{<stdio.h>}
14792
14793 \end_inset
14794
14795 As usual on embedded systems you have to provide your own
14796 \family typewriter
14797 getchar()
14798 \begin_inset LatexCommand \index{getchar()}
14799
14800 \end_inset
14801
14802
14803 \family default
14804 and
14805 \family typewriter
14806 putchar()
14807 \begin_inset LatexCommand \index{putchar()}
14808
14809 \end_inset
14810
14811
14812 \family default
14813  routines.
14814  SDCC does not know whether the system connects to a serial line with or
14815  without handshake, LCD, keyboard or other device.
14816  You'll find examples for serial routines f.e.
14817  in sdcc/device/lib.
14818 \layout Standard
14819
14820 The default
14821 \family typewriter
14822  printf()
14823 \begin_inset LatexCommand \index{printf()}
14824
14825 \end_inset
14826
14827
14828 \family default
14829 implementation in
14830 \family typewriter
14831  printf_large.c
14832 \family default
14833  does not support float (except on ds390).
14834  To enable this recompile it with the option
14835 \emph on
14836 -
14837 \begin_inset ERT
14838 status Collapsed
14839
14840 \layout Standard
14841
14842 \backslash
14843 /
14844 \end_inset
14845
14846 DUSE_FLOATS=1
14847 \begin_inset LatexCommand \index{USE\_FLOATS}
14848
14849 \end_inset
14850
14851
14852 \emph default
14853  on the command line.
14854  Use
14855 \emph on
14856 -
14857 \begin_inset ERT
14858 status Collapsed
14859
14860 \layout Standard
14861
14862 \backslash
14863 /
14864 \end_inset
14865
14866 -model-large
14867 \begin_inset LatexCommand \index{-\/-model-large}
14868
14869 \end_inset
14870
14871
14872 \emph default
14873  for the mcs51 port, since this uses a lot of memory.
14874 \layout Standard
14875
14876 If you're short on memory you might want to use
14877 \family typewriter
14878 printf_small()
14879 \begin_inset LatexCommand \index{printf\_small()}
14880
14881 \end_inset
14882
14883
14884 \family default
14885
14886 \emph on
14887 instead
14888 \emph default
14889  of
14890 \family typewriter
14891  printf().
14892
14893 \family default
14894  For the mcs51 there additionally are assembly versions
14895 \family typewriter
14896 printf_tiny()
14897 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
14898
14899 \end_inset
14900
14901
14902 \family default
14903  and
14904 \family typewriter
14905 printf_fast()
14906 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
14907
14908 \end_inset
14909
14910
14911 \family default
14912 and
14913 \family typewriter
14914  printf_fast_f()
14915 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
14916
14917 \end_inset
14918
14919
14920 \family default
14921  which should fit the requirements of many embedded systems (printf_fast()
14922  can be customized by unsetting #defines to
14923 \emph on
14924 not
14925 \emph default
14926  support long variables and field widths).
14927 \layout Subsection
14928
14929 Math functions (sin, pow, sqrt etc.)
14930 \layout Subsection
14931
14932 Other libraries
14933 \layout Standard
14934
14935 Libraries
14936 \begin_inset LatexCommand \index{Libraries}
14937
14938 \end_inset
14939
14940  included in SDCC should have a license at least as liberal as the GNU Lesser
14941  General Public License
14942 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14943
14944 \end_inset
14945
14946
14947 \emph on
14948 LGPL
14949 \emph default
14950 .
14951 \layout Comment
14952
14953 license statements for the libraries are missing.
14954  sdcc/device/lib/ser_ir.c
14955 \layout Comment
14956
14957 or _decdptr f.e.
14958  come with a GPL (as opposed to LGPL) License - this will not be liberal
14959  enough for many embedded programmers.
14960 \layout Standard
14961
14962 If you have ported some library or want to share experience about some code
14963  which f.e.
14964  falls into any of these categories Busses (I
14965 \begin_inset Formula $^{\textrm{2}}$
14966 \end_inset
14967
14968 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14969  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14970  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14971 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14972
14973 \end_inset
14974
14975 \SpecialChar ~
14976 would certainly like to hear about it.
14977  Programmers coding for embedded systems are not especially famous for being
14978  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14979 e these references are very valuable.
14980  Let's help to create a climate where information is shared.
14981 \layout Section
14982
14983 Memory Models
14984 \layout Subsection
14985
14986 MCS51 Memory Models
14987 \begin_inset LatexCommand \index{Memory model}
14988
14989 \end_inset
14990
14991
14992 \begin_inset LatexCommand \index{MCS51 memory model}
14993
14994 \end_inset
14995
14996
14997 \layout Subsubsection
14998
14999 Small, Medium and Large
15000 \layout Standard
15001
15002 SDCC allows three memory models for MCS51 code,
15003 \shape slanted
15004 small, medium
15005 \shape default
15006  and
15007 \shape slanted
15008 large
15009 \shape default
15010 .
15011  Modules compiled with different memory models should
15012 \emph on
15013 never
15014 \emph default
15015  be combined together or the results would be unpredictable.
15016  The library routines supplied with the compiler are compiled as small,
15017  medium and large.
15018  The compiled library modules are contained in separate directories as small,
15019  medium and large so that you can link to the appropriate set.
15020 \layout Standard
15021
15022 When the medium or large model is used all variables declared without a
15023  storage class will be allocated into the external ram, this includes all
15024  parameters and local variables (for non-reentrant
15025 \begin_inset LatexCommand \index{reentrant}
15026
15027 \end_inset
15028
15029  functions).
15030  When the small model is used variables without storage class are allocated
15031  in the internal ram.
15032 \layout Standard
15033
15034 Judicious usage of the processor specific storage classes
15035 \begin_inset LatexCommand \index{Storage class}
15036
15037 \end_inset
15038
15039  and the 'reentrant' function type will yield much more efficient code,
15040  than using the large model.
15041  Several optimizations are disabled when the program is compiled using the
15042  large model, it is therefore recommended that the small model be used unless
15043  absolutely required.
15044 \layout Subsubsection
15045
15046 External Stack
15047 \begin_inset LatexCommand \label{sub:External-Stack}
15048
15049 \end_inset
15050
15051
15052 \begin_inset LatexCommand \index{stack}
15053
15054 \end_inset
15055
15056
15057 \begin_inset LatexCommand \index{External stack (mcs51)}
15058
15059 \end_inset
15060
15061
15062 \layout Standard
15063
15064 The external stack (-
15065 \begin_inset ERT
15066 status Collapsed
15067
15068 \layout Standard
15069
15070 \backslash
15071 /
15072 \end_inset
15073
15074 -xstack option
15075 \begin_inset LatexCommand \index{-\/-xstack}
15076
15077 \end_inset
15078
15079 ) is located in pdata
15080 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15081
15082 \end_inset
15083
15084  memory (usually at the start of the external ram segment) and uses all
15085  unused space in pdata (max.
15086  256 bytes).
15087  When -
15088 \begin_inset ERT
15089 status Collapsed
15090
15091 \layout Standard
15092
15093 \backslash
15094 /
15095 \end_inset
15096
15097 -xstack option is used to compile the program, the parameters and local
15098  variables
15099 \begin_inset LatexCommand \index{local variables}
15100
15101 \end_inset
15102
15103  of all reentrant functions are allocated in this area.
15104  This option is provided for programs with large stack space requirements.
15105  When used with the -
15106 \begin_inset ERT
15107 status Collapsed
15108
15109 \layout Standard
15110
15111 \backslash
15112 /
15113 \end_inset
15114
15115 -stack-auto
15116 \begin_inset LatexCommand \index{-\/-stack-auto}
15117
15118 \end_inset
15119
15120  option, all parameters and local variables are allocated on the external
15121  stack (note: support libraries will need to be recompiled with the same
15122  options.
15123  There is a predefined target in the library makefile).
15124 \layout Standard
15125
15126 The compiler outputs the higher order address byte of the external ram segment
15127  into port P2
15128 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15129
15130 \end_inset
15131
15132  (see also section
15133 \begin_inset LatexCommand \ref{sub:MCS51-variants}
15134
15135 \end_inset
15136
15137 ), therefore when using the External Stack option, this port
15138 \emph on
15139 may not
15140 \emph default
15141  be used by the application program.
15142 \layout Subsection
15143
15144 DS390 Memory Model
15145 \begin_inset LatexCommand \index{Memory model}
15146
15147 \end_inset
15148
15149
15150 \begin_inset LatexCommand \index{DS390 memory model}
15151
15152 \end_inset
15153
15154
15155 \layout Standard
15156
15157 The only model supported is Flat 24
15158 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
15159
15160 \end_inset
15161
15162 .
15163  This generates code for the 24 bit contiguous addressing mode of the Dallas
15164  DS80C390 part.
15165  In this mode, up to four meg of external RAM or code space can be directly
15166  addressed.
15167  See the data sheets at www.dalsemi.com for further information on this part.
15168 \newline
15169
15170 \newline
15171 Note that the compiler does not generate any code to place the processor
15172  into 24 bitmode (although
15173 \emph on
15174 tinibios
15175 \emph default
15176  in the ds390 libraries will do that for you).
15177  If you don't use
15178 \emph on
15179 tinibios
15180 \emph default
15181
15182 \begin_inset LatexCommand \index{Tinibios (DS390)}
15183
15184 \end_inset
15185
15186 , the boot loader or similar code must ensure that the processor is in 24
15187  bit contiguous addressing mode before calling the SDCC startup code.
15188 \newline
15189
15190 \newline
15191 Like the
15192 \emph on
15193 -
15194 \begin_inset ERT
15195 status Collapsed
15196
15197 \layout Standard
15198
15199 \backslash
15200 /
15201 \end_inset
15202
15203 -model-large
15204 \emph default
15205  option, variables will by default be placed into the XDATA segment.
15206
15207 \newline
15208
15209 \newline
15210 Segments may be placed anywhere in the 4 meg address space using the usual
15211  -
15212 \begin_inset ERT
15213 status Collapsed
15214
15215 \layout Standard
15216
15217 \backslash
15218 /
15219 \end_inset
15220
15221 -*-loc options.
15222  Note that if any segments are located above 64K, the -r flag must be passed
15223  to the linker to generate the proper segment relocations, and the Intel
15224  HEX output format must be used.
15225  The -r flag can be passed to the linker by using the option
15226 \emph on
15227 -Wl-r
15228 \emph default
15229  on the SDCC command line.
15230  However, currently the linker can not handle code segments > 64k.
15231 \layout Section
15232
15233 Pragmas
15234 \begin_inset LatexCommand \index{Pragmas}
15235
15236 \end_inset
15237
15238
15239 \layout Standard
15240
15241 SDCC supports the following #pragma directives:
15242 \layout Itemize
15243
15244 save
15245 \begin_inset LatexCommand \index{\#pragma save}
15246
15247 \end_inset
15248
15249  - this will save all current options to the save/restore stack.
15250  See #pragma\SpecialChar ~
15251 restore.
15252 \layout Itemize
15253
15254 restore
15255 \begin_inset LatexCommand \index{\#pragma restore}
15256
15257 \end_inset
15258
15259  - will restore saved options from the last save.
15260  saves & restores can be nested.
15261  SDCC uses a save/restore stack: save pushes current options to the stack,
15262  restore pulls current options from the stack.
15263  See #pragma\SpecialChar ~
15264 save.
15265 \newline
15266
15267 \layout Itemize
15268
15269 callee_saves
15270 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15271
15272 \end_inset
15273
15274
15275 \begin_inset LatexCommand \index{function prologue}
15276
15277 \end_inset
15278
15279  function1[,function2[,function3...]] - The compiler by default uses a caller
15280  saves convention for register saving across function calls, however this
15281  can cause unnecessary register pushing & popping
15282 \begin_inset LatexCommand \index{push/pop}
15283
15284 \end_inset
15285
15286  when calling small functions from larger functions.
15287  This option can be used to switch off the register saving convention for
15288  the function names specified.
15289  The compiler will not save registers when calling these functions, extra
15290  code need to be manually inserted at the entry & exit for these functions
15291  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15292  reduce code & improve run time performance of the generated code.
15293  In the future the compiler (with inter procedural analysis) may be able
15294  to determine the appropriate scheme to use for each function call.
15295  If -
15296 \begin_inset ERT
15297 status Collapsed
15298
15299 \layout Standard
15300
15301 \backslash
15302 /
15303 \end_inset
15304
15305 -callee-saves command line option is used, the function names specified
15306  in #pragma\SpecialChar ~
15307 callee_saves
15308 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15309
15310 \end_inset
15311
15312  is appended to the list of functions specified in the command line.
15313 \layout Itemize
15314
15315 exclude
15316 \begin_inset LatexCommand \index{\#pragma exclude}
15317
15318 \end_inset
15319
15320  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15321  of pairs of push/pop
15322 \begin_inset LatexCommand \index{push/pop}
15323
15324 \end_inset
15325
15326  instructions in
15327 \emph on
15328 I
15329 \emph default
15330 nterrupt
15331 \begin_inset LatexCommand \index{interrupt}
15332
15333 \end_inset
15334
15335
15336 \emph on
15337 S
15338 \emph default
15339 ervice
15340 \emph on
15341 R
15342 \emph default
15343 outines.
15344  The directive should be placed immediately before the ISR function definition
15345  and it affects ALL ISR functions following it.
15346  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15347 exclude\SpecialChar ~
15348 none
15349 \begin_inset LatexCommand \index{\#pragma exclude}
15350
15351 \end_inset
15352
15353 .
15354  See also the related keyword _naked
15355 \begin_inset LatexCommand \index{\_naked}
15356
15357 \end_inset
15358
15359
15360 \begin_inset LatexCommand \index{\_\_naked}
15361
15362 \end_inset
15363
15364 .
15365 \layout Itemize
15366
15367 less_pedantic
15368 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15369
15370 \end_inset
15371
15372  - the compiler will not warn you anymore for obvious mistakes, you'r on
15373  your own now ;-(
15374 \layout Itemize
15375
15376 disable_warning <nnnn>
15377 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15378
15379 \end_inset
15380
15381  - the compiler will not warn you anymore about warning number <nnnn>.
15382 \layout Itemize
15383
15384 nogcse
15385 \begin_inset LatexCommand \index{\#pragma nogcse}
15386
15387 \end_inset
15388
15389  - will stop global common subexpression elimination.
15390 \layout Itemize
15391
15392 noinduction
15393 \begin_inset LatexCommand \index{\#pragma noinduction}
15394
15395 \end_inset
15396
15397  - will stop loop induction optimizations.
15398 \layout Itemize
15399
15400 noinvariant
15401 \begin_inset LatexCommand \index{\#pragma noinvariant}
15402
15403 \end_inset
15404
15405  - will not do loop invariant optimizations.
15406  For more details see Loop Invariants in section
15407 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15408
15409 \end_inset
15410
15411 .
15412 \layout Itemize
15413
15414 noiv
15415 \begin_inset LatexCommand \index{\#pragma noiv}
15416
15417 \end_inset
15418
15419  - Do not generate interrupt
15420 \begin_inset LatexCommand \index{interrupt}
15421
15422 \end_inset
15423
15424  vector table entries for all ISR functions defined after the pragma.
15425  This is useful in cases where the interrupt vector table must be defined
15426  manually, or when there is a secondary, manually defined interrupt vector
15427  table (e.g.
15428  for the autovector feature of the Cypress EZ-USB FX2).
15429  More elegantly this can be achieved by obmitting the optional interrupt
15430  number after the interrupt keyword, see section
15431 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15432
15433 \end_inset
15434
15435 \SpecialChar ~
15436 about interrupts.
15437 \layout Itemize
15438
15439 nojtbound
15440 \begin_inset LatexCommand \index{\#pragma nojtbound}
15441
15442 \end_inset
15443
15444  - will not generate code for boundary value checking, when switch statements
15445  are turned into jump-tables (dangerous).
15446  For more details see section
15447 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15448
15449 \end_inset
15450
15451 .
15452 \layout Itemize
15453
15454 noloopreverse
15455 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15456
15457 \end_inset
15458
15459  - Will not do loop reversal optimization
15460 \layout Itemize
15461
15462 nooverlay
15463 \begin_inset LatexCommand \index{\#pragma nooverlay}
15464
15465 \end_inset
15466
15467  - the compiler will not overlay the parameters and local variables of a
15468  function.
15469 \layout Itemize
15470
15471 stackauto
15472 \begin_inset LatexCommand \index{\#pragma stackauto}
15473
15474 \end_inset
15475
15476 - See option -
15477 \begin_inset ERT
15478 status Collapsed
15479
15480 \layout Standard
15481
15482 \backslash
15483 /
15484 \end_inset
15485
15486 -stack-auto
15487 \begin_inset LatexCommand \index{-\/-stack-auto}
15488
15489 \end_inset
15490
15491  and section
15492 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
15493
15494 \end_inset
15495
15496  Parameters and Local Variables.
15497 \layout Itemize
15498
15499 opt_code_speed
15500 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
15501
15502 \end_inset
15503
15504 - The compiler will optimize code generation towards fast code, possibly
15505  at the expense of code size.
15506 \layout Itemize
15507
15508 opt_code_size
15509 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
15510
15511 \end_inset
15512
15513 - The compiler will optimize code generation towards compact code, possibly
15514  at the expense of code speed.
15515 \layout Itemize
15516
15517 opt_code_balanced
15518 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
15519
15520 \end_inset
15521
15522 - The compiler will attempt to generate code that is both compact and fast,
15523  as long as meeting one goal is not a detriment to the other (this is the
15524  default).
15525
15526 \layout Itemize
15527
15528 std_sdcc89
15529 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
15530
15531 \end_inset
15532
15533 - Generally follow the C89 standard, but allow SDCC features that conflict
15534  with the standard (default).
15535 \layout Itemize
15536
15537 std_c89
15538 \begin_inset LatexCommand \index{\#pragma std\_c89}
15539
15540 \end_inset
15541
15542 - Follow the C89 standard and disable SDCC features that conflict with the
15543  standard.
15544 \layout Itemize
15545
15546 std_sdcc99
15547 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
15548
15549 \end_inset
15550
15551 - Generally follow the C99 standard, but allow SDCC features that conflict
15552  with the standard (incomplete support).
15553 \layout Itemize
15554
15555 std_c99
15556 \begin_inset LatexCommand \index{\#pragma std\_c99}
15557
15558 \end_inset
15559
15560 - Follow the C99 standard and disable SDCC features that conflict with the
15561  standard (incomplete support).
15562 \layout Itemize
15563
15564 codeseg <name>
15565 \begin_inset LatexCommand \index{\#pragma codeseg}
15566
15567 \end_inset
15568
15569 - Use this name (max.
15570  8 characters) for the code segment.
15571 \layout Itemize
15572
15573 constseg <name>
15574 \begin_inset LatexCommand \index{\#pragma constseg}
15575
15576 \end_inset
15577
15578 - Use this name (max.
15579  8 characters) for the const segment.
15580 \layout Standard
15581
15582 SDCPP supports the following #pragma directives:
15583 \layout Itemize
15584
15585 preproc_asm
15586 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
15587
15588 \end_inset
15589
15590  (+ | -) - switch _asm _endasm block preprocessing on / off.
15591  Default is on.
15592 \layout Standard
15593
15594 The pragma's are intended to be used to turn-on or off certain optimizations
15595  which might cause the compiler to generate extra stack / data space to
15596  store compiler generated temporary variables.
15597  This usually happens in large functions.
15598  Pragma directives should be used as shown in the following example, they
15599  are used to control options & optimizations for a given function; pragmas
15600  should be placed before and/or after a function, placing pragma's inside
15601  a function body could have unpredictable results.
15602 \layout Verse
15603
15604
15605 \family typewriter
15606 #pragma save
15607 \begin_inset LatexCommand \index{\#pragma save}
15608
15609 \end_inset
15610
15611  \SpecialChar ~
15612 \SpecialChar ~
15613 \SpecialChar ~
15614 \SpecialChar ~
15615 \SpecialChar ~
15616 \SpecialChar ~
15617 \SpecialChar ~
15618 /* save the current settings */
15619 \newline
15620 #pragma nogcse
15621 \begin_inset LatexCommand \index{\#pragma nogcse}
15622
15623 \end_inset
15624
15625  \SpecialChar ~
15626 \SpecialChar ~
15627 \SpecialChar ~
15628 \SpecialChar ~
15629 \SpecialChar ~
15630 /* turnoff global subexpression elimination */
15631 \newline
15632 #pragma noinduction
15633 \begin_inset LatexCommand \index{\#pragma noinduction}
15634
15635 \end_inset
15636
15637  /* turn off induction optimizations */
15638 \newline
15639 int foo ()
15640 \newline
15641 {
15642 \newline
15643 \SpecialChar ~
15644  \SpecialChar ~
15645  ...
15646
15647 \newline
15648 \SpecialChar ~
15649  \SpecialChar ~
15650  /* large code */
15651 \newline
15652 \SpecialChar ~
15653  \SpecialChar ~
15654  ...
15655
15656 \newline
15657 }
15658 \newline
15659 #pragma restore
15660 \begin_inset LatexCommand \index{\#pragma restore}
15661
15662 \end_inset
15663
15664  /* turn the optimizations back on */
15665 \layout Standard
15666
15667 The compiler will generate a warning message when extra space is allocated.
15668  It is strongly recommended that the save and restore pragma's be used when
15669  changing options for a function.
15670 \layout Section
15671
15672 Defines Created by the Compiler
15673 \layout Standard
15674
15675 The compiler creates the following #defines
15676 \begin_inset LatexCommand \index{\#defines}
15677
15678 \end_inset
15679
15680
15681 \begin_inset LatexCommand \index{Defines created by the compiler}
15682
15683 \end_inset
15684
15685 :
15686 \newline
15687
15688 \layout Standard
15689
15690
15691 \begin_inset  Tabular
15692 <lyxtabular version="3" rows="11" columns="2">
15693 <features>
15694 <column alignment="center" valignment="top" leftline="true" width="0">
15695 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15696 <row topline="true" bottomline="true">
15697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15698 \begin_inset Text
15699
15700 \layout Standard
15701
15702
15703 \series bold
15704 #define
15705 \end_inset
15706 </cell>
15707 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15708 \begin_inset Text
15709
15710 \layout Standard
15711
15712
15713 \series bold
15714 Description
15715 \end_inset
15716 </cell>
15717 </row>
15718 <row topline="true">
15719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15720 \begin_inset Text
15721
15722 \layout Standard
15723
15724 SDCC
15725 \begin_inset LatexCommand \index{SDCC}
15726
15727 \end_inset
15728
15729
15730 \end_inset
15731 </cell>
15732 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15733 \begin_inset Text
15734
15735 \layout Standard
15736
15737 this Symbol is always defined.
15738  Since version 2.5.6 it's this version number as an int (ex.
15739  256)
15740 \end_inset
15741 </cell>
15742 </row>
15743 <row topline="true">
15744 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15745 \begin_inset Text
15746
15747 \layout Standard
15748
15749 SDCC_mcs51
15750 \begin_inset LatexCommand \index{SDCC\_mcs51}
15751
15752 \end_inset
15753
15754  or SDCC_ds390
15755 \begin_inset LatexCommand \index{SDCC\_ds390}
15756
15757 \end_inset
15758
15759  or SDCC_z80
15760 \begin_inset LatexCommand \index{SDCC\_z80}
15761
15762 \end_inset
15763
15764 , etc
15765 \end_inset
15766 </cell>
15767 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15768 \begin_inset Text
15769
15770 \layout Standard
15771
15772 depending on the model used (e.g.: -mds390
15773 \end_inset
15774 </cell>
15775 </row>
15776 <row topline="true">
15777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15778 \begin_inset Text
15779
15780 \layout Standard
15781
15782 __mcs51
15783 \begin_inset LatexCommand \index{\_\_mcs51}
15784
15785 \end_inset
15786
15787 , __ds390
15788 \begin_inset LatexCommand \index{\_\_ds390}
15789
15790 \end_inset
15791
15792 , __hc08
15793 \begin_inset LatexCommand \index{\_\_hc08}
15794
15795 \end_inset
15796
15797 , __z80
15798 \begin_inset LatexCommand \index{\_\_z80}
15799
15800 \end_inset
15801
15802 , etc
15803 \end_inset
15804 </cell>
15805 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15806 \begin_inset Text
15807
15808 \layout Standard
15809
15810 depending on the model used (e.g.
15811  -mz80)
15812 \end_inset
15813 </cell>
15814 </row>
15815 <row topline="true">
15816 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15817 \begin_inset Text
15818
15819 \layout Standard
15820
15821 SDCC_STACK_AUTO
15822 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
15823
15824 \end_inset
15825
15826
15827 \end_inset
15828 </cell>
15829 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15830 \begin_inset Text
15831
15832 \layout Standard
15833
15834 when
15835 \emph on
15836 -
15837 \begin_inset ERT
15838 status Collapsed
15839
15840 \layout Standard
15841
15842 \backslash
15843 /
15844 \end_inset
15845
15846 -stack-auto
15847 \emph default
15848  option is used
15849 \end_inset
15850 </cell>
15851 </row>
15852 <row topline="true">
15853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15854 \begin_inset Text
15855
15856 \layout Standard
15857
15858 SDCC_MODEL_SMALL
15859 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
15860
15861 \end_inset
15862
15863
15864 \end_inset
15865 </cell>
15866 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15867 \begin_inset Text
15868
15869 \layout Standard
15870
15871 when
15872 \emph on
15873 -
15874 \begin_inset ERT
15875 status Collapsed
15876
15877 \layout Standard
15878
15879 \backslash
15880 /
15881 \end_inset
15882
15883 -model-small
15884 \emph default
15885  is used
15886 \end_inset
15887 </cell>
15888 </row>
15889 <row topline="true">
15890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15891 \begin_inset Text
15892
15893 \layout Standard
15894
15895 SDCC_MODEL_MEDIUM
15896 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
15897
15898 \end_inset
15899
15900
15901 \end_inset
15902 </cell>
15903 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15904 \begin_inset Text
15905
15906 \layout Standard
15907
15908 when
15909 \emph on
15910 -
15911 \begin_inset ERT
15912 status Collapsed
15913
15914 \layout Standard
15915
15916 \backslash
15917 /
15918 \end_inset
15919
15920 -model-medium
15921 \emph default
15922  is used
15923 \end_inset
15924 </cell>
15925 </row>
15926 <row topline="true">
15927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15928 \begin_inset Text
15929
15930 \layout Standard
15931
15932 SDCC_MODEL_LARGE
15933 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
15934
15935 \end_inset
15936
15937
15938 \end_inset
15939 </cell>
15940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15941 \begin_inset Text
15942
15943 \layout Standard
15944
15945 when
15946 \emph on
15947 -
15948 \begin_inset ERT
15949 status Collapsed
15950
15951 \layout Standard
15952
15953 \backslash
15954 /
15955 \end_inset
15956
15957 -model-large
15958 \emph default
15959  is used
15960 \end_inset
15961 </cell>
15962 </row>
15963 <row topline="true">
15964 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15965 \begin_inset Text
15966
15967 \layout Standard
15968
15969 SDCC_USE_XSTACK
15970 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15971
15972 \end_inset
15973
15974
15975 \end_inset
15976 </cell>
15977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15978 \begin_inset Text
15979
15980 \layout Standard
15981
15982 when
15983 \emph on
15984 -
15985 \begin_inset ERT
15986 status Collapsed
15987
15988 \layout Standard
15989
15990 \backslash
15991 /
15992 \end_inset
15993
15994 -xstack
15995 \emph default
15996  option is used
15997 \end_inset
15998 </cell>
15999 </row>
16000 <row topline="true">
16001 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16002 \begin_inset Text
16003
16004 \layout Standard
16005
16006 SDCC_STACK_TENBIT
16007 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
16008
16009 \end_inset
16010
16011
16012 \end_inset
16013 </cell>
16014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16015 \begin_inset Text
16016
16017 \layout Standard
16018
16019 when
16020 \emph on
16021 -mds390
16022 \emph default
16023  is used
16024 \end_inset
16025 </cell>
16026 </row>
16027 <row topline="true" bottomline="true">
16028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16029 \begin_inset Text
16030
16031 \layout Standard
16032
16033 SDCC_MODEL_FLAT24
16034 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
16035
16036 \end_inset
16037
16038
16039 \end_inset
16040 </cell>
16041 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16042 \begin_inset Text
16043
16044 \layout Standard
16045
16046 when
16047 \emph on
16048 -mds390
16049 \emph default
16050  is used
16051 \end_inset
16052 </cell>
16053 </row>
16054 </lyxtabular>
16055
16056 \end_inset
16057
16058
16059 \layout Chapter
16060
16061 Notes on supported Processors
16062 \layout Section
16063
16064 MCS51 variants
16065 \begin_inset LatexCommand \label{sub:MCS51-variants}
16066
16067 \end_inset
16068
16069
16070 \begin_inset LatexCommand \index{MCS51 variants}
16071
16072 \end_inset
16073
16074
16075 \layout Standard
16076
16077 MCS51 processors are available from many vendors and come in many different
16078  flavours.
16079  While they might differ considerably in respect to Special Function Registers
16080  the core MCS51 is usually not modified or is kept compatible.
16081
16082 \layout Subsection
16083
16084 pdata access by SFR
16085 \layout Standard
16086
16087 With the upcome of devices with internal xdata and flash memory devices
16088  using port P2
16089 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
16090
16091 \end_inset
16092
16093  as dedicated I/O port is becoming more popular.
16094  Switching the high byte for pdata
16095 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
16096
16097 \end_inset
16098
16099  access which was formerly done by port P2 is then achieved by a Special
16100  Function Register
16101 \begin_inset LatexCommand \index{sfr}
16102
16103 \end_inset
16104
16105 .
16106  In well-established MCS51 tradition the address of this
16107 \emph on
16108 sfr
16109 \emph default
16110  is where the chip designers decided to put it.
16111  Needless to say that they didn't agree on a common name either.
16112  So that the startup code can correctly initialize xdata variables, you
16113  should define an sfr with the name _XPAGE
16114 \family typewriter
16115
16116 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
16117
16118 \end_inset
16119
16120
16121 \family default
16122  at the appropriate location if the default, port P2, is not used for this.
16123  Some examples are:
16124 \layout Verse
16125
16126
16127 \family typewriter
16128 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
16129 \layout Verse
16130
16131
16132 \family typewriter
16133 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
16134 \layout Verse
16135
16136
16137 \family typewriter
16138 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
16139 \layout Standard
16140
16141 For more exotic implementations further customizations may be needed.
16142  See section
16143 \begin_inset LatexCommand \ref{sub:Startup-Code}
16144
16145 \end_inset
16146
16147  for other possibilities.
16148 \layout Subsection
16149
16150 Other Features available by SFR
16151 \layout Standard
16152
16153 Some MCS51 variants offer features like Double DPTR
16154 \begin_inset LatexCommand \index{DPTR}
16155
16156 \end_inset
16157
16158 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
16159  These are currently not used for the MCS51 port.
16160  If you absolutely need them you can fall back to inline assembly or submit
16161  a patch to SDCC.
16162 \layout Section
16163
16164 DS400 port
16165 \layout Standard
16166
16167 The DS80C400 microcontroller has a rich set of peripherals.
16168  In its built-in ROM library it includes functions to access some of the
16169  features, among them is a TCP stack with IP4 and IP6 support.
16170  Library headers (currently in beta status) and other files are provided
16171  at
16172 \size footnotesize
16173
16174 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
16175
16176 \end_inset
16177
16178 .
16179
16180 \layout Section
16181
16182 The Z80 and gbz80 port
16183 \layout Standard
16184
16185 SDCC can target both the Zilog
16186 \begin_inset LatexCommand \index{Z80}
16187
16188 \end_inset
16189
16190  and the Nintendo Gameboy's Z80-like gbz80
16191 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
16192
16193 \end_inset
16194
16195 .
16196  The Z80 port is passed through the same
16197 \emph on
16198 regressions tests
16199 \begin_inset LatexCommand \index{Regression test}
16200
16201 \end_inset
16202
16203
16204 \emph default
16205  as the MCS51 and DS390 ports, so floating point support, support for long
16206  variables and bitfield support is fine.
16207  See mailing lists and forums about interrupt routines.
16208 \layout Standard
16209
16210 As always, the code is the authoritative reference - see z80/ralloc.c and
16211  z80/gen.c.
16212  The stack
16213 \begin_inset LatexCommand \index{stack}
16214
16215 \end_inset
16216
16217  frame is similar to that generated by the IAR Z80 compiler.
16218  IX is used as the base pointer, HL and IY are used as a temporary registers,
16219  and BC and DE are available for holding variables.
16220  Return values
16221 \begin_inset LatexCommand \index{return value}
16222
16223 \end_inset
16224
16225  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
16226  bytes).
16227  The gbz80 port use the same set of registers for the return values, but
16228  in a different order of significance: E (one byte), DE (two bytes), or
16229  HLDE (four bytes).
16230 \layout Section
16231
16232 The HC08 port
16233 \layout Standard
16234
16235 The port to the Motorola HC08
16236 \begin_inset LatexCommand \index{HC08}
16237
16238 \end_inset
16239
16240  family has been added in October 2003, and is still undergoing some basic
16241  development.
16242  The code generator is complete, but the register allocation is still quite
16243  unoptimized.
16244  Some of the SDCC's standard C library functions have embedded non-HC08
16245  inline assembly and so are not yet usable.
16246 \newline
16247
16248 \newline
16249
16250 \layout Section
16251
16252 The PIC14 port
16253 \layout Standard
16254
16255 The 14bit PIC
16256 \begin_inset LatexCommand \index{PIC14}
16257
16258 \end_inset
16259
16260  port still requires a major effort from the development community.
16261  However it can work for very simple code.
16262 \layout Subsection
16263
16264 C code and 14bit PIC code page
16265 \begin_inset LatexCommand \index{code page (pic14)}
16266
16267 \end_inset
16268
16269  and RAM banks
16270 \begin_inset LatexCommand \index{RAM bank (pic14)}
16271
16272 \end_inset
16273
16274
16275 \layout Standard
16276
16277 The linker organizes allocation for the code page and RAM banks.
16278  It does not have intimate knowledge of the code flow.
16279  It will put all the code section of a single asm file into a single code
16280  page.
16281  In order to make use of multiple code pages, separate asm files must be
16282  used.
16283  The compiler treats all functions of a single C file as being in the same
16284  code page unless it is non static.
16285  The compiler treats all local variables of a single C file as being in
16286  the same RAM bank unless it is an extern.
16287 \newline
16288
16289 \newline
16290 To get the best follow these guide lines:
16291 \layout Enumerate
16292
16293 make local functions static, as non static functions require code page selection
16294  overhead.
16295 \layout Enumerate
16296
16297 Make local variables static as extern variables require RAM bank selection
16298  overhead.
16299 \layout Enumerate
16300
16301 For devices that have multiple code pages it is more efficient to use the
16302  same number of files as pages, i.e.
16303  for the 16F877 use 4 separate files and i.e.
16304  for the 16F874 use 2 separate files.
16305  This way the linker can put the code for each file into different code
16306  pages and the compiler can allocate reusable variables more efficiently
16307  and there's less page selection overhead.
16308  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
16309  instruction set) use 'unsigned char' whereever possible instead of 'int'.
16310 \layout Subsection
16311
16312 Creating a device include file
16313 \layout Standard
16314
16315 For generating a device include file use the support perl script inc2h.pl
16316  kept in directory support/script.
16317 \layout Subsection
16318
16319 Interrupt code
16320 \layout Standard
16321
16322 For the interrupt function, use the keyword 'interrupt'
16323 \begin_inset LatexCommand \index{interrupt}
16324
16325 \end_inset
16326
16327  with level number of 0 (PIC14 only has 1 interrupt so this number is only
16328  there to avoid a syntax error - it ought to be fixed).
16329  E.g.:
16330 \layout Verse
16331
16332
16333 \family typewriter
16334 void Intr(void) interrupt 0
16335 \newline
16336 {
16337 \newline
16338 \SpecialChar ~
16339 \SpecialChar ~
16340 T0IF = 0; /* Clear timer interrupt */
16341 \newline
16342 }
16343 \layout Subsection
16344
16345 Linking and assembling
16346 \layout Standard
16347
16348 For assembling you can use either GPUTILS'
16349 \begin_inset LatexCommand \index{gputils (pic tools)}
16350
16351 \end_inset
16352
16353  gpasm.exe or MPLAB's mpasmwin.exe.
16354  GPUTILS is available from
16355 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
16356
16357 \end_inset
16358
16359 .
16360  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
16361  If you use MPLAB and an interrupt function then the linker script file
16362  vectors section will need to be enlarged to link with mplink.
16363 \newline
16364
16365 \newline
16366 Here is a
16367 \family typewriter
16368 Makefile
16369 \family default
16370  using GPUTILS:
16371 \layout Verse
16372
16373
16374 \family typewriter
16375 .c.o:
16376 \newline
16377 \SpecialChar ~
16378 \SpecialChar ~
16379 \SpecialChar ~
16380 \SpecialChar ~
16381 \SpecialChar ~
16382 \SpecialChar ~
16383 \SpecialChar ~
16384 \SpecialChar ~
16385 sdcc -S -V -mpic14 -p16F877 $<
16386 \newline
16387 \SpecialChar ~
16388 \SpecialChar ~
16389 \SpecialChar ~
16390 \SpecialChar ~
16391 \SpecialChar ~
16392 \SpecialChar ~
16393 \SpecialChar ~
16394 \SpecialChar ~
16395 gpasm -c $*.asm
16396 \newline
16397
16398 \newline
16399 $(PRJ).hex: $(OBJS)
16400 \newline
16401 \SpecialChar ~
16402 \SpecialChar ~
16403 \SpecialChar ~
16404 \SpecialChar ~
16405 \SpecialChar ~
16406 \SpecialChar ~
16407 \SpecialChar ~
16408 \SpecialChar ~
16409 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
16410 \layout Standard
16411
16412 Here is a
16413 \family typewriter
16414 Makefile
16415 \family default
16416  using MPLAB:
16417 \layout Verse
16418
16419
16420 \family typewriter
16421 .c.o:
16422 \newline
16423 \SpecialChar ~
16424 \SpecialChar ~
16425 \SpecialChar ~
16426 \SpecialChar ~
16427 \SpecialChar ~
16428 \SpecialChar ~
16429 \SpecialChar ~
16430 \SpecialChar ~
16431 sdcc -S -V -mpic14 -p16F877 $<
16432 \newline
16433 \SpecialChar ~
16434 \SpecialChar ~
16435 \SpecialChar ~
16436 \SpecialChar ~
16437 \SpecialChar ~
16438 \SpecialChar ~
16439 \SpecialChar ~
16440 \SpecialChar ~
16441 mpasmwin /q /o $*.asm
16442 \newline
16443
16444 \newline
16445 $(PRJ).hex: $(OBJS)
16446 \newline
16447 \SpecialChar ~
16448 \SpecialChar ~
16449 \SpecialChar ~
16450 \SpecialChar ~
16451 \SpecialChar ~
16452 \SpecialChar ~
16453 \SpecialChar ~
16454 \SpecialChar ~
16455 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
16456 \layout Standard
16457
16458 Please note that indentations within a
16459 \family typewriter
16460  Makefile
16461 \family default
16462  have to be done with a tabulator character.
16463 \layout Subsection
16464
16465 Command-line options
16466 \layout Standard
16467
16468 Besides the switches common to all SDCC backends, the PIC14 port accepts
16469  the following options (for an updated list see sdcc -
16470 \begin_inset ERT
16471 status Collapsed
16472
16473 \layout Standard
16474
16475 \backslash
16476 /
16477 \end_inset
16478
16479 -help):
16480 \layout List
16481 \labelwidthstring 00.00.0000
16482
16483 -
16484 \begin_inset ERT
16485 status Collapsed
16486
16487 \layout Standard
16488
16489 \backslash
16490 /
16491 \end_inset
16492
16493 -debug-extra emit debug info in assembly output
16494 \layout List
16495 \labelwidthstring 00.00.0000
16496
16497 -
16498 \begin_inset ERT
16499 status Collapsed
16500
16501 \layout Standard
16502
16503 \backslash
16504 /
16505 \end_inset
16506
16507 -no-pcode-opt disable (slightly faulty) optimization on pCode
16508 \layout Subsection
16509
16510 The library
16511 \layout Subsubsection
16512
16513 error: missing definition for symbol
16514 \begin_inset Quotes sld
16515 \end_inset
16516
16517 __gptrget1
16518 \begin_inset Quotes srd
16519 \end_inset
16520
16521
16522 \layout Standard
16523
16524 The PIC14 port uses library routines to provide more complex operations
16525  like multiplication, division/modulus and (generic) pointer dereferencing.
16526  In order to add these routines to your project, you must link with PIC14's
16527
16528 \family typewriter
16529 libsdcc.lib
16530 \family default
16531 .
16532  For single source file projects this is done automatically, more complex
16533  projects must add
16534 \family typewriter
16535 libsdcc.lib
16536 \family default
16537  to the linker's arguments.
16538  Make sure you also add an include path for the library (using the -I switch
16539  to the linker)!
16540 \layout Subsubsection
16541
16542 Processor mismatch in file
16543 \begin_inset Quotes sld
16544 \end_inset
16545
16546 XXX
16547 \begin_inset Quotes srd
16548 \end_inset
16549
16550 .
16551 \layout Standard
16552
16553 This warning can usually be ignored due to the very good compatibility amongst
16554  14 bit PIC devices.
16555 \layout Standard
16556
16557 You might also consider recompiling the library for your specific device
16558  by changing the ARCH=p16f877 (default target) entry in
16559 \family typewriter
16560 device/lib/pic/Makefile.in
16561 \family default
16562  and
16563 \family typewriter
16564 device/lib/pic/Makefile
16565 \family default
16566  to reflect your device.
16567  This might even improve performance for smaller devices as unneccesary
16568  BANKSELs migth be removed.
16569 \layout Subsection
16570
16571 Known bugs
16572 \layout Subsubsection
16573
16574 initialized data
16575 \layout Standard
16576
16577 Currently, data can only be initialized if it resides in the source file
16578  together with
16579 \emph on
16580 main()
16581 \emph default
16582 .
16583  Data in other source files will silently
16584 \series bold
16585 not
16586 \series default
16587  be initialized.
16588 \layout Section
16589
16590 The PIC16
16591 \begin_inset LatexCommand \index{PIC16}
16592
16593 \end_inset
16594
16595  port
16596 \layout Standard
16597
16598 The PIC16
16599 \begin_inset LatexCommand \index{PIC16}
16600
16601 \end_inset
16602
16603  port is the portion of SDCC that is responsible to produce code for the
16604  Microchip
16605 \begin_inset LatexCommand \index{Microchip}
16606
16607 \end_inset
16608
16609 (TM) microcontrollers with 16 bit core.
16610  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
16611  Currently supported devices are:
16612 \layout Standard
16613 \align center
16614
16615 \begin_inset  Tabular
16616 <lyxtabular version="3" rows="4" columns="6">
16617 <features>
16618 <column alignment="center" valignment="top" leftline="true" width="0">
16619 <column alignment="center" valignment="top" leftline="true" width="0">
16620 <column alignment="center" valignment="top" leftline="true" width="0">
16621 <column alignment="center" valignment="top" leftline="true" width="0">
16622 <column alignment="center" valignment="top" leftline="true" width="0">
16623 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16624 <row topline="true">
16625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16626 \begin_inset Text
16627
16628 \layout Standard
16629
16630 18F242
16631 \end_inset
16632 </cell>
16633 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16634 \begin_inset Text
16635
16636 \layout Standard
16637
16638 18F248
16639 \end_inset
16640 </cell>
16641 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16642 \begin_inset Text
16643
16644 \layout Standard
16645
16646 18F252
16647 \end_inset
16648 </cell>
16649 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16650 \begin_inset Text
16651
16652 \layout Standard
16653
16654 18F258
16655 \end_inset
16656 </cell>
16657 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16658 \begin_inset Text
16659
16660 \layout Standard
16661
16662 18F442
16663 \end_inset
16664 </cell>
16665 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16666 \begin_inset Text
16667
16668 \layout Standard
16669
16670 18F448
16671 \end_inset
16672 </cell>
16673 </row>
16674 <row topline="true">
16675 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16676 \begin_inset Text
16677
16678 \layout Standard
16679
16680 18F452
16681 \end_inset
16682 </cell>
16683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16684 \begin_inset Text
16685
16686 \layout Standard
16687
16688 18F458
16689 \end_inset
16690 </cell>
16691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16692 \begin_inset Text
16693
16694 \layout Standard
16695
16696 18F1220
16697 \end_inset
16698 </cell>
16699 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16700 \begin_inset Text
16701
16702 \layout Standard
16703
16704 18F2220
16705 \end_inset
16706 </cell>
16707 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16708 \begin_inset Text
16709
16710 \layout Standard
16711
16712 18F2550
16713 \end_inset
16714 </cell>
16715 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16716 \begin_inset Text
16717
16718 \layout Standard
16719
16720 18F4331
16721 \end_inset
16722 </cell>
16723 </row>
16724 <row topline="true">
16725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16726 \begin_inset Text
16727
16728 \layout Standard
16729
16730 18F4455
16731 \end_inset
16732 </cell>
16733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16734 \begin_inset Text
16735
16736 \layout Standard
16737
16738 18F6520
16739 \end_inset
16740 </cell>
16741 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16742 \begin_inset Text
16743
16744 \layout Standard
16745
16746 18F6620
16747 \end_inset
16748 </cell>
16749 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16750 \begin_inset Text
16751
16752 \layout Standard
16753
16754 18F6680
16755 \end_inset
16756 </cell>
16757 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16758 \begin_inset Text
16759
16760 \layout Standard
16761
16762 18F6720
16763 \end_inset
16764 </cell>
16765 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16766 \begin_inset Text
16767
16768 \layout Standard
16769
16770 18F8520
16771 \end_inset
16772 </cell>
16773 </row>
16774 <row topline="true" bottomline="true">
16775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16776 \begin_inset Text
16777
16778 \layout Standard
16779
16780 18F8620
16781 \end_inset
16782 </cell>
16783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16784 \begin_inset Text
16785
16786 \layout Standard
16787
16788 18F8680
16789 \end_inset
16790 </cell>
16791 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16792 \begin_inset Text
16793
16794 \layout Standard
16795
16796 18F8720
16797 \end_inset
16798 </cell>
16799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16800 \begin_inset Text
16801
16802 \layout Standard
16803
16804 \end_inset
16805 </cell>
16806 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16807 \begin_inset Text
16808
16809 \layout Standard
16810
16811 \end_inset
16812 </cell>
16813 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16814 \begin_inset Text
16815
16816 \layout Standard
16817
16818 \end_inset
16819 </cell>
16820 </row>
16821 </lyxtabular>
16822
16823 \end_inset
16824
16825
16826 \layout Subsection
16827
16828 Global Options
16829 \layout Standard
16830
16831 PIC16 port supports the standard command line arguments as supposed, with
16832  the exception of certain cases that will be mentioned in the following
16833  list:
16834 \layout List
16835 \labelwidthstring 00.00.0000
16836
16837 -
16838 \begin_inset ERT
16839 status Collapsed
16840
16841 \layout Standard
16842
16843 \backslash
16844 /
16845 \end_inset
16846
16847 -callee-saves See -
16848 \begin_inset ERT
16849 status Collapsed
16850
16851 \layout Standard
16852
16853 \backslash
16854 /
16855 \end_inset
16856
16857 -all-callee-saves
16858 \layout List
16859 \labelwidthstring 00.00.0000
16860
16861 -
16862 \begin_inset ERT
16863 status Collapsed
16864
16865 \layout Standard
16866
16867 \backslash
16868 /
16869 \end_inset
16870
16871 -all-callee-saves All function arguments are passed on stack by default.
16872
16873 \emph on
16874 There is no need to specify this in the command line.
16875 \layout List
16876 \labelwidthstring 00.00.0000
16877
16878 -
16879 \begin_inset ERT
16880 status Collapsed
16881
16882 \layout Standard
16883
16884 \backslash
16885 /
16886 \end_inset
16887
16888 -fommit-frame-pointer Frame pointer will be omitted when the function uses
16889  no local variables.
16890 \layout Subsection
16891
16892 Port Specific Options
16893 \begin_inset LatexCommand \index{Options PIC16}
16894
16895 \end_inset
16896
16897
16898 \layout Standard
16899
16900 The port specific options appear after the global options in the sdcc --help
16901  output.
16902 \layout Subsubsection
16903
16904 General Options
16905 \layout Standard
16906
16907 General options enable certain port features and optimizations.
16908 \layout List
16909 \labelwidthstring 00.00.0000
16910
16911 -
16912 \begin_inset ERT
16913 status Collapsed
16914
16915 \layout Standard
16916
16917 \backslash
16918 /
16919 \end_inset
16920
16921 -stack-model=[model] Used in conjuction with the command above.
16922  Defines the stack model to be used, valid stack models are :
16923 \begin_deeper
16924 \layout List
16925 \labelwidthstring 00.00.0000
16926
16927
16928 \emph on
16929 small
16930 \emph default
16931  Selects small stack model.
16932  8 bit stack and frame pointers.
16933  Supports 256 bytes stack size.
16934 \layout List
16935 \labelwidthstring 00.00.0000
16936
16937
16938 \emph on
16939 large
16940 \emph default
16941  Selects large stack model.
16942  16 bit stack and frame pointers.
16943  Supports 65536 bytes stack size.
16944 \end_deeper
16945 \layout List
16946 \labelwidthstring 00.00.0000
16947
16948 -
16949 \begin_inset ERT
16950 status Collapsed
16951
16952 \layout Standard
16953
16954 \backslash
16955 /
16956 \end_inset
16957
16958 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
16959  unitialized data variables with [kword].
16960  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
16961 \layout List
16962 \labelwidthstring 00.00.0000
16963
16964 -
16965 \begin_inset ERT
16966 status Collapsed
16967
16968 \layout Standard
16969
16970 \backslash
16971 /
16972 \end_inset
16973
16974 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
16975  Useful for bootloaders.
16976 \layout List
16977 \labelwidthstring 00.00.0000
16978
16979 -
16980 \begin_inset ERT
16981 status Collapsed
16982
16983 \layout Standard
16984
16985 \backslash
16986 /
16987 \end_inset
16988
16989 -asm= sets the full path and name of an external assembler to call.
16990 \layout List
16991 \labelwidthstring 00.00.0000
16992
16993 -
16994 \begin_inset ERT
16995 status Collapsed
16996
16997 \layout Standard
16998
16999 \backslash
17000 /
17001 \end_inset
17002
17003 -link= sets the full path and name of an external linker to call.
17004 \layout List
17005 \labelwidthstring 00.00.0000
17006
17007 -
17008 \begin_inset ERT
17009 status Collapsed
17010
17011 \layout Standard
17012
17013 \backslash
17014 /
17015 \end_inset
17016
17017 -mplab-comp MPLAB compatibility option.
17018  Currently only suppresses special gpasm directives.
17019 \layout Subsubsection
17020
17021 Optimization Options
17022 \layout List
17023 \labelwidthstring 00.00.0000
17024
17025 -
17026 \begin_inset ERT
17027 status Collapsed
17028
17029 \layout Standard
17030
17031 \backslash
17032 /
17033 \end_inset
17034
17035 -optimize-goto Try to use (conditional) BRA instead of GOTO
17036 \layout List
17037 \labelwidthstring 00.00.0000
17038
17039 -
17040 \begin_inset ERT
17041 status Collapsed
17042
17043 \layout Standard
17044
17045 \backslash
17046 /
17047 \end_inset
17048
17049 -optimize-cmp Try to optimize some compares.
17050 \layout List
17051 \labelwidthstring 00.00.0000
17052
17053 -
17054 \begin_inset ERT
17055 status Collapsed
17056
17057 \layout Standard
17058
17059 \backslash
17060 /
17061 \end_inset
17062
17063 -optimize-df Analyze the dataflow of the generated code and improve it.
17064 \layout List
17065 \labelwidthstring 00.00.0000
17066
17067 -
17068 \begin_inset ERT
17069 status Collapsed
17070
17071 \layout Standard
17072
17073 \backslash
17074 /
17075 \end_inset
17076
17077 -obanksel=nn Set optimization level for inserting BANKSELs.
17078 \newline
17079
17080 \begin_deeper
17081 \layout List
17082 \labelwidthstring 00.00.0000
17083
17084 0 no optimization
17085 \layout List
17086 \labelwidthstring 00.00.0000
17087
17088 1 checks previous used register and if it is the same then does not emit
17089  BANKSEL, accounts only for labels.
17090 \layout List
17091 \labelwidthstring 00.00.0000
17092
17093 2 tries to check the location of (even different) symbols and removes BANKSELs
17094  if they are in the same bank.
17095
17096 \newline
17097
17098 \emph on
17099 Important: There might be problems if the linker script has data sections
17100  across bank borders!
17101 \end_deeper
17102 \layout Subsubsection
17103
17104 Linking Options
17105 \layout List
17106 \labelwidthstring 00.00.0000
17107
17108 -
17109 \begin_inset ERT
17110 status Collapsed
17111
17112 \layout Standard
17113
17114 \backslash
17115 /
17116 \end_inset
17117
17118 -nodefaultlibs do not link default libraries when linking
17119 \layout List
17120 \labelwidthstring 00.00.0000
17121
17122 -
17123 \begin_inset ERT
17124 status Collapsed
17125
17126 \layout Standard
17127
17128 \backslash
17129 /
17130 \end_inset
17131
17132 -no-crt Don't link the default run-time modules
17133 \layout List
17134 \labelwidthstring 00.00.0000
17135
17136 -
17137 \begin_inset ERT
17138 status Collapsed
17139
17140 \layout Standard
17141
17142 \backslash
17143 /
17144 \end_inset
17145
17146 -use-crt= Use a custom run-time module instead of the defaults.
17147 \layout Subsubsection
17148
17149 Debugging Options
17150 \layout Standard
17151
17152 Debugging options enable extra debugging information in the output files.
17153 \layout List
17154 \labelwidthstring 00.00.0000
17155
17156 -
17157 \begin_inset ERT
17158 status Collapsed
17159
17160 \layout Standard
17161
17162 \backslash
17163 /
17164 \end_inset
17165
17166 -debug-xtra Similar to -
17167 \begin_inset ERT
17168 status Collapsed
17169
17170 \layout Standard
17171
17172 \backslash
17173 /
17174 \end_inset
17175
17176 -debug
17177 \begin_inset LatexCommand \index{-\/-debug}
17178
17179 \end_inset
17180
17181 , but dumps more information.
17182 \layout List
17183 \labelwidthstring 00.00.0000
17184
17185 -
17186 \begin_inset ERT
17187 status Collapsed
17188
17189 \layout Standard
17190
17191 \backslash
17192 /
17193 \end_inset
17194
17195 -debug-ralloc Force register allocator to dump <source>.d file with debugging
17196  information.
17197  <source> is the name of the file compiled.
17198 \layout List
17199 \labelwidthstring 00.00.0000
17200
17201 -
17202 \begin_inset ERT
17203 status Collapsed
17204
17205 \layout Standard
17206
17207 \backslash
17208 /
17209 \end_inset
17210
17211 -pcode-verbose Enable pcode debugging information in translation.
17212 \layout List
17213 \labelwidthstring 00.00.0000
17214
17215 -
17216 \begin_inset ERT
17217 status Collapsed
17218
17219 \layout Standard
17220
17221 \backslash
17222 /
17223 \end_inset
17224
17225 -denable-peeps Force the usage of peepholes.
17226  Use with care.
17227 \layout List
17228 \labelwidthstring 00.00.0000
17229
17230 -
17231 \begin_inset ERT
17232 status Collapsed
17233
17234 \layout Standard
17235
17236 \backslash
17237 /
17238 \end_inset
17239
17240 -gstack Trace push/pops for stack pointer overflow
17241 \layout List
17242 \labelwidthstring 00.00.0000
17243
17244 -
17245 \begin_inset ERT
17246 status Collapsed
17247
17248 \layout Standard
17249
17250 \backslash
17251 /
17252 \end_inset
17253
17254 -call-tree dump call tree in .calltree file
17255 \layout Subsection
17256
17257 Enviromental Variables
17258 \layout Standard
17259
17260 There is a number of enviromental variables that can be used when running
17261  SDCC to enable certain optimizations or force a specific program behaviour.
17262  these variables are primarily for debugging purposes so they can be enabled/dis
17263 abled at will.
17264 \layout Standard
17265
17266 Currently there is only two such variables available:
17267 \layout List
17268 \labelwidthstring 00.00.0000
17269
17270 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
17271  bitfields is optimized by directly loading FSR0 with the address of the
17272  bitfield structure.
17273  Normally SDCC will cast the bitfield structure to a bitfield pointer and
17274  then load FSR0.
17275  This step saves data ram and code space for functions that perform heavy
17276  use of bitfields.
17277  (ie.
17278  80 bytes of code space are saved when compiling malloc.c with this option).
17279
17280 \layout List
17281 \labelwidthstring 00.00.0000
17282
17283 NO_REG_OPT do not perform pCode registers optimization.
17284  This should be used for debugging purposes.
17285  In some where bugs in the pcode optimizer are found, users can benefit
17286  from temporarily disabling the optimizer until the bug is fixed.
17287 \layout Subsection
17288
17289 Preprocessor Macros
17290 \layout Standard
17291
17292 PIC16 port defines the following preprocessor macros while translating a
17293  source.
17294 \layout Standard
17295 \align center
17296
17297 \begin_inset  Tabular
17298 <lyxtabular version="3" rows="6" columns="2">
17299 <features>
17300 <column alignment="center" valignment="top" leftline="true" width="0">
17301 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17302 <row topline="true" bottomline="true">
17303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17304 \begin_inset Text
17305
17306 \layout Standard
17307
17308 Macro
17309 \end_inset
17310 </cell>
17311 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17312 \begin_inset Text
17313
17314 \layout Standard
17315
17316 Description
17317 \end_inset
17318 </cell>
17319 </row>
17320 <row topline="true">
17321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17322 \begin_inset Text
17323
17324 \layout Standard
17325
17326 SDCC_pic16
17327 \end_inset
17328 </cell>
17329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17330 \begin_inset Text
17331
17332 \layout Standard
17333
17334 Port identification
17335 \end_inset
17336 </cell>
17337 </row>
17338 <row topline="true">
17339 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17340 \begin_inset Text
17341
17342 \layout Standard
17343
17344 _
17345 \begin_inset ERT
17346 status Collapsed
17347
17348 \layout Standard
17349
17350 \backslash
17351 /
17352 \end_inset
17353
17354 _pic16
17355 \end_inset
17356 </cell>
17357 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17358 \begin_inset Text
17359
17360 \layout Standard
17361
17362 Port identification (same as above)
17363 \end_inset
17364 </cell>
17365 </row>
17366 <row topline="true">
17367 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17368 \begin_inset Text
17369
17370 \layout Standard
17371
17372 pic18fxxxx
17373 \end_inset
17374 </cell>
17375 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17376 \begin_inset Text
17377
17378 \layout Standard
17379
17380 MCU Identification.
17381
17382 \emph on
17383 xxxx
17384 \emph default
17385  is the microcontrol identification number, i.e.
17386  452, 6620, etc
17387 \end_inset
17388 </cell>
17389 </row>
17390 <row topline="true">
17391 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17392 \begin_inset Text
17393
17394 \layout Standard
17395
17396 _
17397 \begin_inset ERT
17398 status Collapsed
17399
17400 \layout Standard
17401
17402 \backslash
17403 /
17404 \end_inset
17405
17406 _18Fxxxx
17407 \end_inset
17408 </cell>
17409 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17410 \begin_inset Text
17411
17412 \layout Standard
17413
17414 MCU Identification (same as above)
17415 \end_inset
17416 </cell>
17417 </row>
17418 <row topline="true" bottomline="true">
17419 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17420 \begin_inset Text
17421
17422 \layout Standard
17423
17424 STACK_MODEL_nnn
17425 \end_inset
17426 </cell>
17427 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17428 \begin_inset Text
17429
17430 \layout Standard
17431
17432 nnn = SMALL or LARGE respectively according to the stack model used
17433 \end_inset
17434 </cell>
17435 </row>
17436 </lyxtabular>
17437
17438 \end_inset
17439
17440
17441 \layout Standard
17442
17443 In addition the following macros are defined when calling assembler:
17444 \layout Standard
17445 \align center
17446
17447 \begin_inset  Tabular
17448 <lyxtabular version="3" rows="4" columns="2">
17449 <features>
17450 <column alignment="center" valignment="top" leftline="true" width="0">
17451 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17452 <row topline="true" bottomline="true">
17453 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17454 \begin_inset Text
17455
17456 \layout Standard
17457
17458 Macro
17459 \end_inset
17460 </cell>
17461 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17462 \begin_inset Text
17463
17464 \layout Standard
17465
17466 Description
17467 \end_inset
17468 </cell>
17469 </row>
17470 <row topline="true">
17471 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17472 \begin_inset Text
17473
17474 \layout Standard
17475
17476 __18Fxxxx
17477 \end_inset
17478 </cell>
17479 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17480 \begin_inset Text
17481
17482 \layout Standard
17483
17484 MCU Identification.
17485
17486 \emph on
17487 xxxx
17488 \emph default
17489  is the microcontrol identification number, i.e.
17490  452, 6620, etc
17491 \end_inset
17492 </cell>
17493 </row>
17494 <row topline="true">
17495 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17496 \begin_inset Text
17497
17498 \layout Standard
17499
17500 SDCC_MODEL_nnn
17501 \end_inset
17502 </cell>
17503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17504 \begin_inset Text
17505
17506 \layout Standard
17507
17508 nnn = SMALL or LARGE respectively according to the memory model used for
17509  SDCC
17510 \end_inset
17511 </cell>
17512 </row>
17513 <row topline="true" bottomline="true">
17514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17515 \begin_inset Text
17516
17517 \layout Standard
17518
17519 STACK_MODEL_nnn
17520 \end_inset
17521 </cell>
17522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17523 \begin_inset Text
17524
17525 \layout Standard
17526
17527 nnn = SMALL or LARGE respectively according to the stack model used
17528 \end_inset
17529 </cell>
17530 </row>
17531 </lyxtabular>
17532
17533 \end_inset
17534
17535
17536 \layout Subsection
17537
17538 Directories
17539 \layout Standard
17540
17541 PIC16
17542 \begin_inset LatexCommand \index{PIC16}
17543
17544 \end_inset
17545
17546  port uses the following directories for searching header files and libraries.
17547 \layout Standard
17548 \align center
17549
17550 \begin_inset  Tabular
17551 <lyxtabular version="3" rows="3" columns="4">
17552 <features>
17553 <column alignment="center" valignment="top" leftline="true" width="0">
17554 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17555 <column alignment="center" valignment="top" width="0">
17556 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17557 <row topline="true" bottomline="true">
17558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17559 \begin_inset Text
17560
17561 \layout Standard
17562
17563 Directory
17564 \end_inset
17565 </cell>
17566 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17567 \begin_inset Text
17568
17569 \layout Standard
17570
17571 Description
17572 \end_inset
17573 </cell>
17574 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17575 \begin_inset Text
17576
17577 \layout Standard
17578
17579 Target
17580 \end_inset
17581 </cell>
17582 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17583 \begin_inset Text
17584
17585 \layout Standard
17586
17587 Command prefix
17588 \end_inset
17589 </cell>
17590 </row>
17591 <row topline="true">
17592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17593 \begin_inset Text
17594
17595 \layout Standard
17596
17597 PREFIX/sdcc/include/pic16
17598 \end_inset
17599 </cell>
17600 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17601 \begin_inset Text
17602
17603 \layout Standard
17604
17605 PIC16 specific headers
17606 \end_inset
17607 </cell>
17608 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17609 \begin_inset Text
17610
17611 \layout Standard
17612
17613 Compiler
17614 \end_inset
17615 </cell>
17616 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17617 \begin_inset Text
17618
17619 \layout Standard
17620
17621 -I
17622 \end_inset
17623 </cell>
17624 </row>
17625 <row topline="true" bottomline="true">
17626 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17627 \begin_inset Text
17628
17629 \layout Standard
17630
17631 PREFIX/sdcc/lib/pic16
17632 \end_inset
17633 </cell>
17634 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17635 \begin_inset Text
17636
17637 \layout Standard
17638
17639 PIC16 specific libraries
17640 \end_inset
17641 </cell>
17642 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17643 \begin_inset Text
17644
17645 \layout Standard
17646
17647 Linker
17648 \end_inset
17649 </cell>
17650 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17651 \begin_inset Text
17652
17653 \layout Standard
17654
17655 -L
17656 \end_inset
17657 </cell>
17658 </row>
17659 </lyxtabular>
17660
17661 \end_inset
17662
17663
17664 \layout Subsection
17665
17666 Pragmas
17667 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
17668
17669 \end_inset
17670
17671
17672 \layout Standard
17673
17674 PIC16 port currently supports the following pragmas:
17675 \layout List
17676 \labelwidthstring 00.00.0000
17677
17678 stack pragma stack forces the code generator to initialize the stack & frame
17679  pointers at a specific address.
17680  This is an adhoc solution for cases where no STACK directive is available
17681  in the linker script or gplink is not instructed to create a stack section.
17682 \newline
17683 The stack pragma should be used only once in a project.
17684  Multiple pragmas may result in indeterminate behaviour of the program.
17685 \begin_inset Foot
17686 collapsed false
17687
17688 \layout Standard
17689
17690 The old format (ie.
17691  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
17692  cross page boundaries (or even exceed the available data RAM) and crash
17693  the program.
17694  Make sure that stack does not cross page boundaries when using the SMALL
17695  stack model.
17696 \end_inset
17697
17698
17699 \newline
17700 The format is as follows:
17701 \layout LyX-Code
17702
17703 #pragma stack bottom_address [stack_size]
17704 \layout Standard
17705
17706
17707 \emph on
17708 bottom_address
17709 \emph default
17710  is the lower bound of the stack section.
17711  The stack pointer initially will point at address (bottom_address+stack_size-1).
17712 \layout LyX-Code
17713
17714 Example:
17715 \layout LyX-Code
17716
17717 \layout LyX-Code
17718
17719 /* initializes stack of 100 bytes at RAM address 0x200 */
17720 \layout LyX-Code
17721
17722 #pragma stack 0x200 100
17723 \layout Standard
17724
17725 If the stack_size field is omitted then a stack is created with the default
17726  size of 64.
17727  This size might be enough for most programs, but its not enough for operations
17728  with deep function nesting or excessive stack usage.
17729 \layout List
17730 \labelwidthstring 00.00.0000
17731
17732 wparam
17733 \emph on
17734 This pragma is deprecated.
17735  Its use will cause a warning message to be issued.
17736 \emph default
17737
17738 \newline
17739
17740 \layout List
17741 \labelwidthstring 00.00.0000
17742
17743 code place a function symbol at static FLASH address
17744 \layout LyX-Code
17745
17746 Example:
17747 \layout LyX-Code
17748
17749 \layout LyX-Code
17750
17751 /* place function test_func at 0x4000 */
17752 \layout LyX-Code
17753
17754 #pragma code test_func 0x4000
17755 \layout LyX-Code
17756
17757 \layout List
17758 \labelwidthstring 00.00.0000
17759
17760 library instructs the linker to use a library module.
17761 \newline
17762 Usage:
17763 \layout LyX-Code
17764
17765 #pragma library module_name
17766 \layout Standard
17767
17768
17769 \emph on
17770 module_name
17771 \emph default
17772  can be any library or object file (including its path).
17773  Note that there are four reserved keywords which have special meaning.
17774  These are:
17775 \layout Standard
17776 \align center
17777
17778 \begin_inset  Tabular
17779 <lyxtabular version="3" rows="6" columns="3">
17780 <features>
17781 <column alignment="center" valignment="top" leftline="true" width="0">
17782 <column alignment="block" valignment="top" leftline="true" width="20page%">
17783 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
17784 <row topline="true" bottomline="true">
17785 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17786 \begin_inset Text
17787
17788 \layout Standard
17789
17790 Keyword
17791 \end_inset
17792 </cell>
17793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17794 \begin_inset Text
17795
17796 \layout Standard
17797
17798 Description
17799 \end_inset
17800 </cell>
17801 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17802 \begin_inset Text
17803
17804 \layout Standard
17805
17806 Module to link
17807 \end_inset
17808 </cell>
17809 </row>
17810 <row topline="true">
17811 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17812 \begin_inset Text
17813
17814 \layout Standard
17815
17816
17817 \series bold
17818 ignore
17819 \end_inset
17820 </cell>
17821 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17822 \begin_inset Text
17823
17824 \layout Standard
17825
17826 ignore all library pragmas
17827 \end_inset
17828 </cell>
17829 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17830 \begin_inset Text
17831
17832 \layout Standard
17833
17834
17835 \emph on
17836 (none)
17837 \end_inset
17838 </cell>
17839 </row>
17840 <row topline="true">
17841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17842 \begin_inset Text
17843
17844 \layout Standard
17845
17846
17847 \series bold
17848 c
17849 \end_inset
17850 </cell>
17851 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17852 \begin_inset Text
17853
17854 \layout Standard
17855
17856 link the C library
17857 \end_inset
17858 </cell>
17859 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17860 \begin_inset Text
17861
17862 \layout Standard
17863
17864
17865 \emph on
17866 libc18f
17867 \emph default
17868 .lib
17869 \end_inset
17870 </cell>
17871 </row>
17872 <row topline="true">
17873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17874 \begin_inset Text
17875
17876 \layout Standard
17877
17878
17879 \series bold
17880 math
17881 \end_inset
17882 </cell>
17883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17884 \begin_inset Text
17885
17886 \layout Standard
17887
17888 link the Math libarary
17889 \end_inset
17890 </cell>
17891 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17892 \begin_inset Text
17893
17894 \layout Standard
17895
17896
17897 \emph on
17898 libm18f
17899 \emph default
17900 .lib
17901 \end_inset
17902 </cell>
17903 </row>
17904 <row topline="true">
17905 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17906 \begin_inset Text
17907
17908 \layout Standard
17909
17910
17911 \series bold
17912 io
17913 \end_inset
17914 </cell>
17915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17916 \begin_inset Text
17917
17918 \layout Standard
17919
17920 link the I/O library
17921 \end_inset
17922 </cell>
17923 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17924 \begin_inset Text
17925
17926 \layout Standard
17927
17928
17929 \emph on
17930 libio18f*
17931 \emph default
17932 .lib
17933 \end_inset
17934 </cell>
17935 </row>
17936 <row topline="true" bottomline="true">
17937 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17938 \begin_inset Text
17939
17940 \layout Standard
17941
17942
17943 \series bold
17944 debug
17945 \end_inset
17946 </cell>
17947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17948 \begin_inset Text
17949
17950 \layout Standard
17951
17952 link the debug library
17953 \end_inset
17954 </cell>
17955 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17956 \begin_inset Text
17957
17958 \layout Standard
17959
17960
17961 \emph on
17962 libdebug
17963 \emph default
17964 .lib
17965 \end_inset
17966 </cell>
17967 </row>
17968 </lyxtabular>
17969
17970 \end_inset
17971
17972
17973 \newline
17974 * is the device number, i.e.
17975  452 for PIC18F452 MCU.
17976 \layout Standard
17977
17978 This feature allows for linking with specific libraries withoug having to
17979  explicit name them in the command line.
17980  Note that the
17981 \noun on
17982 ignore
17983 \noun default
17984  keyword will reject all modules specified by the library pragma.
17985 \layout List
17986 \labelwidthstring 00.00.0000
17987
17988 udata pragma udata instructs the compiler to emit code so that linker will
17989  place a variable at a specific memory bank
17990 \layout LyX-Code
17991
17992 Example:
17993 \layout LyX-Code
17994
17995 \layout LyX-Code
17996
17997 /* places variable foo at bank2 */
17998 \layout LyX-Code
17999
18000 #pragma udata bank2 foo
18001 \layout LyX-Code
18002
18003 char foo;
18004 \layout Standard
18005
18006 In order for this pragma to work extra SECTION directives should be added
18007  in the .lkr script.
18008  In the following example a sample .lkr file is shown:
18009 \layout LyX-Code
18010
18011 \layout LyX-Code
18012
18013 // Sample linker script for the PIC18F452 processor
18014 \layout LyX-Code
18015
18016 LIBPATH .
18017 \layout LyX-Code
18018
18019 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
18020 \layout LyX-Code
18021
18022 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
18023 \layout LyX-Code
18024
18025 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
18026 \layout LyX-Code
18027
18028 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
18029 \layout LyX-Code
18030
18031 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
18032 \layout LyX-Code
18033
18034 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
18035 \layout LyX-Code
18036
18037 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
18038 \layout LyX-Code
18039
18040 \layout LyX-Code
18041
18042 DATABANK   NAME=gpr0       START=0x80           END=0xFF
18043 \layout LyX-Code
18044
18045 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
18046 \layout LyX-Code
18047
18048 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
18049 \layout LyX-Code
18050
18051 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
18052 \layout LyX-Code
18053
18054 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
18055 \layout LyX-Code
18056
18057 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
18058 \layout LyX-Code
18059
18060 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
18061 \layout LyX-Code
18062
18063 \layout LyX-Code
18064
18065 SECTION    NAME=CONFIG     ROM=config
18066 \layout LyX-Code
18067
18068 \layout LyX-Code
18069
18070 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
18071 \layout LyX-Code
18072
18073 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
18074 \layout LyX-Code
18075
18076 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
18077 \layout LyX-Code
18078
18079 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
18080 \layout LyX-Code
18081
18082 SECTION    NAME=bank4      RAM=gpr4
18083 \layout LyX-Code
18084
18085 SECTION    NAME=bank5      RAM=gpr5
18086 \layout Standard
18087
18088 The linker will recognise the section name set in the pragma statement and
18089  will position the variable at the memory bank set with the RAM field at
18090  the SECTION line in the linker script file.
18091 \layout Subsection
18092
18093 Header Files
18094 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
18095
18096 \end_inset
18097
18098
18099 \layout Standard
18100
18101 There is one main header file that can be included to the source files using
18102  the pic16 port.
18103  That file is the
18104 \series bold
18105 pic18fregs.h
18106 \series default
18107 .
18108  This header file contains the definitions for the processor special registers,
18109  so it is necessary if the source accesses them.
18110  It can be included by adding the following line in the beginning of the
18111  file:
18112 \layout LyX-Code
18113
18114 #include <pic18fregs.h>
18115 \layout Standard
18116
18117 The specific microcontroller is selected within the pic18fregs.h automatically,
18118  so the same source can be used with a variety of devices.
18119 \layout Subsection
18120
18121 Libraries
18122 \layout Standard
18123
18124 The libraries that PIC16
18125 \begin_inset LatexCommand \index{PIC16}
18126
18127 \end_inset
18128
18129  port depends on are the microcontroller device libraries which contain
18130  the symbol definitions for the microcontroller special function registers.
18131  These libraries have the format pic18fxxxx.lib, where
18132 \emph on
18133 xxxx
18134 \emph default
18135  is the microcontroller identification number.
18136  The specific library is selected automatically by the compiler at link
18137  stage according to the selected device.
18138 \layout Standard
18139
18140 Libraries are created with gplib which is part of the gputils package
18141 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
18142
18143 \end_inset
18144
18145 .
18146 \layout Subsubsection*
18147
18148 Building the libraries
18149 \layout Standard
18150
18151 Before using SDCC/pic16 there are some libraries that need to be compiled.
18152  This process is not done automatically by SDCC since not all users use
18153  SDCC for pic16 projects.
18154  So each user should compile the libraries separately.
18155 \layout Standard
18156
18157 The steps to compile the pic16 libraries under Linux are:
18158 \layout LyX-Code
18159
18160 cd device/lib/pic16
18161 \layout LyX-Code
18162
18163 ./configure
18164 \layout LyX-Code
18165
18166 make
18167 \layout LyX-Code
18168
18169 cd ..
18170 \layout LyX-Code
18171
18172 make model-pic16
18173 \layout LyX-Code
18174
18175 su -c 'make install'     # install the libraries, you need the root password
18176 \layout Standard
18177
18178 If you need to install the headers too, do:
18179 \layout LyX-Code
18180
18181 cd device/include
18182 \layout LyX-Code
18183
18184 su -c 'make install'     # install the headers, you need the root password
18185 \layout Standard
18186
18187 There exist a special target to build the I/O libraries.
18188  This target is not automatically build because it will build the I/O library
18189  for
18190 \emph on
18191 every
18192 \emph default
18193  supported device.
18194  This way building will take quite a lot of time.
18195  Users are advised to edit the
18196 \series bold
18197 device/lib/pic16/pics.build
18198 \series default
18199  file and then execute:
18200 \layout LyX-Code
18201
18202 make lib-io
18203 \layout Subsection
18204
18205 Memory Models
18206 \layout Standard
18207
18208 The following memory models are supported by the PIC16 port:
18209 \layout Itemize
18210
18211 small model
18212 \layout Itemize
18213
18214 large model
18215 \layout Standard
18216
18217 Memory model affects the default size of pointers within the source.
18218  The sizes are shown in the next table:
18219 \layout Standard
18220 \align center
18221
18222 \begin_inset  Tabular
18223 <lyxtabular version="3" rows="3" columns="3">
18224 <features>
18225 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18226 <column alignment="center" valignment="top" leftline="true" width="0">
18227 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18228 <row topline="true" bottomline="true">
18229 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18230 \begin_inset Text
18231
18232 \layout Standard
18233
18234 Pointer sizes according to memory model
18235 \end_inset
18236 </cell>
18237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18238 \begin_inset Text
18239
18240 \layout Standard
18241
18242 small model
18243 \end_inset
18244 </cell>
18245 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18246 \begin_inset Text
18247
18248 \layout Standard
18249
18250 large model
18251 \end_inset
18252 </cell>
18253 </row>
18254 <row topline="true" bottomline="true">
18255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18256 \begin_inset Text
18257
18258 \layout Standard
18259
18260 code pointers
18261 \end_inset
18262 </cell>
18263 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18264 \begin_inset Text
18265
18266 \layout Standard
18267
18268 16-bits
18269 \end_inset
18270 </cell>
18271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18272 \begin_inset Text
18273
18274 \layout Standard
18275
18276 24-bits
18277 \end_inset
18278 </cell>
18279 </row>
18280 <row topline="true" bottomline="true">
18281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18282 \begin_inset Text
18283
18284 \layout Standard
18285
18286 data pointers
18287 \end_inset
18288 </cell>
18289 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
18290 \begin_inset Text
18291
18292 \layout Standard
18293
18294 16-bits
18295 \end_inset
18296 </cell>
18297 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18298 \begin_inset Text
18299
18300 \layout Standard
18301
18302 16-bits
18303 \end_inset
18304 </cell>
18305 </row>
18306 </lyxtabular>
18307
18308 \end_inset
18309
18310
18311 \layout Standard
18312
18313 It is advisable that all sources within a project are compiled with the
18314  same memory model.
18315  If one wants to override the default memory model, this can be done by
18316  declaring a pointer as
18317 \series bold
18318 far
18319 \series default
18320  or
18321 \series bold
18322 near
18323 \series default
18324 .
18325  Far selects large memory model's pointers, while near selects small memory
18326  model's pointers.
18327 \layout Standard
18328
18329 The standard device libraries (see
18330 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
18331
18332 \end_inset
18333
18334 ) contain no reference to pointers, so they can be used with both memory
18335  models.
18336 \layout Subsection
18337
18338 Stack
18339 \layout Standard
18340
18341 The stack implementation for the PIC16 port uses two indirect registers,
18342  FSR1 and FSR2.
18343 \layout List
18344 \labelwidthstring 00.00.0000
18345
18346 FSR1 is assigned as stack pointer
18347 \layout List
18348 \labelwidthstring 00.00.0000
18349
18350 FSR2 is assigned as frame pointer
18351 \layout Standard
18352
18353 The following stack models are supported by the PIC16 port
18354 \layout Itemize
18355
18356
18357 \noun on
18358 small
18359 \noun default
18360  model
18361 \layout Itemize
18362
18363
18364 \noun on
18365 large
18366 \noun default
18367  model
18368 \layout Standard
18369
18370
18371 \noun on
18372 Small
18373 \noun default
18374  model means that only the FSRxL byte is used to access stack and frame,
18375  while
18376 \emph on
18377 \noun on
18378 large
18379 \emph default
18380 \noun default
18381  uses both FSRxL and FSRxH registers.
18382  The following table shows the stack/frame pointers sizes according to stack
18383  model and the maximum space they can address:
18384 \layout Standard
18385 \align center
18386
18387 \begin_inset  Tabular
18388 <lyxtabular version="3" rows="3" columns="3">
18389 <features>
18390 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18391 <column alignment="center" valignment="top" leftline="true" width="0">
18392 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18393 <row topline="true" bottomline="true">
18394 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18395 \begin_inset Text
18396
18397 \layout Standard
18398
18399 Stack & Frame pointer sizes according to stack model
18400 \end_inset
18401 </cell>
18402 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18403 \begin_inset Text
18404
18405 \layout Standard
18406
18407 small
18408 \end_inset
18409 </cell>
18410 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18411 \begin_inset Text
18412
18413 \layout Standard
18414
18415 large
18416 \end_inset
18417 </cell>
18418 </row>
18419 <row topline="true">
18420 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18421 \begin_inset Text
18422
18423 \layout Standard
18424
18425 Stack pointer FSR1
18426 \end_inset
18427 </cell>
18428 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18429 \begin_inset Text
18430
18431 \layout Standard
18432
18433 8-bits
18434 \end_inset
18435 </cell>
18436 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18437 \begin_inset Text
18438
18439 \layout Standard
18440
18441 16-bits
18442 \end_inset
18443 </cell>
18444 </row>
18445 <row topline="true" bottomline="true">
18446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18447 \begin_inset Text
18448
18449 \layout Standard
18450
18451 Frame pointer FSR2
18452 \end_inset
18453 </cell>
18454 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18455 \begin_inset Text
18456
18457 \layout Standard
18458
18459 8-bits
18460 \end_inset
18461 </cell>
18462 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18463 \begin_inset Text
18464
18465 \layout Standard
18466
18467 16-bits
18468 \end_inset
18469 </cell>
18470 </row>
18471 </lyxtabular>
18472
18473 \end_inset
18474
18475
18476 \layout Standard
18477
18478
18479 \noun on
18480 Large
18481 \noun default
18482 stack model is currently not working properly throughout the code generator.
18483  So its use is not advised.
18484  Also there are some other points that need special care:
18485 \newline
18486
18487 \layout Enumerate
18488
18489 Do not create stack sections with size more than one physical bank (that
18490  is 256 bytes)
18491 \layout Enumerate
18492
18493 Stack sections should no cross physical bank limits (i.e.
18494  #pragma stack 0x50 0x100)
18495 \layout Standard
18496
18497 These limitations are caused by the fact that only FSRxL is modified when
18498  using SMALL stack model, so no more than 256 bytes of stack can be used.
18499  This problem will disappear after LARGE model is fully implemented.
18500 \layout Subsection
18501
18502 Functions
18503 \layout Standard
18504
18505 In addition to the standard SDCC function keywords, PIC16 port makes available
18506  two more:
18507 \layout List
18508 \labelwidthstring 00.00.0000
18509
18510 wparam Use the WREG to pass one byte of the first function argument.
18511  This improves speed but you may not use this for functions with arguments
18512  that are called via function pointers, otherwise the first byte of the
18513  first parameter will get lost.
18514  Usage:
18515 \layout LyX-Code
18516
18517 void func_wparam(int a) wparam
18518 \layout LyX-Code
18519
18520 {
18521 \layout LyX-Code
18522
18523     /* WREG hold the lower part of a */
18524 \layout LyX-Code
18525
18526     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
18527  */
18528 \layout LyX-Code
18529
18530 ...
18531 \layout LyX-Code
18532
18533 }
18534 \layout Standard
18535
18536 This keyword replaces the deprecated wparam pragma.
18537 \layout List
18538 \labelwidthstring 00.00.0000
18539
18540 shadowregs When entering/exiting an ISR, it is possible to take advantage
18541  of the PIC18F hardware shadow registers which hold the values of WREG,
18542  STATUS and BSR registers.
18543  This can be done by adding the keyword
18544 \emph on
18545 shadowregs
18546 \emph default
18547  before the
18548 \emph on
18549 interrupt
18550 \emph default
18551  keyword in the function's header.
18552 \layout LyX-Code
18553
18554 void isr_shadow(void) shadowregs interrupt 1
18555 \layout LyX-Code
18556
18557 {
18558 \layout LyX-Code
18559
18560 ...
18561 \layout LyX-Code
18562
18563 }
18564 \layout Standard
18565
18566
18567 \emph on
18568 shadowregs
18569 \emph default
18570  instructs the code generator not to store/restore WREG, STATUS, BSR when
18571  entering/exiting the ISR.
18572 \layout Subsection
18573
18574 Function return values
18575 \layout Standard
18576
18577 Return values from functions are placed to the appropriate registers following
18578  a modified Microchip policy optimized for SDCC.
18579  The following table shows these registers:
18580 \layout Standard
18581 \align center
18582
18583 \begin_inset  Tabular
18584 <lyxtabular version="3" rows="6" columns="2">
18585 <features>
18586 <column alignment="center" valignment="top" leftline="true" width="0">
18587 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18588 <row topline="true" bottomline="true">
18589 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18590 \begin_inset Text
18591
18592 \layout Standard
18593
18594 size
18595 \end_inset
18596 </cell>
18597 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18598 \begin_inset Text
18599
18600 \layout Standard
18601
18602 destination register
18603 \end_inset
18604 </cell>
18605 </row>
18606 <row topline="true">
18607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18608 \begin_inset Text
18609
18610 \layout Standard
18611
18612 8 bits
18613 \end_inset
18614 </cell>
18615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18616 \begin_inset Text
18617
18618 \layout Standard
18619
18620 WREG
18621 \end_inset
18622 </cell>
18623 </row>
18624 <row topline="true">
18625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18626 \begin_inset Text
18627
18628 \layout Standard
18629
18630 16 bits
18631 \end_inset
18632 </cell>
18633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18634 \begin_inset Text
18635
18636 \layout Standard
18637
18638 PRODL:WREG
18639 \end_inset
18640 </cell>
18641 </row>
18642 <row topline="true">
18643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18644 \begin_inset Text
18645
18646 \layout Standard
18647
18648 24 bits
18649 \end_inset
18650 </cell>
18651 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18652 \begin_inset Text
18653
18654 \layout Standard
18655
18656 PRODH:PRODL:WREG
18657 \end_inset
18658 </cell>
18659 </row>
18660 <row topline="true">
18661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18662 \begin_inset Text
18663
18664 \layout Standard
18665
18666 32 bits
18667 \end_inset
18668 </cell>
18669 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18670 \begin_inset Text
18671
18672 \layout Standard
18673
18674 FSR0L:PRODH:PRODL:WREG
18675 \end_inset
18676 </cell>
18677 </row>
18678 <row topline="true" bottomline="true">
18679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18680 \begin_inset Text
18681
18682 \layout Standard
18683
18684 >32 bits
18685 \end_inset
18686 </cell>
18687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18688 \begin_inset Text
18689
18690 \layout Standard
18691
18692 on stack, FSR0 points to the beginning
18693 \end_inset
18694 </cell>
18695 </row>
18696 </lyxtabular>
18697
18698 \end_inset
18699
18700
18701 \layout Subsection
18702
18703 Interrupts
18704 \layout Standard
18705
18706 An interrupt servive routine (ISR) is declared using the
18707 \emph on
18708 interrupt
18709 \emph default
18710  keyword.
18711 \layout LyX-Code
18712
18713 void isr(void) interrupt
18714 \emph on
18715 n
18716 \layout LyX-Code
18717
18718 {
18719 \layout LyX-Code
18720
18721 ...
18722 \layout LyX-Code
18723
18724 }
18725 \layout Standard
18726
18727
18728 \emph on
18729 n
18730 \emph default
18731  is the interrupt number, which for PIC18F devices can be:
18732 \layout Standard
18733 \align center
18734
18735 \begin_inset  Tabular
18736 <lyxtabular version="3" rows="4" columns="3">
18737 <features>
18738 <column alignment="center" valignment="top" leftline="true" width="0">
18739 <column alignment="center" valignment="top" leftline="true" width="0">
18740 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18741 <row topline="true" bottomline="true">
18742 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18743 \begin_inset Text
18744
18745 \layout Standard
18746
18747
18748 \emph on
18749 n
18750 \end_inset
18751 </cell>
18752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18753 \begin_inset Text
18754
18755 \layout Standard
18756
18757 Interrupt Vector
18758 \end_inset
18759 </cell>
18760 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18761 \begin_inset Text
18762
18763 \layout Standard
18764
18765 Interrupt Vector Address
18766 \end_inset
18767 </cell>
18768 </row>
18769 <row topline="true">
18770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18771 \begin_inset Text
18772
18773 \layout Standard
18774
18775 0
18776 \end_inset
18777 </cell>
18778 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18779 \begin_inset Text
18780
18781 \layout Standard
18782
18783 RESET vector
18784 \end_inset
18785 </cell>
18786 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18787 \begin_inset Text
18788
18789 \layout Standard
18790
18791 0x000000
18792 \end_inset
18793 </cell>
18794 </row>
18795 <row topline="true">
18796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18797 \begin_inset Text
18798
18799 \layout Standard
18800
18801
18802 \family roman
18803 \series medium
18804 \shape up
18805 \size normal
18806 \emph off
18807 \bar no
18808 \noun off
18809 \color none
18810 1
18811 \end_inset
18812 </cell>
18813 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18814 \begin_inset Text
18815
18816 \layout Standard
18817
18818
18819 \family roman
18820 \series medium
18821 \shape up
18822 \size normal
18823 \emph off
18824 \bar no
18825 \noun off
18826 \color none
18827 HIGH priority interrupts
18828 \end_inset
18829 </cell>
18830 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18831 \begin_inset Text
18832
18833 \layout Standard
18834
18835 0x000008
18836 \end_inset
18837 </cell>
18838 </row>
18839 <row topline="true" bottomline="true">
18840 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18841 \begin_inset Text
18842
18843 \layout Standard
18844
18845 2
18846 \end_inset
18847 </cell>
18848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18849 \begin_inset Text
18850
18851 \layout Standard
18852
18853 LOW priority interrupts
18854 \end_inset
18855 </cell>
18856 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18857 \begin_inset Text
18858
18859 \layout Standard
18860
18861 0x000018
18862 \end_inset
18863 </cell>
18864 </row>
18865 </lyxtabular>
18866
18867 \end_inset
18868
18869
18870 \layout Standard
18871
18872 When generating assembly code for ISR the code generator places a
18873 \noun on
18874 goto
18875 \noun default
18876 instruction at the
18877 \emph on
18878 Interrupt Vector Address
18879 \emph default
18880  which points at the genetated ISR.
18881  This single GOTO instruction is part of an automatically generated
18882 \emph on
18883 interrupt entry point
18884 \emph default
18885  function.
18886  The actuall ISR code is placed as normally would in the code space.
18887  Upon interrupt request, the GOTO instruction is executed which jumps to
18888  the ISR code.
18889  When declaring interrupt functions as _naked this GOTO instruction is
18890 \series bold
18891 not
18892 \series default
18893  generated.
18894  The whole interrupt functions is therefore placed at the Interrupt Vector
18895  Address of the specific interrupt.
18896  This is not a problem for the LOW priority interrupts, but it is a problem
18897  for the RESET and the HIGH priority interrupts because code may be written
18898  at the next interrupt´s vector address and cause undeterminate program
18899  behaviour if that interrupt is raised.
18900 \begin_inset Foot
18901 collapsed false
18902
18903 \layout Standard
18904
18905 This is not a problem when
18906 \layout Enumerate
18907
18908 this is a HIGH interrupt ISR and LOW interrupts are
18909 \emph on
18910 disabled
18911 \emph default
18912  or not used.
18913 \layout Enumerate
18914
18915 when the ISR is small enough not to reach the next interrupt´s vector address.
18916 \end_inset
18917
18918
18919 \layout Standard
18920
18921
18922 \emph on
18923 n
18924 \emph default
18925  is possible to be omitted.
18926  This way a function is generated similar to an ISR, but it is not assigned
18927  to any interrupt.
18928 \layout Standard
18929
18930 When entering an interrupt, currently the PIC16
18931 \begin_inset LatexCommand \index{PIC16}
18932
18933 \end_inset
18934
18935  port automatically saves the following registers:
18936 \layout Itemize
18937
18938 WREG
18939 \layout Itemize
18940
18941 STATUS
18942 \layout Itemize
18943
18944 BSR
18945 \layout Itemize
18946
18947 PROD (PRODL and PRODH)
18948 \layout Itemize
18949
18950 FSR0 (FSR0L and FSR0H)
18951 \layout Standard
18952
18953 These registers are restored upon return from the interrupt routine.
18954 \begin_inset Foot
18955 collapsed false
18956
18957 \layout Standard
18958
18959 NOTE that when the _naked attribute is specified for an interrupt routine,
18960  then NO registers are stored or restored.
18961 \end_inset
18962
18963
18964 \layout Subsection
18965
18966 Generic Pointers
18967 \layout Standard
18968
18969 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
18970  There are 3 types of generic pointers currently implemented data, code
18971  and eeprom pointers.
18972  They are differentiated by the value of the 7th and 6th bits of the upper
18973  byte:
18974 \layout Standard
18975 \align center
18976
18977 \begin_inset  Tabular
18978 <lyxtabular version="3" rows="5" columns="5">
18979 <features>
18980 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18981 <column alignment="center" valignment="top" width="0">
18982 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18983 <column alignment="center" valignment="top" width="0">
18984 <column alignment="left" valignment="top" rightline="true" width="0">
18985 <row topline="true" bottomline="true">
18986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18987 \begin_inset Text
18988
18989 \layout Standard
18990
18991 pointer type
18992 \end_inset
18993 </cell>
18994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18995 \begin_inset Text
18996
18997 \layout Standard
18998
18999 7th bit
19000 \end_inset
19001 </cell>
19002 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19003 \begin_inset Text
19004
19005 \layout Standard
19006
19007 6th bit
19008 \end_inset
19009 </cell>
19010 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19011 \begin_inset Text
19012
19013 \layout Standard
19014
19015 rest of the pointer
19016 \end_inset
19017 </cell>
19018 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19019 \begin_inset Text
19020
19021 \layout Standard
19022
19023 descrption
19024 \end_inset
19025 </cell>
19026 </row>
19027 <row topline="true" bottomline="true">
19028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19029 \begin_inset Text
19030
19031 \layout Standard
19032
19033 data
19034 \end_inset
19035 </cell>
19036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19037 \begin_inset Text
19038
19039 \layout Standard
19040
19041 1
19042 \end_inset
19043 </cell>
19044 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19045 \begin_inset Text
19046
19047 \layout Standard
19048
19049 0
19050 \end_inset
19051 </cell>
19052 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19053 \begin_inset Text
19054
19055 \layout Standard
19056
19057
19058 \family typewriter
19059 \shape slanted
19060 \emph on
19061 uuuuuu uuuuxxxx xxxxxxxx
19062 \end_inset
19063 </cell>
19064 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19065 \begin_inset Text
19066
19067 \layout Standard
19068
19069 a 12-bit data pointer in data RAM memory
19070 \end_inset
19071 </cell>
19072 </row>
19073 <row bottomline="true">
19074 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19075 \begin_inset Text
19076
19077 \layout Standard
19078
19079 code
19080 \end_inset
19081 </cell>
19082 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19083 \begin_inset Text
19084
19085 \layout Standard
19086
19087 0
19088 \end_inset
19089 </cell>
19090 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19091 \begin_inset Text
19092
19093 \layout Standard
19094
19095 0
19096 \end_inset
19097 </cell>
19098 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19099 \begin_inset Text
19100
19101 \layout Standard
19102
19103
19104 \family typewriter
19105 \shape slanted
19106 \emph on
19107 uxxxxx xxxxxxxx xxxxxxxx
19108 \end_inset
19109 </cell>
19110 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19111 \begin_inset Text
19112
19113 \layout Standard
19114
19115 a 21-bit code pointer in FLASH memory
19116 \end_inset
19117 </cell>
19118 </row>
19119 <row bottomline="true">
19120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19121 \begin_inset Text
19122
19123 \layout Standard
19124
19125 eeprom
19126 \end_inset
19127 </cell>
19128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19129 \begin_inset Text
19130
19131 \layout Standard
19132
19133 0
19134 \end_inset
19135 </cell>
19136 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19137 \begin_inset Text
19138
19139 \layout Standard
19140
19141 1
19142 \end_inset
19143 </cell>
19144 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19145 \begin_inset Text
19146
19147 \layout Standard
19148
19149
19150 \family typewriter
19151 \shape slanted
19152 \emph on
19153 uuuuuu uuuuuuxx xxxxxxxx
19154 \end_inset
19155 </cell>
19156 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19157 \begin_inset Text
19158
19159 \layout Standard
19160
19161 a 10-bit eeprom pointer in EEPROM memory
19162 \end_inset
19163 </cell>
19164 </row>
19165 <row bottomline="true">
19166 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19167 \begin_inset Text
19168
19169 \layout Standard
19170
19171 (unimplemented)
19172 \end_inset
19173 </cell>
19174 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19175 \begin_inset Text
19176
19177 \layout Standard
19178
19179 1
19180 \end_inset
19181 </cell>
19182 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19183 \begin_inset Text
19184
19185 \layout Standard
19186
19187 1
19188 \end_inset
19189 </cell>
19190 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19191 \begin_inset Text
19192
19193 \layout Standard
19194
19195
19196 \family typewriter
19197 \shape slanted
19198 \emph on
19199 xxxxxx xxxxxxxx xxxxxxxx
19200 \end_inset
19201 </cell>
19202 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19203 \begin_inset Text
19204
19205 \layout Standard
19206
19207 unimplemented pointer type
19208 \end_inset
19209 </cell>
19210 </row>
19211 </lyxtabular>
19212
19213 \end_inset
19214
19215
19216 \layout Standard
19217
19218 Generic pointer are read and written with a set of library functions which
19219  read/write 1, 2, 3, 4 bytes.
19220 \layout Subsection
19221
19222 PIC16 C Libraries
19223 \layout Subsubsection
19224
19225 Standard I/O Streams
19226 \layout Standard
19227
19228 In the
19229 \emph on
19230 stdio.h
19231 \emph default
19232  the type FILE is defined as:
19233 \layout LyX-Code
19234
19235 typedef char * FILE;
19236 \layout Standard
19237
19238 This type is the stream type implemented I/O in the PIC18F devices.
19239  Also the standard input and output streams are declared in stdio.h:
19240 \layout LyX-Code
19241
19242 extern FILE * stdin;
19243 \layout LyX-Code
19244
19245 extern FILE * stdout;
19246 \layout Standard
19247
19248 The FILE type is actually a generic pointer which defines one more type
19249  of generic pointers, the
19250 \emph on
19251 stream
19252 \emph default
19253 pointer.
19254  This new type has the format:
19255 \layout Standard
19256 \align center
19257
19258 \begin_inset  Tabular
19259 <lyxtabular version="3" rows="2" columns="7">
19260 <features>
19261 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19262 <column alignment="center" valignment="top" width="0">
19263 <column alignment="center" valignment="top" leftline="true" width="0">
19264 <column alignment="center" valignment="top" leftline="true" width="0">
19265 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19266 <column alignment="center" valignment="top" width="0">
19267 <column alignment="left" valignment="top" rightline="true" width="0">
19268 <row topline="true" bottomline="true">
19269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19270 \begin_inset Text
19271
19272 \layout Standard
19273
19274 pointer type
19275 \end_inset
19276 </cell>
19277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19278 \begin_inset Text
19279
19280 \layout Standard
19281
19282 <7:6>
19283 \end_inset
19284 </cell>
19285 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19286 \begin_inset Text
19287
19288 \layout Standard
19289
19290 <5>
19291 \end_inset
19292 </cell>
19293 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19294 \begin_inset Text
19295
19296 \layout Standard
19297
19298 <4>
19299 \end_inset
19300 </cell>
19301 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19302 \begin_inset Text
19303
19304 \layout Standard
19305
19306 <3:0>
19307 \end_inset
19308 </cell>
19309 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19310 \begin_inset Text
19311
19312 \layout Standard
19313
19314 rest of the pointer
19315 \end_inset
19316 </cell>
19317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19318 \begin_inset Text
19319
19320 \layout Standard
19321
19322 descrption
19323 \end_inset
19324 </cell>
19325 </row>
19326 <row topline="true" bottomline="true">
19327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19328 \begin_inset Text
19329
19330 \layout Standard
19331
19332 stream
19333 \end_inset
19334 </cell>
19335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19336 \begin_inset Text
19337
19338 \layout Standard
19339
19340 00
19341 \end_inset
19342 </cell>
19343 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19344 \begin_inset Text
19345
19346 \layout Standard
19347
19348 1
19349 \end_inset
19350 </cell>
19351 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19352 \begin_inset Text
19353
19354 \layout Standard
19355
19356 0
19357 \end_inset
19358 </cell>
19359 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19360 \begin_inset Text
19361
19362 \layout Standard
19363
19364 nnnn
19365 \end_inset
19366 </cell>
19367 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19368 \begin_inset Text
19369
19370 \layout Standard
19371
19372
19373 \family typewriter
19374 \shape slanted
19375 \emph on
19376 uuuuuuuu uuuuuuuu
19377 \end_inset
19378 </cell>
19379 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19380 \begin_inset Text
19381
19382 \layout Standard
19383
19384 upper byte high nubble is 0x2n, the rest are zeroes
19385 \end_inset
19386 </cell>
19387 </row>
19388 </lyxtabular>
19389
19390 \end_inset
19391
19392
19393 \layout Standard
19394
19395 Currently implemented there are 3 types of streams defined:
19396 \layout Standard
19397 \align center
19398
19399 \begin_inset  Tabular
19400 <lyxtabular version="3" rows="4" columns="4">
19401 <features>
19402 <column alignment="center" valignment="top" leftline="true" width="0">
19403 <column alignment="center" valignment="top" leftline="true" width="0">
19404 <column alignment="center" valignment="top" leftline="true" width="0">
19405 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19406 <row topline="true" bottomline="true">
19407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19408 \begin_inset Text
19409
19410 \layout Standard
19411
19412 stream type
19413 \end_inset
19414 </cell>
19415 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19416 \begin_inset Text
19417
19418 \layout Standard
19419
19420 value
19421 \end_inset
19422 </cell>
19423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19424 \begin_inset Text
19425
19426 \layout Standard
19427
19428 module
19429 \end_inset
19430 </cell>
19431 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19432 \begin_inset Text
19433
19434 \layout Standard
19435
19436 description
19437 \end_inset
19438 </cell>
19439 </row>
19440 <row topline="true">
19441 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19442 \begin_inset Text
19443
19444 \layout Standard
19445
19446 STREAM_USART
19447 \end_inset
19448 </cell>
19449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19450 \begin_inset Text
19451
19452 \layout Standard
19453
19454
19455 \family typewriter
19456 0x200000UL
19457 \end_inset
19458 </cell>
19459 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19460 \begin_inset Text
19461
19462 \layout Standard
19463
19464 USART
19465 \end_inset
19466 </cell>
19467 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19468 \begin_inset Text
19469
19470 \layout Standard
19471
19472 Writes/Reads characters via the USART peripheral
19473 \end_inset
19474 </cell>
19475 </row>
19476 <row topline="true">
19477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19478 \begin_inset Text
19479
19480 \layout Standard
19481
19482 STREAM_MSSP
19483 \end_inset
19484 </cell>
19485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19486 \begin_inset Text
19487
19488 \layout Standard
19489
19490
19491 \family typewriter
19492 0x210000UL
19493 \end_inset
19494 </cell>
19495 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19496 \begin_inset Text
19497
19498 \layout Standard
19499
19500 MSSP
19501 \end_inset
19502 </cell>
19503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19504 \begin_inset Text
19505
19506 \layout Standard
19507
19508 Writes/Reads characters via the MSSP peripheral
19509 \end_inset
19510 </cell>
19511 </row>
19512 <row topline="true" bottomline="true">
19513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19514 \begin_inset Text
19515
19516 \layout Standard
19517
19518 STREAM_USER
19519 \end_inset
19520 </cell>
19521 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19522 \begin_inset Text
19523
19524 \layout Standard
19525
19526
19527 \family typewriter
19528 0x2f0000UL
19529 \end_inset
19530 </cell>
19531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19532 \begin_inset Text
19533
19534 \layout Standard
19535
19536 (none)
19537 \end_inset
19538 </cell>
19539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19540 \begin_inset Text
19541
19542 \layout Standard
19543
19544 Writes/Reads characters via used defined functions
19545 \end_inset
19546 </cell>
19547 </row>
19548 </lyxtabular>
19549
19550 \end_inset
19551
19552
19553 \layout Standard
19554
19555 The stream identifiers are declared as macros in the stdio.h header.
19556 \layout Standard
19557
19558 In the libc library there exist the functions that are used to write to
19559  each of the above streams.
19560  These are
19561 \layout List
19562 \labelwidthstring 00.00.0000
19563
19564 _
19565 \begin_inset ERT
19566 status Collapsed
19567
19568 \layout Standard
19569
19570 \backslash
19571 /
19572 \end_inset
19573
19574 _stream_usart_putchar writes a character at the USART stream
19575 \layout List
19576 \labelwidthstring 00.00.0000
19577
19578 _
19579 \begin_inset ERT
19580 status Collapsed
19581
19582 \layout Standard
19583
19584 \backslash
19585 /
19586 \end_inset
19587
19588 _stream_mssp_putchar writes a character at the MSSP stream
19589 \layout List
19590 \labelwidthstring 00.00.0000
19591
19592 putchar dummy function.
19593  This writes a character to a user specified manner.
19594 \layout Standard
19595
19596 In order to increase performance
19597 \emph on
19598 putchar
19599 \emph default
19600 is declared in stdio.h as having its parameter in WREG (it has the wparam
19601  keyword).
19602  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
19603  in a user-friendly way.
19604
19605 \emph on
19606 arg
19607 \emph default
19608  is the name of the variable that holds the character to print.
19609  An example follows:
19610 \layout LyX-Code
19611
19612 #include <pic18fregs.h>
19613 \newline
19614 #include <stdio.h>
19615 \newline
19616
19617 \newline
19618 PUTCHAR( c )
19619 \layout LyX-Code
19620
19621 {
19622 \layout LyX-Code
19623
19624     PORTA = c;    /* dump character c to PORTA */
19625 \layout LyX-Code
19626
19627 }
19628 \newline
19629
19630 \newline
19631 void main(void)
19632 \layout LyX-Code
19633
19634 {
19635 \layout LyX-Code
19636
19637     stdout = STREAM_USER;    /* this is not necessery, since stdout points
19638 \layout LyX-Code
19639
19640                               * by default to STREAM_USER */
19641 \layout LyX-Code
19642
19643     printf (¨This is a printf test
19644 \backslash
19645 n¨);
19646 \layout LyX-Code
19647
19648 }
19649 \layout LyX-Code
19650
19651 \layout Subsubsection
19652
19653 Printing functions
19654 \layout Standard
19655
19656 PIC16 contains an implementation of the printf-family of functions.
19657  There exist the following functions:
19658 \layout LyX-Code
19659
19660 extern unsigned int sprintf(char *buf, char *fmt, ...);
19661 \layout LyX-Code
19662
19663 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
19664 \layout LyX-Code
19665
19666 \layout LyX-Code
19667
19668 extern unsigned int printf(char *fmt, ...);
19669 \layout LyX-Code
19670
19671 extern unsigned int vprintf(char *fmt, va_lista ap);
19672 \layout LyX-Code
19673
19674 \layout LyX-Code
19675
19676 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
19677 \layout LyX-Code
19678
19679 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
19680 \layout Standard
19681
19682 For sprintf and vsprintf
19683 \emph on
19684 buf
19685 \emph default
19686 should normally be a data pointer where the resulting string will be placed.
19687  No range checking is done so the user should allocate the necessery buffer.
19688  For fprintf and vfprintf
19689 \emph on
19690 fp
19691 \emph default
19692  should be a stream pointer (i.e.
19693  stdout, STREAM_MSSP, etc...).
19694 \layout Subsubsection
19695
19696 Signals
19697 \layout Standard
19698
19699 The PIC18F family of microcontrollers supports a number of interrupt sources.
19700  A list of these interrupts is shown in the following table:
19701 \layout Standard
19702 \align center
19703
19704 \begin_inset  Tabular
19705 <lyxtabular version="3" rows="11" columns="4">
19706 <features>
19707 <column alignment="left" valignment="top" leftline="true" width="0">
19708 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19709 <column alignment="left" valignment="top" leftline="true" width="0">
19710 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19711 <row topline="true" bottomline="true">
19712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19713 \begin_inset Text
19714
19715 \layout Standard
19716
19717 signal name
19718 \end_inset
19719 </cell>
19720 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19721 \begin_inset Text
19722
19723 \layout Standard
19724
19725 description
19726 \end_inset
19727 </cell>
19728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19729 \begin_inset Text
19730
19731 \layout Standard
19732
19733 signal name
19734 \end_inset
19735 </cell>
19736 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19737 \begin_inset Text
19738
19739 \layout Standard
19740
19741 descritpion
19742 \end_inset
19743 </cell>
19744 </row>
19745 <row topline="true">
19746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19747 \begin_inset Text
19748
19749 \layout Standard
19750
19751 SIG_RB
19752 \end_inset
19753 </cell>
19754 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19755 \begin_inset Text
19756
19757 \layout Standard
19758
19759 PORTB change interrupt
19760 \end_inset
19761 </cell>
19762 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19763 \begin_inset Text
19764
19765 \layout Standard
19766
19767 SIG_EE
19768 \end_inset
19769 </cell>
19770 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19771 \begin_inset Text
19772
19773 \layout Standard
19774
19775 EEPROM/FLASH write complete interrupt
19776 \end_inset
19777 </cell>
19778 </row>
19779 <row topline="true">
19780 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19781 \begin_inset Text
19782
19783 \layout Standard
19784
19785 SIG_INT0
19786 \end_inset
19787 </cell>
19788 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19789 \begin_inset Text
19790
19791 \layout Standard
19792
19793 INT0 external interrupt
19794 \end_inset
19795 </cell>
19796 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19797 \begin_inset Text
19798
19799 \layout Standard
19800
19801 SIG_BCOL
19802 \end_inset
19803 </cell>
19804 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19805 \begin_inset Text
19806
19807 \layout Standard
19808
19809 Bus collision interrupt
19810 \end_inset
19811 </cell>
19812 </row>
19813 <row topline="true">
19814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19815 \begin_inset Text
19816
19817 \layout Standard
19818
19819 SIG_INT1
19820 \end_inset
19821 </cell>
19822 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19823 \begin_inset Text
19824
19825 \layout Standard
19826
19827 INT1 external interrupt
19828 \end_inset
19829 </cell>
19830 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19831 \begin_inset Text
19832
19833 \layout Standard
19834
19835 SIG_LVD
19836 \end_inset
19837 </cell>
19838 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19839 \begin_inset Text
19840
19841 \layout Standard
19842
19843 Low voltage detect interrupt
19844 \end_inset
19845 </cell>
19846 </row>
19847 <row topline="true">
19848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19849 \begin_inset Text
19850
19851 \layout Standard
19852
19853 SIG_INT2
19854 \end_inset
19855 </cell>
19856 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19857 \begin_inset Text
19858
19859 \layout Standard
19860
19861 INT2 external interrupt
19862 \end_inset
19863 </cell>
19864 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19865 \begin_inset Text
19866
19867 \layout Standard
19868
19869 SIG_PSP
19870 \end_inset
19871 </cell>
19872 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19873 \begin_inset Text
19874
19875 \layout Standard
19876
19877 Parallel slave port interrupt
19878 \end_inset
19879 </cell>
19880 </row>
19881 <row topline="true">
19882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19883 \begin_inset Text
19884
19885 \layout Standard
19886
19887 SIG_CCP1
19888 \end_inset
19889 </cell>
19890 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19891 \begin_inset Text
19892
19893 \layout Standard
19894
19895 CCP1 module interrupt
19896 \end_inset
19897 </cell>
19898 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19899 \begin_inset Text
19900
19901 \layout Standard
19902
19903 SIG_AD
19904 \end_inset
19905 </cell>
19906 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19907 \begin_inset Text
19908
19909 \layout Standard
19910
19911 AD convertion complete interrupt
19912 \end_inset
19913 </cell>
19914 </row>
19915 <row topline="true">
19916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19917 \begin_inset Text
19918
19919 \layout Standard
19920
19921 SIG_CCP2
19922 \end_inset
19923 </cell>
19924 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19925 \begin_inset Text
19926
19927 \layout Standard
19928
19929 CCP2 module interrupt
19930 \end_inset
19931 </cell>
19932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19933 \begin_inset Text
19934
19935 \layout Standard
19936
19937 SIG_RC
19938 \end_inset
19939 </cell>
19940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19941 \begin_inset Text
19942
19943 \layout Standard
19944
19945 USART receive interrupt
19946 \end_inset
19947 </cell>
19948 </row>
19949 <row topline="true">
19950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19951 \begin_inset Text
19952
19953 \layout Standard
19954
19955 SIG_TMR0
19956 \end_inset
19957 </cell>
19958 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19959 \begin_inset Text
19960
19961 \layout Standard
19962
19963 TMR0 overflow interrupt
19964 \end_inset
19965 </cell>
19966 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19967 \begin_inset Text
19968
19969 \layout Standard
19970
19971 SIG_TX
19972 \end_inset
19973 </cell>
19974 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19975 \begin_inset Text
19976
19977 \layout Standard
19978
19979 USART transmit interrupt
19980 \end_inset
19981 </cell>
19982 </row>
19983 <row topline="true">
19984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19985 \begin_inset Text
19986
19987 \layout Standard
19988
19989 SIG_TMR1
19990 \end_inset
19991 </cell>
19992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19993 \begin_inset Text
19994
19995 \layout Standard
19996
19997 TMR1 overflow interrupt
19998 \end_inset
19999 </cell>
20000 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20001 \begin_inset Text
20002
20003 \layout Standard
20004
20005 SIG_MSSP
20006 \end_inset
20007 </cell>
20008 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20009 \begin_inset Text
20010
20011 \layout Standard
20012
20013 SSP receive/transmit interrupt
20014 \end_inset
20015 </cell>
20016 </row>
20017 <row topline="true">
20018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20019 \begin_inset Text
20020
20021 \layout Standard
20022
20023 SIG_TMR2
20024 \end_inset
20025 </cell>
20026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20027 \begin_inset Text
20028
20029 \layout Standard
20030
20031 TMR2 matches PR2 interrupt
20032 \end_inset
20033 </cell>
20034 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20035 \begin_inset Text
20036
20037 \layout Standard
20038
20039 \end_inset
20040 </cell>
20041 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20042 \begin_inset Text
20043
20044 \layout Standard
20045
20046 \end_inset
20047 </cell>
20048 </row>
20049 <row topline="true" bottomline="true">
20050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20051 \begin_inset Text
20052
20053 \layout Standard
20054
20055 SIG_TMR3
20056 \end_inset
20057 </cell>
20058 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20059 \begin_inset Text
20060
20061 \layout Standard
20062
20063 TMR3 overflow interrupt
20064 \end_inset
20065 </cell>
20066 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20067 \begin_inset Text
20068
20069 \layout Standard
20070
20071 \end_inset
20072 </cell>
20073 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20074 \begin_inset Text
20075
20076 \layout Standard
20077
20078 \end_inset
20079 </cell>
20080 </row>
20081 </lyxtabular>
20082
20083 \end_inset
20084
20085
20086 \layout Standard
20087
20088 The prototypes for these names are defined in the header file
20089 \emph on
20090 signal.h
20091 \emph default
20092  .
20093 \layout Standard
20094
20095 In order to simplify signal handling, a number of macros is provided:
20096 \layout List
20097 \labelwidthstring 00.00.0000
20098
20099 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
20100  high priority interrupts.
20101
20102 \emph on
20103 name
20104 \emph default
20105  is the function name to use.
20106 \layout List
20107 \labelwidthstring 00.00.0000
20108
20109 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
20110  low priority interrupt.
20111
20112 \emph on
20113 name
20114 \emph default
20115  is the function name to use.
20116 \layout List
20117 \labelwidthstring 00.00.0000
20118
20119 DEF_HANDLER(sig,handler) define a handler for signal
20120 \emph on
20121 sig.
20122 \layout List
20123 \labelwidthstring 00.00.0000
20124
20125 END_DEF end the declaration of the dispatch table.
20126 \layout Standard
20127
20128 Additionally there are two more macros to simplify the declaration of the
20129  signal handler:
20130 \layout List
20131 \labelwidthstring 00.00.0000
20132
20133
20134 \series medium
20135 SIGHANDLER(handler)
20136 \series default
20137 this declares the function prototype for the
20138 \emph on
20139 handler
20140 \emph default
20141  function.
20142 \layout List
20143 \labelwidthstring 00.00.0000
20144
20145 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
20146 \layout Standard
20147
20148 An example of using the macros above is shown below:
20149 \layout LyX-Code
20150
20151 #include <pic18fregs.h>
20152 \layout LyX-Code
20153
20154 #include <signal.h>
20155 \newline
20156
20157 \newline
20158 DEF_INTHIGH(high_int)
20159 \layout LyX-Code
20160
20161 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
20162 \layout LyX-Code
20163
20164 DEF_HANDLER(SIG_BCOL, _bcol_handler)
20165 \layout LyX-Code
20166
20167 END_DEF
20168 \newline
20169
20170 \newline
20171 SIGHANDLER(_tmr0_handler)
20172 \layout LyX-Code
20173
20174 {
20175 \layout LyX-Code
20176
20177   /* action to be taken when timer 0 overflows */
20178 \layout LyX-Code
20179
20180 }
20181 \newline
20182
20183 \newline
20184 SIGHANDLERNAKED(_bcol_handler)
20185 \layout LyX-Code
20186
20187 {
20188 \layout LyX-Code
20189
20190   _asm
20191 \layout LyX-Code
20192
20193     /* action to be taken when bus collision occurs */
20194 \layout LyX-Code
20195
20196     retfie
20197 \layout LyX-Code
20198
20199  _endasm;
20200 \layout LyX-Code
20201
20202 }
20203 \layout Standard
20204
20205
20206 \series bold
20207 NOTES:
20208 \series default
20209  Special care should be taken when using the above scheme:
20210 \layout Itemize
20211
20212 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
20213 \layout Itemize
20214
20215 when declaring SIGHANDLERNAKED handler never forget to use
20216 \emph on
20217 retfie
20218 \emph default
20219  for proper returning.
20220 \layout Subsection
20221
20222 PIC16 Port -- Tips
20223 \layout Standard
20224
20225 Here you can find some general tips for compiling programs with SDCC/pic16.
20226 \layout Subsubsection
20227
20228 Stack size
20229 \layout Standard
20230
20231 The default stack size (that is 64 bytes) probably is enough for many programs.
20232  One must take care that when there are many levels of function nesting,
20233  or there is excessive usage of stack, its size should be extended.
20234  An example of such a case is the printf/sprintf family of functions.
20235  If you encounter problems like not being able to print integers, then you
20236  need to set the stack size around the maximum (256 for small stack model).
20237  The following diagram shows what happens when calling printf to print an
20238  integer:
20239 \layout LyX-Code
20240
20241 printf () --> ltoa () --> ultoa () --> divschar ()
20242 \layout Standard
20243
20244 It is should be understood that stack is easily consumed when calling complicate
20245 d functions.
20246  Using command line arguments like -
20247 \begin_inset ERT
20248 status Collapsed
20249
20250 \layout Standard
20251
20252 \backslash
20253 /
20254 \end_inset
20255
20256 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
20257  stack frames.
20258  Other ways to reduce stack usage may exist.
20259 \layout Chapter
20260
20261 Debugging with SDCDB
20262 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
20263
20264 \end_inset
20265
20266
20267 \begin_inset LatexCommand \index{sdcdb (debugger)}
20268
20269 \end_inset
20270
20271
20272 \layout Standard
20273
20274 SDCC is distributed with a source level debugger
20275 \begin_inset LatexCommand \index{Debugger}
20276
20277 \end_inset
20278
20279 .
20280  The debugger uses a command line interface, the command repertoire of the
20281  debugger has been kept as close to gdb
20282 \begin_inset LatexCommand \index{gdb}
20283
20284 \end_inset
20285
20286  (the GNU debugger) as possible.
20287  The configuration and build process is part of the standard compiler installati
20288 on, which also builds and installs the debugger in the target directory
20289  specified during configuration.
20290  The debugger allows you debug BOTH at the C source and at the ASM source
20291  level.
20292  Sdcdb is currently not available on Win32 platforms.
20293 \layout Section
20294
20295 Compiling for Debugging
20296 \layout Standard
20297
20298 The -
20299 \begin_inset ERT
20300 status Collapsed
20301
20302 \layout Standard
20303
20304 \backslash
20305 /
20306 \end_inset
20307
20308 -debug
20309 \begin_inset LatexCommand \index{-\/-debug}
20310
20311 \end_inset
20312
20313  option must be specified for all files for which debug information is to
20314  be generated.
20315  The complier generates a .adb file for each of these files.
20316  The linker creates the .cdb
20317 \begin_inset LatexCommand \index{<file>.cdb}
20318
20319 \end_inset
20320
20321  file from the .adb
20322 \begin_inset LatexCommand \index{<file>.adb}
20323
20324 \end_inset
20325
20326  files and the address information.
20327  This .cdb is used by the debugger.
20328 \layout Section
20329
20330 How the Debugger Works
20331 \layout Standard
20332
20333 When the -
20334 \begin_inset ERT
20335 status Collapsed
20336
20337 \layout Standard
20338
20339 \backslash
20340 /
20341 \end_inset
20342
20343 -debug option is specified the compiler generates extra symbol information
20344  some of which are put into the assembler source and some are put into the
20345  .adb file.
20346   Then the linker creates the .cdb file from the individual .adb files with
20347  the address information for the symbols.
20348  The debugger reads the symbolic information generated by the compiler &
20349  the address information generated by the linker.
20350  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
20351  execution is controlled by the debugger.
20352  When a command is issued for the debugger, it translates it into appropriate
20353  commands for the simulator.
20354 \layout Section
20355
20356 Starting the Debugger
20357 \layout Standard
20358
20359 The debugger can be started using the following command line.
20360  (Assume the file you are debugging has the file name foo).
20361 \newline
20362
20363 \newline
20364
20365 \family sans
20366 \series bold
20367 sdcdb foo
20368 \newline
20369
20370 \family default
20371 \series default
20372
20373 \newline
20374 The debugger will look for the following files.
20375 \layout Itemize
20376
20377 foo.c - the source file.
20378 \layout Itemize
20379
20380 foo.cdb - the debugger symbol information file.
20381 \layout Itemize
20382
20383 foo.ihx - the Intel hex format
20384 \begin_inset LatexCommand \index{Intel hex format}
20385
20386 \end_inset
20387
20388  object file.
20389 \layout Section
20390
20391 Command Line Options
20392 \layout Itemize
20393
20394 -
20395 \begin_inset ERT
20396 status Collapsed
20397
20398 \layout Standard
20399
20400 \backslash
20401 /
20402 \end_inset
20403
20404 -directory=<source file directory> this option can used to specify the directory
20405  search list.
20406  The debugger will look into the directory list specified for source, cdb
20407  & ihx files.
20408  The items in the directory list must be separated by ':', e.g.
20409  if the source files can be in the directories /home/src1 and /home/src2,
20410  the -
20411 \begin_inset ERT
20412 status Collapsed
20413
20414 \layout Standard
20415
20416 \backslash
20417 /
20418 \end_inset
20419
20420 -directory option should be -
20421 \begin_inset ERT
20422 status Collapsed
20423
20424 \layout Standard
20425
20426 \backslash
20427 /
20428 \end_inset
20429
20430 -directory=/home/src1:/home/src2.
20431  Note there can be no spaces in the option.
20432
20433 \layout Itemize
20434
20435 -cd <directory> - change to the <directory>.
20436 \layout Itemize
20437
20438 -fullname - used by GUI front ends.
20439 \layout Itemize
20440
20441 -cpu <cpu-type> - this argument is passed to the simulator please see the
20442  simulator docs for details.
20443 \layout Itemize
20444
20445 -X <Clock frequency > this options is passed to the simulator please see
20446  the simulator docs for details.
20447 \layout Itemize
20448
20449 -s <serial port file> passed to simulator see the simulator docs for details.
20450 \layout Itemize
20451
20452 -S <serial in,out> passed to simulator see the simulator docs for details.
20453 \layout Itemize
20454
20455 -k <port number> passed to simulator see the simulator docs for details.
20456 \layout Section
20457
20458 Debugger Commands
20459 \layout Standard
20460
20461 As mentioned earlier the command interface for the debugger has been deliberatel
20462 y kept as close the GNU debugger gdb, as possible.
20463  This will help the integration with existing graphical user interfaces
20464  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
20465  If you use a graphical user interface for the debugger you can skip this
20466  section.
20467 \layout Subsubsection*
20468
20469 break [line | file:line | function | file:function]
20470 \layout Standard
20471
20472 Set breakpoint at specified line or function:
20473 \newline
20474
20475 \newline
20476
20477 \family sans
20478 \series bold
20479 sdcdb>break 100
20480 \newline
20481 sdcdb>break foo.c:100
20482 \newline
20483 sdcdb>break funcfoo
20484 \newline
20485 sdcdb>break foo.c:funcfoo
20486 \layout Subsubsection*
20487
20488 clear [line | file:line | function | file:function ]
20489 \layout Standard
20490
20491 Clear breakpoint at specified line or function:
20492 \newline
20493
20494 \newline
20495
20496 \family sans
20497 \series bold
20498 sdcdb>clear 100
20499 \newline
20500 sdcdb>clear foo.c:100
20501 \newline
20502 sdcdb>clear funcfoo
20503 \newline
20504 sdcdb>clear foo.c:funcfoo
20505 \layout Subsubsection*
20506
20507 continue
20508 \layout Standard
20509
20510 Continue program being debugged, after breakpoint.
20511 \layout Subsubsection*
20512
20513 finish
20514 \layout Standard
20515
20516 Execute till the end of the current function.
20517 \layout Subsubsection*
20518
20519 delete [n]
20520 \layout Standard
20521
20522 Delete breakpoint number 'n'.
20523  If used without any option clear ALL user defined break points.
20524 \layout Subsubsection*
20525
20526 info [break | stack | frame | registers ]
20527 \layout Itemize
20528
20529 info break - list all breakpoints
20530 \layout Itemize
20531
20532 info stack - show the function call stack.
20533 \layout Itemize
20534
20535 info frame - show information about the current execution frame.
20536 \layout Itemize
20537
20538 info registers - show content of all registers.
20539 \layout Subsubsection*
20540
20541 step
20542 \layout Standard
20543
20544 Step program until it reaches a different source line.
20545  Note: pressing <return> repeats the last command.
20546 \layout Subsubsection*
20547
20548 next
20549 \layout Standard
20550
20551 Step program, proceeding through subroutine calls.
20552 \layout Subsubsection*
20553
20554 run
20555 \layout Standard
20556
20557 Start debugged program.
20558 \layout Subsubsection*
20559
20560 ptype variable
20561 \layout Standard
20562
20563 Print type information of the variable.
20564 \layout Subsubsection*
20565
20566 print variable
20567 \layout Standard
20568
20569 print value of variable.
20570 \layout Subsubsection*
20571
20572 file filename
20573 \layout Standard
20574
20575 load the given file name.
20576  Note this is an alternate method of loading file for debugging.
20577 \layout Subsubsection*
20578
20579 frame
20580 \layout Standard
20581
20582 print information about current frame.
20583 \layout Subsubsection*
20584
20585 set srcmode
20586 \layout Standard
20587
20588 Toggle between C source & assembly source.
20589 \layout Subsubsection*
20590
20591 ! simulator command
20592 \layout Standard
20593
20594 Send the string following '!' to the simulator, the simulator response is
20595  displayed.
20596  Note the debugger does not interpret the command being sent to the simulator,
20597  so if a command like 'go' is sent the debugger can loose its execution
20598  context and may display incorrect values.
20599 \layout Subsubsection*
20600
20601 quit
20602 \layout Standard
20603
20604 "Watch me now.
20605  Iam going Down.
20606  My name is Bobby Brown"
20607 \layout Section
20608
20609 Interfacing with DDD
20610 \layout Comment
20611
20612 The screenshot was converted from png to eps with:
20613 \begin_inset Quotes sld
20614 \end_inset
20615
20616 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
20617 \begin_inset Quotes srd
20618 \end_inset
20619
20620  which produces a pretty compact eps file which is free from compression
20621  artifacts.
20622 \layout Comment
20623
20624 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
20625  as this broke the build system on Sourceforge (pdf-file was broken).
20626 \layout Standard
20627
20628 The .eps File
20629 \size footnotesize
20630
20631 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.eps}
20632
20633 \end_inset
20634
20635
20636 \size default
20637  shows a screenshot of a debugging session with DDD
20638 \begin_inset LatexCommand \index{DDD (debugger)}
20639
20640 \end_inset
20641
20642  (Unix only) on a simulated 8032.
20643  The debugging session might not run as smoothly as the screenshot suggests.
20644  The debugger allows setting of breakpoints, displaying and changing variables,
20645  single stepping through C and assembler code.
20646
20647 \newline
20648 The source was compiled with
20649 \family sans
20650 \series bold
20651
20652 \newline
20653
20654 \newline
20655 sdcc -
20656 \family default
20657 \series default
20658
20659 \begin_inset ERT
20660 status Collapsed
20661
20662 \layout Standard
20663
20664 \backslash
20665 /
20666 \end_inset
20667
20668
20669 \family sans
20670 \series bold
20671 -debug ddd_example.c
20672 \family default
20673 \series default
20674
20675 \family sans
20676 \series bold
20677
20678 \newline
20679
20680 \family default
20681 \series default
20682
20683 \newline
20684 and DDD was invoked with
20685 \family sans
20686 \series bold
20687
20688 \newline
20689
20690 \newline
20691 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
20692 \layout Section
20693
20694 Interfacing with XEmacs
20695 \begin_inset LatexCommand \index{XEmacs}
20696
20697 \end_inset
20698
20699
20700 \begin_inset LatexCommand \index{Emacs}
20701
20702 \end_inset
20703
20704
20705 \layout Standard
20706
20707 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
20708  sdcdb.el and sdcdbsrc.el.
20709  These two files can be found in the $(prefix)/bin directory after the installat
20710 ion is complete.
20711  These files need to be loaded into XEmacs for the interface to work.
20712  This can be done at XEmacs startup time by inserting the following into
20713  your '.xemacs' file (which can be found in your HOME directory):
20714 \newline
20715
20716 \newline
20717
20718 \family typewriter
20719 (load-file sdcdbsrc.el)
20720 \family default
20721
20722 \newline
20723
20724 \newline
20725 .xemacs is a lisp file so the () around the command is REQUIRED.
20726  The files can also be loaded dynamically while XEmacs is running, set the
20727  environment variable 'EMACSLOADPATH' to the installation bin directory
20728  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
20729  To start the interface enter the following command:
20730 \newline
20731
20732 \newline
20733
20734 \family sans
20735 \series bold
20736 ESC-x sdcdbsrc
20737 \family default
20738 \series default
20739
20740 \newline
20741
20742 \newline
20743 You will prompted to enter the file name to be debugged.
20744
20745 \newline
20746
20747 \newline
20748 The command line options that are passed to the simulator directly are bound
20749  to default values in the file sdcdbsrc.el.
20750  The variables are listed below, these values maybe changed as required.
20751 \layout Itemize
20752
20753 sdcdbsrc-cpu-type '51
20754 \layout Itemize
20755
20756 sdcdbsrc-frequency '11059200
20757 \layout Itemize
20758
20759 sdcdbsrc-serial nil
20760 \layout Standard
20761
20762 The following is a list of key mapping for the debugger interface.
20763 \layout Standard
20764
20765 \SpecialChar ~
20766
20767 \family typewriter
20768
20769 \newline
20770 ;;\SpecialChar ~
20771 Current Listing ::
20772 \newline
20773 ;;key\SpecialChar ~
20774 \SpecialChar ~
20775 \SpecialChar ~
20776 \SpecialChar ~
20777 \SpecialChar ~
20778 \SpecialChar ~
20779 \SpecialChar ~
20780 \SpecialChar ~
20781 \SpecialChar ~
20782 \SpecialChar ~
20783 \SpecialChar ~
20784 \SpecialChar ~
20785 \SpecialChar ~
20786 \SpecialChar ~
20787 binding\SpecialChar ~
20788 \SpecialChar ~
20789 \SpecialChar ~
20790 \SpecialChar ~
20791 \SpecialChar ~
20792 \SpecialChar ~
20793 \SpecialChar ~
20794 \SpecialChar ~
20795 \SpecialChar ~
20796 \SpecialChar ~
20797 \SpecialChar ~
20798 \SpecialChar ~
20799 \SpecialChar ~
20800 \SpecialChar ~
20801 \SpecialChar ~
20802 \SpecialChar ~
20803 \SpecialChar ~
20804 \SpecialChar ~
20805 \SpecialChar ~
20806 \SpecialChar ~
20807 \SpecialChar ~
20808 \SpecialChar ~
20809 Comment
20810 \newline
20811 ;;---\SpecialChar ~
20812 \SpecialChar ~
20813 \SpecialChar ~
20814 \SpecialChar ~
20815 \SpecialChar ~
20816 \SpecialChar ~
20817 \SpecialChar ~
20818 \SpecialChar ~
20819 \SpecialChar ~
20820 \SpecialChar ~
20821 \SpecialChar ~
20822 \SpecialChar ~
20823 \SpecialChar ~
20824 \SpecialChar ~
20825 -------\SpecialChar ~
20826 \SpecialChar ~
20827 \SpecialChar ~
20828 \SpecialChar ~
20829 \SpecialChar ~
20830 \SpecialChar ~
20831 \SpecialChar ~
20832 \SpecialChar ~
20833 \SpecialChar ~
20834 \SpecialChar ~
20835 \SpecialChar ~
20836 \SpecialChar ~
20837 \SpecialChar ~
20838 \SpecialChar ~
20839 \SpecialChar ~
20840 \SpecialChar ~
20841 \SpecialChar ~
20842 \SpecialChar ~
20843 \SpecialChar ~
20844 \SpecialChar ~
20845 \SpecialChar ~
20846 \SpecialChar ~
20847 -------
20848 \newline
20849 ;;
20850 \newline
20851 ;;\SpecialChar ~
20852 n\SpecialChar ~
20853 \SpecialChar ~
20854 \SpecialChar ~
20855 \SpecialChar ~
20856 \SpecialChar ~
20857 \SpecialChar ~
20858 \SpecialChar ~
20859 \SpecialChar ~
20860 \SpecialChar ~
20861 \SpecialChar ~
20862 \SpecialChar ~
20863 \SpecialChar ~
20864 \SpecialChar ~
20865 \SpecialChar ~
20866 \SpecialChar ~
20867 sdcdb-next-from-src\SpecialChar ~
20868 \SpecialChar ~
20869 \SpecialChar ~
20870 \SpecialChar ~
20871 \SpecialChar ~
20872 \SpecialChar ~
20873 \SpecialChar ~
20874 \SpecialChar ~
20875 \SpecialChar ~
20876 \SpecialChar ~
20877 SDCDB next command
20878 \newline
20879 ;;\SpecialChar ~
20880 b\SpecialChar ~
20881 \SpecialChar ~
20882 \SpecialChar ~
20883 \SpecialChar ~
20884 \SpecialChar ~
20885 \SpecialChar ~
20886 \SpecialChar ~
20887 \SpecialChar ~
20888 \SpecialChar ~
20889 \SpecialChar ~
20890 \SpecialChar ~
20891 \SpecialChar ~
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895 sdcdb-back-from-src\SpecialChar ~
20896 \SpecialChar ~
20897 \SpecialChar ~
20898 \SpecialChar ~
20899 \SpecialChar ~
20900 \SpecialChar ~
20901 \SpecialChar ~
20902 \SpecialChar ~
20903 \SpecialChar ~
20904 \SpecialChar ~
20905 SDCDB back command
20906 \newline
20907 ;;\SpecialChar ~
20908 c\SpecialChar ~
20909 \SpecialChar ~
20910 \SpecialChar ~
20911 \SpecialChar ~
20912 \SpecialChar ~
20913 \SpecialChar ~
20914 \SpecialChar ~
20915 \SpecialChar ~
20916 \SpecialChar ~
20917 \SpecialChar ~
20918 \SpecialChar ~
20919 \SpecialChar ~
20920 \SpecialChar ~
20921 \SpecialChar ~
20922 \SpecialChar ~
20923 sdcdb-cont-from-src\SpecialChar ~
20924 \SpecialChar ~
20925 \SpecialChar ~
20926 \SpecialChar ~
20927 \SpecialChar ~
20928 \SpecialChar ~
20929 \SpecialChar ~
20930 \SpecialChar ~
20931 \SpecialChar ~
20932 \SpecialChar ~
20933 SDCDB continue command
20934 \newline
20935 ;;\SpecialChar ~
20936 s\SpecialChar ~
20937 \SpecialChar ~
20938 \SpecialChar ~
20939 \SpecialChar ~
20940 \SpecialChar ~
20941 \SpecialChar ~
20942 \SpecialChar ~
20943 \SpecialChar ~
20944 \SpecialChar ~
20945 \SpecialChar ~
20946 \SpecialChar ~
20947 \SpecialChar ~
20948 \SpecialChar ~
20949 \SpecialChar ~
20950 \SpecialChar ~
20951 sdcdb-step-from-src\SpecialChar ~
20952 \SpecialChar ~
20953 \SpecialChar ~
20954 \SpecialChar ~
20955 \SpecialChar ~
20956 \SpecialChar ~
20957 \SpecialChar ~
20958 \SpecialChar ~
20959 \SpecialChar ~
20960 \SpecialChar ~
20961 SDCDB step command
20962 \newline
20963 ;;\SpecialChar ~
20964 ?\SpecialChar ~
20965 \SpecialChar ~
20966 \SpecialChar ~
20967 \SpecialChar ~
20968 \SpecialChar ~
20969 \SpecialChar ~
20970 \SpecialChar ~
20971 \SpecialChar ~
20972 \SpecialChar ~
20973 \SpecialChar ~
20974 \SpecialChar ~
20975 \SpecialChar ~
20976 \SpecialChar ~
20977 \SpecialChar ~
20978 \SpecialChar ~
20979 sdcdb-whatis-c-sexp\SpecialChar ~
20980 \SpecialChar ~
20981 \SpecialChar ~
20982 \SpecialChar ~
20983 \SpecialChar ~
20984 \SpecialChar ~
20985 \SpecialChar ~
20986 \SpecialChar ~
20987 \SpecialChar ~
20988 \SpecialChar ~
20989 SDCDB ptypecommand for data at
20990 \newline
20991 ;;\SpecialChar ~
20992 \SpecialChar ~
20993 \SpecialChar ~
20994 \SpecialChar ~
20995 \SpecialChar ~
20996 \SpecialChar ~
20997 \SpecialChar ~
20998 \SpecialChar ~
20999 \SpecialChar ~
21000 \SpecialChar ~
21001 \SpecialChar ~
21002 \SpecialChar ~
21003 \SpecialChar ~
21004 \SpecialChar ~
21005 \SpecialChar ~
21006 \SpecialChar ~
21007 \SpecialChar ~
21008 \SpecialChar ~
21009 \SpecialChar ~
21010 \SpecialChar ~
21011 \SpecialChar ~
21012 \SpecialChar ~
21013 \SpecialChar ~
21014 \SpecialChar ~
21015 \SpecialChar ~
21016 \SpecialChar ~
21017 \SpecialChar ~
21018 \SpecialChar ~
21019 \SpecialChar ~
21020 \SpecialChar ~
21021 \SpecialChar ~
21022 \SpecialChar ~
21023 \SpecialChar ~
21024 \SpecialChar ~
21025 \SpecialChar ~
21026 \SpecialChar ~
21027 \SpecialChar ~
21028 \SpecialChar ~
21029 \SpecialChar ~
21030 \SpecialChar ~
21031 \SpecialChar ~
21032 \SpecialChar ~
21033 \SpecialChar ~
21034 \SpecialChar ~
21035 \SpecialChar ~
21036 \SpecialChar ~
21037 \SpecialChar ~
21038 buffer point
21039 \newline
21040 ;;\SpecialChar ~
21041 x\SpecialChar ~
21042 \SpecialChar ~
21043 \SpecialChar ~
21044 \SpecialChar ~
21045 \SpecialChar ~
21046 \SpecialChar ~
21047 \SpecialChar ~
21048 \SpecialChar ~
21049 \SpecialChar ~
21050 \SpecialChar ~
21051 \SpecialChar ~
21052 \SpecialChar ~
21053 \SpecialChar ~
21054 \SpecialChar ~
21055 \SpecialChar ~
21056 sdcdbsrc-delete\SpecialChar ~
21057 \SpecialChar ~
21058 \SpecialChar ~
21059 \SpecialChar ~
21060 \SpecialChar ~
21061 \SpecialChar ~
21062 \SpecialChar ~
21063 \SpecialChar ~
21064 \SpecialChar ~
21065 \SpecialChar ~
21066 \SpecialChar ~
21067 \SpecialChar ~
21068 \SpecialChar ~
21069 \SpecialChar ~
21070 SDCDB Delete all breakpoints if no arg
21071 \newline
21072 ;;\SpecialChar ~
21073 \SpecialChar ~
21074 \SpecialChar ~
21075 \SpecialChar ~
21076 \SpecialChar ~
21077 \SpecialChar ~
21078 \SpecialChar ~
21079 \SpecialChar ~
21080 \SpecialChar ~
21081 \SpecialChar ~
21082 \SpecialChar ~
21083 \SpecialChar ~
21084 \SpecialChar ~
21085 \SpecialChar ~
21086 \SpecialChar ~
21087 \SpecialChar ~
21088 \SpecialChar ~
21089 \SpecialChar ~
21090 \SpecialChar ~
21091 \SpecialChar ~
21092 \SpecialChar ~
21093 \SpecialChar ~
21094 \SpecialChar ~
21095 \SpecialChar ~
21096 \SpecialChar ~
21097 \SpecialChar ~
21098 \SpecialChar ~
21099 \SpecialChar ~
21100 \SpecialChar ~
21101 \SpecialChar ~
21102 \SpecialChar ~
21103 \SpecialChar ~
21104 \SpecialChar ~
21105 \SpecialChar ~
21106 \SpecialChar ~
21107 \SpecialChar ~
21108 \SpecialChar ~
21109 \SpecialChar ~
21110 \SpecialChar ~
21111 \SpecialChar ~
21112 \SpecialChar ~
21113 \SpecialChar ~
21114 \SpecialChar ~
21115 \SpecialChar ~
21116 \SpecialChar ~
21117 \SpecialChar ~
21118 \SpecialChar ~
21119 given or delete arg (C-u arg x)
21120 \newline
21121 ;;\SpecialChar ~
21122 m\SpecialChar ~
21123 \SpecialChar ~
21124 \SpecialChar ~
21125 \SpecialChar ~
21126 \SpecialChar ~
21127 \SpecialChar ~
21128 \SpecialChar ~
21129 \SpecialChar ~
21130 \SpecialChar ~
21131 \SpecialChar ~
21132 \SpecialChar ~
21133 \SpecialChar ~
21134 \SpecialChar ~
21135 \SpecialChar ~
21136 \SpecialChar ~
21137 sdcdbsrc-frame\SpecialChar ~
21138 \SpecialChar ~
21139 \SpecialChar ~
21140 \SpecialChar ~
21141 \SpecialChar ~
21142 \SpecialChar ~
21143 \SpecialChar ~
21144 \SpecialChar ~
21145 \SpecialChar ~
21146 \SpecialChar ~
21147 \SpecialChar ~
21148 \SpecialChar ~
21149 \SpecialChar ~
21150 \SpecialChar ~
21151 \SpecialChar ~
21152 SDCDB Display current frame if no arg,
21153 \newline
21154 ;;\SpecialChar ~
21155 \SpecialChar ~
21156 \SpecialChar ~
21157 \SpecialChar ~
21158 \SpecialChar ~
21159 \SpecialChar ~
21160 \SpecialChar ~
21161 \SpecialChar ~
21162 \SpecialChar ~
21163 \SpecialChar ~
21164 \SpecialChar ~
21165 \SpecialChar ~
21166 \SpecialChar ~
21167 \SpecialChar ~
21168 \SpecialChar ~
21169 \SpecialChar ~
21170 \SpecialChar ~
21171 \SpecialChar ~
21172 \SpecialChar ~
21173 \SpecialChar ~
21174 \SpecialChar ~
21175 \SpecialChar ~
21176 \SpecialChar ~
21177 \SpecialChar ~
21178 \SpecialChar ~
21179 \SpecialChar ~
21180 \SpecialChar ~
21181 \SpecialChar ~
21182 \SpecialChar ~
21183 \SpecialChar ~
21184 \SpecialChar ~
21185 \SpecialChar ~
21186 \SpecialChar ~
21187 \SpecialChar ~
21188 \SpecialChar ~
21189 \SpecialChar ~
21190 \SpecialChar ~
21191 \SpecialChar ~
21192 \SpecialChar ~
21193 \SpecialChar ~
21194 \SpecialChar ~
21195 \SpecialChar ~
21196 \SpecialChar ~
21197 \SpecialChar ~
21198 \SpecialChar ~
21199 \SpecialChar ~
21200 \SpecialChar ~
21201 given or display frame arg
21202 \newline
21203 ;;\SpecialChar ~
21204 \SpecialChar ~
21205 \SpecialChar ~
21206 \SpecialChar ~
21207 \SpecialChar ~
21208 \SpecialChar ~
21209 \SpecialChar ~
21210 \SpecialChar ~
21211 \SpecialChar ~
21212 \SpecialChar ~
21213 \SpecialChar ~
21214 \SpecialChar ~
21215 \SpecialChar ~
21216 \SpecialChar ~
21217 \SpecialChar ~
21218 \SpecialChar ~
21219 \SpecialChar ~
21220 \SpecialChar ~
21221 \SpecialChar ~
21222 \SpecialChar ~
21223 \SpecialChar ~
21224 \SpecialChar ~
21225 \SpecialChar ~
21226 \SpecialChar ~
21227 \SpecialChar ~
21228 \SpecialChar ~
21229 \SpecialChar ~
21230 \SpecialChar ~
21231 \SpecialChar ~
21232 \SpecialChar ~
21233 \SpecialChar ~
21234 \SpecialChar ~
21235 \SpecialChar ~
21236 \SpecialChar ~
21237 \SpecialChar ~
21238 \SpecialChar ~
21239 \SpecialChar ~
21240 \SpecialChar ~
21241 \SpecialChar ~
21242 \SpecialChar ~
21243 \SpecialChar ~
21244 \SpecialChar ~
21245 \SpecialChar ~
21246 \SpecialChar ~
21247 \SpecialChar ~
21248 \SpecialChar ~
21249 \SpecialChar ~
21250 buffer point
21251 \newline
21252 ;;\SpecialChar ~
21253 !\SpecialChar ~
21254 \SpecialChar ~
21255 \SpecialChar ~
21256 \SpecialChar ~
21257 \SpecialChar ~
21258 \SpecialChar ~
21259 \SpecialChar ~
21260 \SpecialChar ~
21261 \SpecialChar ~
21262 \SpecialChar ~
21263 \SpecialChar ~
21264 \SpecialChar ~
21265 \SpecialChar ~
21266 \SpecialChar ~
21267 \SpecialChar ~
21268 sdcdbsrc-goto-sdcdb\SpecialChar ~
21269 \SpecialChar ~
21270 \SpecialChar ~
21271 \SpecialChar ~
21272 \SpecialChar ~
21273 \SpecialChar ~
21274 \SpecialChar ~
21275 \SpecialChar ~
21276 \SpecialChar ~
21277 \SpecialChar ~
21278 Goto the SDCDB output buffer
21279 \newline
21280 ;;\SpecialChar ~
21281 p\SpecialChar ~
21282 \SpecialChar ~
21283 \SpecialChar ~
21284 \SpecialChar ~
21285 \SpecialChar ~
21286 \SpecialChar ~
21287 \SpecialChar ~
21288 \SpecialChar ~
21289 \SpecialChar ~
21290 \SpecialChar ~
21291 \SpecialChar ~
21292 \SpecialChar ~
21293 \SpecialChar ~
21294 \SpecialChar ~
21295 \SpecialChar ~
21296 sdcdb-print-c-sexp\SpecialChar ~
21297 \SpecialChar ~
21298 \SpecialChar ~
21299 \SpecialChar ~
21300 \SpecialChar ~
21301 \SpecialChar ~
21302 \SpecialChar ~
21303 \SpecialChar ~
21304 \SpecialChar ~
21305 \SpecialChar ~
21306 \SpecialChar ~
21307 SDCDB print command for data at
21308 \newline
21309 ;;\SpecialChar ~
21310 \SpecialChar ~
21311 \SpecialChar ~
21312 \SpecialChar ~
21313 \SpecialChar ~
21314 \SpecialChar ~
21315 \SpecialChar ~
21316 \SpecialChar ~
21317 \SpecialChar ~
21318 \SpecialChar ~
21319 \SpecialChar ~
21320 \SpecialChar ~
21321 \SpecialChar ~
21322 \SpecialChar ~
21323 \SpecialChar ~
21324 \SpecialChar ~
21325 \SpecialChar ~
21326 \SpecialChar ~
21327 \SpecialChar ~
21328 \SpecialChar ~
21329 \SpecialChar ~
21330 \SpecialChar ~
21331 \SpecialChar ~
21332 \SpecialChar ~
21333 \SpecialChar ~
21334 \SpecialChar ~
21335 \SpecialChar ~
21336 \SpecialChar ~
21337 \SpecialChar ~
21338 \SpecialChar ~
21339 \SpecialChar ~
21340 \SpecialChar ~
21341 \SpecialChar ~
21342 \SpecialChar ~
21343 \SpecialChar ~
21344 \SpecialChar ~
21345 \SpecialChar ~
21346 \SpecialChar ~
21347 \SpecialChar ~
21348 \SpecialChar ~
21349 \SpecialChar ~
21350 \SpecialChar ~
21351 \SpecialChar ~
21352 \SpecialChar ~
21353 \SpecialChar ~
21354 \SpecialChar ~
21355 \SpecialChar ~
21356 buffer point
21357 \newline
21358 ;;\SpecialChar ~
21359 g\SpecialChar ~
21360 \SpecialChar ~
21361 \SpecialChar ~
21362 \SpecialChar ~
21363 \SpecialChar ~
21364 \SpecialChar ~
21365 \SpecialChar ~
21366 \SpecialChar ~
21367 \SpecialChar ~
21368 \SpecialChar ~
21369 \SpecialChar ~
21370 \SpecialChar ~
21371 \SpecialChar ~
21372 \SpecialChar ~
21373 \SpecialChar ~
21374 sdcdbsrc-goto-sdcdb\SpecialChar ~
21375 \SpecialChar ~
21376 \SpecialChar ~
21377 \SpecialChar ~
21378 \SpecialChar ~
21379 \SpecialChar ~
21380 \SpecialChar ~
21381 \SpecialChar ~
21382 \SpecialChar ~
21383 \SpecialChar ~
21384 Goto the SDCDB output buffer
21385 \newline
21386 ;;\SpecialChar ~
21387 t\SpecialChar ~
21388 \SpecialChar ~
21389 \SpecialChar ~
21390 \SpecialChar ~
21391 \SpecialChar ~
21392 \SpecialChar ~
21393 \SpecialChar ~
21394 \SpecialChar ~
21395 \SpecialChar ~
21396 \SpecialChar ~
21397 \SpecialChar ~
21398 \SpecialChar ~
21399 \SpecialChar ~
21400 \SpecialChar ~
21401 \SpecialChar ~
21402 sdcdbsrc-mode\SpecialChar ~
21403 \SpecialChar ~
21404 \SpecialChar ~
21405 \SpecialChar ~
21406 \SpecialChar ~
21407 \SpecialChar ~
21408 \SpecialChar ~
21409 \SpecialChar ~
21410 \SpecialChar ~
21411 \SpecialChar ~
21412 \SpecialChar ~
21413 \SpecialChar ~
21414 \SpecialChar ~
21415 \SpecialChar ~
21416 \SpecialChar ~
21417 \SpecialChar ~
21418 Toggles Sdcdbsrc mode (turns it off)
21419 \newline
21420 ;;
21421 \newline
21422 ;;\SpecialChar ~
21423 C-c\SpecialChar ~
21424 C-f\SpecialChar ~
21425 \SpecialChar ~
21426 \SpecialChar ~
21427 \SpecialChar ~
21428 \SpecialChar ~
21429 \SpecialChar ~
21430 \SpecialChar ~
21431 \SpecialChar ~
21432 \SpecialChar ~
21433 sdcdb-finish-from-src\SpecialChar ~
21434 \SpecialChar ~
21435 \SpecialChar ~
21436 \SpecialChar ~
21437 \SpecialChar ~
21438 \SpecialChar ~
21439 \SpecialChar ~
21440 \SpecialChar ~
21441 SDCDB finish command
21442 \newline
21443 ;;
21444 \newline
21445 ;;\SpecialChar ~
21446 C-x\SpecialChar ~
21447 SPC\SpecialChar ~
21448 \SpecialChar ~
21449 \SpecialChar ~
21450 \SpecialChar ~
21451 \SpecialChar ~
21452 \SpecialChar ~
21453 \SpecialChar ~
21454 \SpecialChar ~
21455 \SpecialChar ~
21456 sdcdb-break\SpecialChar ~
21457 \SpecialChar ~
21458 \SpecialChar ~
21459 \SpecialChar ~
21460 \SpecialChar ~
21461 \SpecialChar ~
21462 \SpecialChar ~
21463 \SpecialChar ~
21464 \SpecialChar ~
21465 \SpecialChar ~
21466 \SpecialChar ~
21467 \SpecialChar ~
21468 \SpecialChar ~
21469 \SpecialChar ~
21470 \SpecialChar ~
21471 \SpecialChar ~
21472 \SpecialChar ~
21473 \SpecialChar ~
21474 Set break for line with point
21475 \newline
21476 ;;\SpecialChar ~
21477 ESC\SpecialChar ~
21478 t\SpecialChar ~
21479 \SpecialChar ~
21480 \SpecialChar ~
21481 \SpecialChar ~
21482 \SpecialChar ~
21483 \SpecialChar ~
21484 \SpecialChar ~
21485 \SpecialChar ~
21486 \SpecialChar ~
21487 \SpecialChar ~
21488 \SpecialChar ~
21489 sdcdbsrc-mode\SpecialChar ~
21490 \SpecialChar ~
21491 \SpecialChar ~
21492 \SpecialChar ~
21493 \SpecialChar ~
21494 \SpecialChar ~
21495 \SpecialChar ~
21496 \SpecialChar ~
21497 \SpecialChar ~
21498 \SpecialChar ~
21499 \SpecialChar ~
21500 \SpecialChar ~
21501 \SpecialChar ~
21502 \SpecialChar ~
21503 \SpecialChar ~
21504 \SpecialChar ~
21505 Toggle Sdcdbsrc mode
21506 \newline
21507 ;;\SpecialChar ~
21508 ESC\SpecialChar ~
21509 m\SpecialChar ~
21510 \SpecialChar ~
21511 \SpecialChar ~
21512 \SpecialChar ~
21513 \SpecialChar ~
21514 \SpecialChar ~
21515 \SpecialChar ~
21516 \SpecialChar ~
21517 \SpecialChar ~
21518 \SpecialChar ~
21519 \SpecialChar ~
21520 sdcdbsrc-srcmode\SpecialChar ~
21521 \SpecialChar ~
21522 \SpecialChar ~
21523 \SpecialChar ~
21524 \SpecialChar ~
21525 \SpecialChar ~
21526 \SpecialChar ~
21527 \SpecialChar ~
21528 \SpecialChar ~
21529 \SpecialChar ~
21530 \SpecialChar ~
21531 \SpecialChar ~
21532 \SpecialChar ~
21533 Toggle list mode
21534 \newline
21535 ;;
21536 \newline
21537
21538 \layout Chapter
21539 \pagebreak_top
21540 TIPS
21541 \layout Standard
21542
21543 Here are a few guidelines that will help the compiler generate more efficient
21544  code, some of the tips are specific to this compiler others are generally
21545  good programming practice.
21546 \layout Itemize
21547
21548 Use the smallest data type to represent your data-value.
21549  If it is known in advance that the value is going to be less than 256 then
21550  use an 'unsigned char' instead of a 'short' or 'int'.
21551  Please note, that ANSI C requires both signed and unsigned chars to be
21552  promoted to 'signed int' before doing any operation.
21553  This promotion
21554 \begin_inset LatexCommand \index{type promotion}
21555
21556 \end_inset
21557
21558  can be omitted, if the result is the same.
21559  The effect of the promotion rules together with the sign-extension is often
21560  surprising:
21561 \begin_deeper
21562 \layout Verse
21563
21564
21565 \family typewriter
21566 unsigned char uc = 0xfe;
21567 \newline
21568 if (uc * uc < 0) /* this is true! */
21569 \newline
21570 {
21571 \newline
21572 \SpecialChar ~
21573 \SpecialChar ~
21574 \SpecialChar ~
21575 \SpecialChar ~
21576 ....
21577 \newline
21578 }
21579 \layout Standard
21580
21581
21582 \family typewriter
21583 uc * uc
21584 \family default
21585  is evaluated as
21586 \family typewriter
21587 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
21588 \family default
21589 .
21590
21591 \newline
21592 Another one:
21593 \layout Verse
21594
21595
21596 \family typewriter
21597 (unsigned char) -12 / (signed char) -3 = ...
21598 \layout Standard
21599
21600 No, the result is not 4:
21601 \layout Verse
21602
21603
21604 \family typewriter
21605 (int) (unsigned char) -12 / (int) (signed char) -3 =
21606 \newline
21607 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
21608 \newline
21609 (int) 0x00f4 / (int) 0xfffd =
21610 \newline
21611 (int) 0x00f4 / (int) 0xfffd =
21612 \newline
21613 (int) 244 / (int) -3 =
21614 \newline
21615 (int) -81 = (int) 0xffaf;
21616 \layout Standard
21617
21618 Don't complain, that gcc gives you a different result.
21619  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
21620  Therefore the results are different.
21621 \newline
21622 From
21623 \begin_inset Quotes sld
21624 \end_inset
21625
21626 comp.lang.c FAQ
21627 \begin_inset Quotes srd
21628 \end_inset
21629
21630 :
21631 \layout Quote
21632
21633 If well-defined overflow characteristics are important and negative values
21634  are not, or if you want to steer clear of sign-extension problems when
21635  manipulating bits or bytes, use one of the corresponding unsigned types.
21636  (Beware when mixing signed and unsigned values in expressions, though.)
21637 \newline
21638 Although character types (especially unsigned char) can be used as "tiny"
21639  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
21640 ble sign extension and increased code size.
21641 \end_deeper
21642 \layout Itemize
21643
21644 Use unsigned when it is known in advance that the value is not going to
21645  be negative.
21646  This helps especially if you are doing division or multiplication, bit-shifting
21647  or are using an array index.
21648 \layout Itemize
21649
21650 NEVER jump into a LOOP.
21651 \layout Itemize
21652
21653 Declare the variables to be local
21654 \begin_inset LatexCommand \index{local variables}
21655
21656 \end_inset
21657
21658  whenever possible, especially loop control variables (induction).
21659 \layout Itemize
21660
21661 Since the compiler does not always do implicit integral promotion, the programme
21662 r should do an explicit cast when integral promotion is required.
21663 \layout Itemize
21664
21665 Reducing the size of division, multiplication & modulus operations can reduce
21666  code size substantially.
21667  Take the following code for example.
21668 \begin_deeper
21669 \layout Verse
21670
21671
21672 \family typewriter
21673 foobar(unsigned int p1, unsigned char ch)
21674 \newline
21675 {
21676 \newline
21677 \SpecialChar ~
21678 \SpecialChar ~
21679 \SpecialChar ~
21680 \SpecialChar ~
21681 unsigned char ch1 = p1 % ch ;
21682 \newline
21683 \SpecialChar ~
21684 \SpecialChar ~
21685 \SpecialChar ~
21686 \SpecialChar ~
21687 ....
21688 \newline
21689 }
21690 \layout Standard
21691
21692 For the modulus operation the variable ch will be promoted to unsigned int
21693  first then the modulus operation will be performed (this will lead to a
21694  call to support routine _moduint()), and the result will be casted to a
21695  char.
21696  If the code is changed to
21697 \layout Verse
21698
21699
21700 \family typewriter
21701 foobar(unsigned int p1, unsigned char ch)
21702 \newline
21703 {
21704 \newline
21705 \SpecialChar ~
21706 \SpecialChar ~
21707 \SpecialChar ~
21708 \SpecialChar ~
21709 unsigned char ch1 = (unsigned char)p1 % ch ;
21710 \newline
21711 \SpecialChar ~
21712 \SpecialChar ~
21713 \SpecialChar ~
21714 \SpecialChar ~
21715 ....
21716 \newline
21717 }
21718 \layout Standard
21719
21720 It would substantially reduce the code generated (future versions of the
21721  compiler will be smart enough to detect such optimization opportunities).
21722 \end_deeper
21723 \layout Itemize
21724
21725 Have a look at the assembly listing to get a
21726 \begin_inset Quotes sld
21727 \end_inset
21728
21729 feeling
21730 \begin_inset Quotes srd
21731 \end_inset
21732
21733  for the code generation.
21734 \layout Section
21735
21736 Tools
21737 \begin_inset LatexCommand \index{Tools}
21738
21739 \end_inset
21740
21741  included in the distribution
21742 \layout Standard
21743 \align center
21744
21745 \begin_inset  Tabular
21746 <lyxtabular version="3" rows="12" columns="3">
21747 <features>
21748 <column alignment="center" valignment="top" leftline="true" width="0pt">
21749 <column alignment="center" valignment="top" leftline="true" width="0pt">
21750 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21751 <row topline="true" bottomline="true">
21752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21753 \begin_inset Text
21754
21755 \layout Standard
21756
21757 Name
21758 \end_inset
21759 </cell>
21760 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21761 \begin_inset Text
21762
21763 \layout Standard
21764
21765 Purpose
21766 \end_inset
21767 </cell>
21768 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21769 \begin_inset Text
21770
21771 \layout Standard
21772
21773 Directory
21774 \end_inset
21775 </cell>
21776 </row>
21777 <row topline="true">
21778 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21779 \begin_inset Text
21780
21781 \layout Standard
21782
21783 uCsim
21784 \end_inset
21785 </cell>
21786 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21787 \begin_inset Text
21788
21789 \layout Standard
21790
21791 Simulator for various architectures
21792 \end_inset
21793 </cell>
21794 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21795 \begin_inset Text
21796
21797 \layout Standard
21798
21799 sdcc/sim/ucsim
21800 \end_inset
21801 </cell>
21802 </row>
21803 <row topline="true">
21804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21805 \begin_inset Text
21806
21807 \layout Standard
21808
21809 keil2sdcc.pl
21810 \end_inset
21811 </cell>
21812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21813 \begin_inset Text
21814
21815 \layout Standard
21816
21817 header file conversion
21818 \end_inset
21819 </cell>
21820 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21821 \begin_inset Text
21822
21823 \layout Standard
21824
21825 sdcc/support/scripts
21826 \end_inset
21827 </cell>
21828 </row>
21829 <row topline="true">
21830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21831 \begin_inset Text
21832
21833 \layout Standard
21834
21835 mh2h.c
21836 \end_inset
21837 </cell>
21838 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21839 \begin_inset Text
21840
21841 \layout Standard
21842
21843 header file conversion
21844 \end_inset
21845 </cell>
21846 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21847 \begin_inset Text
21848
21849 \layout Standard
21850
21851 sdcc/support/scripts
21852 \end_inset
21853 </cell>
21854 </row>
21855 <row topline="true">
21856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21857 \begin_inset Text
21858
21859 \layout Standard
21860
21861 as-gbz80
21862 \end_inset
21863 </cell>
21864 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21865 \begin_inset Text
21866
21867 \layout Standard
21868
21869 Assembler
21870 \end_inset
21871 </cell>
21872 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21873 \begin_inset Text
21874
21875 \layout Standard
21876
21877
21878 \family roman
21879 \series medium
21880 \shape up
21881 \size normal
21882 \emph off
21883 \bar no
21884 \noun off
21885 \color none
21886 sdcc/bin
21887 \end_inset
21888 </cell>
21889 </row>
21890 <row topline="true">
21891 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21892 \begin_inset Text
21893
21894 \layout Standard
21895
21896 as-z80
21897 \end_inset
21898 </cell>
21899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21900 \begin_inset Text
21901
21902 \layout Standard
21903
21904 Assembler
21905 \end_inset
21906 </cell>
21907 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21908 \begin_inset Text
21909
21910 \layout Standard
21911
21912
21913 \family roman
21914 \series medium
21915 \shape up
21916 \size normal
21917 \emph off
21918 \bar no
21919 \noun off
21920 \color none
21921 sdcc/bin
21922 \end_inset
21923 </cell>
21924 </row>
21925 <row topline="true">
21926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21927 \begin_inset Text
21928
21929 \layout Standard
21930
21931 asx8051
21932 \end_inset
21933 </cell>
21934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21935 \begin_inset Text
21936
21937 \layout Standard
21938
21939 Assembler
21940 \end_inset
21941 </cell>
21942 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21943 \begin_inset Text
21944
21945 \layout Standard
21946
21947
21948 \family roman
21949 \series medium
21950 \shape up
21951 \size normal
21952 \emph off
21953 \bar no
21954 \noun off
21955 \color none
21956 sdcc/bin
21957 \end_inset
21958 </cell>
21959 </row>
21960 <row topline="true">
21961 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21962 \begin_inset Text
21963
21964 \layout Standard
21965
21966 sdcdb
21967 \end_inset
21968 </cell>
21969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21970 \begin_inset Text
21971
21972 \layout Standard
21973
21974 Simulator
21975 \end_inset
21976 </cell>
21977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21978 \begin_inset Text
21979
21980 \layout Standard
21981
21982
21983 \family roman
21984 \series medium
21985 \shape up
21986 \size normal
21987 \emph off
21988 \bar no
21989 \noun off
21990 \color none
21991 sdcc/bin
21992 \end_inset
21993 </cell>
21994 </row>
21995 <row topline="true">
21996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21997 \begin_inset Text
21998
21999 \layout Standard
22000
22001 aslink
22002 \end_inset
22003 </cell>
22004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22005 \begin_inset Text
22006
22007 \layout Standard
22008
22009 Linker
22010 \end_inset
22011 </cell>
22012 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22013 \begin_inset Text
22014
22015 \layout Standard
22016
22017
22018 \family roman
22019 \series medium
22020 \shape up
22021 \size normal
22022 \emph off
22023 \bar no
22024 \noun off
22025 \color none
22026 sdcc/bin
22027 \end_inset
22028 </cell>
22029 </row>
22030 <row topline="true">
22031 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22032 \begin_inset Text
22033
22034 \layout Standard
22035
22036 link-z80
22037 \end_inset
22038 </cell>
22039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22040 \begin_inset Text
22041
22042 \layout Standard
22043
22044 Linker
22045 \end_inset
22046 </cell>
22047 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22048 \begin_inset Text
22049
22050 \layout Standard
22051
22052
22053 \family roman
22054 \series medium
22055 \shape up
22056 \size normal
22057 \emph off
22058 \bar no
22059 \noun off
22060 \color none
22061 sdcc/bin
22062 \end_inset
22063 </cell>
22064 </row>
22065 <row topline="true">
22066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22067 \begin_inset Text
22068
22069 \layout Standard
22070
22071 link-gbz80
22072 \end_inset
22073 </cell>
22074 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22075 \begin_inset Text
22076
22077 \layout Standard
22078
22079 Linker
22080 \end_inset
22081 </cell>
22082 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22083 \begin_inset Text
22084
22085 \layout Standard
22086
22087
22088 \family roman
22089 \series medium
22090 \shape up
22091 \size normal
22092 \emph off
22093 \bar no
22094 \noun off
22095 \color none
22096 sdcc/bin
22097 \end_inset
22098 </cell>
22099 </row>
22100 <row topline="true" bottomline="true">
22101 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22102 \begin_inset Text
22103
22104 \layout Standard
22105
22106 packihx
22107 \end_inset
22108 </cell>
22109 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22110 \begin_inset Text
22111
22112 \layout Standard
22113
22114 ihx packer
22115 \end_inset
22116 </cell>
22117 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22118 \begin_inset Text
22119
22120 \layout Standard
22121
22122
22123 \family roman
22124 \series medium
22125 \shape up
22126 \size normal
22127 \emph off
22128 \bar no
22129 \noun off
22130 \color none
22131 sdcc/bin
22132 \end_inset
22133 </cell>
22134 </row>
22135 </lyxtabular>
22136
22137 \end_inset
22138
22139
22140 \newline
22141
22142 \layout Section
22143
22144 Documentation
22145 \begin_inset LatexCommand \index{Documentation}
22146
22147 \end_inset
22148
22149  included in the distribution
22150 \layout Standard
22151 \align center
22152
22153 \begin_inset  Tabular
22154 <lyxtabular version="3" rows="10" columns="2">
22155 <features>
22156 <column alignment="left" valignment="top" leftline="true" width="0">
22157 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22158 <row topline="true" bottomline="true">
22159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22160 \begin_inset Text
22161
22162 \layout Standard
22163
22164 Subject / Title
22165 \end_inset
22166 </cell>
22167 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22168 \begin_inset Text
22169
22170 \layout Standard
22171
22172 Where to get / filename
22173 \end_inset
22174 </cell>
22175 </row>
22176 <row topline="true">
22177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22178 \begin_inset Text
22179
22180 \layout Standard
22181
22182 SDCC Compiler User Guide
22183 \end_inset
22184 </cell>
22185 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22186 \begin_inset Text
22187
22188 \layout Standard
22189
22190 You're reading it right now
22191 \end_inset
22192 </cell>
22193 </row>
22194 <row topline="true">
22195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22196 \begin_inset Text
22197
22198 \layout Standard
22199
22200 Changelog of SDCC
22201 \end_inset
22202 </cell>
22203 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22204 \begin_inset Text
22205
22206 \layout Standard
22207
22208 sdcc/Changelog
22209 \end_inset
22210 </cell>
22211 </row>
22212 <row topline="true">
22213 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22214 \begin_inset Text
22215
22216 \layout Standard
22217
22218 ASXXXX
22219 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
22220
22221 \end_inset
22222
22223
22224 \begin_inset LatexCommand \index{Assembler documentation}
22225
22226 \end_inset
22227
22228  Assemblers and ASLINK
22229 \begin_inset LatexCommand \index{aslink}
22230
22231 \end_inset
22232
22233
22234 \begin_inset LatexCommand \index{Linker documentation}
22235
22236 \end_inset
22237
22238  Relocating Linker
22239 \end_inset
22240 </cell>
22241 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22242 \begin_inset Text
22243
22244 \layout Standard
22245
22246 sdcc/as/doc/asxhtm.html
22247 \end_inset
22248 </cell>
22249 </row>
22250 <row topline="true">
22251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22252 \begin_inset Text
22253
22254 \layout Standard
22255
22256 SDCC regression test
22257 \begin_inset LatexCommand \index{Regression test}
22258
22259 \end_inset
22260
22261
22262 \end_inset
22263 </cell>
22264 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22265 \begin_inset Text
22266
22267 \layout Standard
22268
22269 sdcc/doc/test_suite_spec.pdf
22270 \end_inset
22271 </cell>
22272 </row>
22273 <row topline="true">
22274 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22275 \begin_inset Text
22276
22277 \layout Standard
22278
22279 Various notes
22280 \end_inset
22281 </cell>
22282 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22283 \begin_inset Text
22284
22285 \layout Standard
22286
22287 sdcc/doc/*
22288 \end_inset
22289 </cell>
22290 </row>
22291 <row topline="true">
22292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22293 \begin_inset Text
22294
22295 \layout Standard
22296
22297 Notes on debugging with sdcdb
22298 \begin_inset LatexCommand \index{sdcdb (debugger)}
22299
22300 \end_inset
22301
22302
22303 \end_inset
22304 </cell>
22305 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22306 \begin_inset Text
22307
22308 \layout Standard
22309
22310 sdcc/debugger/README
22311 \end_inset
22312 </cell>
22313 </row>
22314 <row topline="true">
22315 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22316 \begin_inset Text
22317
22318 \layout Standard
22319
22320 Software simulator for microcontrollers
22321 \end_inset
22322 </cell>
22323 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22324 \begin_inset Text
22325
22326 \layout Standard
22327
22328
22329 \family roman
22330 \series medium
22331 \shape up
22332 \size normal
22333 \emph off
22334 \bar no
22335 \noun off
22336 \color none
22337 sdcc/sim/ucsim/doc
22338 \family default
22339 \series default
22340 \shape default
22341 \size default
22342 \emph default
22343 \bar default
22344 \noun default
22345 \color default
22346 /index.html
22347 \end_inset
22348 </cell>
22349 </row>
22350 <row topline="true">
22351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22352 \begin_inset Text
22353
22354 \layout Standard
22355
22356 Temporary notes on the pic16
22357 \begin_inset LatexCommand \index{PIC16}
22358
22359 \end_inset
22360
22361  port
22362 \end_inset
22363 </cell>
22364 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22365 \begin_inset Text
22366
22367 \layout Standard
22368
22369 sdcc/src/pic16/NOTES
22370 \end_inset
22371 </cell>
22372 </row>
22373 <row topline="true" bottomline="true">
22374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22375 \begin_inset Text
22376
22377 \layout Standard
22378
22379 SDCC internal documentation (debugging file format)
22380 \end_inset
22381 </cell>
22382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22383 \begin_inset Text
22384
22385 \layout Standard
22386
22387 sdcc/doc/
22388 \family roman
22389 \series medium
22390 \shape up
22391 \size normal
22392 \emph off
22393 \bar no
22394 \noun off
22395 \color none
22396 cdbfileformat.pd
22397 \family default
22398 \series default
22399 \shape default
22400 \size default
22401 \emph default
22402 \bar default
22403 \noun default
22404 \color default
22405 f
22406 \end_inset
22407 </cell>
22408 </row>
22409 </lyxtabular>
22410
22411 \end_inset
22412
22413
22414 \newline
22415
22416 \layout Section
22417
22418 Related open source tools
22419 \begin_inset LatexCommand \index{Related tools}
22420
22421 \end_inset
22422
22423
22424 \layout Standard
22425 \align center
22426
22427 \begin_inset  Tabular
22428 <lyxtabular version="3" rows="11" columns="3">
22429 <features>
22430 <column alignment="center" valignment="top" leftline="true" width="0pt">
22431 <column alignment="block" valignment="top" leftline="true" width="30line%">
22432 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22433 <row topline="true" bottomline="true">
22434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22435 \begin_inset Text
22436
22437 \layout Standard
22438
22439 Name
22440 \end_inset
22441 </cell>
22442 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22443 \begin_inset Text
22444
22445 \layout Standard
22446
22447 Purpose
22448 \end_inset
22449 </cell>
22450 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22451 \begin_inset Text
22452
22453 \layout Standard
22454
22455 Where to get
22456 \end_inset
22457 </cell>
22458 </row>
22459 <row topline="true">
22460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22461 \begin_inset Text
22462
22463 \layout Standard
22464
22465 gpsim
22466 \begin_inset LatexCommand \index{gpsim (pic simulator)}
22467
22468 \end_inset
22469
22470
22471 \end_inset
22472 </cell>
22473 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22474 \begin_inset Text
22475
22476 \layout Standard
22477
22478 PIC simulator
22479 \end_inset
22480 </cell>
22481 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22482 \begin_inset Text
22483
22484 \layout Standard
22485
22486
22487 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
22488
22489 \end_inset
22490
22491
22492 \end_inset
22493 </cell>
22494 </row>
22495 <row topline="true">
22496 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22497 \begin_inset Text
22498
22499 \layout Standard
22500
22501 gputils
22502 \begin_inset LatexCommand \index{gputils (pic tools)}
22503
22504 \end_inset
22505
22506
22507 \end_inset
22508 </cell>
22509 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22510 \begin_inset Text
22511
22512 \layout Standard
22513
22514 GNU PIC utilities
22515 \end_inset
22516 </cell>
22517 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22518 \begin_inset Text
22519
22520 \layout Standard
22521
22522
22523 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
22524
22525 \end_inset
22526
22527
22528 \end_inset
22529 </cell>
22530 </row>
22531 <row topline="true">
22532 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22533 \begin_inset Text
22534
22535 \layout Standard
22536
22537 flP5
22538 \end_inset
22539 </cell>
22540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22541 \begin_inset Text
22542
22543 \layout Standard
22544
22545 PIC programmer
22546 \end_inset
22547 </cell>
22548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22549 \begin_inset Text
22550
22551 \layout Standard
22552
22553
22554 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
22555
22556 \end_inset
22557
22558
22559 \end_inset
22560 </cell>
22561 </row>
22562 <row topline="true">
22563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22564 \begin_inset Text
22565
22566 \layout Standard
22567
22568 indent
22569 \begin_inset LatexCommand \index{indent (source formatting tool)}
22570
22571 \end_inset
22572
22573
22574 \end_inset
22575 </cell>
22576 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22577 \begin_inset Text
22578
22579 \layout Standard
22580
22581 Formats C source - Master of the white spaces
22582 \end_inset
22583 </cell>
22584 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22585 \begin_inset Text
22586
22587 \layout Standard
22588
22589
22590 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
22591
22592 \end_inset
22593
22594
22595 \end_inset
22596 </cell>
22597 </row>
22598 <row topline="true">
22599 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22600 \begin_inset Text
22601
22602 \layout Standard
22603
22604 srecord
22605 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
22606
22607 \end_inset
22608
22609
22610 \end_inset
22611 </cell>
22612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22613 \begin_inset Text
22614
22615 \layout Standard
22616
22617 Object file conversion, checksumming, ...
22618 \end_inset
22619 </cell>
22620 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22621 \begin_inset Text
22622
22623 \layout Standard
22624
22625
22626 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
22627
22628 \end_inset
22629
22630
22631 \end_inset
22632 </cell>
22633 </row>
22634 <row topline="true">
22635 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22636 \begin_inset Text
22637
22638 \layout Standard
22639
22640 objdump
22641 \begin_inset LatexCommand \index{objdump (tool)}
22642
22643 \end_inset
22644
22645
22646 \end_inset
22647 </cell>
22648 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22649 \begin_inset Text
22650
22651 \layout Standard
22652
22653 Object file conversion, ...
22654 \end_inset
22655 </cell>
22656 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22657 \begin_inset Text
22658
22659 \layout Standard
22660
22661 Part of binutils (should be there anyway)
22662 \end_inset
22663 </cell>
22664 </row>
22665 <row topline="true">
22666 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22667 \begin_inset Text
22668
22669 \layout Standard
22670
22671 doxygen
22672 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
22673
22674 \end_inset
22675
22676
22677 \end_inset
22678 </cell>
22679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22680 \begin_inset Text
22681
22682 \layout Standard
22683
22684 Source code documentation system
22685 \end_inset
22686 </cell>
22687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22688 \begin_inset Text
22689
22690 \layout Standard
22691
22692
22693 \begin_inset LatexCommand \url{http://www.doxygen.org}
22694
22695 \end_inset
22696
22697
22698 \end_inset
22699 </cell>
22700 </row>
22701 <row topline="true">
22702 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22703 \begin_inset Text
22704
22705 \layout Standard
22706
22707 kdevelop
22708 \end_inset
22709 </cell>
22710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22711 \begin_inset Text
22712
22713 \layout Standard
22714
22715 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
22716 \end_inset
22717 </cell>
22718 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22719 \begin_inset Text
22720
22721 \layout Standard
22722
22723
22724 \begin_inset LatexCommand \url{http://www.kdevelop.org}
22725
22726 \end_inset
22727
22728
22729 \end_inset
22730 </cell>
22731 </row>
22732 <row topline="true">
22733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22734 \begin_inset Text
22735
22736 \layout Standard
22737
22738 splint
22739 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22740
22741 \end_inset
22742
22743
22744 \end_inset
22745 </cell>
22746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22747 \begin_inset Text
22748
22749 \layout Standard
22750
22751 Statically checks c sources (see
22752 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22753
22754 \end_inset
22755
22756 )
22757 \end_inset
22758 </cell>
22759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22760 \begin_inset Text
22761
22762 \layout Standard
22763
22764
22765 \begin_inset LatexCommand \url{http://www.splint.org}
22766
22767 \end_inset
22768
22769
22770 \end_inset
22771 </cell>
22772 </row>
22773 <row topline="true" bottomline="true">
22774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22775 \begin_inset Text
22776
22777 \layout Standard
22778
22779 ddd
22780 \begin_inset LatexCommand \index{ddd (debugger)}
22781
22782 \end_inset
22783
22784
22785 \end_inset
22786 </cell>
22787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22788 \begin_inset Text
22789
22790 \layout Standard
22791
22792 Debugger, serves nicely as GUI to sdcdb
22793 \begin_inset LatexCommand \index{sdcdb (debugger)}
22794
22795 \end_inset
22796
22797  (Unix only)
22798 \end_inset
22799 </cell>
22800 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22801 \begin_inset Text
22802
22803 \layout Standard
22804
22805
22806 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
22807
22808 \end_inset
22809
22810
22811 \end_inset
22812 </cell>
22813 </row>
22814 </lyxtabular>
22815
22816 \end_inset
22817
22818
22819 \newline
22820
22821 \layout Section
22822
22823 Related documentation / recommended reading
22824 \layout Standard
22825 \align center
22826
22827 \begin_inset  Tabular
22828 <lyxtabular version="3" rows="6" columns="3">
22829 <features>
22830 <column alignment="center" valignment="top" leftline="true" width="0pt">
22831 <column alignment="block" valignment="top" leftline="true" width="30line%">
22832 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
22833 <row topline="true" bottomline="true">
22834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22835 \begin_inset Text
22836
22837 \layout Standard
22838
22839 Name
22840 \end_inset
22841 </cell>
22842 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22843 \begin_inset Text
22844
22845 \layout Standard
22846
22847 Subject / Title
22848 \end_inset
22849 </cell>
22850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22851 \begin_inset Text
22852
22853 \layout Standard
22854
22855 Where to get
22856 \end_inset
22857 </cell>
22858 </row>
22859 <row topline="true">
22860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22861 \begin_inset Text
22862
22863 \layout Standard
22864
22865
22866 \family roman
22867 \series medium
22868 \shape up
22869 \size normal
22870 \emph off
22871 \bar no
22872 \noun off
22873 \color none
22874 c-refcard.pdf
22875 \end_inset
22876 </cell>
22877 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22878 \begin_inset Text
22879
22880 \layout Standard
22881
22882 C Reference Card
22883 \begin_inset LatexCommand \index{C Reference card}
22884
22885 \end_inset
22886
22887 , 2 pages
22888 \end_inset
22889 </cell>
22890 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22891 \begin_inset Text
22892
22893 \layout Standard
22894
22895
22896 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
22897
22898 \end_inset
22899
22900
22901 \end_inset
22902 </cell>
22903 </row>
22904 <row topline="true">
22905 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22906 \begin_inset Text
22907
22908 \layout Standard
22909
22910 c-faq
22911 \end_inset
22912 </cell>
22913 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22914 \begin_inset Text
22915
22916 \layout Standard
22917
22918 C-FAQ-list
22919 \end_inset
22920 </cell>
22921 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22922 \begin_inset Text
22923
22924 \layout Standard
22925
22926
22927 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
22928
22929 \end_inset
22930
22931
22932 \end_inset
22933 </cell>
22934 </row>
22935 <row topline="true">
22936 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22937 \begin_inset Text
22938
22939 \layout Standard
22940
22941 \end_inset
22942 </cell>
22943 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22944 \begin_inset Text
22945
22946 \layout Standard
22947
22948 Latest datasheet of the target CPU
22949 \end_inset
22950 </cell>
22951 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22952 \begin_inset Text
22953
22954 \layout Standard
22955
22956 vendor
22957 \end_inset
22958 </cell>
22959 </row>
22960 <row topline="true">
22961 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22962 \begin_inset Text
22963
22964 \layout Standard
22965
22966 \end_inset
22967 </cell>
22968 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22969 \begin_inset Text
22970
22971 \layout Standard
22972
22973 Revision history of datasheet
22974 \end_inset
22975 </cell>
22976 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22977 \begin_inset Text
22978
22979 \layout Standard
22980
22981 vendor
22982 \end_inset
22983 </cell>
22984 </row>
22985 <row topline="true" bottomline="true">
22986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22987 \begin_inset Text
22988
22989 \layout Standard
22990
22991 S.
22992  S.
22993  Muchnick
22994 \end_inset
22995 </cell>
22996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22997 \begin_inset Text
22998
22999 \layout Standard
23000
23001 Advanced Compiler Design and Implementation
23002 \end_inset
23003 </cell>
23004 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23005 \begin_inset Text
23006
23007 \layout Standard
23008
23009 bookstore (very dedicated, probably read other books first)
23010 \end_inset
23011 </cell>
23012 </row>
23013 </lyxtabular>
23014
23015 \end_inset
23016
23017
23018 \newline
23019
23020 \layout Section
23021
23022 Some Questions
23023 \layout Standard
23024
23025 Some questions answered, some pointers given - it might be time to in turn
23026  ask
23027 \emph on
23028 you
23029 \emph default
23030  some questions:
23031 \layout Itemize
23032
23033 can you solve your project with the selected microcontroller? Would you
23034  find out early or rather late that your target is too small/slow/whatever?
23035  Can you switch to a slightly better device if it doesn't fit?
23036 \layout Itemize
23037
23038 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
23039  and/or another programming language be more adequate? Would an operating
23040  system on the target device help?
23041 \layout Itemize
23042
23043 if you solved the problem, will the marketing department be happy?
23044 \layout Itemize
23045
23046 if the marketing department is happy, will customers be happy?
23047 \layout Itemize
23048
23049 if you're the project manager, marketing department and maybe even the customer
23050  in one person, have you tried to see the project from the outside?
23051 \layout Itemize
23052
23053 is the project done if you think it is done? Or is just that other interface/pro
23054 tocol/feature/configuration/option missing? How about website, manual(s),
23055  internationali(z|s)ation, packaging, labels, 2nd source for components,
23056  electromagnetic compatability/interference, documentation for production,
23057  production test software, update mechanism, patent issues?
23058 \layout Itemize
23059
23060 is your project adequately positioned in that magic triangle: fame, fortune,
23061  fun?
23062 \layout Standard
23063
23064 Maybe not all answers to these questions are known and some answers may
23065  even be
23066 \emph on
23067 no
23068 \emph default
23069 , nevertheless knowing these questions may help you to avoid burnout
23070 \begin_inset Foot
23071 collapsed false
23072
23073 \layout Standard
23074
23075 burnout is bad for electronic devices, programmers and motorcycle tyres
23076 \end_inset
23077
23078 .
23079  Chances are you didn't want to hear some of them...
23080 \layout Chapter
23081
23082 Support
23083 \begin_inset LatexCommand \index{Support}
23084
23085 \end_inset
23086
23087
23088 \layout Standard
23089
23090 SDCC has grown to be a large project.
23091  The compiler alone (without the preprocessor, assembler and linker) is
23092  well over 100,000 lines of code (blank stripped).
23093  The open source nature of this project is a key to its continued growth
23094  and support.
23095  You gain the benefit and support of many active software developers and
23096  end users.
23097  Is SDCC perfect? No, that's why we need your help.
23098  The developers take pride in fixing reported bugs.
23099  You can help by reporting the bugs and helping other SDCC users.
23100  There are lots of ways to contribute, and we encourage you to take part
23101  in making SDCC a great software package.
23102
23103 \layout Standard
23104
23105 The SDCC project is hosted on the SDCC sourceforge site at
23106 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
23107
23108 \end_inset
23109
23110 .
23111  You'll find the complete set of mailing lists
23112 \begin_inset LatexCommand \index{Mailing list(s)}
23113
23114 \end_inset
23115
23116 , forums, bug reporting system, patch submission
23117 \begin_inset LatexCommand \index{Patch submission}
23118
23119 \end_inset
23120
23121  system, download
23122 \begin_inset LatexCommand \index{download}
23123
23124 \end_inset
23125
23126  area and Subversion code repository
23127 \begin_inset LatexCommand \index{Subversion code repository}
23128
23129 \end_inset
23130
23131  there.
23132 \layout Section
23133
23134 Reporting Bugs
23135 \begin_inset LatexCommand \index{Bug reporting}
23136
23137 \end_inset
23138
23139
23140 \begin_inset LatexCommand \index{Reporting bugs}
23141
23142 \end_inset
23143
23144
23145 \layout Standard
23146
23147 The recommended way of reporting bugs is using the infrastructure of the
23148  sourceforge site.
23149  You can follow the status of bug reports there and have an overview about
23150  the known bugs.
23151 \layout Standard
23152
23153 Bug reports are automatically forwarded to the developer mailing list and
23154  will be fixed ASAP.
23155  When reporting a bug, it is very useful to include a small test program
23156  (the smaller the better) which reproduces the problem.
23157  If you can isolate the problem by looking at the generated assembly code,
23158  this can be very helpful.
23159  Compiling your program with the -
23160 \begin_inset ERT
23161 status Collapsed
23162
23163 \layout Standard
23164
23165 \backslash
23166 /
23167 \end_inset
23168
23169 -dumpall
23170 \begin_inset LatexCommand \index{-\/-dumpall}
23171
23172 \end_inset
23173
23174  option can sometimes be useful in locating optimization problems.
23175  When reporting a bug please maker sure you:
23176 \layout Enumerate
23177
23178 Attach the code you are compiling with SDCC.
23179
23180 \layout Enumerate
23181
23182 Specify the exact command you use to run SDCC, or attach your Makefile.
23183
23184 \layout Enumerate
23185
23186 Specify the SDCC version (type "
23187 \family sans
23188 \series bold
23189 sdcc -v
23190 \family default
23191 \series default
23192 "), your platform, and operating system.
23193
23194 \layout Enumerate
23195
23196 Provide an exact copy of any error message or incorrect output.
23197
23198 \layout Enumerate
23199
23200 Put something meaningful in the subject of your message.
23201 \layout Standard
23202
23203 Please attempt to include these 5 important parts, as applicable, in all
23204  requests for support or when reporting any problems or bugs with SDCC.
23205  Though this will make your message lengthy, it will greatly improve your
23206  chance that SDCC users and developers will be able to help you.
23207  Some SDCC developers are frustrated by bug reports without code provided
23208  that they can use to reproduce and ultimately fix the problem, so please
23209  be sure to provide sample code if you are reporting a bug!
23210 \layout Standard
23211
23212 Please have a short check that you are using a recent version of SDCC and
23213  the bug is not yet known.
23214  This is the link for reporting bugs:
23215 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
23216
23217 \end_inset
23218
23219 .
23220 \layout Section
23221
23222 Requesting Features
23223 \begin_inset LatexCommand \label{sub:Requesting-Features}
23224
23225 \end_inset
23226
23227
23228 \begin_inset LatexCommand \index{Feature request}
23229
23230 \end_inset
23231
23232
23233 \begin_inset LatexCommand \index{Requesting features}
23234
23235 \end_inset
23236
23237
23238 \layout Standard
23239
23240 Like bug reports feature requests are forwarded to the developer mailing
23241  list.
23242  This is the link for requesting features:
23243 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
23244
23245 \end_inset
23246
23247 .
23248 \layout Section
23249
23250 Submitting patches
23251 \layout Standard
23252
23253 Like bug reports contributed patches are forwarded to the developer mailing
23254  list.
23255  This is the link for submitting patches
23256 \begin_inset LatexCommand \index{Patch submission}
23257
23258 \end_inset
23259
23260 :
23261 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
23262
23263 \end_inset
23264
23265 .
23266 \layout Standard
23267
23268 You need to specify some parameters to the
23269 \family typewriter
23270 diff
23271 \family default
23272  command for the patches to be useful.
23273  If you modified more than one file a patch created f.e.
23274  with
23275 \family sans
23276 \series bold
23277
23278 \begin_inset Quotes sld
23279 \end_inset
23280
23281 diff -Naur unmodified_directory modified_directory >my_changes.patch
23282 \begin_inset Quotes srd
23283 \end_inset
23284
23285
23286 \family default
23287 \series default
23288  will be fine, otherwise
23289 \family sans
23290 \series bold
23291
23292 \begin_inset Quotes sld
23293 \end_inset
23294
23295 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
23296 \begin_inset Quotes srd
23297 \end_inset
23298
23299
23300 \series default
23301
23302 \family default
23303 will do.
23304 \layout Section
23305
23306 Getting Help
23307 \layout Standard
23308
23309 These links should take you directly to the
23310 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
23311
23312 \end_inset
23313
23314
23315 \begin_inset Foot
23316 collapsed false
23317
23318 \layout Standard
23319
23320 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
23321  automated messages (mid 2003)
23322 \end_inset
23323
23324  and the
23325 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
23326
23327 \end_inset
23328
23329 , lists
23330 \begin_inset LatexCommand \index{Mailing list(s)}
23331
23332 \end_inset
23333
23334  and forums are archived and searchable so if you are lucky someone already
23335  had a similar problem.
23336  While mails to the lists themselves are delivered promptly their web front
23337  end on sourceforge sometimes shows a severe time lag (up to several weeks),
23338  if you're seriously using SDCC please consider subscribing to the lists.
23339 \layout Section
23340
23341 ChangeLog
23342 \layout Standard
23343
23344 You can follow the status of the Subversion version
23345 \begin_inset LatexCommand \index{version}
23346
23347 \end_inset
23348
23349  of SDCC by watching the Changelog
23350 \begin_inset LatexCommand \index{Changelog}
23351
23352 \end_inset
23353
23354  in the Subversion repository
23355 \newline
23356
23357 \size footnotesize
23358
23359 \begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
23360
23361 \end_inset
23362
23363 .
23364 \layout Section
23365
23366 Release policy
23367 \begin_inset LatexCommand \index{Release policy}
23368
23369 \end_inset
23370
23371
23372 \layout Standard
23373
23374 Historically there often were long delays between official releases and
23375  the sourceforge download area tends to get not updated at all.
23376  Excuses in the past might have referred to problems with live range analysis,
23377  but as this was fixed a while ago, the current problem is that another
23378  excuse has to be found.
23379  Kidding aside, we have to get better there! On the other hand there are
23380  daily snapshots available at
23381 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
23382
23383 \end_inset
23384
23385 , and you can always build the very last version (hopefully with many bugs
23386  fixed, and features added) from the source code available at
23387 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
23388
23389 \end_inset
23390
23391 .
23392 \layout Section
23393
23394 Examples
23395 \begin_inset LatexCommand \index{Examples}
23396
23397 \end_inset
23398
23399
23400 \layout Standard
23401
23402 You'll find some small examples in the directory
23403 \emph on
23404 sdcc/device/examples/.
23405
23406 \emph default
23407 More examples and libraries are available at
23408 \emph on
23409  The SDCC Open Knowledge Resource
23410 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
23411
23412 \end_inset
23413
23414
23415 \emph default
23416 web site or at
23417 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
23418
23419 \end_inset
23420
23421 .
23422 \layout Comment
23423
23424 I did insert a reference to Paul's web site here although it seems rather
23425  dedicated to a specific 8032 board (I think it's okay because it f.e.
23426  shows LCD/Harddisc interface and has a free 8051 monitor.
23427  Independent 8032 board vendors face hard competition of heavily subsidized
23428  development boards anyway).
23429 \layout Comment
23430
23431 Maybe we should include some links to real world applications.
23432  Preferably pointer to pointers (one for each architecture) so this stays
23433  manageable here?
23434 \layout Section
23435
23436 Quality control
23437 \begin_inset LatexCommand \index{Quality control}
23438
23439 \end_inset
23440
23441
23442 \layout Standard
23443
23444 The compiler is passed through nightly compile and build checks.
23445  The so called
23446 \shape italic
23447 regression tests
23448 \shape default
23449
23450 \begin_inset LatexCommand \index{Regression test}
23451
23452 \end_inset
23453
23454  check that SDCC itself compiles flawlessly on several platforms and checks
23455  the quality of the code generated by SDCC by running the code through simulator
23456 s.
23457  There is a separate document
23458 \shape italic
23459 test_suite.pdf
23460 \begin_inset LatexCommand \index{Test suite}
23461
23462 \end_inset
23463
23464
23465 \shape default
23466  about this.
23467 \layout Standard
23468
23469 You'll find the test code in the directory
23470 \shape italic
23471 sdcc/support/regression
23472 \shape default
23473 .
23474  You can run these tests manually by running
23475 \family sans
23476 make
23477 \family default
23478  in this directory (or f.e.
23479
23480 \family sans
23481 \series bold
23482
23483 \begin_inset Quotes sld
23484 \end_inset
23485
23486 make test-mcs51
23487 \begin_inset Quotes srd
23488 \end_inset
23489
23490
23491 \family default
23492 \series default
23493  if you don't want to run the complete tests).
23494  The test code might also be interesting if you want to look for examples
23495 \begin_inset LatexCommand \index{Examples}
23496
23497 \end_inset
23498
23499  checking corner cases of SDCC or if you plan to submit patches
23500 \begin_inset LatexCommand \index{Patch submission}
23501
23502 \end_inset
23503
23504 .
23505 \layout Standard
23506
23507 The pic port uses a different set of regression tests, you'll find them
23508  in the directory
23509 \shape italic
23510 sdcc/src/regression
23511 \shape default
23512 .
23513 \layout Section
23514
23515 Use of SDCC in Education
23516 \layout Standard
23517
23518 In short:
23519 \emph on
23520 highly
23521 \emph default
23522  encouraged
23523 \begin_inset Foot
23524 collapsed false
23525
23526 \layout Standard
23527
23528 the phrase "use in education" might evoke the association "
23529 \emph on
23530 only
23531 \emph default
23532  fit for use in education".
23533  This connotation is not intended but nevertheless risked as the licensing
23534  of SDCC makes it difficult to offer educational discounts
23535 \end_inset
23536
23537 .
23538  If your rationales are to:
23539 \layout Enumerate
23540
23541 give students a chance to understand the
23542 \emph on
23543 complete
23544 \emph default
23545  steps of code generation
23546 \layout Enumerate
23547
23548 have a curriculum that can be extended for years.
23549  Then you could use an fpga board as target and your curriculum will seamlessly
23550  extend from logic synthesis (
23551 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
23552
23553 \end_inset
23554
23555 ,
23556 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
23557
23558 \end_inset
23559
23560 ), over assembly programming, to C to FPGA compilers (
23561 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
23562
23563 \end_inset
23564
23565 ) and to C.
23566 \layout Enumerate
23567
23568 be able to insert excursions about skills like using a revision control
23569  system, submitting/applying patches, using a type-setting (as opposed to
23570  word-processing) engine LyX/LaTeX, using
23571 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
23572
23573 \end_inset
23574
23575 , following some
23576 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
23577
23578 \end_inset
23579
23580 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
23581  Source Software, CPU simulation, compiler regression tests
23582 \begin_inset LatexCommand \index{Regression test}
23583
23584 \end_inset
23585
23586 .
23587
23588 \newline
23589 And if there should be a shortage of ideas then you can always point students
23590  to the ever-growing feature request list
23591 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
23592
23593 \end_inset
23594
23595 .
23596 \layout Enumerate
23597
23598 not tie students to a specific host platform and instead allow them to use
23599  a host platform of
23600 \emph on
23601 their
23602 \emph default
23603  choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
23604  eventually
23605 \begin_inset LatexCommand \url[OLPC]{http://wiki.laptop.org/wiki/One_Laptop_per_Child}
23606
23607 \end_inset
23608
23609 )
23610 \layout Enumerate
23611
23612 not encourage students to use illegal copies of educational software
23613 \layout Enumerate
23614
23615 be immune to licensing/availability/price changes of the chosen tool chain
23616 \layout Enumerate
23617
23618 be able to change to a new target platform without having to adopt a new
23619  tool chain
23620 \layout Enumerate
23621
23622 have complete control over and insight into the tool chain
23623 \layout Enumerate
23624
23625 make your students aware about the pros and cons of open source software
23626  development
23627 \layout Enumerate
23628
23629 give back to the public as you are probably at least partially publically
23630  funded
23631 \layout Enumerate
23632
23633 give students a chance to publically prove their skills and to possibly
23634  see a world wide impact
23635 \layout Standard
23636
23637 then SDCC is probably among the first choices.
23638  Well, probably SDCC might be the only choice.
23639 \layout Chapter
23640 \pagebreak_top
23641 SDCC Technical Data
23642 \layout Section
23643
23644 Optimizations
23645 \begin_inset LatexCommand \index{Optimizations}
23646
23647 \end_inset
23648
23649
23650 \layout Standard
23651
23652 SDCC performs a host of standard optimizations in addition to some MCU specific
23653  optimizations.
23654
23655 \layout Subsection
23656
23657 Sub-expression Elimination
23658 \begin_inset LatexCommand \index{Subexpression elimination}
23659
23660 \end_inset
23661
23662
23663 \layout Standard
23664
23665 The compiler does local and
23666 \emph on
23667 g
23668 \emph default
23669 lobal
23670 \emph on
23671 c
23672 \emph default
23673 ommon
23674 \emph on
23675 s
23676 \emph default
23677 ubexpression
23678 \emph on
23679 e
23680 \emph default
23681 limination, e.g.:
23682 \layout Verse
23683
23684
23685 \family typewriter
23686 i = x + y + 1;
23687 \newline
23688 j = x + y;
23689 \layout Standard
23690
23691 will be translated to
23692 \layout Verse
23693
23694
23695 \family typewriter
23696 iTemp = x + y;
23697 \newline
23698 i = iTemp + 1;
23699 \newline
23700 j = iTemp;
23701 \layout Standard
23702
23703 Some subexpressions are not as obvious as the above example, e.g.:
23704 \layout Verse
23705
23706
23707 \family typewriter
23708 a->b[i].c = 10;
23709 \newline
23710 a->b[i].d = 11;
23711 \layout Standard
23712
23713 In this case the address arithmetic a->b[i] will be computed only once;
23714  the equivalent code in C would be.
23715 \layout Verse
23716
23717
23718 \family typewriter
23719 iTemp = a->b[i];
23720 \newline
23721 iTemp.c = 10;
23722 \newline
23723 iTemp.d = 11;
23724 \layout Standard
23725
23726 The compiler will try to keep these temporary variables in registers.
23727 \layout Subsection
23728
23729 Dead-Code Elimination
23730 \begin_inset LatexCommand \index{Dead-code elimination}
23731
23732 \end_inset
23733
23734
23735 \layout Verse
23736
23737
23738 \family typewriter
23739 int global;
23740 \newline
23741
23742 \newline
23743 void f () {
23744 \newline
23745 \SpecialChar ~
23746 \SpecialChar ~
23747 int i;
23748 \newline
23749 \SpecialChar ~
23750 \SpecialChar ~
23751 i = 1; \SpecialChar ~
23752 \SpecialChar ~
23753 \SpecialChar ~
23754 \SpecialChar ~
23755 \SpecialChar ~
23756 /* dead store */
23757 \newline
23758 \SpecialChar ~
23759 \SpecialChar ~
23760 global = 1;\SpecialChar ~
23761 /* dead store */
23762 \newline
23763 \SpecialChar ~
23764 \SpecialChar ~
23765 global = 2;
23766 \newline
23767 \SpecialChar ~
23768 \SpecialChar ~
23769 return;
23770 \newline
23771 \SpecialChar ~
23772 \SpecialChar ~
23773 global = 3;\SpecialChar ~
23774 /* unreachable */
23775 \newline
23776 }
23777 \layout Standard
23778
23779 will be changed to
23780 \layout Verse
23781
23782
23783 \family typewriter
23784 int global;
23785 \newline
23786
23787 \newline
23788 void f () {
23789 \newline
23790 \SpecialChar ~
23791 \SpecialChar ~
23792 global = 2;
23793 \newline
23794 }
23795 \layout Subsection
23796
23797 Copy-Propagation
23798 \begin_inset LatexCommand \index{Copy propagation}
23799
23800 \end_inset
23801
23802
23803 \layout Verse
23804
23805
23806 \family typewriter
23807 int f() {
23808 \newline
23809 \SpecialChar ~
23810 \SpecialChar ~
23811 int i, j;
23812 \newline
23813 \SpecialChar ~
23814 \SpecialChar ~
23815 i = 10;
23816 \newline
23817 \SpecialChar ~
23818 \SpecialChar ~
23819 j = i;
23820 \newline
23821 \SpecialChar ~
23822 \SpecialChar ~
23823 return j;
23824 \newline
23825 }
23826 \layout Standard
23827
23828 will be changed to
23829 \layout Verse
23830
23831
23832 \family typewriter
23833 int f() {
23834 \newline
23835 \SpecialChar ~
23836 \SpecialChar ~
23837 int i, j;
23838 \newline
23839 \SpecialChar ~
23840 \SpecialChar ~
23841 i = 10;
23842 \newline
23843 \SpecialChar ~
23844 \SpecialChar ~
23845 j = 10;
23846 \newline
23847 \SpecialChar ~
23848 \SpecialChar ~
23849 return 10;
23850 \newline
23851 }
23852 \layout Standard
23853
23854 Note: the dead stores created by this copy propagation will be eliminated
23855  by dead-code elimination.
23856 \layout Subsection
23857
23858 Loop Optimizations
23859 \begin_inset LatexCommand \index{Loop optimization}
23860
23861 \end_inset
23862
23863
23864 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
23865
23866 \end_inset
23867
23868
23869 \layout Standard
23870
23871 Two types of loop optimizations are done by SDCC
23872 \emph on
23873 loop invariant
23874 \emph default
23875  lifting and
23876 \emph on
23877  strength reduction
23878 \emph default
23879  of loop induction variables.
23880  In addition to the strength reduction the optimizer marks the induction
23881  variables and the register allocator tries to keep the induction variables
23882  in registers for the duration of the loop.
23883  Because of this preference of the register allocator
23884 \begin_inset LatexCommand \index{Register allocation}
23885
23886 \end_inset
23887
23888 , loop induction optimization causes an increase in register pressure, which
23889  may cause unwanted spilling of other temporary variables into the stack
23890 \begin_inset LatexCommand \index{stack}
23891
23892 \end_inset
23893
23894  / data space.
23895  The compiler will generate a warning message when it is forced to allocate
23896  extra space either on the stack or data space.
23897  If this extra space allocation is undesirable then induction optimization
23898  can be eliminated either for the entire source file (with -
23899 \begin_inset ERT
23900 status Collapsed
23901
23902 \layout Standard
23903
23904 \backslash
23905 /
23906 \end_inset
23907
23908 -noinduction option) or for a given function only using #pragma\SpecialChar ~
23909 noinduction
23910 \begin_inset LatexCommand \index{\#pragma noinduction}
23911
23912 \end_inset
23913
23914 .
23915 \newline
23916
23917 \newline
23918 Loop Invariant:
23919 \layout Verse
23920
23921
23922 \family typewriter
23923 for (i = 0 ; i < 100 ; i ++)
23924 \newline
23925 \SpecialChar ~
23926 \SpecialChar ~
23927 \SpecialChar ~
23928 \SpecialChar ~
23929 f += k + l;
23930 \layout Standard
23931
23932 changed to
23933 \layout Verse
23934
23935
23936 \family typewriter
23937 itemp = k + l;
23938 \newline
23939 for (i = 0; i < 100; i++)
23940 \newline
23941 \SpecialChar ~
23942 \SpecialChar ~
23943 \SpecialChar ~
23944 \SpecialChar ~
23945 f += itemp;
23946 \layout Standard
23947
23948 As mentioned previously some loop invariants are not as apparent, all static
23949  address computations are also moved out of the loop.
23950 \newline
23951
23952 \newline
23953 Strength Reduction
23954 \begin_inset LatexCommand \index{Strength reduction}
23955
23956 \end_inset
23957
23958 , this optimization substitutes an expression by a cheaper expression:
23959 \layout Verse
23960
23961
23962 \family typewriter
23963 for (i=0;i < 100; i++)
23964 \newline
23965 \SpecialChar ~
23966 \SpecialChar ~
23967 \SpecialChar ~
23968 \SpecialChar ~
23969 ar[i*5] = i*3;
23970 \layout Standard
23971
23972 changed to
23973 \layout Verse
23974
23975
23976 \family typewriter
23977 itemp1 = 0;
23978 \newline
23979 itemp2 = 0;
23980 \newline
23981 for (i=0;i< 100;i++) {
23982 \newline
23983 \SpecialChar ~
23984 \SpecialChar ~
23985 \SpecialChar ~
23986 \SpecialChar ~
23987 ar[itemp1] = itemp2;
23988 \newline
23989 \SpecialChar ~
23990 \SpecialChar ~
23991 \SpecialChar ~
23992 \SpecialChar ~
23993 itemp1 += 5;
23994 \newline
23995 \SpecialChar ~
23996 \SpecialChar ~
23997 \SpecialChar ~
23998 \SpecialChar ~
23999 itemp2 += 3;
24000 \newline
24001 }
24002 \layout Standard
24003
24004 The more expensive multiplication
24005 \begin_inset LatexCommand \index{Multiplication}
24006
24007 \end_inset
24008
24009  is changed to a less expensive addition.
24010 \layout Subsection
24011
24012 Loop Reversing
24013 \begin_inset LatexCommand \index{Loop reversing}
24014
24015 \end_inset
24016
24017
24018 \layout Standard
24019
24020 This optimization is done to reduce the overhead of checking loop boundaries
24021  for every iteration.
24022  Some simple loops can be reversed and implemented using a
24023 \begin_inset Quotes eld
24024 \end_inset
24025
24026 decrement and jump if not zero
24027 \begin_inset Quotes erd
24028 \end_inset
24029
24030  instruction.
24031  SDCC checks for the following criterion to determine if a loop is reversible
24032  (note: more sophisticated compilers use data-dependency analysis to make
24033  this determination, SDCC uses a more simple minded analysis).
24034 \layout Itemize
24035
24036 The 'for' loop is of the form
24037 \newline
24038
24039 \newline
24040
24041 \family typewriter
24042 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
24043  += 1])
24044 \newline
24045 \SpecialChar ~
24046 \SpecialChar ~
24047 \SpecialChar ~
24048 \SpecialChar ~
24049 <for body>
24050 \layout Itemize
24051
24052 The <for body> does not contain
24053 \begin_inset Quotes eld
24054 \end_inset
24055
24056 continue
24057 \begin_inset Quotes erd
24058 \end_inset
24059
24060  or 'break
24061 \begin_inset Quotes erd
24062 \end_inset
24063
24064 .
24065 \layout Itemize
24066
24067 All goto's are contained within the loop.
24068 \layout Itemize
24069
24070 No function calls within the loop.
24071 \layout Itemize
24072
24073 The loop control variable <sym> is not assigned any value within the loop
24074 \layout Itemize
24075
24076 The loop control variable does NOT participate in any arithmetic operation
24077  within the loop.
24078 \layout Itemize
24079
24080 There are NO switch statements in the loop.
24081 \layout Subsection
24082
24083 Algebraic Simplifications
24084 \layout Standard
24085
24086 SDCC does numerous algebraic simplifications, the following is a small sub-set
24087  of these optimizations.
24088 \layout Verse
24089
24090
24091 \family typewriter
24092 i = j + 0;\SpecialChar ~
24093 \SpecialChar ~
24094 \SpecialChar ~
24095 \SpecialChar ~
24096  /* changed to: */\SpecialChar ~
24097 \SpecialChar ~
24098 \SpecialChar ~
24099 \SpecialChar ~
24100  i = j;
24101 \newline
24102 i /= 2;\SpecialChar ~
24103 \SpecialChar ~
24104 \SpecialChar ~
24105 \SpecialChar ~
24106 \SpecialChar ~
24107 \SpecialChar ~
24108 \SpecialChar ~
24109  /* changed to: */\SpecialChar ~
24110 \SpecialChar ~
24111 \SpecialChar ~
24112 \SpecialChar ~
24113  i >>= 1;
24114 \newline
24115 i = j - j;\SpecialChar ~
24116 \SpecialChar ~
24117 \SpecialChar ~
24118 \SpecialChar ~
24119  /* changed to: */\SpecialChar ~
24120 \SpecialChar ~
24121 \SpecialChar ~
24122 \SpecialChar ~
24123  i = 0;
24124 \newline
24125 i = j / 1;\SpecialChar ~
24126 \SpecialChar ~
24127 \SpecialChar ~
24128 \SpecialChar ~
24129  /* changed to: */\SpecialChar ~
24130 \SpecialChar ~
24131 \SpecialChar ~
24132 \SpecialChar ~
24133  i = j;
24134 \layout Standard
24135
24136 Note the subexpressions
24137 \begin_inset LatexCommand \index{Subexpression}
24138
24139 \end_inset
24140
24141  given above are generally introduced by macro expansions or as a result
24142  of copy/constant propagation.
24143 \layout Subsection
24144
24145 'switch' Statements
24146 \begin_inset LatexCommand \label{sub:'switch'-Statements}
24147
24148 \end_inset
24149
24150
24151 \begin_inset LatexCommand \index{switch statement}
24152
24153 \end_inset
24154
24155
24156 \layout Standard
24157
24158 SDCC can optimize switch statements to jump tables
24159 \begin_inset LatexCommand \index{jump tables}
24160
24161 \end_inset
24162
24163 .
24164  It makes the decision based on an estimate of the generated code size.
24165  SDCC is quite liberal in the requirements for jump table generation:
24166 \layout Itemize
24167
24168 The labels need not be in order, and the starting number need not be one
24169  or zero, the case labels are in numerical sequence or not too many case
24170  labels are missing.
24171 \begin_deeper
24172 \layout Verse
24173
24174
24175 \family typewriter
24176 switch(i) {\SpecialChar ~
24177 \SpecialChar ~
24178 \SpecialChar ~
24179 \SpecialChar ~
24180 \SpecialChar ~
24181 \SpecialChar ~
24182 \SpecialChar ~
24183 \SpecialChar ~
24184 \SpecialChar ~
24185 \SpecialChar ~
24186 \SpecialChar ~
24187 \SpecialChar ~
24188 \SpecialChar ~
24189 \SpecialChar ~
24190 \SpecialChar ~
24191 \SpecialChar ~
24192 \SpecialChar ~
24193 \SpecialChar ~
24194 \SpecialChar ~
24195 \SpecialChar ~
24196 \SpecialChar ~
24197 \SpecialChar ~
24198 \SpecialChar ~
24199 \SpecialChar ~
24200 \SpecialChar ~
24201 \SpecialChar ~
24202 switch (i) {
24203 \newline
24204 \SpecialChar ~
24205 \SpecialChar ~
24206 \SpecialChar ~
24207 case 4: ...\SpecialChar ~
24208 \SpecialChar ~
24209 \SpecialChar ~
24210 \SpecialChar ~
24211 \SpecialChar ~
24212 \SpecialChar ~
24213 \SpecialChar ~
24214 \SpecialChar ~
24215 \SpecialChar ~
24216 \SpecialChar ~
24217 \SpecialChar ~
24218 \SpecialChar ~
24219 \SpecialChar ~
24220 \SpecialChar ~
24221 \SpecialChar ~
24222 \SpecialChar ~
24223 \SpecialChar ~
24224 \SpecialChar ~
24225 \SpecialChar ~
24226 \SpecialChar ~
24227 \SpecialChar ~
24228 \SpecialChar ~
24229 \SpecialChar ~
24230 \SpecialChar ~
24231 \SpecialChar ~
24232 \SpecialChar ~
24233 case 0: ...
24234
24235 \newline
24236 \SpecialChar ~
24237 \SpecialChar ~
24238 \SpecialChar ~
24239 case 5: ...\SpecialChar ~
24240 \SpecialChar ~
24241 \SpecialChar ~
24242 \SpecialChar ~
24243 \SpecialChar ~
24244 \SpecialChar ~
24245 \SpecialChar ~
24246 \SpecialChar ~
24247 \SpecialChar ~
24248 \SpecialChar ~
24249 \SpecialChar ~
24250 \SpecialChar ~
24251 \SpecialChar ~
24252 \SpecialChar ~
24253 \SpecialChar ~
24254 \SpecialChar ~
24255 \SpecialChar ~
24256 \SpecialChar ~
24257 \SpecialChar ~
24258 \SpecialChar ~
24259 \SpecialChar ~
24260 \SpecialChar ~
24261 \SpecialChar ~
24262 \SpecialChar ~
24263 \SpecialChar ~
24264 \SpecialChar ~
24265 case 1: ...
24266
24267 \newline
24268 \SpecialChar ~
24269 \SpecialChar ~
24270 \SpecialChar ~
24271 case 3: ...\SpecialChar ~
24272 \SpecialChar ~
24273 \SpecialChar ~
24274 \SpecialChar ~
24275 \SpecialChar ~
24276 \SpecialChar ~
24277 \SpecialChar ~
24278 \SpecialChar ~
24279 \SpecialChar ~
24280 \SpecialChar ~
24281 \SpecialChar ~
24282 \SpecialChar ~
24283 \SpecialChar ~
24284 \SpecialChar ~
24285 \SpecialChar ~
24286 \SpecialChar ~
24287 \SpecialChar ~
24288 \SpecialChar ~
24289 \SpecialChar ~
24290 \SpecialChar ~
24291 \SpecialChar ~
24292 \SpecialChar ~
24293 \SpecialChar ~
24294 \SpecialChar ~
24295 \SpecialChar ~
24296 \SpecialChar ~
24297
24298 \newline
24299 \SpecialChar ~
24300 \SpecialChar ~
24301 \SpecialChar ~
24302 case 6: ...\SpecialChar ~
24303 \SpecialChar ~
24304 \SpecialChar ~
24305 \SpecialChar ~
24306 \SpecialChar ~
24307 \SpecialChar ~
24308 \SpecialChar ~
24309 \SpecialChar ~
24310 \SpecialChar ~
24311 \SpecialChar ~
24312 \SpecialChar ~
24313 \SpecialChar ~
24314 \SpecialChar ~
24315 \SpecialChar ~
24316 \SpecialChar ~
24317 \SpecialChar ~
24318 \SpecialChar ~
24319 \SpecialChar ~
24320 \SpecialChar ~
24321 \SpecialChar ~
24322 \SpecialChar ~
24323 \SpecialChar ~
24324 \SpecialChar ~
24325 \SpecialChar ~
24326 \SpecialChar ~
24327 \SpecialChar ~
24328 case 3: ...
24329
24330 \newline
24331 \SpecialChar ~
24332 \SpecialChar ~
24333 \SpecialChar ~
24334 case 7: ...\SpecialChar ~
24335 \SpecialChar ~
24336 \SpecialChar ~
24337 \SpecialChar ~
24338 \SpecialChar ~
24339 \SpecialChar ~
24340 \SpecialChar ~
24341 \SpecialChar ~
24342 \SpecialChar ~
24343 \SpecialChar ~
24344 \SpecialChar ~
24345 \SpecialChar ~
24346 \SpecialChar ~
24347 \SpecialChar ~
24348 \SpecialChar ~
24349 \SpecialChar ~
24350 \SpecialChar ~
24351 \SpecialChar ~
24352 \SpecialChar ~
24353 \SpecialChar ~
24354 \SpecialChar ~
24355 \SpecialChar ~
24356 \SpecialChar ~
24357 \SpecialChar ~
24358 \SpecialChar ~
24359 \SpecialChar ~
24360 case 4: ...
24361
24362 \newline
24363 \SpecialChar ~
24364 \SpecialChar ~
24365 \SpecialChar ~
24366 case 8: ...\SpecialChar ~
24367 \SpecialChar ~
24368 \SpecialChar ~
24369 \SpecialChar ~
24370 \SpecialChar ~
24371 \SpecialChar ~
24372 \SpecialChar ~
24373 \SpecialChar ~
24374 \SpecialChar ~
24375 \SpecialChar ~
24376 \SpecialChar ~
24377 \SpecialChar ~
24378 \SpecialChar ~
24379 \SpecialChar ~
24380 \SpecialChar ~
24381 \SpecialChar ~
24382 \SpecialChar ~
24383 \SpecialChar ~
24384 \SpecialChar ~
24385 \SpecialChar ~
24386 \SpecialChar ~
24387 \SpecialChar ~
24388 \SpecialChar ~
24389 \SpecialChar ~
24390 \SpecialChar ~
24391 \SpecialChar ~
24392 case 5: ...
24393
24394 \newline
24395 \SpecialChar ~
24396 \SpecialChar ~
24397 \SpecialChar ~
24398 case 9: ...\SpecialChar ~
24399 \SpecialChar ~
24400 \SpecialChar ~
24401 \SpecialChar ~
24402 \SpecialChar ~
24403 \SpecialChar ~
24404 \SpecialChar ~
24405 \SpecialChar ~
24406 \SpecialChar ~
24407 \SpecialChar ~
24408 \SpecialChar ~
24409 \SpecialChar ~
24410 \SpecialChar ~
24411 \SpecialChar ~
24412 \SpecialChar ~
24413 \SpecialChar ~
24414 \SpecialChar ~
24415 \SpecialChar ~
24416 \SpecialChar ~
24417 \SpecialChar ~
24418 \SpecialChar ~
24419 \SpecialChar ~
24420 \SpecialChar ~
24421 \SpecialChar ~
24422 \SpecialChar ~
24423 \SpecialChar ~
24424 case 6: ...
24425
24426 \newline
24427 \SpecialChar ~
24428 \SpecialChar ~
24429 \SpecialChar ~
24430 case 10: ...\SpecialChar ~
24431 \SpecialChar ~
24432 \SpecialChar ~
24433 \SpecialChar ~
24434 \SpecialChar ~
24435 \SpecialChar ~
24436 \SpecialChar ~
24437 \SpecialChar ~
24438 \SpecialChar ~
24439 \SpecialChar ~
24440 \SpecialChar ~
24441 \SpecialChar ~
24442 \SpecialChar ~
24443 \SpecialChar ~
24444 \SpecialChar ~
24445 \SpecialChar ~
24446 \SpecialChar ~
24447 \SpecialChar ~
24448 \SpecialChar ~
24449 \SpecialChar ~
24450 \SpecialChar ~
24451 \SpecialChar ~
24452 \SpecialChar ~
24453 \SpecialChar ~
24454 \SpecialChar ~
24455 case 7: ...
24456
24457 \newline
24458 \SpecialChar ~
24459 \SpecialChar ~
24460 \SpecialChar ~
24461 case 11: ...\SpecialChar ~
24462 \SpecialChar ~
24463 \SpecialChar ~
24464 \SpecialChar ~
24465 \SpecialChar ~
24466 \SpecialChar ~
24467 \SpecialChar ~
24468 \SpecialChar ~
24469 \SpecialChar ~
24470 \SpecialChar ~
24471 \SpecialChar ~
24472 \SpecialChar ~
24473 \SpecialChar ~
24474 \SpecialChar ~
24475 \SpecialChar ~
24476 \SpecialChar ~
24477 \SpecialChar ~
24478 \SpecialChar ~
24479 \SpecialChar ~
24480 \SpecialChar ~
24481 \SpecialChar ~
24482 \SpecialChar ~
24483 \SpecialChar ~
24484 \SpecialChar ~
24485 \SpecialChar ~
24486 case 8: ...
24487
24488 \newline
24489 }\SpecialChar ~
24490 \SpecialChar ~
24491 \SpecialChar ~
24492 \SpecialChar ~
24493 \SpecialChar ~
24494 \SpecialChar ~
24495 \SpecialChar ~
24496 \SpecialChar ~
24497 \SpecialChar ~
24498 \SpecialChar ~
24499 \SpecialChar ~
24500 \SpecialChar ~
24501 \SpecialChar ~
24502 \SpecialChar ~
24503 \SpecialChar ~
24504 \SpecialChar ~
24505 \SpecialChar ~
24506 \SpecialChar ~
24507 \SpecialChar ~
24508 \SpecialChar ~
24509 \SpecialChar ~
24510 \SpecialChar ~
24511 \SpecialChar ~
24512 \SpecialChar ~
24513 \SpecialChar ~
24514 \SpecialChar ~
24515 \SpecialChar ~
24516 \SpecialChar ~
24517 \SpecialChar ~
24518 \SpecialChar ~
24519 \SpecialChar ~
24520 \SpecialChar ~
24521 \SpecialChar ~
24522 \SpecialChar ~
24523 \SpecialChar ~
24524 \SpecialChar ~
24525 }
24526 \layout Standard
24527
24528 Both the above switch statements will be implemented using a jump-table.
24529  The example to the right side is slightly more efficient as the check for
24530  the lower boundary of the jump-table is not needed.
24531 \end_deeper
24532 \layout Itemize
24533
24534 The number of case labels is not larger than supported by the target architectur
24535 e.
24536 \layout Itemize
24537
24538 If the case labels are not in numerical sequence ('gaps' between cases)
24539  SDCC checks whether a jump table with additionally inserted dummy cases
24540  is still attractive.
24541
24542 \layout Itemize
24543
24544 If the starting number is not zero and a check for the lower boundary of
24545  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
24546  ...
24547  .
24548 \layout Standard
24549
24550 Switch statements which have large gaps in the numeric sequence or those
24551  that have too many case labels can be split into more than one switch statement
24552  for efficient code generation, e.g.:
24553 \layout Verse
24554
24555
24556 \family typewriter
24557 switch (i) {
24558 \newline
24559 \SpecialChar ~
24560 \SpecialChar ~
24561 case 1: ...
24562
24563 \newline
24564 \SpecialChar ~
24565 \SpecialChar ~
24566 case 2: ...
24567
24568 \newline
24569 \SpecialChar ~
24570 \SpecialChar ~
24571 case 3: ...
24572
24573 \newline
24574 \SpecialChar ~
24575 \SpecialChar ~
24576 case 4: ...
24577
24578 \newline
24579 \SpecialChar ~
24580 \SpecialChar ~
24581 case 5: ...
24582
24583 \newline
24584 \SpecialChar ~
24585 \SpecialChar ~
24586 case 6: ...
24587
24588 \newline
24589 \SpecialChar ~
24590 \SpecialChar ~
24591 case 7: ...
24592
24593 \newline
24594 \SpecialChar ~
24595 \SpecialChar ~
24596 case 101: ...
24597
24598 \newline
24599 \SpecialChar ~
24600 \SpecialChar ~
24601 case 102: ...
24602
24603 \newline
24604 \SpecialChar ~
24605 \SpecialChar ~
24606 case 103: ...
24607
24608 \newline
24609 \SpecialChar ~
24610 \SpecialChar ~
24611 case 104: ...
24612
24613 \newline
24614 \SpecialChar ~
24615 \SpecialChar ~
24616 case 105: ...
24617
24618 \newline
24619 \SpecialChar ~
24620 \SpecialChar ~
24621 case 106: ...
24622
24623 \newline
24624 \SpecialChar ~
24625 \SpecialChar ~
24626 case 107: ...
24627
24628 \newline
24629 }
24630 \layout Standard
24631
24632 If the above switch statement is broken down into two switch statements
24633 \layout Verse
24634
24635
24636 \family typewriter
24637 switch (i) {
24638 \newline
24639 \SpecialChar ~
24640 \SpecialChar ~
24641 case 1: ...
24642
24643 \newline
24644 \SpecialChar ~
24645 \SpecialChar ~
24646 case 2: ...
24647
24648 \newline
24649 \SpecialChar ~
24650 \SpecialChar ~
24651 case 3: ...
24652
24653 \newline
24654 \SpecialChar ~
24655 \SpecialChar ~
24656 case 4: ...
24657
24658 \newline
24659 \SpecialChar ~
24660 \SpecialChar ~
24661 case 5: ...
24662
24663 \newline
24664 \SpecialChar ~
24665 \SpecialChar ~
24666 case 6: ...
24667
24668 \newline
24669 \SpecialChar ~
24670 \SpecialChar ~
24671 case 7: ...
24672
24673 \newline
24674 }
24675 \layout Standard
24676
24677 and
24678 \layout Verse
24679
24680
24681 \family typewriter
24682 switch (i) {
24683 \newline
24684 \SpecialChar ~
24685 \SpecialChar ~
24686 case 101: ...
24687
24688 \newline
24689 \SpecialChar ~
24690 \SpecialChar ~
24691 case 102: ...
24692
24693 \newline
24694 \SpecialChar ~
24695 \SpecialChar ~
24696 case 103: ...
24697
24698 \newline
24699 \SpecialChar ~
24700 \SpecialChar ~
24701 case 104: ...
24702
24703 \newline
24704 \SpecialChar ~
24705 \SpecialChar ~
24706 case 105: ...
24707
24708 \newline
24709 \SpecialChar ~
24710 \SpecialChar ~
24711 case 106: ...
24712
24713 \newline
24714 \SpecialChar ~
24715 \SpecialChar ~
24716 case 107: ...
24717
24718 \newline
24719 }
24720 \layout Standard
24721
24722 then both the switch statements will be implemented using jump-tables whereas
24723  the unmodified switch statement will not be.
24724 \layout Comment
24725
24726 There might be reasons which SDCC cannot know about to either favour or
24727  not favour jump tables.
24728  If the target system has to be as quick for the last switch case as for
24729  the first (pro jump table), or if the switch argument is known to be zero
24730  in the majority of the cases (contra jump table).
24731 \layout Standard
24732
24733 The pragma nojtbound
24734 \begin_inset LatexCommand \index{\#pragma nojtbound}
24735
24736 \end_inset
24737
24738  can be used to turn off checking the
24739 \emph on
24740 j
24741 \emph default
24742 ump
24743 \emph on
24744 t
24745 \emph default
24746 able
24747 \emph on
24748 bound
24749 \emph default
24750 aries.
24751  It has no effect if a default label is supplied.
24752  Use of this pragma is dangerous: if the switch
24753 \begin_inset LatexCommand \index{switch statement}
24754
24755 \end_inset
24756
24757  argument is not matched by a case statement the processor will happily
24758  jump into Nirvana.
24759 \layout Subsection
24760
24761 Bit-shifting Operations
24762 \begin_inset LatexCommand \index{Bit shifting}
24763
24764 \end_inset
24765
24766 .
24767 \layout Standard
24768
24769 Bit shifting is one of the most frequently used operation in embedded programmin
24770 g.
24771  SDCC tries to implement bit-shift operations in the most efficient way
24772  possible, e.g.:
24773 \layout Verse
24774
24775
24776 \family typewriter
24777 unsigned char i;
24778 \newline
24779 ...
24780
24781 \newline
24782 i >>= 4;
24783 \newline
24784 ...
24785 \layout Standard
24786
24787 generates the following code:
24788 \layout Verse
24789
24790
24791 \family typewriter
24792 mov\SpecialChar ~
24793  a,_i
24794 \newline
24795 swap a
24796 \newline
24797 anl\SpecialChar ~
24798  a,#0x0f
24799 \newline
24800 mov\SpecialChar ~
24801  _i,a
24802 \layout Standard
24803
24804 In general SDCC will never setup a loop if the shift count is known.
24805  Another example:
24806 \layout Verse
24807
24808
24809 \family typewriter
24810 unsigned int i;
24811 \newline
24812 ...
24813
24814 \newline
24815 i >>= 9;
24816 \newline
24817 ...
24818 \layout Standard
24819
24820 will generate:
24821 \layout Verse
24822
24823
24824 \family typewriter
24825 mov\SpecialChar ~
24826 \SpecialChar ~
24827 a,(_i + 1)
24828 \newline
24829 mov\SpecialChar ~
24830 \SpecialChar ~
24831 (_i + 1),#0x00
24832 \newline
24833 clr\SpecialChar ~
24834 \SpecialChar ~
24835 c
24836 \newline
24837 rrc\SpecialChar ~
24838 \SpecialChar ~
24839 a
24840 \newline
24841 mov\SpecialChar ~
24842 \SpecialChar ~
24843 _i,a
24844 \layout Subsection
24845
24846 Bit-rotation
24847 \begin_inset LatexCommand \index{Bit rotation}
24848
24849 \end_inset
24850
24851
24852 \layout Standard
24853
24854 A special case of the bit-shift operation is bit rotation
24855 \begin_inset LatexCommand \index{rotating bits}
24856
24857 \end_inset
24858
24859 , SDCC recognizes the following expression to be a left bit-rotation:
24860 \layout Verse
24861
24862
24863 \family typewriter
24864 \series bold
24865 unsigned
24866 \series default
24867 \SpecialChar ~
24868 \SpecialChar ~
24869 char i;\SpecialChar ~
24870 \SpecialChar ~
24871 \SpecialChar ~
24872 \SpecialChar ~
24873 \SpecialChar ~
24874 \SpecialChar ~
24875 \SpecialChar ~
24876 \SpecialChar ~
24877 \SpecialChar ~
24878 \SpecialChar ~
24879 \SpecialChar ~
24880 /* unsigned is needed for rotation */
24881 \newline
24882 ...
24883
24884 \newline
24885 i = ((i << 1) | (i >> 7));
24886 \family default
24887
24888 \newline
24889
24890 \family typewriter
24891 ...
24892 \layout Standard
24893
24894 will generate the following code:
24895 \layout Verse
24896
24897
24898 \family typewriter
24899 mov\SpecialChar ~
24900 \SpecialChar ~
24901 a,_i
24902 \newline
24903 rl\SpecialChar ~
24904 \SpecialChar ~
24905 \SpecialChar ~
24906 a
24907 \newline
24908 mov\SpecialChar ~
24909 \SpecialChar ~
24910 _i,a
24911 \layout Standard
24912
24913 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
24914 ns of this case will also be recognized as bit-rotation, i.e.:
24915 \layout Verse
24916
24917
24918 \family typewriter
24919 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
24920 \layout Subsection
24921
24922 Nibble and Byte Swapping
24923 \layout Standard
24924
24925 Other special cases of the bit-shift operations are nibble or byte swapping
24926 \begin_inset LatexCommand \index{swapping nibbles/bytes}
24927
24928 \end_inset
24929
24930 , SDCC recognizes the following expressions:
24931 \layout Verse
24932
24933
24934 \family typewriter
24935 \series bold
24936 unsigned
24937 \series default
24938 \SpecialChar ~
24939 \SpecialChar ~
24940 char i;
24941 \newline
24942
24943 \series bold
24944 unsigned
24945 \series default
24946 \SpecialChar ~
24947 \SpecialChar ~
24948 int j;
24949 \newline
24950 ...
24951
24952 \newline
24953 i = ((i << 4) | (i >> 4));
24954 \family default
24955
24956 \newline
24957
24958 \family typewriter
24959 j = ((j << 8) | (j >> 8));
24960 \layout Standard
24961
24962 and generates a swap instruction for the nibble swapping
24963 \begin_inset LatexCommand \index{Nibble swapping}
24964
24965 \end_inset
24966
24967  or move instructions for the byte swapping
24968 \begin_inset LatexCommand \index{Byte swapping}
24969
24970 \end_inset
24971
24972 .
24973  The
24974 \begin_inset Quotes sld
24975 \end_inset
24976
24977 j
24978 \begin_inset Quotes srd
24979 \end_inset
24980
24981  example can be used to convert from little to big-endian or vice versa.
24982  If you want to change the endianness of a
24983 \emph on
24984 signed
24985 \emph default
24986  integer you have to cast to
24987 \family typewriter
24988 (unsigned int)
24989 \family default
24990  first.
24991 \layout Standard
24992
24993 Note that SDCC stores numbers in little-endian
24994 \begin_inset Foot
24995 collapsed false
24996
24997 \layout Standard
24998
24999 Usually 8-bit processors don't care much about endianness.
25000  This is not the case for the standard 8051 which only has an instruction
25001  to increment its
25002 \emph on
25003 dptr
25004 \emph default
25005
25006 \begin_inset LatexCommand \index{DPTR}
25007
25008 \end_inset
25009
25010 -datapointer
25011 \emph on
25012
25013 \emph default
25014 so little-endian is the more efficient byte order.
25015 \end_inset
25016
25017
25018 \begin_inset LatexCommand \index{little-endian}
25019
25020 \end_inset
25021
25022
25023 \begin_inset LatexCommand \index{Endianness}
25024
25025 \end_inset
25026
25027  format (i.e.
25028  lowest order first).
25029 \layout Subsection
25030
25031 Highest Order Bit
25032 \begin_inset LatexCommand \index{Highest Order Bit}
25033
25034 \end_inset
25035
25036  / Any Order Bit
25037 \begin_inset LatexCommand \index{Any Order Bit}
25038
25039 \end_inset
25040
25041
25042 \layout Standard
25043
25044 It is frequently required to obtain the highest order bit of an integral
25045  type (long, int, short or char types).
25046  Also obtaining any other order bit is not uncommon.
25047  SDCC recognizes the following expressions to yield the highest order bit
25048  and generates optimized code for it, e.g.:
25049 \layout Verse
25050
25051
25052 \family typewriter
25053 unsigned int gint;
25054 \newline
25055
25056 \newline
25057 foo () {
25058 \newline
25059 \SpecialChar ~
25060 \SpecialChar ~
25061 unsigned char hob1, aob1;
25062 \newline
25063 \SpecialChar ~
25064 \SpecialChar ~
25065 bit hob2, hob3, aob2, aob3;
25066 \newline
25067 \SpecialChar ~
25068 \SpecialChar ~
25069 ...
25070
25071 \newline
25072 \SpecialChar ~
25073 \SpecialChar ~
25074 hob1 = (gint >> 15) & 1;
25075 \newline
25076 \SpecialChar ~
25077 \SpecialChar ~
25078 hob2 = (gint >> 15) & 1;
25079 \newline
25080 \SpecialChar ~
25081 \SpecialChar ~
25082 hob3 = gint & 0x8000;
25083 \newline
25084 \SpecialChar ~
25085 \SpecialChar ~
25086 aob1 = (gint >> 9) & 1;
25087 \newline
25088 \SpecialChar ~
25089 \SpecialChar ~
25090 aob2 = (gint >> 8) & 1;
25091 \newline
25092 \SpecialChar ~
25093 \SpecialChar ~
25094 aob3 = gint & 0x0800;
25095 \newline
25096 \SpecialChar ~
25097 \SpecialChar ~
25098 ..
25099
25100 \newline
25101 }
25102 \layout Standard
25103
25104 will generate the following code:
25105 \layout Verse
25106
25107
25108 \family typewriter
25109 \SpecialChar ~
25110 \SpecialChar ~
25111 \SpecialChar ~
25112 \SpecialChar ~
25113 \SpecialChar ~
25114 \SpecialChar ~
25115 \SpecialChar ~
25116 \SpecialChar ~
25117 \SpecialChar ~
25118 \SpecialChar ~
25119 \SpecialChar ~
25120 \SpecialChar ~
25121 \SpecialChar ~
25122 \SpecialChar ~
25123 \SpecialChar ~
25124 \SpecialChar ~
25125 \SpecialChar ~
25126 \SpecialChar ~
25127 \SpecialChar ~
25128 \SpecialChar ~
25129 \SpecialChar ~
25130 \SpecialChar ~
25131 \SpecialChar ~
25132 \SpecialChar ~
25133 \SpecialChar ~
25134  61 ;\SpecialChar ~
25135  hob.c 7
25136 \newline
25137 000A E5*01\SpecialChar ~
25138 \SpecialChar ~
25139 \SpecialChar ~
25140 \SpecialChar ~
25141 \SpecialChar ~
25142 \SpecialChar ~
25143 \SpecialChar ~
25144 \SpecialChar ~
25145 \SpecialChar ~
25146 \SpecialChar ~
25147 \SpecialChar ~
25148 \SpecialChar ~
25149 \SpecialChar ~
25150 \SpecialChar ~
25151 \SpecialChar ~
25152  62\SpecialChar ~
25153 \SpecialChar ~
25154 \SpecialChar ~
25155 \SpecialChar ~
25156 \SpecialChar ~
25157 \SpecialChar ~
25158 \SpecialChar ~
25159 \SpecialChar ~
25160  mov\SpecialChar ~
25161 \SpecialChar ~
25162  a,(_gint + 1)
25163 \newline
25164 000C 23\SpecialChar ~
25165 \SpecialChar ~
25166 \SpecialChar ~
25167 \SpecialChar ~
25168 \SpecialChar ~
25169 \SpecialChar ~
25170 \SpecialChar ~
25171 \SpecialChar ~
25172 \SpecialChar ~
25173 \SpecialChar ~
25174 \SpecialChar ~
25175 \SpecialChar ~
25176 \SpecialChar ~
25177 \SpecialChar ~
25178 \SpecialChar ~
25179 \SpecialChar ~
25180 \SpecialChar ~
25181 \SpecialChar ~
25182  63\SpecialChar ~
25183 \SpecialChar ~
25184 \SpecialChar ~
25185 \SpecialChar ~
25186 \SpecialChar ~
25187 \SpecialChar ~
25188 \SpecialChar ~
25189 \SpecialChar ~
25190  rl\SpecialChar ~
25191 \SpecialChar ~
25192 \SpecialChar ~
25193  a
25194 \newline
25195 000D 54 01\SpecialChar ~
25196 \SpecialChar ~
25197 \SpecialChar ~
25198 \SpecialChar ~
25199 \SpecialChar ~
25200 \SpecialChar ~
25201 \SpecialChar ~
25202 \SpecialChar ~
25203 \SpecialChar ~
25204 \SpecialChar ~
25205 \SpecialChar ~
25206 \SpecialChar ~
25207 \SpecialChar ~
25208 \SpecialChar ~
25209 \SpecialChar ~
25210  64\SpecialChar ~
25211 \SpecialChar ~
25212 \SpecialChar ~
25213 \SpecialChar ~
25214 \SpecialChar ~
25215 \SpecialChar ~
25216 \SpecialChar ~
25217 \SpecialChar ~
25218  anl\SpecialChar ~
25219 \SpecialChar ~
25220  a,#0x01
25221 \newline
25222 000F F5*02\SpecialChar ~
25223 \SpecialChar ~
25224 \SpecialChar ~
25225 \SpecialChar ~
25226 \SpecialChar ~
25227 \SpecialChar ~
25228 \SpecialChar ~
25229 \SpecialChar ~
25230 \SpecialChar ~
25231 \SpecialChar ~
25232 \SpecialChar ~
25233 \SpecialChar ~
25234 \SpecialChar ~
25235 \SpecialChar ~
25236 \SpecialChar ~
25237  65\SpecialChar ~
25238 \SpecialChar ~
25239 \SpecialChar ~
25240 \SpecialChar ~
25241 \SpecialChar ~
25242 \SpecialChar ~
25243 \SpecialChar ~
25244 \SpecialChar ~
25245  mov\SpecialChar ~
25246 \SpecialChar ~
25247  _foo_hob1_1_1,a
25248 \newline
25249 \SpecialChar ~
25250 \SpecialChar ~
25251 \SpecialChar ~
25252 \SpecialChar ~
25253 \SpecialChar ~
25254 \SpecialChar ~
25255 \SpecialChar ~
25256 \SpecialChar ~
25257 \SpecialChar ~
25258 \SpecialChar ~
25259 \SpecialChar ~
25260 \SpecialChar ~
25261 \SpecialChar ~
25262 \SpecialChar ~
25263 \SpecialChar ~
25264 \SpecialChar ~
25265 \SpecialChar ~
25266 \SpecialChar ~
25267 \SpecialChar ~
25268 \SpecialChar ~
25269 \SpecialChar ~
25270 \SpecialChar ~
25271 \SpecialChar ~
25272 \SpecialChar ~
25273 \SpecialChar ~
25274  66 ;\SpecialChar ~
25275  hob.c 8
25276 \newline
25277 0011 E5*01\SpecialChar ~
25278 \SpecialChar ~
25279 \SpecialChar ~
25280 \SpecialChar ~
25281 \SpecialChar ~
25282 \SpecialChar ~
25283 \SpecialChar ~
25284 \SpecialChar ~
25285 \SpecialChar ~
25286 \SpecialChar ~
25287 \SpecialChar ~
25288 \SpecialChar ~
25289 \SpecialChar ~
25290 \SpecialChar ~
25291 \SpecialChar ~
25292  67\SpecialChar ~
25293 \SpecialChar ~
25294 \SpecialChar ~
25295 \SpecialChar ~
25296 \SpecialChar ~
25297 \SpecialChar ~
25298 \SpecialChar ~
25299 \SpecialChar ~
25300  mov\SpecialChar ~
25301 \SpecialChar ~
25302  a,(_gint + 1)
25303 \newline
25304 0013 33\SpecialChar ~
25305 \SpecialChar ~
25306 \SpecialChar ~
25307 \SpecialChar ~
25308 \SpecialChar ~
25309 \SpecialChar ~
25310 \SpecialChar ~
25311 \SpecialChar ~
25312 \SpecialChar ~
25313 \SpecialChar ~
25314 \SpecialChar ~
25315 \SpecialChar ~
25316 \SpecialChar ~
25317 \SpecialChar ~
25318 \SpecialChar ~
25319 \SpecialChar ~
25320 \SpecialChar ~
25321 \SpecialChar ~
25322  68\SpecialChar ~
25323 \SpecialChar ~
25324 \SpecialChar ~
25325 \SpecialChar ~
25326 \SpecialChar ~
25327 \SpecialChar ~
25328 \SpecialChar ~
25329 \SpecialChar ~
25330  rlc\SpecialChar ~
25331 \SpecialChar ~
25332  a
25333 \newline
25334 0014 92*00\SpecialChar ~
25335 \SpecialChar ~
25336 \SpecialChar ~
25337 \SpecialChar ~
25338 \SpecialChar ~
25339 \SpecialChar ~
25340 \SpecialChar ~
25341 \SpecialChar ~
25342 \SpecialChar ~
25343 \SpecialChar ~
25344 \SpecialChar ~
25345 \SpecialChar ~
25346 \SpecialChar ~
25347 \SpecialChar ~
25348 \SpecialChar ~
25349  69\SpecialChar ~
25350 \SpecialChar ~
25351 \SpecialChar ~
25352 \SpecialChar ~
25353 \SpecialChar ~
25354 \SpecialChar ~
25355 \SpecialChar ~
25356 \SpecialChar ~
25357  mov\SpecialChar ~
25358 \SpecialChar ~
25359  _foo_hob2_1_1,c
25360 \newline
25361 \SpecialChar ~
25362 \SpecialChar ~
25363 \SpecialChar ~
25364 \SpecialChar ~
25365 \SpecialChar ~
25366 \SpecialChar ~
25367 \SpecialChar ~
25368 \SpecialChar ~
25369 \SpecialChar ~
25370 \SpecialChar ~
25371 \SpecialChar ~
25372 \SpecialChar ~
25373 \SpecialChar ~
25374 \SpecialChar ~
25375 \SpecialChar ~
25376 \SpecialChar ~
25377 \SpecialChar ~
25378 \SpecialChar ~
25379 \SpecialChar ~
25380 \SpecialChar ~
25381 \SpecialChar ~
25382 \SpecialChar ~
25383 \SpecialChar ~
25384 \SpecialChar ~
25385 \SpecialChar ~
25386  66 ;\SpecialChar ~
25387  hob.c 9
25388 \newline
25389 0016 E5*01\SpecialChar ~
25390 \SpecialChar ~
25391 \SpecialChar ~
25392 \SpecialChar ~
25393 \SpecialChar ~
25394 \SpecialChar ~
25395 \SpecialChar ~
25396 \SpecialChar ~
25397 \SpecialChar ~
25398 \SpecialChar ~
25399 \SpecialChar ~
25400 \SpecialChar ~
25401 \SpecialChar ~
25402 \SpecialChar ~
25403 \SpecialChar ~
25404  67\SpecialChar ~
25405 \SpecialChar ~
25406 \SpecialChar ~
25407 \SpecialChar ~
25408 \SpecialChar ~
25409 \SpecialChar ~
25410 \SpecialChar ~
25411 \SpecialChar ~
25412  mov\SpecialChar ~
25413 \SpecialChar ~
25414  a,(_gint + 1)
25415 \newline
25416 0018 33\SpecialChar ~
25417 \SpecialChar ~
25418 \SpecialChar ~
25419 \SpecialChar ~
25420 \SpecialChar ~
25421 \SpecialChar ~
25422 \SpecialChar ~
25423 \SpecialChar ~
25424 \SpecialChar ~
25425 \SpecialChar ~
25426 \SpecialChar ~
25427 \SpecialChar ~
25428 \SpecialChar ~
25429 \SpecialChar ~
25430 \SpecialChar ~
25431 \SpecialChar ~
25432 \SpecialChar ~
25433 \SpecialChar ~
25434  68\SpecialChar ~
25435 \SpecialChar ~
25436 \SpecialChar ~
25437 \SpecialChar ~
25438 \SpecialChar ~
25439 \SpecialChar ~
25440 \SpecialChar ~
25441 \SpecialChar ~
25442  rlc\SpecialChar ~
25443 \SpecialChar ~
25444  a
25445 \newline
25446 0019 92*01\SpecialChar ~
25447 \SpecialChar ~
25448 \SpecialChar ~
25449 \SpecialChar ~
25450 \SpecialChar ~
25451 \SpecialChar ~
25452 \SpecialChar ~
25453 \SpecialChar ~
25454 \SpecialChar ~
25455 \SpecialChar ~
25456 \SpecialChar ~
25457 \SpecialChar ~
25458 \SpecialChar ~
25459 \SpecialChar ~
25460 \SpecialChar ~
25461  69\SpecialChar ~
25462 \SpecialChar ~
25463 \SpecialChar ~
25464 \SpecialChar ~
25465 \SpecialChar ~
25466 \SpecialChar ~
25467 \SpecialChar ~
25468 \SpecialChar ~
25469  mov\SpecialChar ~
25470 \SpecialChar ~
25471  _foo_hob3_1_1,c
25472 \newline
25473 \SpecialChar ~
25474 \SpecialChar ~
25475 \SpecialChar ~
25476 \SpecialChar ~
25477 \SpecialChar ~
25478 \SpecialChar ~
25479 \SpecialChar ~
25480 \SpecialChar ~
25481 \SpecialChar ~
25482 \SpecialChar ~
25483 \SpecialChar ~
25484 \SpecialChar ~
25485 \SpecialChar ~
25486 \SpecialChar ~
25487 \SpecialChar ~
25488 \SpecialChar ~
25489 \SpecialChar ~
25490 \SpecialChar ~
25491 \SpecialChar ~
25492 \SpecialChar ~
25493 \SpecialChar ~
25494 \SpecialChar ~
25495 \SpecialChar ~
25496 \SpecialChar ~
25497 \SpecialChar ~
25498  70 ;\SpecialChar ~
25499  hob.c 10
25500 \newline
25501 001B E5*01\SpecialChar ~
25502 \SpecialChar ~
25503 \SpecialChar ~
25504 \SpecialChar ~
25505 \SpecialChar ~
25506 \SpecialChar ~
25507 \SpecialChar ~
25508 \SpecialChar ~
25509 \SpecialChar ~
25510 \SpecialChar ~
25511 \SpecialChar ~
25512 \SpecialChar ~
25513 \SpecialChar ~
25514 \SpecialChar ~
25515 \SpecialChar ~
25516  71\SpecialChar ~
25517 \SpecialChar ~
25518 \SpecialChar ~
25519 \SpecialChar ~
25520 \SpecialChar ~
25521 \SpecialChar ~
25522 \SpecialChar ~
25523 \SpecialChar ~
25524  mov\SpecialChar ~
25525 \SpecialChar ~
25526  a,(_gint + 1)
25527 \newline
25528 001D 03\SpecialChar ~
25529 \SpecialChar ~
25530 \SpecialChar ~
25531 \SpecialChar ~
25532 \SpecialChar ~
25533 \SpecialChar ~
25534 \SpecialChar ~
25535 \SpecialChar ~
25536 \SpecialChar ~
25537 \SpecialChar ~
25538 \SpecialChar ~
25539 \SpecialChar ~
25540 \SpecialChar ~
25541 \SpecialChar ~
25542 \SpecialChar ~
25543 \SpecialChar ~
25544 \SpecialChar ~
25545 \SpecialChar ~
25546  72\SpecialChar ~
25547 \SpecialChar ~
25548 \SpecialChar ~
25549 \SpecialChar ~
25550 \SpecialChar ~
25551 \SpecialChar ~
25552 \SpecialChar ~
25553 \SpecialChar ~
25554  rr\SpecialChar ~
25555 \SpecialChar ~
25556 \SpecialChar ~
25557  a
25558 \newline
25559 001E 54 01\SpecialChar ~
25560 \SpecialChar ~
25561 \SpecialChar ~
25562 \SpecialChar ~
25563 \SpecialChar ~
25564 \SpecialChar ~
25565 \SpecialChar ~
25566 \SpecialChar ~
25567 \SpecialChar ~
25568 \SpecialChar ~
25569 \SpecialChar ~
25570 \SpecialChar ~
25571 \SpecialChar ~
25572 \SpecialChar ~
25573 \SpecialChar ~
25574  73\SpecialChar ~
25575 \SpecialChar ~
25576 \SpecialChar ~
25577 \SpecialChar ~
25578 \SpecialChar ~
25579 \SpecialChar ~
25580 \SpecialChar ~
25581 \SpecialChar ~
25582  anl\SpecialChar ~
25583 \SpecialChar ~
25584  a,#0x01
25585 \newline
25586 0020 F5*03\SpecialChar ~
25587 \SpecialChar ~
25588 \SpecialChar ~
25589 \SpecialChar ~
25590 \SpecialChar ~
25591 \SpecialChar ~
25592 \SpecialChar ~
25593 \SpecialChar ~
25594 \SpecialChar ~
25595 \SpecialChar ~
25596 \SpecialChar ~
25597 \SpecialChar ~
25598 \SpecialChar ~
25599 \SpecialChar ~
25600 \SpecialChar ~
25601  74\SpecialChar ~
25602 \SpecialChar ~
25603 \SpecialChar ~
25604 \SpecialChar ~
25605 \SpecialChar ~
25606 \SpecialChar ~
25607 \SpecialChar ~
25608 \SpecialChar ~
25609  mov\SpecialChar ~
25610 \SpecialChar ~
25611  _foo_aob1_1_1,a
25612 \newline
25613 \SpecialChar ~
25614 \SpecialChar ~
25615 \SpecialChar ~
25616 \SpecialChar ~
25617 \SpecialChar ~
25618 \SpecialChar ~
25619 \SpecialChar ~
25620 \SpecialChar ~
25621 \SpecialChar ~
25622 \SpecialChar ~
25623 \SpecialChar ~
25624 \SpecialChar ~
25625 \SpecialChar ~
25626 \SpecialChar ~
25627 \SpecialChar ~
25628 \SpecialChar ~
25629 \SpecialChar ~
25630 \SpecialChar ~
25631 \SpecialChar ~
25632 \SpecialChar ~
25633 \SpecialChar ~
25634 \SpecialChar ~
25635 \SpecialChar ~
25636 \SpecialChar ~
25637 \SpecialChar ~
25638  75 ;\SpecialChar ~
25639  hob.c 11
25640 \newline
25641 0022 E5*01\SpecialChar ~
25642 \SpecialChar ~
25643 \SpecialChar ~
25644 \SpecialChar ~
25645 \SpecialChar ~
25646 \SpecialChar ~
25647 \SpecialChar ~
25648 \SpecialChar ~
25649 \SpecialChar ~
25650 \SpecialChar ~
25651 \SpecialChar ~
25652 \SpecialChar ~
25653 \SpecialChar ~
25654 \SpecialChar ~
25655 \SpecialChar ~
25656  76\SpecialChar ~
25657 \SpecialChar ~
25658 \SpecialChar ~
25659 \SpecialChar ~
25660 \SpecialChar ~
25661 \SpecialChar ~
25662 \SpecialChar ~
25663 \SpecialChar ~
25664  mov\SpecialChar ~
25665 \SpecialChar ~
25666  a,(_gint + 1)
25667 \newline
25668 0024 13\SpecialChar ~
25669 \SpecialChar ~
25670 \SpecialChar ~
25671 \SpecialChar ~
25672 \SpecialChar ~
25673 \SpecialChar ~
25674 \SpecialChar ~
25675 \SpecialChar ~
25676 \SpecialChar ~
25677 \SpecialChar ~
25678 \SpecialChar ~
25679 \SpecialChar ~
25680 \SpecialChar ~
25681 \SpecialChar ~
25682 \SpecialChar ~
25683 \SpecialChar ~
25684 \SpecialChar ~
25685 \SpecialChar ~
25686  77\SpecialChar ~
25687 \SpecialChar ~
25688 \SpecialChar ~
25689 \SpecialChar ~
25690 \SpecialChar ~
25691 \SpecialChar ~
25692 \SpecialChar ~
25693 \SpecialChar ~
25694  rrc\SpecialChar ~
25695 \SpecialChar ~
25696  a
25697 \newline
25698 0025 92*02\SpecialChar ~
25699 \SpecialChar ~
25700 \SpecialChar ~
25701 \SpecialChar ~
25702 \SpecialChar ~
25703 \SpecialChar ~
25704 \SpecialChar ~
25705 \SpecialChar ~
25706 \SpecialChar ~
25707 \SpecialChar ~
25708 \SpecialChar ~
25709 \SpecialChar ~
25710 \SpecialChar ~
25711 \SpecialChar ~
25712 \SpecialChar ~
25713  78\SpecialChar ~
25714 \SpecialChar ~
25715 \SpecialChar ~
25716 \SpecialChar ~
25717 \SpecialChar ~
25718 \SpecialChar ~
25719 \SpecialChar ~
25720 \SpecialChar ~
25721  mov\SpecialChar ~
25722 \SpecialChar ~
25723  _foo_aob2_1_1,c
25724 \newline
25725 \SpecialChar ~
25726 \SpecialChar ~
25727 \SpecialChar ~
25728 \SpecialChar ~
25729 \SpecialChar ~
25730 \SpecialChar ~
25731 \SpecialChar ~
25732 \SpecialChar ~
25733 \SpecialChar ~
25734 \SpecialChar ~
25735 \SpecialChar ~
25736 \SpecialChar ~
25737 \SpecialChar ~
25738 \SpecialChar ~
25739 \SpecialChar ~
25740 \SpecialChar ~
25741 \SpecialChar ~
25742 \SpecialChar ~
25743 \SpecialChar ~
25744 \SpecialChar ~
25745 \SpecialChar ~
25746 \SpecialChar ~
25747 \SpecialChar ~
25748 \SpecialChar ~
25749 \SpecialChar ~
25750  79 ;\SpecialChar ~
25751  hob.c 12
25752 \newline
25753 0027 E5*01\SpecialChar ~
25754 \SpecialChar ~
25755 \SpecialChar ~
25756 \SpecialChar ~
25757 \SpecialChar ~
25758 \SpecialChar ~
25759 \SpecialChar ~
25760 \SpecialChar ~
25761 \SpecialChar ~
25762 \SpecialChar ~
25763 \SpecialChar ~
25764 \SpecialChar ~
25765 \SpecialChar ~
25766 \SpecialChar ~
25767 \SpecialChar ~
25768  80\SpecialChar ~
25769 \SpecialChar ~
25770 \SpecialChar ~
25771 \SpecialChar ~
25772 \SpecialChar ~
25773 \SpecialChar ~
25774 \SpecialChar ~
25775 \SpecialChar ~
25776  mov\SpecialChar ~
25777 \SpecialChar ~
25778  a,(_gint + 1)
25779 \newline
25780 0029 A2 E3\SpecialChar ~
25781 \SpecialChar ~
25782 \SpecialChar ~
25783 \SpecialChar ~
25784 \SpecialChar ~
25785 \SpecialChar ~
25786 \SpecialChar ~
25787 \SpecialChar ~
25788 \SpecialChar ~
25789 \SpecialChar ~
25790 \SpecialChar ~
25791 \SpecialChar ~
25792 \SpecialChar ~
25793 \SpecialChar ~
25794 \SpecialChar ~
25795  81\SpecialChar ~
25796 \SpecialChar ~
25797 \SpecialChar ~
25798 \SpecialChar ~
25799 \SpecialChar ~
25800 \SpecialChar ~
25801 \SpecialChar ~
25802 \SpecialChar ~
25803  mov\SpecialChar ~
25804 \SpecialChar ~
25805  c,acc[3]
25806 \newline
25807 002B 92*03\SpecialChar ~
25808 \SpecialChar ~
25809 \SpecialChar ~
25810 \SpecialChar ~
25811 \SpecialChar ~
25812 \SpecialChar ~
25813 \SpecialChar ~
25814 \SpecialChar ~
25815 \SpecialChar ~
25816 \SpecialChar ~
25817 \SpecialChar ~
25818 \SpecialChar ~
25819 \SpecialChar ~
25820 \SpecialChar ~
25821 \SpecialChar ~
25822  82\SpecialChar ~
25823 \SpecialChar ~
25824 \SpecialChar ~
25825 \SpecialChar ~
25826 \SpecialChar ~
25827 \SpecialChar ~
25828 \SpecialChar ~
25829 \SpecialChar ~
25830  mov\SpecialChar ~
25831 \SpecialChar ~
25832  _foo_aob3_1_1,c
25833 \layout Standard
25834
25835 Other variations of these cases however will
25836 \emph on
25837 not
25838 \emph default
25839  be recognized.
25840  They are standard C expressions, so I heartily recommend these be the only
25841  way to get the highest order bit, (it is portable).
25842  Of course it will be recognized even if it is embedded in other expressions,
25843  e.g.:
25844 \layout Verse
25845
25846
25847 \family typewriter
25848 xyz = gint + ((gint >> 15) & 1);
25849 \layout Standard
25850
25851 will still be recognized.
25852 \layout Subsection
25853
25854 Higher Order Byte
25855 \begin_inset LatexCommand \index{Higher Order Byte}
25856
25857 \end_inset
25858
25859  / Higher Order Word
25860 \begin_inset LatexCommand \index{Higher Order Word}
25861
25862 \end_inset
25863
25864
25865 \layout Standard
25866
25867 It is also frequently required to obtain a higher order byte or word of
25868  a larger integral type (long, int or short types).
25869  SDCC recognizes the following expressions to yield the higher order byte
25870  or word and generates optimized code for it, e.g.:
25871 \layout Verse
25872
25873
25874 \family typewriter
25875 unsigned int gint;
25876 \newline
25877 unsigned long int glong;
25878 \newline
25879
25880 \newline
25881 foo () {
25882 \newline
25883 \SpecialChar ~
25884 \SpecialChar ~
25885 unsigned char hob1, hob2;
25886 \newline
25887 \SpecialChar ~
25888 \SpecialChar ~
25889 unsigned int how1, how2;
25890 \newline
25891 \SpecialChar ~
25892 \SpecialChar ~
25893 ...
25894
25895 \newline
25896 \SpecialChar ~
25897 \SpecialChar ~
25898 hob1 = (gint >> 8) & 0xFF;
25899 \newline
25900 \SpecialChar ~
25901 \SpecialChar ~
25902 hob2 = glong >> 24;
25903 \newline
25904 \SpecialChar ~
25905 \SpecialChar ~
25906 how1 = (glong >> 16) & 0xFFFF;
25907 \newline
25908 \SpecialChar ~
25909 \SpecialChar ~
25910 how2 = glong >> 8;
25911 \newline
25912 \SpecialChar ~
25913 \SpecialChar ~
25914 ..
25915
25916 \newline
25917 }
25918 \layout Standard
25919
25920 will generate the following code:
25921 \layout Verse
25922
25923
25924 \family typewriter
25925 \SpecialChar ~
25926 \SpecialChar ~
25927 \SpecialChar ~
25928 \SpecialChar ~
25929 \SpecialChar ~
25930 \SpecialChar ~
25931 \SpecialChar ~
25932 \SpecialChar ~
25933 \SpecialChar ~
25934 \SpecialChar ~
25935 \SpecialChar ~
25936 \SpecialChar ~
25937 \SpecialChar ~
25938 \SpecialChar ~
25939 \SpecialChar ~
25940 \SpecialChar ~
25941 \SpecialChar ~
25942 \SpecialChar ~
25943 \SpecialChar ~
25944 \SpecialChar ~
25945 \SpecialChar ~
25946 \SpecialChar ~
25947 \SpecialChar ~
25948 \SpecialChar ~
25949 \SpecialChar ~
25950  91 ;\SpecialChar ~
25951  hob.c 15
25952 \newline
25953 0037 85*01*06\SpecialChar ~
25954 \SpecialChar ~
25955 \SpecialChar ~
25956 \SpecialChar ~
25957 \SpecialChar ~
25958 \SpecialChar ~
25959 \SpecialChar ~
25960 \SpecialChar ~
25961 \SpecialChar ~
25962 \SpecialChar ~
25963 \SpecialChar ~
25964 \SpecialChar ~
25965  92\SpecialChar ~
25966 \SpecialChar ~
25967 \SpecialChar ~
25968 \SpecialChar ~
25969 \SpecialChar ~
25970 \SpecialChar ~
25971 \SpecialChar ~
25972 \SpecialChar ~
25973  mov\SpecialChar ~
25974 \SpecialChar ~
25975  _foo_hob1_1_1,(_gint + 1)
25976 \newline
25977 \SpecialChar ~
25978 \SpecialChar ~
25979 \SpecialChar ~
25980 \SpecialChar ~
25981 \SpecialChar ~
25982 \SpecialChar ~
25983 \SpecialChar ~
25984 \SpecialChar ~
25985 \SpecialChar ~
25986 \SpecialChar ~
25987 \SpecialChar ~
25988 \SpecialChar ~
25989 \SpecialChar ~
25990 \SpecialChar ~
25991 \SpecialChar ~
25992 \SpecialChar ~
25993 \SpecialChar ~
25994 \SpecialChar ~
25995 \SpecialChar ~
25996 \SpecialChar ~
25997 \SpecialChar ~
25998 \SpecialChar ~
25999 \SpecialChar ~
26000 \SpecialChar ~
26001 \SpecialChar ~
26002  93 ;\SpecialChar ~
26003  hob.c 16
26004 \newline
26005 003A 85*05*07\SpecialChar ~
26006 \SpecialChar ~
26007 \SpecialChar ~
26008 \SpecialChar ~
26009 \SpecialChar ~
26010 \SpecialChar ~
26011 \SpecialChar ~
26012 \SpecialChar ~
26013 \SpecialChar ~
26014 \SpecialChar ~
26015 \SpecialChar ~
26016 \SpecialChar ~
26017  94\SpecialChar ~
26018 \SpecialChar ~
26019 \SpecialChar ~
26020 \SpecialChar ~
26021 \SpecialChar ~
26022 \SpecialChar ~
26023 \SpecialChar ~
26024 \SpecialChar ~
26025  mov\SpecialChar ~
26026 \SpecialChar ~
26027  _foo_hob2_1_1,(_glong + 3)
26028 \newline
26029 \SpecialChar ~
26030 \SpecialChar ~
26031 \SpecialChar ~
26032 \SpecialChar ~
26033 \SpecialChar ~
26034 \SpecialChar ~
26035 \SpecialChar ~
26036 \SpecialChar ~
26037 \SpecialChar ~
26038 \SpecialChar ~
26039 \SpecialChar ~
26040 \SpecialChar ~
26041 \SpecialChar ~
26042 \SpecialChar ~
26043 \SpecialChar ~
26044 \SpecialChar ~
26045 \SpecialChar ~
26046 \SpecialChar ~
26047 \SpecialChar ~
26048 \SpecialChar ~
26049 \SpecialChar ~
26050 \SpecialChar ~
26051 \SpecialChar ~
26052 \SpecialChar ~
26053 \SpecialChar ~
26054  95 ;\SpecialChar ~
26055  hob.c 17
26056 \newline
26057 003D 85*04*08\SpecialChar ~
26058 \SpecialChar ~
26059 \SpecialChar ~
26060 \SpecialChar ~
26061 \SpecialChar ~
26062 \SpecialChar ~
26063 \SpecialChar ~
26064 \SpecialChar ~
26065 \SpecialChar ~
26066 \SpecialChar ~
26067 \SpecialChar ~
26068 \SpecialChar ~
26069  96\SpecialChar ~
26070 \SpecialChar ~
26071 \SpecialChar ~
26072 \SpecialChar ~
26073 \SpecialChar ~
26074 \SpecialChar ~
26075 \SpecialChar ~
26076 \SpecialChar ~
26077  mov\SpecialChar ~
26078 \SpecialChar ~
26079  _foo_how1_1_1,(_glong + 2)
26080 \newline
26081 0040 85*05*09\SpecialChar ~
26082 \SpecialChar ~
26083 \SpecialChar ~
26084 \SpecialChar ~
26085 \SpecialChar ~
26086 \SpecialChar ~
26087 \SpecialChar ~
26088 \SpecialChar ~
26089 \SpecialChar ~
26090 \SpecialChar ~
26091 \SpecialChar ~
26092 \SpecialChar ~
26093  97\SpecialChar ~
26094 \SpecialChar ~
26095 \SpecialChar ~
26096 \SpecialChar ~
26097 \SpecialChar ~
26098 \SpecialChar ~
26099 \SpecialChar ~
26100 \SpecialChar ~
26101  mov\SpecialChar ~
26102 \SpecialChar ~
26103  (_foo_how1_1_1 + 1),(_glong + 3)
26104 \newline
26105 0043 85*03*0A\SpecialChar ~
26106 \SpecialChar ~
26107 \SpecialChar ~
26108 \SpecialChar ~
26109 \SpecialChar ~
26110 \SpecialChar ~
26111 \SpecialChar ~
26112 \SpecialChar ~
26113 \SpecialChar ~
26114 \SpecialChar ~
26115 \SpecialChar ~
26116 \SpecialChar ~
26117  98\SpecialChar ~
26118 \SpecialChar ~
26119 \SpecialChar ~
26120 \SpecialChar ~
26121 \SpecialChar ~
26122 \SpecialChar ~
26123 \SpecialChar ~
26124 \SpecialChar ~
26125  mov\SpecialChar ~
26126 \SpecialChar ~
26127  _foo_how2_1_1,(_glong + 1)
26128 \newline
26129 0046 85*04*0B\SpecialChar ~
26130 \SpecialChar ~
26131 \SpecialChar ~
26132 \SpecialChar ~
26133 \SpecialChar ~
26134 \SpecialChar ~
26135 \SpecialChar ~
26136 \SpecialChar ~
26137 \SpecialChar ~
26138 \SpecialChar ~
26139 \SpecialChar ~
26140 \SpecialChar ~
26141  99\SpecialChar ~
26142 \SpecialChar ~
26143 \SpecialChar ~
26144 \SpecialChar ~
26145 \SpecialChar ~
26146 \SpecialChar ~
26147 \SpecialChar ~
26148 \SpecialChar ~
26149  mov\SpecialChar ~
26150 \SpecialChar ~
26151  (_foo_how2_1_1 + 1),(_glong + 2)
26152 \layout Standard
26153
26154 Again, variations of these cases may
26155 \emph on
26156 not
26157 \emph default
26158  be recognized.
26159  They are standard C expressions, so I heartily recommend these be the only
26160  way to get the higher order byte/word, (it is portable).
26161  Of course it will be recognized even if it is embedded in other expressions,
26162  e.g.:
26163 \layout Verse
26164
26165
26166 \family typewriter
26167 xyz = gint + ((gint >> 8) & 0xFF);
26168 \layout Standard
26169
26170 will still be recognized.
26171 \layout Subsection
26172
26173 Peephole Optimizer
26174 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
26175
26176 \end_inset
26177
26178
26179 \begin_inset LatexCommand \index{Peephole optimizer}
26180
26181 \end_inset
26182
26183
26184 \layout Standard
26185
26186 The compiler uses a rule based, pattern matching and re-writing mechanism
26187  for peep-hole optimization.
26188  It is inspired by
26189 \emph on
26190 copt
26191 \emph default
26192  a peep-hole optimizer by Christopher W.
26193  Fraser (cwfraser\SpecialChar ~
26194 @\SpecialChar ~
26195 microsoft.com).
26196  A default set of rules are compiled into the compiler, additional rules
26197  may be added with the
26198 \emph on
26199 -
26200 \begin_inset ERT
26201 status Collapsed
26202
26203 \layout Standard
26204
26205 \backslash
26206 /
26207 \end_inset
26208
26209 -peep-file
26210 \begin_inset LatexCommand \index{-\/-peep-file}
26211
26212 \end_inset
26213
26214  <filename>
26215 \emph default
26216  option.
26217  The rule language is best illustrated with examples.
26218 \layout Verse
26219
26220
26221 \family typewriter
26222 replace {
26223 \newline
26224 \SpecialChar ~
26225 \SpecialChar ~
26226 mov %1,a
26227 \newline
26228 \SpecialChar ~
26229 \SpecialChar ~
26230 mov a,%1
26231 \newline
26232 } by {
26233 \newline
26234 \SpecialChar ~
26235 \SpecialChar ~
26236 mov %1,a
26237 \newline
26238 }
26239 \layout Standard
26240
26241 The above rule will change the following assembly
26242 \begin_inset LatexCommand \index{Assembler routines}
26243
26244 \end_inset
26245
26246  sequence:
26247 \layout Verse
26248
26249
26250 \family typewriter
26251 mov r1,a
26252 \newline
26253 mov a,r1
26254 \layout Standard
26255
26256 to
26257 \layout Verse
26258
26259
26260 \family typewriter
26261 mov r1,a
26262 \layout Standard
26263
26264 Note: All occurrences of a
26265 \emph on
26266 %n
26267 \emph default
26268  (pattern variable) must denote the same string.
26269  With the above rule, the assembly sequence:
26270 \layout Verse
26271
26272
26273 \family typewriter
26274 mov r1,a
26275 \newline
26276 mov a,r2
26277 \layout Standard
26278
26279 will remain unmodified.
26280 \newline
26281
26282 \newline
26283 Other special case optimizations may be added by the user (via
26284 \emph on
26285 -
26286 \begin_inset ERT
26287 status Collapsed
26288
26289 \layout Standard
26290
26291 \backslash
26292 /
26293 \end_inset
26294
26295 -peep-file option
26296 \emph default
26297 ).
26298  E.g.
26299  some variants of the 8051 MCU
26300 \begin_inset LatexCommand \index{MCS51 variants}
26301
26302 \end_inset
26303
26304  allow only
26305 \family typewriter
26306 ajmp
26307 \family default
26308  and
26309 \family typewriter
26310 acall
26311 \family default
26312 .
26313  The following two rules will change all
26314 \family typewriter
26315 ljmp
26316 \family default
26317  and
26318 \family typewriter
26319 lcall
26320 \family default
26321  to
26322 \family typewriter
26323 ajmp
26324 \family default
26325  and
26326 \family typewriter
26327 acall
26328 \layout Verse
26329
26330
26331 \family typewriter
26332 replace { lcall %1 } by { acall %1 }
26333 \newline
26334 replace { ljmp %1 } by { ajmp %1 }
26335 \layout Standard
26336
26337 The
26338 \emph on
26339 inline-assembler code
26340 \emph default
26341  is also passed through the peep hole optimizer, thus the peephole optimizer
26342  can also be used as an assembly level macro expander.
26343  The rules themselves are MCU dependent whereas the rule language infra-structur
26344 e is MCU independent.
26345  Peephole optimization rules for other MCU can be easily programmed using
26346  the rule language.
26347 \newline
26348
26349 \newline
26350 The syntax for a rule is as follows:
26351 \layout Verse
26352
26353
26354 \family typewriter
26355 rule := replace [ restart ] '{' <assembly sequence> '
26356 \backslash
26357 n'
26358 \newline
26359 \SpecialChar ~
26360  \SpecialChar ~
26361  \SpecialChar ~
26362  \SpecialChar ~
26363  \SpecialChar ~
26364  \SpecialChar ~
26365  \SpecialChar ~
26366  \SpecialChar ~
26367  \SpecialChar ~
26368  \SpecialChar ~
26369  \SpecialChar ~
26370  \SpecialChar ~
26371  \SpecialChar ~
26372  \SpecialChar ~
26373  '}' by '{' '
26374 \backslash
26375 n'
26376 \newline
26377 \SpecialChar ~
26378  \SpecialChar ~
26379  \SpecialChar ~
26380  \SpecialChar ~
26381  \SpecialChar ~
26382  \SpecialChar ~
26383  \SpecialChar ~
26384  \SpecialChar ~
26385  \SpecialChar ~
26386  \SpecialChar ~
26387  \SpecialChar ~
26388  \SpecialChar ~
26389  \SpecialChar ~
26390  \SpecialChar ~
26391  \SpecialChar ~
26392  \SpecialChar ~
26393  <assembly sequence> '
26394 \backslash
26395 n'
26396 \newline
26397 \SpecialChar ~
26398  \SpecialChar ~
26399  \SpecialChar ~
26400  \SpecialChar ~
26401  \SpecialChar ~
26402  \SpecialChar ~
26403  \SpecialChar ~
26404  \SpecialChar ~
26405  \SpecialChar ~
26406  \SpecialChar ~
26407  \SpecialChar ~
26408  \SpecialChar ~
26409  \SpecialChar ~
26410  \SpecialChar ~
26411  '}' [if <functionName> ] '
26412 \backslash
26413 n'
26414 \layout Standard
26415
26416 <assembly sequence> := assembly instruction (each instruction including
26417  labels must be on a separate line).
26418 \newline
26419
26420 \newline
26421 The optimizer will apply to the rules one by one from the top in the sequence
26422  of their appearance, it will terminate when all rules are exhausted.
26423  If the 'restart' option is specified, then the optimizer will start matching
26424  the rules again from the top, this option for a rule is expensive (performance)
26425 , it is intended to be used in situations where a transformation will trigger
26426  the same rule again.
26427  An example of this (not a good one, it has side effects) is the following
26428  rule:
26429 \layout Verse
26430
26431
26432 \family typewriter
26433 replace restart {
26434 \newline
26435 \SpecialChar ~
26436 \SpecialChar ~
26437 pop %1
26438 \newline
26439 \SpecialChar ~
26440 \SpecialChar ~
26441 push %1 } by {
26442 \newline
26443 \SpecialChar ~
26444 \SpecialChar ~
26445 ; nop
26446 \newline
26447 }
26448 \layout Standard
26449
26450 Note that the replace pattern cannot be a blank, but can be a comment line.
26451  Without the 'restart' option only the innermost 'pop' 'push' pair would
26452  be eliminated, i.e.:
26453 \layout Verse
26454
26455
26456 \family typewriter
26457 pop ar1
26458 \newline
26459 pop ar2
26460 \newline
26461 push ar2
26462 \newline
26463 push ar1
26464 \layout Standard
26465
26466 would result in:
26467 \layout Verse
26468
26469
26470 \family typewriter
26471 pop ar1
26472 \newline
26473 ; nop
26474 \newline
26475 push ar1
26476 \layout Standard
26477
26478
26479 \emph on
26480 with
26481 \emph default
26482  the restart option the rule will be applied again to the resulting code
26483  and then all the pop-push pairs will be eliminated to yield:
26484 \layout Verse
26485
26486
26487 \family typewriter
26488 ; nop
26489 \newline
26490 ; nop
26491 \layout Standard
26492
26493 A conditional function can be attached to a rule.
26494  Attaching rules are somewhat more involved, let me illustrate this with
26495  an example.
26496 \layout Verse
26497
26498
26499 \family typewriter
26500 replace {
26501 \newline
26502 \SpecialChar ~
26503  \SpecialChar ~
26504  \SpecialChar ~
26505 ljmp %5
26506 \newline
26507 %2:
26508 \newline
26509 } by {
26510 \newline
26511 \SpecialChar ~
26512  \SpecialChar ~
26513  \SpecialChar ~
26514 sjmp %5
26515 \newline
26516 %2:
26517 \newline
26518 } if labelInRange
26519 \layout Standard
26520
26521 The optimizer does a look-up of a function name table defined in function
26522
26523 \emph on
26524 callFuncByName
26525 \emph default
26526  in the source file SDCCpeeph.c, with the name
26527 \emph on
26528 labelInRange
26529 \emph default
26530 .
26531  If it finds a corresponding entry the function is called.
26532  Note there can be no parameters specified for these functions, in this
26533  case the use of
26534 \emph on
26535 %5
26536 \emph default
26537  is crucial, since the function
26538 \emph on
26539 labelInRange
26540 \emph default
26541  expects to find the label in that particular variable (the hash table containin
26542 g the variable bindings is passed as a parameter).
26543  If you want to code more such functions, take a close look at the function
26544  labelInRange and the calling mechanism in source file SDCCpeeph.c.
26545  Currently implemented are
26546 \emph on
26547 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
26548  24bitMode, portIsDS390, 24bitModeAndPortDS390
26549 \emph default
26550 and
26551 \emph on
26552  notVolatile
26553 \emph default
26554 .
26555 \layout Standard
26556
26557 I know this whole thing is a little kludgey, but maybe some day we will
26558  have some better means.
26559  If you are looking at this file, you will see the default rules that are
26560  compiled into the compiler, you can add your own rules in the default set
26561  there if you get tired of specifying the -
26562 \begin_inset ERT
26563 status Collapsed
26564
26565 \layout Standard
26566
26567 \backslash
26568 /
26569 \end_inset
26570
26571 -peep-file option.
26572 \layout Section
26573
26574 ANSI-Compliance
26575 \begin_inset LatexCommand \index{ANSI-compliance}
26576
26577 \end_inset
26578
26579
26580 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
26581
26582 \end_inset
26583
26584
26585 \layout Standard
26586
26587 Deviations from the compliance:
26588 \layout Itemize
26589
26590 functions are not reentrant
26591 \begin_inset LatexCommand \index{reentrant}
26592
26593 \end_inset
26594
26595  unless explicitly declared as such or the
26596 \series bold
26597 -
26598 \begin_inset ERT
26599 status Collapsed
26600
26601 \layout Standard
26602
26603 \backslash
26604 /
26605 \end_inset
26606
26607 -stack-auto
26608 \begin_inset LatexCommand \index{-\/-stack-auto}
26609
26610 \end_inset
26611
26612
26613 \series default
26614  command line option is specified.
26615 \layout Itemize
26616
26617 structures and unions cannot be assigned values directly, cannot be passed
26618  as function parameters or assigned to each other and cannot be a return
26619  value from a function, e.g.:
26620 \begin_deeper
26621 \layout Verse
26622
26623
26624 \family typewriter
26625 struct s { ...
26626  };
26627 \newline
26628 struct s s1, s2;
26629 \newline
26630 foo()
26631 \newline
26632 {
26633 \newline
26634 \SpecialChar ~
26635 \SpecialChar ~
26636 \SpecialChar ~
26637 \SpecialChar ~
26638 ...
26639
26640 \newline
26641 \SpecialChar ~
26642 \SpecialChar ~
26643 \SpecialChar ~
26644 \SpecialChar ~
26645 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
26646 \newline
26647 \SpecialChar ~
26648 \SpecialChar ~
26649 \SpecialChar ~
26650 \SpecialChar ~
26651 ...
26652
26653 \newline
26654 }
26655 \newline
26656 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
26657  */
26658 \newline
26659 {
26660 \newline
26661 \SpecialChar ~
26662 \SpecialChar ~
26663 \SpecialChar ~
26664 \SpecialChar ~
26665 struct s rets;
26666 \newline
26667 \SpecialChar ~
26668 \SpecialChar ~
26669 \SpecialChar ~
26670 \SpecialChar ~
26671 ...
26672
26673 \newline
26674 \SpecialChar ~
26675 \SpecialChar ~
26676 \SpecialChar ~
26677 \SpecialChar ~
26678 return rets;/* is invalid in SDCC although allowed in ANSI */
26679 \newline
26680 }
26681 \end_deeper
26682 \layout Itemize
26683
26684 initialization of structure arrays must be fully braced.
26685 \begin_deeper
26686 \layout Verse
26687
26688
26689 \family typewriter
26690 struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
26691 \newline
26692 struct s { char x } a[] = {{1}, {2}}; /* OK */
26693 \end_deeper
26694 \layout Itemize
26695
26696 'long long
26697 \begin_inset LatexCommand \index{long long (not supported)}
26698
26699 \end_inset
26700
26701 ' (64 bit integers
26702 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
26703
26704 \end_inset
26705
26706 ) not supported.
26707 \layout Itemize
26708
26709 'double
26710 \begin_inset LatexCommand \index{double (not supported)}
26711
26712 \end_inset
26713
26714 ' precision floating point
26715 \begin_inset LatexCommand \index{Floating point support}
26716
26717 \end_inset
26718
26719 not supported.
26720 \layout Itemize
26721
26722 Old K&R style
26723 \begin_inset LatexCommand \index{K\&R style}
26724
26725 \end_inset
26726
26727  function declarations are NOT allowed.
26728 \begin_deeper
26729 \layout Verse
26730
26731
26732 \family typewriter
26733 foo(i,j) /* this old style of function declarations */
26734 \newline
26735 int i,j; /* are valid in ANSI but not valid in SDCC */
26736 \newline
26737 {
26738 \newline
26739 \SpecialChar ~
26740 \SpecialChar ~
26741 \SpecialChar ~
26742 \SpecialChar ~
26743 ...
26744
26745 \newline
26746 }
26747 \end_deeper
26748 \layout Itemize
26749
26750 Most enhancements in C99 are not supported, f.e.:
26751 \begin_deeper
26752 \layout Verse
26753
26754
26755 \family typewriter
26756 \series bold
26757 inline
26758 \series default
26759  int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
26760  in C99 */
26761 \newline
26762 for (
26763 \series bold
26764 int
26765 \series default
26766  i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
26767 \end_deeper
26768 \layout Itemize
26769
26770 Certain words that are valid identifiers in the standard may be reserved
26771  words in SDCC unless the
26772 \series bold
26773 -
26774 \begin_inset ERT
26775 status Collapsed
26776
26777 \layout Standard
26778
26779 \backslash
26780 /
26781 \end_inset
26782
26783 -std-c89
26784 \begin_inset LatexCommand \index{-\/-std-c89}
26785
26786 \end_inset
26787
26788  or -
26789 \begin_inset ERT
26790 status Collapsed
26791
26792 \layout Standard
26793
26794 \backslash
26795 /
26796 \end_inset
26797
26798 -std-c99
26799 \begin_inset LatexCommand \index{-\/-std-c99}
26800
26801 \end_inset
26802
26803
26804 \series default
26805  command line options are used.
26806  These may include (depending on the selected processor): 'at', 'banked',
26807  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
26808 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
26809  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
26810  '_naked'.
26811  Compliant equivalents of these keywords are always available in a form
26812  that begin with two underscores
26813 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
26814
26815 \end_inset
26816
26817 , f.e.
26818  '__data' instead of 'data'.
26819 \layout Section
26820
26821 Cyclomatic Complexity
26822 \begin_inset LatexCommand \index{Cyclomatic complexity}
26823
26824 \end_inset
26825
26826
26827 \layout Standard
26828
26829 Cyclomatic complexity of a function is defined as the number of independent
26830  paths the program can take during execution of the function.
26831  This is an important number since it defines the number test cases you
26832  have to generate to validate the function.
26833  The accepted industry standard for complexity number is 10, if the cyclomatic
26834  complexity reported by SDCC exceeds 10 you should think about simplification
26835  of the function logic.
26836  Note that the complexity level is not related to the number of lines of
26837  code in a function.
26838  Large functions can have low complexity, and small functions can have large
26839  complexity levels.
26840
26841 \newline
26842
26843 \newline
26844 SDCC uses the following formula to compute the complexity:
26845 \newline
26846
26847 \layout Standard
26848
26849 complexity = (number of edges in control flow graph) - (number of nodes
26850  in control flow graph) + 2;
26851 \newline
26852
26853 \newline
26854 Having said that the industry standard is 10, you should be aware that in
26855  some cases it be may unavoidable to have a complexity level of less than
26856  10.
26857  For example if you have switch statement with more than 10 case labels,
26858  each case label adds one to the complexity level.
26859  The complexity level is by no means an absolute measure of the algorithmic
26860  complexity of the function, it does however provide a good starting point
26861  for which functions you might look at for further optimization.
26862 \layout Section
26863
26864 Retargetting for other Processors
26865 \layout Standard
26866
26867 The issues for retargetting the compiler are far too numerous to be covered
26868  by this document.
26869  What follows is a brief description of each of the seven phases of the
26870  compiler and its MCU dependency.
26871 \layout Itemize
26872
26873 Parsing the source and building the annotated parse tree.
26874  This phase is largely MCU independent (except for the language extensions).
26875  Syntax & semantic checks are also done in this phase, along with some initial
26876  optimizations like back patching labels and the pattern matching optimizations
26877  like bit-rotation etc.
26878 \layout Itemize
26879
26880 The second phase involves generating an intermediate code which can be easy
26881  manipulated during the later phases.
26882  This phase is entirely MCU independent.
26883  The intermediate code generation assumes the target machine has unlimited
26884  number of registers, and designates them with the name iTemp.
26885  The compiler can be made to dump a human readable form of the code generated
26886  by using the -
26887 \begin_inset ERT
26888 status Collapsed
26889
26890 \layout Standard
26891
26892 \backslash
26893 /
26894 \end_inset
26895
26896 -dumpraw option.
26897 \layout Itemize
26898
26899 This phase does the bulk of the standard optimizations and is also MCU independe
26900 nt.
26901  This phase can be broken down into several sub-phases:
26902 \newline
26903
26904 \newline
26905 Break down intermediate code (iCode) into basic blocks.
26906 \newline
26907 Do control flow & data flow analysis on the basic blocks.
26908 \newline
26909 Do local common subexpression elimination, then global subexpression elimination
26910 \newline
26911 Dead code elimination
26912 \newline
26913 Loop optimizations
26914 \newline
26915 If loop optimizations caused any changes then do 'global subexpression eliminati
26916 on' and 'dead code elimination' again.
26917 \layout Itemize
26918
26919 This phase determines the live-ranges; by live range I mean those iTemp
26920  variables defined by the compiler that still survive after all the optimization
26921 s.
26922  Live range analysis
26923 \begin_inset LatexCommand \index{Live range analysis}
26924
26925 \end_inset
26926
26927  is essential for register allocation, since these computation determines
26928  which of these iTemps will be assigned to registers, and for how long.
26929 \layout Itemize
26930
26931 Phase five is register allocation.
26932  There are two parts to this process.
26933 \newline
26934
26935 \newline
26936 The first part I call 'register packing' (for lack of a better term).
26937  In this case several MCU specific expression folding is done to reduce
26938  register pressure.
26939 \newline
26940
26941 \newline
26942 The second part is more MCU independent and deals with allocating registers
26943  to the remaining live ranges.
26944  A lot of MCU specific code does creep into this phase because of the limited
26945  number of index registers available in the 8051.
26946 \layout Itemize
26947
26948 The Code generation phase is (unhappily), entirely MCU dependent and very
26949  little (if any at all) of this code can be reused for other MCU.
26950  However the scheme for allocating a homogenized assembler operand for each
26951  iCode operand may be reused.
26952 \layout Itemize
26953
26954 As mentioned in the optimization section the peep-hole optimizer is rule
26955  based system, which can reprogrammed for other MCUs.
26956 \layout Chapter
26957
26958 Compiler internals
26959 \begin_inset LatexCommand \index{Compiler internals}
26960
26961 \end_inset
26962
26963
26964 \layout Section
26965
26966 The anatomy of the compiler
26967 \begin_inset LatexCommand \label{sub:The-anatomy-of}
26968
26969 \end_inset
26970
26971
26972 \layout Standard
26973
26974
26975 \shape italic
26976 This is an excerpt from an article published in Circuit Cellar Magazine
26977  in
26978 \series bold
26979 August 2000
26980 \series default
26981 .
26982  It's a little outdated (the compiler is much more efficient now and user/develo
26983 per friendly), but pretty well exposes the guts of it all.
26984 \shape default
26985
26986 \newline
26987
26988 \newline
26989 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
26990  It is fairly easy to retarget for other 8-bit MCU.
26991  Here we take a look at some of the internals of the compiler.
26992
26993 \layout Paragraph*
26994
26995 Parsing
26996 \begin_inset LatexCommand \index{Parsing}
26997
26998 \end_inset
26999
27000
27001 \layout Standard
27002
27003 Parsing the input source file and creating an AST (Annotated Syntax Tree
27004 \begin_inset LatexCommand \index{Annotated syntax tree}
27005
27006 \end_inset
27007
27008 ).
27009  This phase also involves propagating types (annotating each node of the
27010  parse tree with type information) and semantic analysis.
27011  There are some MCU specific parsing rules.
27012  For example the storage classes, the extended storage classes are MCU specific
27013  while there may be a xdata storage class for 8051 there is no such storage
27014  class for z80 or Atmel AVR.
27015  SDCC allows MCU specific storage class extensions, i.e.
27016  xdata will be treated as a storage class specifier when parsing 8051 C
27017  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
27018  C code.
27019 \layout Paragraph*
27020
27021 Generating iCode
27022 \begin_inset LatexCommand \index{iCode}
27023
27024 \end_inset
27025
27026
27027 \layout Standard
27028
27029 Intermediate code generation.
27030  In this phase the AST is broken down into three-operand form (iCode).
27031  These three operand forms are represented as doubly linked lists.
27032  ICode is the term given to the intermediate form generated by the compiler.
27033  ICode example section shows some examples of iCode generated for some simple
27034  C source functions.
27035 \layout Paragraph*
27036
27037 Optimizations
27038 \begin_inset LatexCommand \index{Optimizations}
27039
27040 \end_inset
27041
27042 .
27043 \layout Standard
27044
27045 Bulk of the target independent optimizations is performed in this phase.
27046  The optimizations include constant propagation, common sub-expression eliminati
27047 on, loop invariant code movement, strength reduction of loop induction variables
27048  and dead-code elimination.
27049 \layout Paragraph*
27050
27051 Live range analysis
27052 \begin_inset LatexCommand \index{Live range analysis}
27053
27054 \end_inset
27055
27056
27057 \layout Standard
27058
27059 During intermediate code generation phase, the compiler assumes the target
27060  machine has infinite number of registers and generates a lot of temporary
27061  variables.
27062  The live range computation determines the lifetime of each of these compiler-ge
27063 nerated temporaries.
27064  A picture speaks a thousand words.
27065  ICode example sections show the live range annotations for each of the
27066  operand.
27067  It is important to note here, each iCode is assigned a number in the order
27068  of its execution in the function.
27069  The live ranges are computed in terms of these numbers.
27070  The from number is the number of the iCode which first defines the operand
27071  and the to number signifies the iCode which uses this operand last.
27072 \layout Paragraph*
27073
27074 Register Allocation
27075 \begin_inset LatexCommand \index{Register allocation}
27076
27077 \end_inset
27078
27079
27080 \layout Standard
27081
27082 The register allocation determines the type and number of registers needed
27083  by each operand.
27084  In most MCUs only a few registers can be used for indirect addressing.
27085  In case of 8051 for example the registers R0 & R1 can be used to indirectly
27086  address the internal ram and DPTR to indirectly address the external ram.
27087  The compiler will try to allocate the appropriate register to pointer variables
27088  if it can.
27089  ICode example section shows the operands annotated with the registers assigned
27090  to them.
27091  The compiler will try to keep operands in registers as much as possible;
27092  there are several schemes the compiler uses to do achieve this.
27093  When the compiler runs out of registers the compiler will check to see
27094  if there are any live operands which is not used or defined in the current
27095  basic block being processed, if there are any found then it will push that
27096  operand and use the registers in this block, the operand will then be popped
27097  at the end of the basic block.
27098
27099 \layout Standard
27100
27101 There are other MCU specific considerations in this phase.
27102  Some MCUs have an accumulator; very short-lived operands could be assigned
27103  to the accumulator instead of a general-purpose register.
27104 \layout Paragraph*
27105
27106 Code generation
27107 \layout Standard
27108
27109 Figure II gives a table of iCode operations supported by the compiler.
27110  The code generation involves translating these operations into corresponding
27111  assembly code for the processor.
27112  This sounds overly simple but that is the essence of code generation.
27113  Some of the iCode operations are generated on a MCU specific manner for
27114  example, the z80 port does not use registers to pass parameters so the
27115  SEND and RECV iCode operations will not be generated, and it also does
27116  not support JUMPTABLES.
27117
27118 \newline
27119
27120 \series bold
27121 \shape italic
27122 \color red
27123 <Where is Figure II?>
27124 \layout Comment
27125
27126 In the original article Figure II was announced to be downloadable on
27127 \shape italic
27128 Circuit Cellar
27129 \shape default
27130 's web site.
27131  Unfortunately it never seemed to have shown up there, so: where is Figure
27132  II?
27133 \layout Paragraph*
27134
27135 ICode Example
27136 \begin_inset LatexCommand \index{iCode}
27137
27138 \end_inset
27139
27140
27141 \layout Standard
27142
27143 This section shows some details of iCode.
27144  The example C code does not do anything useful; it is used as an example
27145  to illustrate the intermediate code generated by the compiler.
27146 \layout Verse
27147
27148
27149 \family typewriter
27150 1.\SpecialChar ~
27151 xdata int * p;
27152 \newline
27153 2.\SpecialChar ~
27154 int gint;
27155 \newline
27156 3.\SpecialChar ~
27157 /* This function does nothing useful.
27158  It is used
27159 \newline
27160 4.\SpecialChar ~
27161 \SpecialChar ~
27162 \SpecialChar ~
27163 \SpecialChar ~
27164 for the purpose of explaining iCode */
27165 \newline
27166 5.\SpecialChar ~
27167 short function (data int *x)
27168 \newline
27169 6.\SpecialChar ~
27170 {
27171 \newline
27172 7.\SpecialChar ~
27173 \SpecialChar ~
27174 \SpecialChar ~
27175 short i=10; \SpecialChar ~
27176 \SpecialChar ~
27177 /* dead initialization eliminated */
27178 \newline
27179 8.\SpecialChar ~
27180 \SpecialChar ~
27181 \SpecialChar ~
27182 short sum=10; /* dead initialization eliminated */
27183 \newline
27184 9.\SpecialChar ~
27185 \SpecialChar ~
27186 \SpecialChar ~
27187 short mul;
27188 \newline
27189 10.\SpecialChar ~
27190 \SpecialChar ~
27191 int j ;
27192 \newline
27193 11.\SpecialChar ~
27194 \SpecialChar ~
27195 while (*x) *x++ = *p++;
27196 \newline
27197 12.\SpecialChar ~
27198 \SpecialChar ~
27199 \SpecialChar ~
27200 \SpecialChar ~
27201 sum = 0 ;
27202 \newline
27203 13.\SpecialChar ~
27204 \SpecialChar ~
27205 mul = 0;
27206 \newline
27207 14.\SpecialChar ~
27208 \SpecialChar ~
27209 /* compiler detects i,j to be induction variables */
27210 \newline
27211 15.\SpecialChar ~
27212 \SpecialChar ~
27213 for (i = 0, j = 10 ; i < 10 ; i++, j
27214 \family default
27215 -
27216 \begin_inset ERT
27217 status Collapsed
27218
27219 \layout Standard
27220
27221 \backslash
27222 /
27223 \end_inset
27224
27225 -
27226 \family typewriter
27227 ) {
27228 \newline
27229 16.\SpecialChar ~
27230 \SpecialChar ~
27231 \SpecialChar ~
27232 \SpecialChar ~
27233 sum += i;
27234 \newline
27235 17.\SpecialChar ~
27236 \SpecialChar ~
27237 \SpecialChar ~
27238 \SpecialChar ~
27239 mul += i * 3; \SpecialChar ~
27240 \SpecialChar ~
27241 /* this multiplication remains */
27242 \newline
27243 18.\SpecialChar ~
27244 \SpecialChar ~
27245 \SpecialChar ~
27246 \SpecialChar ~
27247 gint += j * 3;\SpecialChar ~
27248 \SpecialChar ~
27249 /* this multiplication changed to addition */
27250 \newline
27251 19.\SpecialChar ~
27252 \SpecialChar ~
27253 }
27254 \newline
27255 20.\SpecialChar ~
27256 \SpecialChar ~
27257 return sum+mul;
27258 \newline
27259 21.\SpecialChar ~
27260 }
27261 \layout Standard
27262
27263 In addition to the operands each iCode contains information about the filename
27264  and line it corresponds to in the source file.
27265  The first field in the listing should be interpreted as follows:
27266 \newline
27267
27268 \shape italic
27269 \size footnotesize
27270 Filename(linenumber: iCode Execution sequence number : ICode hash table
27271  key : loop depth of the iCode).
27272 \shape default
27273 \size default
27274
27275 \newline
27276 Then follows the human readable form of the ICode operation.
27277  Each operand of this triplet form can be of three basic types a) compiler
27278  generated temporary b) user defined variable c) a constant value.
27279  Note that local variables and parameters are replaced by compiler generated
27280  temporaries.
27281  Live ranges
27282 \begin_inset LatexCommand \index{Live range analysis}
27283
27284 \end_inset
27285
27286  are computed only for temporaries (i.e.
27287  live ranges are not computed for global variables).
27288  Registers
27289 \begin_inset LatexCommand \index{Register allocation}
27290
27291 \end_inset
27292
27293  are allocated for temporaries only.
27294  Operands are formatted in the following manner:
27295 \newline
27296
27297 \shape italic
27298 \size footnotesize
27299 Operand Name [lr live-from : live-to ] { type information } [ registers
27300  allocated ].
27301 \shape default
27302 \size default
27303
27304 \newline
27305 As mentioned earlier the live ranges are computed in terms of the execution
27306  sequence number of the iCodes, for example
27307 \newline
27308 the iTemp0 is live from (i.e.
27309  first defined in iCode with execution sequence number 3, and is last used
27310  in the iCode with sequence number 5).
27311  For induction variables such as iTemp21 the live range computation extends
27312  the lifetime from the start to the end of the loop.
27313 \newline
27314 The register allocator used the live range information to allocate registers,
27315  the same registers may be used for different temporaries if their live
27316  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
27317  iTemp17 since their live ranges do not overlap.
27318  In addition the allocator also takes into consideration the type and usage
27319  of a temporary, for example itemp6 is a pointer to near space and is used
27320  as to fetch data from (i.e.
27321  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
27322  Some short lived temporaries are allocated to special registers which have
27323  meaning to the code generator e.g.
27324  iTemp13 is allocated to a pseudo register CC which tells the back end that
27325  the temporary is used only for a conditional jump the code generation makes
27326  use of this information to optimize a compare and jump ICode.
27327 \newline
27328 There are several loop optimizations
27329 \begin_inset LatexCommand \index{Loop optimization}
27330
27331 \end_inset
27332
27333  performed by the compiler.
27334  It can detect induction variables iTemp21(i) and iTemp23(j).
27335  Also note the compiler does selective strength reduction
27336 \begin_inset LatexCommand \index{Strength reduction}
27337
27338 \end_inset
27339
27340 , i.e.
27341  the multiplication of an induction variable in line 18 (gint = j * 3) is
27342  changed to addition, a new temporary iTemp17 is allocated and assigned
27343  a initial value, a constant 3 is then added for each iteration of the loop.
27344  The compiler does not change the multiplication
27345 \begin_inset LatexCommand \index{Multiplication}
27346
27347 \end_inset
27348
27349  in line 17 however since the processor does support an 8 * 8 bit multiplication.
27350 \newline
27351 Note the dead code elimination
27352 \begin_inset LatexCommand \index{Dead-code elimination}
27353
27354 \end_inset
27355
27356  optimization eliminated the dead assignments in line 7 & 8 to I and sum
27357  respectively.
27358 \newline
27359
27360 \layout Standard
27361
27362
27363 \size footnotesize
27364 Sample.c (5:1:0:0) _entry($9) :
27365 \layout Standard
27366
27367
27368 \size footnotesize
27369 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
27370 \layout Standard
27371
27372
27373 \size footnotesize
27374 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
27375 \layout Standard
27376
27377
27378 \size footnotesize
27379 Sample.c(11:4:53:0) preHeaderLbl0($11) :
27380 \layout Standard
27381
27382
27383 \size footnotesize
27384 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
27385  * int}[r2]
27386 \layout Standard
27387
27388
27389 \size footnotesize
27390 Sample.c(11:6:5:1) _whilecontinue_0($1) :
27391 \layout Standard
27392
27393
27394 \size footnotesize
27395 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
27396  int}[r0]]
27397 \layout Standard
27398
27399
27400 \size footnotesize
27401 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27402 \layout Standard
27403
27404
27405 \size footnotesize
27406 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
27407  * int}
27408 \layout Standard
27409
27410
27411 \size footnotesize
27412 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
27413  {short}
27414 \layout Standard
27415
27416
27417 \size footnotesize
27418 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
27419  * int}[DPTR]]
27420 \layout Standard
27421
27422
27423 \size footnotesize
27424 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
27425 }[r2 r3]
27426 \layout Standard
27427
27428
27429 \size footnotesize
27430 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
27431  * int}[r0] + 0x2 {short}
27432 \layout Standard
27433
27434
27435 \size footnotesize
27436 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
27437 \layout Standard
27438
27439
27440 \size footnotesize
27441 Sample.c(11:17:21:0)_whilebreak_0($3) :
27442 \layout Standard
27443
27444
27445 \size footnotesize
27446 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27447 \layout Standard
27448
27449
27450 \size footnotesize
27451 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27452 \layout Standard
27453
27454
27455 \size footnotesize
27456 Sample.c(15:20:54:0)preHeaderLbl1($13) :
27457 \layout Standard
27458
27459
27460 \size footnotesize
27461 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27462 \layout Standard
27463
27464
27465 \size footnotesize
27466 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27467 \layout Standard
27468
27469
27470 \size footnotesize
27471 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27472 \layout Standard
27473
27474
27475 \size footnotesize
27476 Sample.c(15:24:26:1)_forcond_0($4) :
27477 \layout Standard
27478
27479
27480 \size footnotesize
27481 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
27482  < 0xa {short}
27483 \layout Standard
27484
27485
27486 \size footnotesize
27487 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27488 \layout Standard
27489
27490
27491 \size footnotesize
27492 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
27493  + ITemp21 [lr21:38]{short}[r4]
27494 \layout Standard
27495
27496
27497 \size footnotesize
27498 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
27499  * 0x3 {short}
27500 \layout Standard
27501
27502
27503 \size footnotesize
27504 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
27505  + iTemp15 [lr29:30]{short}[r1]
27506 \layout Standard
27507
27508
27509 \size footnotesize
27510 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
27511  r0]- 0x3 {short}
27512 \layout Standard
27513
27514
27515 \size footnotesize
27516 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
27517 int}[r7 r0]
27518 \layout Standard
27519
27520
27521 \size footnotesize
27522 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
27523  + 0x1 {short}
27524 \layout Standard
27525
27526
27527 \size footnotesize
27528 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
27529  r6]- 0x1 {short}
27530 \layout Standard
27531
27532
27533 \size footnotesize
27534 Sample.c(19:38:47:1) goto _forcond_0($4)
27535 \layout Standard
27536
27537
27538 \size footnotesize
27539 Sample.c(19:39:48:0)_forbreak_0($7) :
27540 \layout Standard
27541
27542
27543 \size footnotesize
27544 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
27545  + ITemp11 [lr19:40]{short}[r3]
27546 \layout Standard
27547
27548
27549 \size footnotesize
27550 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
27551 \layout Standard
27552
27553
27554 \size footnotesize
27555 Sample.c(20:42:51:0)_return($8) :
27556 \layout Standard
27557
27558
27559 \size footnotesize
27560 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
27561 \size default
27562
27563 \newline
27564
27565 \newline
27566 Finally the code generated for this function:
27567 \newline
27568
27569 \layout Standard
27570
27571
27572 \size footnotesize
27573 .area DSEG (DATA)
27574 \layout Standard
27575
27576
27577 \size footnotesize
27578 _p::
27579 \layout Standard
27580
27581
27582 \size footnotesize
27583 \SpecialChar ~
27584 \SpecialChar ~
27585 .ds 2
27586 \layout Standard
27587
27588
27589 \size footnotesize
27590 _gint::
27591 \layout Standard
27592
27593
27594 \size footnotesize
27595 \SpecialChar ~
27596 \SpecialChar ~
27597 .ds 2
27598 \layout Standard
27599
27600
27601 \size footnotesize
27602 ; sample.c 5
27603 \layout Standard
27604
27605
27606 \size footnotesize
27607 ; ----------------------------------------------
27608 \layout Standard
27609
27610
27611 \size footnotesize
27612 ; function function
27613 \layout Standard
27614
27615
27616 \size footnotesize
27617 ; ----------------------------------------------
27618 \layout Standard
27619
27620
27621 \size footnotesize
27622 _function:
27623 \layout Standard
27624
27625
27626 \size footnotesize
27627 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
27628 \layout Standard
27629
27630
27631 \size footnotesize
27632 \SpecialChar ~
27633 \SpecialChar ~
27634 mov r2,dpl
27635 \layout Standard
27636
27637
27638 \size footnotesize
27639 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
27640 \layout Standard
27641
27642
27643 \size footnotesize
27644 \SpecialChar ~
27645 \SpecialChar ~
27646 mov ar0,r2
27647 \layout Standard
27648
27649
27650 \size footnotesize
27651 ;_whilecontinue_0($1) :
27652 \layout Standard
27653
27654
27655 \size footnotesize
27656 00101$:
27657 \layout Standard
27658
27659
27660 \size footnotesize
27661 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
27662 \layout Standard
27663
27664
27665 \size footnotesize
27666 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27667 \layout Standard
27668
27669
27670 \size footnotesize
27671 \SpecialChar ~
27672 \SpecialChar ~
27673 mov ar2,@r0
27674 \layout Standard
27675
27676
27677 \size footnotesize
27678 \SpecialChar ~
27679 \SpecialChar ~
27680 inc r0
27681 \layout Standard
27682
27683
27684 \size footnotesize
27685 \SpecialChar ~
27686 \SpecialChar ~
27687 mov ar3,@r0
27688 \layout Standard
27689
27690
27691 \size footnotesize
27692 \SpecialChar ~
27693 \SpecialChar ~
27694 dec r0
27695 \layout Standard
27696
27697
27698 \size footnotesize
27699 \SpecialChar ~
27700 \SpecialChar ~
27701 mov a,r2
27702 \layout Standard
27703
27704
27705 \size footnotesize
27706 \SpecialChar ~
27707 \SpecialChar ~
27708 orl a,r3
27709 \layout Standard
27710
27711
27712 \size footnotesize
27713 \SpecialChar ~
27714 \SpecialChar ~
27715 jz 00103$
27716 \layout Standard
27717
27718
27719 \size footnotesize
27720 00114$:
27721 \layout Standard
27722
27723
27724 \size footnotesize
27725 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
27726 \layout Standard
27727
27728
27729 \size footnotesize
27730 \SpecialChar ~
27731 \SpecialChar ~
27732 mov dpl,_p
27733 \layout Standard
27734
27735
27736 \size footnotesize
27737 \SpecialChar ~
27738 \SpecialChar ~
27739 mov dph,(_p + 1)
27740 \layout Standard
27741
27742
27743 \size footnotesize
27744 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
27745 \layout Standard
27746
27747
27748 \size footnotesize
27749 \SpecialChar ~
27750 \SpecialChar ~
27751 mov a,#0x02
27752 \layout Standard
27753
27754
27755 \size footnotesize
27756 \SpecialChar ~
27757 \SpecialChar ~
27758 add a,_p
27759 \layout Standard
27760
27761
27762 \size footnotesize
27763 \SpecialChar ~
27764 \SpecialChar ~
27765 mov _p,a
27766 \layout Standard
27767
27768
27769 \size footnotesize
27770 \SpecialChar ~
27771 \SpecialChar ~
27772 clr a
27773 \layout Standard
27774
27775
27776 \size footnotesize
27777 \SpecialChar ~
27778 \SpecialChar ~
27779 addc a,(_p + 1)
27780 \layout Standard
27781
27782
27783 \size footnotesize
27784 \SpecialChar ~
27785 \SpecialChar ~
27786 mov (_p + 1),a
27787 \layout Standard
27788
27789
27790 \size footnotesize
27791 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
27792 \layout Standard
27793
27794
27795 \size footnotesize
27796 \SpecialChar ~
27797 \SpecialChar ~
27798 movx a,@dptr
27799 \layout Standard
27800
27801
27802 \size footnotesize
27803 \SpecialChar ~
27804 \SpecialChar ~
27805 mov r2,a
27806 \layout Standard
27807
27808
27809 \size footnotesize
27810 \SpecialChar ~
27811 \SpecialChar ~
27812 inc dptr
27813 \layout Standard
27814
27815
27816 \size footnotesize
27817 \SpecialChar ~
27818 \SpecialChar ~
27819 movx a,@dptr
27820 \layout Standard
27821
27822
27823 \size footnotesize
27824 \SpecialChar ~
27825 \SpecialChar ~
27826 mov r3,a
27827 \layout Standard
27828
27829
27830 \size footnotesize
27831 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
27832 \layout Standard
27833
27834
27835 \size footnotesize
27836 \SpecialChar ~
27837 \SpecialChar ~
27838 mov @r0,ar2
27839 \layout Standard
27840
27841
27842 \size footnotesize
27843 \SpecialChar ~
27844 \SpecialChar ~
27845 inc r0
27846 \layout Standard
27847
27848
27849 \size footnotesize
27850 \SpecialChar ~
27851 \SpecialChar ~
27852 mov @r0,ar3
27853 \layout Standard
27854
27855
27856 \size footnotesize
27857 ; iTemp6 [lr5:16]{_near * int}[r0] =
27858 \layout Standard
27859
27860
27861 \size footnotesize
27862 ; iTemp6 [lr5:16]{_near * int}[r0] +
27863 \layout Standard
27864
27865
27866 \size footnotesize
27867 ; 0x2 {short}
27868 \layout Standard
27869
27870
27871 \size footnotesize
27872 \SpecialChar ~
27873 \SpecialChar ~
27874 inc r0
27875 \layout Standard
27876
27877
27878 \size footnotesize
27879 ; goto _whilecontinue_0($1)
27880 \layout Standard
27881
27882
27883 \size footnotesize
27884 \SpecialChar ~
27885 \SpecialChar ~
27886 sjmp 00101$
27887 \layout Standard
27888
27889
27890 \size footnotesize
27891 ; _whilebreak_0($3) :
27892 \layout Standard
27893
27894
27895 \size footnotesize
27896 00103$:
27897 \layout Standard
27898
27899
27900 \size footnotesize
27901 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27902 \layout Standard
27903
27904
27905 \size footnotesize
27906 \SpecialChar ~
27907 \SpecialChar ~
27908 mov r2,#0x00
27909 \layout Standard
27910
27911
27912 \size footnotesize
27913 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27914 \layout Standard
27915
27916
27917 \size footnotesize
27918 \SpecialChar ~
27919 \SpecialChar ~
27920 mov r3,#0x00
27921 \layout Standard
27922
27923
27924 \size footnotesize
27925 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27926 \layout Standard
27927
27928
27929 \size footnotesize
27930 \SpecialChar ~
27931 \SpecialChar ~
27932 mov r4,#0x00
27933 \layout Standard
27934
27935
27936 \size footnotesize
27937 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27938 \layout Standard
27939
27940
27941 \size footnotesize
27942 \SpecialChar ~
27943 \SpecialChar ~
27944 mov r5,#0x0A
27945 \layout Standard
27946
27947
27948 \size footnotesize
27949 \SpecialChar ~
27950 \SpecialChar ~
27951 mov r6,#0x00
27952 \layout Standard
27953
27954
27955 \size footnotesize
27956 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27957 \layout Standard
27958
27959
27960 \size footnotesize
27961 \SpecialChar ~
27962 \SpecialChar ~
27963 mov r7,#0x1E
27964 \layout Standard
27965
27966
27967 \size footnotesize
27968 \SpecialChar ~
27969 \SpecialChar ~
27970 mov r0,#0x00
27971 \layout Standard
27972
27973
27974 \size footnotesize
27975 ; _forcond_0($4) :
27976 \layout Standard
27977
27978
27979 \size footnotesize
27980 00104$:
27981 \layout Standard
27982
27983
27984 \size footnotesize
27985 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
27986 \layout Standard
27987
27988
27989 \size footnotesize
27990 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27991 \layout Standard
27992
27993
27994 \size footnotesize
27995 \SpecialChar ~
27996 \SpecialChar ~
27997 clr c
27998 \layout Standard
27999
28000
28001 \size footnotesize
28002 \SpecialChar ~
28003 \SpecialChar ~
28004 mov a,r4
28005 \layout Standard
28006
28007
28008 \size footnotesize
28009 \SpecialChar ~
28010 \SpecialChar ~
28011 xrl a,#0x80
28012 \layout Standard
28013
28014
28015 \size footnotesize
28016 \SpecialChar ~
28017 \SpecialChar ~
28018 subb a,#0x8a
28019 \layout Standard
28020
28021
28022 \size footnotesize
28023 \SpecialChar ~
28024 \SpecialChar ~
28025 jnc 00107$
28026 \layout Standard
28027
28028
28029 \size footnotesize
28030 00115$:
28031 \layout Standard
28032
28033
28034 \size footnotesize
28035 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
28036 \layout Standard
28037
28038
28039 \size footnotesize
28040 ; iTemp21 [lr21:38]{short}[r4]
28041 \layout Standard
28042
28043
28044 \size footnotesize
28045 \SpecialChar ~
28046 \SpecialChar ~
28047 mov a,r4
28048 \layout Standard
28049
28050
28051 \size footnotesize
28052 \SpecialChar ~
28053 \SpecialChar ~
28054 add a,r2
28055 \layout Standard
28056
28057
28058 \size footnotesize
28059 \SpecialChar ~
28060 \SpecialChar ~
28061 mov r2,a
28062 \layout Standard
28063
28064
28065 \size footnotesize
28066 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
28067 \layout Standard
28068
28069
28070 \size footnotesize
28071 \SpecialChar ~
28072 \SpecialChar ~
28073 mov b,#0x03
28074 \layout Standard
28075
28076
28077 \size footnotesize
28078 \SpecialChar ~
28079 \SpecialChar ~
28080 mov a,r4
28081 \layout Standard
28082
28083
28084 \size footnotesize
28085 \SpecialChar ~
28086 \SpecialChar ~
28087 mul ab
28088 \layout Standard
28089
28090
28091 \size footnotesize
28092 \SpecialChar ~
28093 \SpecialChar ~
28094 mov r1,a
28095 \layout Standard
28096
28097
28098 \size footnotesize
28099 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
28100 \layout Standard
28101
28102
28103 \size footnotesize
28104 ; iTemp15 [lr29:30]{short}[r1]
28105 \layout Standard
28106
28107
28108 \size footnotesize
28109 \SpecialChar ~
28110 \SpecialChar ~
28111 add a,r3
28112 \layout Standard
28113
28114
28115 \size footnotesize
28116 \SpecialChar ~
28117 \SpecialChar ~
28118 mov r3,a
28119 \layout Standard
28120
28121
28122 \size footnotesize
28123 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
28124 \layout Standard
28125
28126
28127 \size footnotesize
28128 \SpecialChar ~
28129 \SpecialChar ~
28130 mov a,r7
28131 \layout Standard
28132
28133
28134 \size footnotesize
28135 \SpecialChar ~
28136 \SpecialChar ~
28137 add a,#0xfd
28138 \layout Standard
28139
28140
28141 \size footnotesize
28142 \SpecialChar ~
28143 \SpecialChar ~
28144 mov r7,a
28145 \layout Standard
28146
28147
28148 \size footnotesize
28149 \SpecialChar ~
28150 \SpecialChar ~
28151 mov a,r0
28152 \layout Standard
28153
28154
28155 \size footnotesize
28156 \SpecialChar ~
28157 \SpecialChar ~
28158 addc a,#0xff
28159 \layout Standard
28160
28161
28162 \size footnotesize
28163 \SpecialChar ~
28164 \SpecialChar ~
28165 mov r0,a
28166 \layout Standard
28167
28168
28169 \size footnotesize
28170 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
28171 \layout Standard
28172
28173
28174 \size footnotesize
28175 \SpecialChar ~
28176 \SpecialChar ~
28177 mov a,r7
28178 \layout Standard
28179
28180
28181 \size footnotesize
28182 \SpecialChar ~
28183 \SpecialChar ~
28184 add a,_gint
28185 \layout Standard
28186
28187
28188 \size footnotesize
28189 \SpecialChar ~
28190 \SpecialChar ~
28191 mov _gint,a
28192 \layout Standard
28193
28194
28195 \size footnotesize
28196 \SpecialChar ~
28197 \SpecialChar ~
28198 mov a,r0
28199 \layout Standard
28200
28201
28202 \size footnotesize
28203 \SpecialChar ~
28204 \SpecialChar ~
28205 addc a,(_gint + 1)
28206 \layout Standard
28207
28208
28209 \size footnotesize
28210 \SpecialChar ~
28211 \SpecialChar ~
28212 mov (_gint + 1),a
28213 \layout Standard
28214
28215
28216 \size footnotesize
28217 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
28218 \layout Standard
28219
28220
28221 \size footnotesize
28222 \SpecialChar ~
28223 \SpecialChar ~
28224 inc r4
28225 \layout Standard
28226
28227
28228 \size footnotesize
28229 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
28230 \layout Standard
28231
28232
28233 \size footnotesize
28234 \SpecialChar ~
28235 \SpecialChar ~
28236 dec r5
28237 \layout Standard
28238
28239
28240 \size footnotesize
28241 \SpecialChar ~
28242 \SpecialChar ~
28243 cjne r5,#0xff,00104$
28244 \layout Standard
28245
28246
28247 \size footnotesize
28248 \SpecialChar ~
28249 \SpecialChar ~
28250 dec r6
28251 \layout Standard
28252
28253
28254 \size footnotesize
28255 ; goto _forcond_0($4)
28256 \layout Standard
28257
28258
28259 \size footnotesize
28260 \SpecialChar ~
28261 \SpecialChar ~
28262 sjmp 00104$
28263 \layout Standard
28264
28265
28266 \size footnotesize
28267 ; _forbreak_0($7) :
28268 \layout Standard
28269
28270
28271 \size footnotesize
28272 00107$:
28273 \layout Standard
28274
28275
28276 \size footnotesize
28277 ; ret iTemp24 [lr40:41]{short}
28278 \layout Standard
28279
28280
28281 \size footnotesize
28282 \SpecialChar ~
28283 \SpecialChar ~
28284 mov a,r3
28285 \layout Standard
28286
28287
28288 \size footnotesize
28289 \SpecialChar ~
28290 \SpecialChar ~
28291 add a,r2
28292 \layout Standard
28293
28294
28295 \size footnotesize
28296 \SpecialChar ~
28297 \SpecialChar ~
28298 mov dpl,a
28299 \layout Standard
28300
28301
28302 \size footnotesize
28303 ; _return($8) :
28304 \layout Standard
28305
28306
28307 \size footnotesize
28308 00108$:
28309 \layout Standard
28310
28311
28312 \size footnotesize
28313 \SpecialChar ~
28314 \SpecialChar ~
28315 ret
28316 \newline
28317
28318 \layout Section
28319
28320 A few words about basic block successors, predecessors and dominators
28321 \layout Standard
28322
28323 Successors are basic blocks
28324 \begin_inset LatexCommand \index{Basic blocks}
28325
28326 \end_inset
28327
28328  that might execute after this basic block.
28329 \newline
28330 Predecessors are basic blocks that might execute before reaching this basic
28331  block.
28332 \newline
28333 Dominators are basic blocks that WILL execute before reaching this basic
28334  block.
28335 \newline
28336
28337 \layout Standard
28338
28339 [basic block 1]
28340 \layout Standard
28341
28342 if (something)
28343 \layout Standard
28344
28345 \SpecialChar ~
28346 \SpecialChar ~
28347 \SpecialChar ~
28348 \SpecialChar ~
28349 [basic block 2]
28350 \layout Standard
28351
28352 else
28353 \layout Standard
28354
28355 \SpecialChar ~
28356 \SpecialChar ~
28357 \SpecialChar ~
28358 \SpecialChar ~
28359 [basic block 3]
28360 \layout Standard
28361
28362 [basic block 4]
28363 \newline
28364
28365 \layout Standard
28366
28367 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
28368 \layout Standard
28369
28370 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
28371 \layout Standard
28372
28373 c) domVect of [BB4] = BB1 ...
28374  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
28375  was executed.
28376 \layout Chapter
28377
28378 Acknowledgments
28379 \layout Standard
28380
28381
28382 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
28383
28384 \end_inset
28385
28386
28387 \newline
28388
28389 \newline
28390
28391 \emph on
28392 Thanks to all the other volunteer developers who have helped with coding,
28393  testing, web-page creation, distribution sets, etc.
28394  You know who you are :-)
28395 \emph default
28396
28397 \newline
28398
28399 \layout Standard
28400
28401 This document was initially written by Sandeep Dutta
28402 \layout Standard
28403
28404 All product names mentioned herein may be trademarks
28405 \begin_inset LatexCommand \index{Trademarks}
28406
28407 \end_inset
28408
28409  of their respective companies.
28410
28411 \layout Section*
28412
28413 Alphabetical index
28414 \layout Standard
28415
28416 To avoid confusion, the installation and building options for SDCC itself
28417  (chapter 2) are not part of the index.
28418 \layout Standard
28419
28420
28421 \begin_inset LatexCommand \printindex{}
28422
28423 \end_inset
28424
28425
28426 \the_end