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-build 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-libgc Use the Bohem memory allocator.
 872  Lower runtime footprint.
 873 \layout Standard
 874
 875 Furthermore the environment variables CC, CFLAGS, ...
 876  the tools and their arguments can be influenced.
 877  Please see `configure -
 878 \begin_inset ERT
 879 status Collapsed
 880
 881 \layout Standard
 882
 883 \backslash
 884 /
 885 \end_inset
 886
 887 -help` and the man/info pages of `configure` for details.
 888 \newline
 889
 890 \newline
 891 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 892  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 893 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 894  At the moment it's not possible to change the default settings (it was
 895  simply never required).
 896 \newline
 897
 898 \newline
 899 These configure options are compiled into the binaries, and can only be
 900  changed by rerunning 'configure' and recompiling SDCC.
 901  The configure options are written in
 902 \emph on
 903 italics
 904 \emph default
 905  to distinguish them from run time environment variables (see section search
 906  paths).
 907 \newline
 908
 909 \newline
 910 The settings for
 911 \begin_inset Quotes sld
 912 \end_inset
 913
 914 Win32 builds
 915 \begin_inset Quotes srd
 916 \end_inset
 917
 918  are used by the SDCC team to build the official Win32 binaries.
 919  The SDCC team uses Mingw32 to build the official Windows binaries, because
 920  it's
 921 \layout Enumerate
 922
 923 open source,
 924 \layout Enumerate
 925
 926 a gcc compiler and last but not least
 927 \layout Enumerate
 928
 929 the binaries can be built by cross compiling on Sourceforge's compile farm.
 930 \layout Standard
 931
 932 See the examples, how to pass the Win32 settings to 'configure'.
 933  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 934  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 935  for Win32.
 936 \newline
 937
 938 \newline
 939 These defaults are:
 940 \newline
 941
 942 \layout Standard
 943 \align center
 944
 945 \begin_inset  Tabular
 946 <lyxtabular version="3" rows="8" columns="3">
 947 <features>
 948 <column alignment="block" valignment="top" leftline="true" width="0in">
 949 <column alignment="block" valignment="top" leftline="true" width="0in">
 950 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 951 <row topline="true" bottomline="true">
 952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 953 \begin_inset Text
 954
 955 \layout Standard
 956
 957 Variable
 958 \end_inset
 959 </cell>
 960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 961 \begin_inset Text
 962
 963 \layout Standard
 964
 965 default
 966 \end_inset
 967 </cell>
 968 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 969 \begin_inset Text
 970
 971 \layout Standard
 972
 973 Win32 builds
 974 \end_inset
 975 </cell>
 976 </row>
 977 <row topline="true">
 978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 979 \begin_inset Text
 980
 981 \layout Standard
 982
 983
 984 \emph on
 985 PREFIX
 986 \end_inset
 987 </cell>
 988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 989 \begin_inset Text
 990
 991 \layout Standard
 992
 993 /usr/local
 994 \end_inset
 995 </cell>
 996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 997 \begin_inset Text
 998
 999 \layout Standard
1000
1001
1002 \backslash
1003 sdcc
1004 \end_inset
1005 </cell>
1006 </row>
1007 <row topline="true">
1008 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1009 \begin_inset Text
1010
1011 \layout Standard
1012
1013
1014 \emph on
1015 EXEC_PREFIX
1016 \end_inset
1017 </cell>
1018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1019 \begin_inset Text
1020
1021 \layout Standard
1022
1023
1024 \emph on
1025 $PREFIX
1026 \end_inset
1027 </cell>
1028 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1029 \begin_inset Text
1030
1031 \layout Standard
1032
1033
1034 \emph on
1035 $PREFIX
1036 \end_inset
1037 </cell>
1038 </row>
1039 <row topline="true">
1040 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1041 \begin_inset Text
1042
1043 \layout Standard
1044
1045
1046 \emph on
1047 BINDIR
1048 \end_inset
1049 </cell>
1050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1051 \begin_inset Text
1052
1053 \layout Standard
1054
1055
1056 \emph on
1057 $EXECPREFIX
1058 \emph default
1059 /bin
1060 \end_inset
1061 </cell>
1062 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1063 \begin_inset Text
1064
1065 \layout Standard
1066
1067
1068 \emph on
1069 $EXECPREFIX
1070 \emph default
1071
1072 \backslash
1073 bin
1074 \end_inset
1075 </cell>
1076 </row>
1077 <row topline="true">
1078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1079 \begin_inset Text
1080
1081 \layout Standard
1082
1083
1084 \emph on
1085 DATADIR
1086 \end_inset
1087 </cell>
1088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1089 \begin_inset Text
1090
1091 \layout Standard
1092
1093
1094 \emph on
1095 $PREFIX
1096 \emph default
1097 /share
1098 \end_inset
1099 </cell>
1100 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1101 \begin_inset Text
1102
1103 \layout Standard
1104
1105
1106 \emph on
1107 $PREFIX
1108 \end_inset
1109 </cell>
1110 </row>
1111 <row topline="true">
1112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1113 \begin_inset Text
1114
1115 \layout Standard
1116
1117
1118 \emph on
1119 DOCDIR
1120 \end_inset
1121 </cell>
1122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1123 \begin_inset Text
1124
1125 \layout Standard
1126
1127
1128 \emph on
1129 $DATADIR
1130 \emph default
1131 /sdcc/doc
1132 \end_inset
1133 </cell>
1134 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1135 \begin_inset Text
1136
1137 \layout Standard
1138
1139
1140 \emph on
1141 $DATADIR
1142 \emph default
1143
1144 \backslash
1145 doc
1146 \end_inset
1147 </cell>
1148 </row>
1149 <row topline="true">
1150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1151 \begin_inset Text
1152
1153 \layout Standard
1154
1155
1156 \emph on
1157 INCLUDE_DIR_SUFFIX
1158 \end_inset
1159 </cell>
1160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1161 \begin_inset Text
1162
1163 \layout Standard
1164
1165 sdcc/include
1166 \end_inset
1167 </cell>
1168 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1169 \begin_inset Text
1170
1171 \layout Standard
1172
1173 include
1174 \end_inset
1175 </cell>
1176 </row>
1177 <row topline="true" bottomline="true">
1178 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1179 \begin_inset Text
1180
1181 \layout Standard
1182
1183
1184 \emph on
1185 LIB_DIR_SUFFIX
1186 \end_inset
1187 </cell>
1188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1189 \begin_inset Text
1190
1191 \layout Standard
1192
1193 sdcc/lib
1194 \end_inset
1195 </cell>
1196 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1197 \begin_inset Text
1198
1199 \layout Standard
1200
1201 lib
1202 \end_inset
1203 </cell>
1204 </row>
1205 </lyxtabular>
1206
1207 \end_inset
1208
1209
1210 \newline
1211
1212 \layout Standard
1213 \noindent
1214 'configure' also computes relative paths.
1215  This is needed for full relocatability of a binary package and to complete
1216  search paths (see section search paths below):
1217 \newline
1218
1219 \layout Standard
1220 \align center
1221
1222 \begin_inset  Tabular
1223 <lyxtabular version="3" rows="4" columns="3">
1224 <features>
1225 <column alignment="block" valignment="top" leftline="true" width="0in">
1226 <column alignment="block" valignment="top" leftline="true" width="0in">
1227 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1228 <row topline="true" bottomline="true">
1229 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1230 \begin_inset Text
1231
1232 \layout Standard
1233
1234 Variable (computed)
1235 \end_inset
1236 </cell>
1237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1238 \begin_inset Text
1239
1240 \layout Standard
1241
1242 default
1243 \end_inset
1244 </cell>
1245 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1246 \begin_inset Text
1247
1248 \layout Standard
1249
1250 Win32 builds
1251 \end_inset
1252 </cell>
1253 </row>
1254 <row topline="true" bottomline="true">
1255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1256 \begin_inset Text
1257
1258 \layout Standard
1259
1260
1261 \emph on
1262 BIN2DATA_DIR
1263 \end_inset
1264 </cell>
1265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1266 \begin_inset Text
1267
1268 \layout Standard
1269
1270 ../share
1271 \end_inset
1272 </cell>
1273 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1274 \begin_inset Text
1275
1276 \layout Standard
1277
1278 ..
1279 \end_inset
1280 </cell>
1281 </row>
1282 <row bottomline="true">
1283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1284 \begin_inset Text
1285
1286 \layout Standard
1287
1288
1289 \emph on
1290 PREFIX2BIN_DIR
1291 \end_inset
1292 </cell>
1293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1294 \begin_inset Text
1295
1296 \layout Standard
1297
1298 bin
1299 \end_inset
1300 </cell>
1301 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1302 \begin_inset Text
1303
1304 \layout Standard
1305
1306 bin
1307 \end_inset
1308 </cell>
1309 </row>
1310 <row bottomline="true">
1311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1312 \begin_inset Text
1313
1314 \layout Standard
1315
1316
1317 \emph on
1318 PREFIX2DATA_DIR
1319 \end_inset
1320 </cell>
1321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1322 \begin_inset Text
1323
1324 \layout Standard
1325
1326 share/sdcc
1327 \end_inset
1328 </cell>
1329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1330 \begin_inset Text
1331
1332 \layout Standard
1333
1334 \end_inset
1335 </cell>
1336 </row>
1337 </lyxtabular>
1338
1339 \end_inset
1340
1341
1342 \newline
1343
1344 \layout Standard
1345 \noindent
1346 Examples:
1347 \layout LyX-Code
1348
1349 ./configure
1350 \newline
1351 ./configure -
1352 \begin_inset ERT
1353 status Collapsed
1354
1355 \layout Standard
1356
1357 \backslash
1358 /
1359 \end_inset
1360
1361 -prefix=
1362 \begin_inset Quotes srd
1363 \end_inset
1364
1365 /usr/bin
1366 \begin_inset Quotes srd
1367 \end_inset
1368
1369  -
1370 \begin_inset ERT
1371 status Collapsed
1372
1373 \layout Standard
1374
1375 \backslash
1376 /
1377 \end_inset
1378
1379 -datadir=
1380 \begin_inset Quotes srd
1381 \end_inset
1382
1383 /usr/share
1384 \begin_inset Quotes srd
1385 \end_inset
1386
1387
1388 \newline
1389 ./configure -
1390 \begin_inset ERT
1391 status Collapsed
1392
1393 \layout Standard
1394
1395 \backslash
1396 /
1397 \end_inset
1398
1399 -disable-avr-port -
1400 \begin_inset ERT
1401 status Collapsed
1402
1403 \layout Standard
1404
1405 \backslash
1406 /
1407 \end_inset
1408
1409 -disable-xa51-port
1410 \layout Standard
1411
1412 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1413 32'):
1414 \layout LyX-Code
1415
1416 ./configure
1417 \backslash
1418
1419 \newline
1420 CC=
1421 \begin_inset Quotes srd
1422 \end_inset
1423
1424 i586-mingw32msvc-gcc
1425 \begin_inset Quotes srd
1426 \end_inset
1427
1428  CXX=
1429 \begin_inset Quotes srd
1430 \end_inset
1431
1432 i586-mingw32msvc-g++
1433 \begin_inset Quotes srd
1434 \end_inset
1435
1436
1437 \backslash
1438
1439 \newline
1440 RANLIB=
1441 \begin_inset Quotes srd
1442 \end_inset
1443
1444 i586-mingw32msvc-ranlib
1445 \begin_inset Quotes srd
1446 \end_inset
1447
1448
1449 \backslash
1450
1451 \newline
1452 STRIP=
1453 \begin_inset Quotes srd
1454 \end_inset
1455
1456 i586-mingw32msvc-strip
1457 \begin_inset Quotes srd
1458 \end_inset
1459
1460
1461 \backslash
1462
1463 \newline
1464 -
1465 \begin_inset ERT
1466 status Collapsed
1467
1468 \layout Standard
1469
1470 \backslash
1471 /
1472 \end_inset
1473
1474 -prefix=
1475 \begin_inset Quotes srd
1476 \end_inset
1477
1478 /sdcc
1479 \begin_inset Quotes srd
1480 \end_inset
1481
1482
1483 \backslash
1484
1485 \newline
1486 -
1487 \begin_inset ERT
1488 status Collapsed
1489
1490 \layout Standard
1491
1492 \backslash
1493 /
1494 \end_inset
1495
1496 -datadir=
1497 \begin_inset Quotes srd
1498 \end_inset
1499
1500 /sdcc
1501 \begin_inset Quotes srd
1502 \end_inset
1503
1504
1505 \backslash
1506
1507 \newline
1508 docdir=
1509 \begin_inset Quotes srd
1510 \end_inset
1511
1512 /sdcc/doc
1513 \begin_inset Quotes srd
1514 \end_inset
1515
1516
1517 \backslash
1518
1519 \newline
1520 include_dir_suffix=
1521 \begin_inset Quotes srd
1522 \end_inset
1523
1524 include
1525 \begin_inset Quotes srd
1526 \end_inset
1527
1528
1529 \backslash
1530
1531 \newline
1532 lib_dir_suffix=
1533 \begin_inset Quotes srd
1534 \end_inset
1535
1536 lib
1537 \begin_inset Quotes srd
1538 \end_inset
1539
1540
1541 \backslash
1542
1543 \newline
1544 sdccconf_h_dir_separator=
1545 \begin_inset Quotes srd
1546 \end_inset
1547
1548
1549 \backslash
1550
1551 \backslash
1552
1553 \backslash
1554
1555 \backslash
1556
1557 \begin_inset Quotes srd
1558 \end_inset
1559
1560
1561 \backslash
1562
1563 \newline
1564 -
1565 \begin_inset ERT
1566 status Collapsed
1567
1568 \layout Standard
1569
1570 \backslash
1571 /
1572 \end_inset
1573
1574 -disable-device-lib-build
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-ucsim
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 -host=i586-mingw32msvc -
1603 \begin_inset ERT
1604 status Collapsed
1605
1606 \layout Standard
1607
1608 \backslash
1609 /
1610 \end_inset
1611
1612 -build=unknown-unknown-linux-gnu
1613 \layout Standard
1614
1615 To
1616 \begin_inset Quotes sld
1617 \end_inset
1618
1619 cross
1620 \begin_inset Quotes srd
1621 \end_inset
1622
1623 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1624 ):
1625 \layout LyX-Code
1626
1627 ./configure -C
1628 \backslash
1629
1630 \newline
1631 CFLAGS=
1632 \begin_inset Quotes srd
1633 \end_inset
1634
1635 -mno-cygwin -O2
1636 \begin_inset Quotes srd
1637 \end_inset
1638
1639
1640 \backslash
1641
1642 \newline
1643 LDFLAGS=
1644 \begin_inset Quotes srd
1645 \end_inset
1646
1647 -mno-cygwin
1648 \begin_inset Quotes srd
1649 \end_inset
1650
1651
1652 \backslash
1653
1654 \newline
1655 -
1656 \begin_inset ERT
1657 status Collapsed
1658
1659 \layout Standard
1660
1661 \backslash
1662 /
1663 \end_inset
1664
1665 -prefix=
1666 \begin_inset Quotes srd
1667 \end_inset
1668
1669 /sdcc
1670 \begin_inset Quotes srd
1671 \end_inset
1672
1673
1674 \backslash
1675
1676 \newline
1677 -
1678 \begin_inset ERT
1679 status Collapsed
1680
1681 \layout Standard
1682
1683 \backslash
1684 /
1685 \end_inset
1686
1687 -datadir=
1688 \begin_inset Quotes srd
1689 \end_inset
1690
1691 /sdcc
1692 \begin_inset Quotes srd
1693 \end_inset
1694
1695
1696 \backslash
1697
1698 \newline
1699 docdir=
1700 \begin_inset Quotes srd
1701 \end_inset
1702
1703 /sdcc/doc
1704 \begin_inset Quotes srd
1705 \end_inset
1706
1707
1708 \backslash
1709
1710 \newline
1711 include_dir_suffix=
1712 \begin_inset Quotes srd
1713 \end_inset
1714
1715 include
1716 \begin_inset Quotes srd
1717 \end_inset
1718
1719
1720 \backslash
1721
1722 \newline
1723 lib_dir_suffix=
1724 \begin_inset Quotes srd
1725 \end_inset
1726
1727 lib
1728 \begin_inset Quotes srd
1729 \end_inset
1730
1731
1732 \backslash
1733
1734 \newline
1735 sdccconf_h_dir_separator=
1736 \begin_inset Quotes srd
1737 \end_inset
1738
1739
1740 \backslash
1741
1742 \backslash
1743
1744 \backslash
1745
1746 \backslash
1747
1748 \begin_inset Quotes srd
1749 \end_inset
1750
1751
1752 \backslash
1753
1754 \newline
1755 -
1756 \begin_inset ERT
1757 status Collapsed
1758
1759 \layout Standard
1760
1761 \backslash
1762 /
1763 \end_inset
1764
1765 -disable-ucsim
1766 \layout Standard
1767
1768 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1769  The option '-
1770 \begin_inset ERT
1771 status Collapsed
1772
1773 \layout Standard
1774
1775 \backslash
1776 /
1777 \end_inset
1778
1779 -C' turns on caching, which gives a little bit extra speed.
1780  However if options are changed, it can be necessary to delete the config.cache
1781  file.
1782 \layout Section
1783
1784 Install paths
1785 \begin_inset LatexCommand \label{sub:Install-paths}
1786
1787 \end_inset
1788
1789
1790 \begin_inset LatexCommand \index{Install paths}
1791
1792 \end_inset
1793
1794
1795 \layout Standard
1796 \added_space_top medskip \align center
1797
1798 \begin_inset  Tabular
1799 <lyxtabular version="3" rows="5" columns="4">
1800 <features>
1801 <column alignment="center" valignment="top" leftline="true" width="0">
1802 <column alignment="center" valignment="top" leftline="true" width="0">
1803 <column alignment="center" valignment="top" leftline="true" width="0">
1804 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1805 <row topline="true" bottomline="true">
1806 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1807 \begin_inset Text
1808
1809 \layout Standard
1810
1811
1812 \series bold
1813 Description
1814 \end_inset
1815 </cell>
1816 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1817 \begin_inset Text
1818
1819 \layout Standard
1820
1821
1822 \series bold
1823 Path
1824 \end_inset
1825 </cell>
1826 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1827 \begin_inset Text
1828
1829 \layout Standard
1830
1831
1832 \series bold
1833 Default
1834 \end_inset
1835 </cell>
1836 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1837 \begin_inset Text
1838
1839 \layout Standard
1840
1841
1842 \series bold
1843 Win32 builds
1844 \end_inset
1845 </cell>
1846 </row>
1847 <row topline="true">
1848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1849 \begin_inset Text
1850
1851 \layout Standard
1852
1853 Binary files*
1854 \end_inset
1855 </cell>
1856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1857 \begin_inset Text
1858
1859 \layout Standard
1860
1861
1862 \emph on
1863 $EXEC_PREFIX
1864 \end_inset
1865 </cell>
1866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1867 \begin_inset Text
1868
1869 \layout Standard
1870
1871 /usr/local/bin
1872 \end_inset
1873 </cell>
1874 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1875 \begin_inset Text
1876
1877 \layout Standard
1878
1879
1880 \backslash
1881 sdcc
1882 \backslash
1883 bin
1884 \end_inset
1885 </cell>
1886 </row>
1887 <row topline="true">
1888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1889 \begin_inset Text
1890
1891 \layout Standard
1892
1893 Include files
1894 \end_inset
1895 </cell>
1896 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1897 \begin_inset Text
1898
1899 \layout Standard
1900
1901
1902 \emph on
1903 $DATADIR/ $INCLUDE_DIR_SUFFIX
1904 \end_inset
1905 </cell>
1906 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1907 \begin_inset Text
1908
1909 \layout Standard
1910
1911 /usr/local/share/sdcc/include
1912 \end_inset
1913 </cell>
1914 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1915 \begin_inset Text
1916
1917 \layout Standard
1918
1919
1920 \backslash
1921 sdcc
1922 \backslash
1923 include
1924 \end_inset
1925 </cell>
1926 </row>
1927 <row topline="true">
1928 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1929 \begin_inset Text
1930
1931 \layout Standard
1932
1933 Library file**
1934 \end_inset
1935 </cell>
1936 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1937 \begin_inset Text
1938
1939 \layout Standard
1940
1941
1942 \emph on
1943 $DATADIR/$LIB_DIR_SUFFIX
1944 \end_inset
1945 </cell>
1946 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1947 \begin_inset Text
1948
1949 \layout Standard
1950
1951 /usr/local/share/sdcc/lib
1952 \end_inset
1953 </cell>
1954 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1955 \begin_inset Text
1956
1957 \layout Standard
1958
1959
1960 \backslash
1961 sdcc
1962 \backslash
1963 lib
1964 \end_inset
1965 </cell>
1966 </row>
1967 <row topline="true" bottomline="true">
1968 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1969 \begin_inset Text
1970
1971 \layout Standard
1972
1973 Documentation
1974 \end_inset
1975 </cell>
1976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1977 \begin_inset Text
1978
1979 \layout Standard
1980
1981
1982 \emph on
1983 $DOCDIR
1984 \end_inset
1985 </cell>
1986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1987 \begin_inset Text
1988
1989 \layout Standard
1990
1991 /usr/local/share/sdcc/doc
1992 \end_inset
1993 </cell>
1994 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1995 \begin_inset Text
1996
1997 \layout Standard
1998
1999
2000 \backslash
2001 sdcc
2002 \backslash
2003 doc
2004 \end_inset
2005 </cell>
2006 </row>
2007 </lyxtabular>
2008
2009 \end_inset
2010
2011
2012 \layout Verse
2013
2014
2015 \size footnotesize
2016 *compiler, preprocessor, assembler, and linker
2017 \newline
2018 **the
2019 \shape italic
2020 model
2021 \shape default
2022  is auto-appended by the compiler, e.g.
2023  small, large, z80, ds390 etc
2024 \layout Standard
2025 \noindent
2026 The install paths can still be changed during `make install` with e.g.:
2027 \layout LyX-Code
2028
2029 make install prefix=$(HOME)/local/sdcc
2030 \layout Standard
2031
2032 Of course this doesn't change the search paths compiled into the binaries.
2033 \newline
2034
2035 \newline
2036 Moreover the install path can be changed by defining DESTDIR
2037 \begin_inset LatexCommand \index{DESTDIR}
2038
2039 \end_inset
2040
2041 :
2042 \layout LyX-Code
2043
2044 make install DESTDIR=$(HOME)/sdcc.rpm/
2045 \layout Standard
2046
2047 Please note that DESTDIR must have a trailing slash!
2048 \layout Section
2049
2050 Search Paths
2051 \begin_inset LatexCommand \label{sub:Search-Paths}
2052
2053 \end_inset
2054
2055
2056 \begin_inset LatexCommand \index{Search path}
2057
2058 \end_inset
2059
2060
2061 \layout Standard
2062
2063 Some search paths or parts of them are determined by configure variables
2064  (in
2065 \emph on
2066 italics
2067 \emph default
2068 , see section above).
2069  Further search paths are determined by environment variables during runtime.
2070
2071 \newline
2072 The paths searched when running the compiler are as follows (the first catch
2073  wins):
2074 \newline
2075
2076 \newline
2077 1.
2078  Binary files (preprocessor, assembler and linker)
2079 \newline
2080
2081 \layout Standard
2082 \align center
2083
2084 \begin_inset  Tabular
2085 <lyxtabular version="3" rows="4" columns="3">
2086 <features>
2087 <column alignment="block" valignment="top" leftline="true" width="0in">
2088 <column alignment="block" valignment="top" leftline="true" width="0in">
2089 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2090 <row topline="true" bottomline="true">
2091 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2092 \begin_inset Text
2093
2094 \layout Standard
2095
2096 Search path
2097 \end_inset
2098 </cell>
2099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2100 \begin_inset Text
2101
2102 \layout Standard
2103
2104 default
2105 \end_inset
2106 </cell>
2107 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2108 \begin_inset Text
2109
2110 \layout Standard
2111
2112 Win32 builds
2113 \end_inset
2114 </cell>
2115 </row>
2116 <row topline="true">
2117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2118 \begin_inset Text
2119
2120 \layout Standard
2121
2122 $SDCC_HOME/
2123 \emph on
2124 $PPREFIX2BIN_DIR
2125 \end_inset
2126 </cell>
2127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2128 \begin_inset Text
2129
2130 \layout Standard
2131
2132 $SDCC_HOME/bin
2133 \end_inset
2134 </cell>
2135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2136 \begin_inset Text
2137
2138 \layout Standard
2139
2140 $SDCC_HOME
2141 \backslash
2142 bin
2143 \end_inset
2144 </cell>
2145 </row>
2146 <row topline="true">
2147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2148 \begin_inset Text
2149
2150 \layout Standard
2151
2152 Path of argv[0] (if available)
2153 \end_inset
2154 </cell>
2155 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2156 \begin_inset Text
2157
2158 \layout Standard
2159
2160 Path of argv[0]
2161 \end_inset
2162 </cell>
2163 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2164 \begin_inset Text
2165
2166 \layout Standard
2167
2168 Path of argv[0]
2169 \end_inset
2170 </cell>
2171 </row>
2172 <row topline="true" bottomline="true">
2173 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2174 \begin_inset Text
2175
2176 \layout Standard
2177
2178 $PATH
2179 \end_inset
2180 </cell>
2181 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2182 \begin_inset Text
2183
2184 \layout Standard
2185
2186 $PATH
2187 \end_inset
2188 </cell>
2189 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2190 \begin_inset Text
2191
2192 \layout Standard
2193
2194 $PATH
2195 \end_inset
2196 </cell>
2197 </row>
2198 </lyxtabular>
2199
2200 \end_inset
2201
2202
2203 \newline
2204
2205 \layout Standard
2206 \noindent
2207 2.
2208  Include files
2209 \newline
2210
2211 \layout Standard
2212 \align center
2213
2214 \begin_inset  Tabular
2215 <lyxtabular version="3" rows="6" columns="3">
2216 <features>
2217 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2218 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2219 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2220 <row topline="true" bottomline="true">
2221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2222 \begin_inset Text
2223
2224 \layout Standard
2225
2226 Search path
2227 \end_inset
2228 </cell>
2229 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2230 \begin_inset Text
2231
2232 \layout Standard
2233
2234 default
2235 \end_inset
2236 </cell>
2237 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2238 \begin_inset Text
2239
2240 \layout Standard
2241
2242 Win32 builds
2243 \end_inset
2244 </cell>
2245 </row>
2246 <row topline="true">
2247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2248 \begin_inset Text
2249
2250 \layout Standard
2251
2252 -
2253 \begin_inset ERT
2254 status Collapsed
2255
2256 \layout Standard
2257
2258 \backslash
2259 /
2260 \end_inset
2261
2262 -I dir
2263 \end_inset
2264 </cell>
2265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2266 \begin_inset Text
2267
2268 \layout Standard
2269
2270 -
2271 \begin_inset ERT
2272 status Collapsed
2273
2274 \layout Standard
2275
2276 \backslash
2277 /
2278 \end_inset
2279
2280 -I dir
2281 \end_inset
2282 </cell>
2283 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2284 \begin_inset Text
2285
2286 \layout Standard
2287
2288 -
2289 \begin_inset ERT
2290 status Collapsed
2291
2292 \layout Standard
2293
2294 \backslash
2295 /
2296 \end_inset
2297
2298 -I dir
2299 \end_inset
2300 </cell>
2301 </row>
2302 <row topline="true">
2303 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2304 \begin_inset Text
2305
2306 \layout Standard
2307
2308 $SDCC_INCLUDE
2309 \end_inset
2310 </cell>
2311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2312 \begin_inset Text
2313
2314 \layout Standard
2315
2316 $SDCC_INCLUDE
2317 \end_inset
2318 </cell>
2319 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2320 \begin_inset Text
2321
2322 \layout Standard
2323
2324 $SDCC_INCLUDE
2325 \end_inset
2326 </cell>
2327 </row>
2328 <row topline="true">
2329 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2330 \begin_inset Text
2331
2332 \layout Standard
2333
2334 $SDCC_HOME/
2335 \newline
2336
2337 \emph on
2338 $PREFIX2DATA_DIR/
2339 \newline
2340 $INCLUDE_DIR_SUFFIX
2341 \end_inset
2342 </cell>
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 share/sdcc/
2351 \newline
2352 include
2353 \end_inset
2354 </cell>
2355 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2356 \begin_inset Text
2357
2358 \layout Standard
2359
2360 $SDCC_HOME
2361 \backslash
2362 include
2363 \end_inset
2364 </cell>
2365 </row>
2366 <row topline="true">
2367 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2368 \begin_inset Text
2369
2370 \layout Standard
2371
2372 path(argv[0])/
2373 \newline
2374
2375 \emph on
2376 $BIN2DATADIR/
2377 \emph default
2378
2379 \newline
2380
2381 \emph on
2382 $INCLUDE_DIR_SUFFIX
2383 \end_inset
2384 </cell>
2385 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2386 \begin_inset Text
2387
2388 \layout Standard
2389
2390 path(argv[0])/
2391 \newline
2392 ../sdcc/include
2393 \newline
2394 \SpecialChar ~
2395 \SpecialChar ~
2396 \SpecialChar ~
2397 \SpecialChar ~
2398 \SpecialChar ~
2399 \SpecialChar ~
2400 \SpecialChar ~
2401 \SpecialChar ~
2402 \SpecialChar ~
2403 \SpecialChar ~
2404 \SpecialChar ~
2405 \SpecialChar ~
2406 \SpecialChar ~
2407 \SpecialChar ~
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
2433 \end_inset
2434 </cell>
2435 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2436 \begin_inset Text
2437
2438 \layout Standard
2439
2440 path(argv[0])
2441 \backslash
2442 ..
2443 \backslash
2444 include
2445 \end_inset
2446 </cell>
2447 </row>
2448 <row topline="true" bottomline="true">
2449 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2450 \begin_inset Text
2451
2452 \layout Standard
2453
2454
2455 \emph on
2456 $DATADIR/
2457 \emph default
2458
2459 \newline
2460
2461 \emph on
2462 $INCLUDE_DIR_SUFFIX
2463 \end_inset
2464 </cell>
2465 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2466 \begin_inset Text
2467
2468 \layout Standard
2469
2470 /usr/local/share/sdcc/
2471 \newline
2472 include
2473 \end_inset
2474 </cell>
2475 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2476 \begin_inset Text
2477
2478 \layout Standard
2479
2480 (not on Win32)
2481 \end_inset
2482 </cell>
2483 </row>
2484 </lyxtabular>
2485
2486 \end_inset
2487
2488
2489 \newline
2490
2491 \layout Standard
2492 \noindent
2493 The option -
2494 \begin_inset ERT
2495 status Collapsed
2496
2497 \layout Standard
2498
2499 \backslash
2500 /
2501 \end_inset
2502
2503 -nostdinc disables the last two search paths.
2504 \newline
2505
2506 \newline
2507 3.
2508  Library files
2509 \newline
2510
2511 \layout Standard
2512
2513 With the exception of
2514 \begin_inset Quotes sld
2515 \end_inset
2516
2517 -
2518 \begin_inset ERT
2519 status Collapsed
2520
2521 \layout Standard
2522
2523 \backslash
2524 /
2525 \end_inset
2526
2527 -L dir
2528 \begin_inset Quotes srd
2529 \end_inset
2530
2531  the
2532 \shape italic
2533 model
2534 \shape default
2535  is auto-appended by the compiler (e.g.
2536  small, large, z80, ds390 etc.).
2537
2538 \newline
2539
2540 \layout Standard
2541 \align center
2542
2543 \begin_inset  Tabular
2544 <lyxtabular version="3" rows="6" columns="3">
2545 <features>
2546 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2547 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2548 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2549 <row topline="true" bottomline="true">
2550 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2551 \begin_inset Text
2552
2553 \layout Standard
2554
2555 Search path
2556 \end_inset
2557 </cell>
2558 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2559 \begin_inset Text
2560
2561 \layout Standard
2562
2563 default
2564 \end_inset
2565 </cell>
2566 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2567 \begin_inset Text
2568
2569 \layout Standard
2570
2571 Win32 builds
2572 \end_inset
2573 </cell>
2574 </row>
2575 <row topline="true">
2576 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2577 \begin_inset Text
2578
2579 \layout Standard
2580
2581 -
2582 \begin_inset ERT
2583 status Collapsed
2584
2585 \layout Standard
2586
2587 \backslash
2588 /
2589 \end_inset
2590
2591 -L dir
2592 \end_inset
2593 </cell>
2594 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2595 \begin_inset Text
2596
2597 \layout Standard
2598
2599 -
2600 \begin_inset ERT
2601 status Collapsed
2602
2603 \layout Standard
2604
2605 \backslash
2606 /
2607 \end_inset
2608
2609 -L dir
2610 \end_inset
2611 </cell>
2612 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2613 \begin_inset Text
2614
2615 \layout Standard
2616
2617 -
2618 \begin_inset ERT
2619 status Collapsed
2620
2621 \layout Standard
2622
2623 \backslash
2624 /
2625 \end_inset
2626
2627 -L dir
2628 \end_inset
2629 </cell>
2630 </row>
2631 <row topline="true">
2632 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2633 \begin_inset Text
2634
2635 \layout Standard
2636
2637 $SDCC_LIB/
2638 \newline
2639
2640 \emph on
2641 <model>
2642 \end_inset
2643 </cell>
2644 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2645 \begin_inset Text
2646
2647 \layout Standard
2648
2649 $SDCC_LIB/
2650 \newline
2651
2652 \emph on
2653 <model>
2654 \end_inset
2655 </cell>
2656 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2657 \begin_inset Text
2658
2659 \layout Standard
2660
2661 $SDCC_LIB
2662 \backslash
2663
2664 \newline
2665
2666 \emph on
2667 <model>
2668 \end_inset
2669 </cell>
2670 </row>
2671 <row topline="true">
2672 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2673 \begin_inset Text
2674
2675 \layout Standard
2676
2677 $SDCC_HOME/
2678 \newline
2679
2680 \emph on
2681 $PREFIX2DATA_DIR/
2682 \newline
2683 $LIB_DIR_SUFFIX/<model>
2684 \end_inset
2685 </cell>
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 share/sdcc/
2694 \newline
2695 lib/
2696 \emph on
2697 <model>
2698 \end_inset
2699 </cell>
2700 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2701 \begin_inset Text
2702
2703 \layout Standard
2704
2705 $SDCC_HOME
2706 \backslash
2707 lib
2708 \backslash
2709
2710 \emph on
2711
2712 \newline
2713 <model>
2714 \end_inset
2715 </cell>
2716 </row>
2717 <row topline="true">
2718 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2719 \begin_inset Text
2720
2721 \layout Standard
2722
2723 path(argv[0])/
2724 \newline
2725
2726 \emph on
2727 $BIN2DATADIR/
2728 \emph default
2729
2730 \newline
2731
2732 \emph on
2733 $LIB_DIR_SUFFIX/<model>
2734 \end_inset
2735 </cell>
2736 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2737 \begin_inset Text
2738
2739 \layout Standard
2740
2741 path(argv[0])/
2742 \newline
2743 ../sdcc/lib/
2744 \emph on
2745 <model>
2746 \newline
2747 \SpecialChar ~
2748 \SpecialChar ~
2749 \SpecialChar ~
2750 \SpecialChar ~
2751 \SpecialChar ~
2752 \SpecialChar ~
2753 \SpecialChar ~
2754 \SpecialChar ~
2755 \SpecialChar ~
2756 \SpecialChar ~
2757 \SpecialChar ~
2758 \SpecialChar ~
2759 \SpecialChar ~
2760 \SpecialChar ~
2761 \SpecialChar ~
2762 \SpecialChar ~
2763 \SpecialChar ~
2764 \SpecialChar ~
2765 \SpecialChar ~
2766 \SpecialChar ~
2767 \SpecialChar ~
2768 \SpecialChar ~
2769 \SpecialChar ~
2770 \SpecialChar ~
2771 \SpecialChar ~
2772 \SpecialChar ~
2773 \SpecialChar ~
2774 \SpecialChar ~
2775 \SpecialChar ~
2776 \SpecialChar ~
2777 \SpecialChar ~
2778 \SpecialChar ~
2779 \SpecialChar ~
2780 \SpecialChar ~
2781 \SpecialChar ~
2782 \SpecialChar ~
2783 \SpecialChar ~
2784 \SpecialChar ~
2785 \SpecialChar ~
2786
2787 \end_inset
2788 </cell>
2789 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2790 \begin_inset Text
2791
2792 \layout Standard
2793
2794 path(argv[0])
2795 \backslash
2796
2797 \newline
2798 ..
2799 \backslash
2800 lib
2801 \backslash
2802
2803 \emph on
2804 <model>
2805 \newline
2806 \SpecialChar ~
2807 \SpecialChar ~
2808 \SpecialChar ~
2809 \SpecialChar ~
2810 \SpecialChar ~
2811 \SpecialChar ~
2812 \SpecialChar ~
2813 \SpecialChar ~
2814 \SpecialChar ~
2815 \SpecialChar ~
2816 \SpecialChar ~
2817 \SpecialChar ~
2818 \SpecialChar ~
2819 \SpecialChar ~
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
2842 \end_inset
2843 </cell>
2844 </row>
2845 <row topline="true" bottomline="true">
2846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2847 \begin_inset Text
2848
2849 \layout Standard
2850
2851
2852 \emph on
2853 $DATADIR/
2854 \newline
2855 $LIB_DIR_SUFFIX/<model>
2856 \end_inset
2857 </cell>
2858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2859 \begin_inset Text
2860
2861 \layout Standard
2862
2863 /usr/local/share/sdcc/
2864 \newline
2865 lib/
2866 \emph on
2867 <model>
2868 \end_inset
2869 </cell>
2870 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2871 \begin_inset Text
2872
2873 \layout Standard
2874
2875 (not on Win32)
2876 \end_inset
2877 </cell>
2878 </row>
2879 </lyxtabular>
2880
2881 \end_inset
2882
2883
2884 \newline
2885
2886 \layout Comment
2887
2888 Don't delete any of the stray spaces in the table above without checking
2889  the HTML output (last line)!
2890 \layout Standard
2891
2892 \SpecialChar ~
2893
2894 \newline
2895 The option -
2896 \begin_inset ERT
2897 status Collapsed
2898
2899 \layout Standard
2900
2901 \backslash
2902 /
2903 \end_inset
2904
2905 -nostdlib disables the last two search paths.
2906 \layout Section
2907
2908 Building SDCC
2909 \begin_inset LatexCommand \index{Building SDCC}
2910
2911 \end_inset
2912
2913
2914 \layout Subsection
2915
2916 Building SDCC on Linux
2917 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2918
2919 \end_inset
2920
2921
2922 \layout Enumerate
2923
2924
2925 \series medium
2926 Download the source package
2927 \series default
2928  either from the SDCC Subversion repository or from the nightly snapshots
2929 \series medium
2930 , it will be named something like sdcc
2931 \series default
2932 .src
2933 \series medium
2934 .t
2935 \series default
2936 ar.
2937 \series medium
2938 gz
2939 \series default
2940
2941 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2942
2943 \end_inset
2944
2945 .
2946 \layout Enumerate
2947
2948
2949 \series medium
2950 Bring up a command line terminal, such as xterm.
2951 \layout Enumerate
2952
2953
2954 \series medium
2955 Unpack the file using a command like:
2956 \family sans
2957 \series bold
2958 "tar -xvzf sdcc.src.tar.gz
2959 \family default
2960 \series default
2961 "
2962 \series medium
2963 , this will create a sub-directory called sdcc with all of the sources.
2964 \layout Enumerate
2965
2966 Change directory into the main SDCC directory, for example type:
2967 \family sans
2968 \series bold
2969 "cd sdcc
2970 \series default
2971 ".
2972 \layout Enumerate
2973
2974
2975 \series medium
2976 Type
2977 \family sans
2978 \series bold
2979 "./configure
2980 \family default
2981 \series default
2982 ".
2983  This configures the package for compilation on your system.
2984 \layout Enumerate
2985
2986
2987 \series medium
2988 Type
2989 \family sans
2990 \series bold
2991 "make
2992 \family default
2993 \series default
2994 "
2995 \series medium
2996 .
2997
2998 \series default
2999  All of the source packages will compile, this can take a while.
3000 \layout Enumerate
3001
3002
3003 \series medium
3004 Type
3005 \family sans
3006 \series bold
3007 "make install"
3008 \family default
3009 \series default
3010  as root
3011 \series medium
3012 .
3013
3014 \series default
3015  This copies the binary executables, the include files, the libraries and
3016  the documentation to the install directories.
3017  Proceed with section
3018 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
3019
3020 \end_inset
3021
3022 .
3023 \layout Subsection
3024
3025 Building SDCC on OSX 2.x
3026 \layout Standard
3027
3028 Follow the instruction for Linux.
3029 \newline
3030
3031 \newline
3032 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
3033 )) fails to compile SDCC.
3034  Fortunately there's also gcc 2.9.x installed, which works fine.
3035  This compiler can be selected by running 'configure' with:
3036 \layout LyX-Code
3037
3038 ./configure CC=gcc2 CXX=g++2
3039 \layout Subsection
3040
3041 Cross compiling SDCC on Linux for Windows
3042 \layout Standard
3043
3044 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
3045  See section 'Configure Options'.
3046 \layout Subsection
3047
3048 Building SDCC on Windows
3049 \layout Standard
3050
3051 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
3052  built on Windows.
3053  They use Unix-sockets, which are not available on Win32.
3054 \layout Subsection
3055
3056 Building SDCC using Cygwin and Mingw32
3057 \layout Standard
3058
3059 For building and installing a Cygwin executable follow the instructions
3060  for Linux.
3061 \newline
3062
3063 \newline
3064 On Cygwin a
3065 \begin_inset Quotes sld
3066 \end_inset
3067
3068 native
3069 \begin_inset Quotes srd
3070 \end_inset
3071
3072  Win32-binary can be built, which will not need the Cygwin-DLL.
3073  For the necessary 'configure' options see section 'configure options' or
3074  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3075 \newline
3076
3077 \newline
3078 In order to install Cygwin on Windows download setup.exe from
3079 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3080
3081 \end_inset
3082
3083 .
3084  Run it, set the
3085 \begin_inset Quotes sld
3086 \end_inset
3087
3088 default text file type
3089 \begin_inset Quotes srd
3090 \end_inset
3091
3092  to
3093 \begin_inset Quotes sld
3094 \end_inset
3095
3096 unix
3097 \begin_inset Quotes srd
3098 \end_inset
3099
3100  and download/install at least the following packages.
3101  Some packages are selected by default, others will be automatically selected
3102  because of dependencies with the manually selected packages.
3103  Never deselect these packages!
3104 \layout Itemize
3105
3106 flex
3107 \layout Itemize
3108
3109 bison
3110 \layout Itemize
3111
3112 gcc ; version 3.x is fine, no need to use the old 2.9x
3113 \layout Itemize
3114
3115 binutils ; selected with gcc
3116 \layout Itemize
3117
3118 make
3119 \layout Itemize
3120
3121 rxvt ; a nice console, which makes life much easier under windoze (see below)
3122 \layout Itemize
3123
3124 man ; not really needed for building SDCC, but you'll miss it sooner or
3125  later
3126 \layout Itemize
3127
3128 less ; not really needed for building SDCC, but you'll miss it sooner or
3129  later
3130 \layout Itemize
3131
3132 svn ; only if you use Subversion access
3133 \layout Standard
3134
3135 If you want to develop something you'll need:
3136 \layout Itemize
3137
3138 python ; for the regression tests
3139 \layout Itemize
3140
3141 gdb ; the gnu debugger, together with the nice GUI
3142 \begin_inset Quotes sld
3143 \end_inset
3144
3145 insight
3146 \begin_inset Quotes srd
3147 \end_inset
3148
3149
3150 \layout Itemize
3151
3152 openssh ; to access the CF or commit changes
3153 \layout Itemize
3154
3155 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3156  use autoconf-stable!
3157 \layout Standard
3158
3159 rxvt is a nice console with history.
3160  Replace in your cygwin.bat the line
3161 \layout LyX-Code
3162
3163 bash -
3164 \begin_inset ERT
3165 status Collapsed
3166
3167 \layout Standard
3168
3169 \backslash
3170 /
3171 \end_inset
3172
3173 -login -i
3174 \layout Standard
3175
3176 with (one line):
3177 \layout LyX-Code
3178
3179 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3180 \layout LyX-Code
3181
3182      -bg black -fg white -geometry 100x65 -e bash -
3183 \begin_inset ERT
3184 status Collapsed
3185
3186 \layout Standard
3187
3188 \backslash
3189 /
3190 \end_inset
3191
3192 -login
3193 \layout Standard
3194
3195 Text selected with the mouse is automatically copied to the clipboard, pasting
3196  works with shift-insert.
3197 \newline
3198
3199 \newline
3200 The other good tip is to make sure you have no //c/-style paths anywhere,
3201  use /cygdrive/c/ instead.
3202  Using // invokes a network lookup which is very slow.
3203  If you think
3204 \begin_inset Quotes sld
3205 \end_inset
3206
3207 cygdrive
3208 \begin_inset Quotes srd
3209 \end_inset
3210
3211  is too long, you can change it with e.g.
3212 \layout LyX-Code
3213
3214 mount -s -u -c /mnt
3215 \layout Standard
3216
3217 SDCC sources use the unix line ending LF.
3218  Life is much easier, if you store the source tree on a drive which is mounted
3219  in binary mode.
3220  And use an editor which can handle LF-only line endings.
3221  Make sure not to commit files with windows line endings.
3222  The tabulator spacing
3223 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3224
3225 \end_inset
3226
3227  used in the project is 8.
3228  Although a tabulator spacing of 8 is a sensible choice for programmers
3229  (it's a power of 2 and allows to display 8/16 bit signed variables without
3230  loosing columns) the plan is to move towards using only spaces in the source.
3231 \layout Subsection
3232
3233 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3234 \layout Standard
3235
3236
3237 \series medium
3238 Download the source package
3239 \series default
3240  either from the SDCC Subversion repository or from the
3241 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3242
3243 \end_inset
3244
3245
3246 \series medium
3247 , it will be named something like sdcc
3248 \series default
3249 .src
3250 \series medium
3251 .tgz.
3252
3253 \series default
3254  SDCC is distributed with all the projects, workspaces, and files you need
3255  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3256  doesn't build under MSVC).
3257  The workspace name is 'sdcc.dsw'.
3258  Please note that as it is now, all the executables are created in a folder
3259  called sdcc
3260 \backslash
3261 bin_vc.
3262  Once built you need to copy the executables from sdcc
3263 \backslash
3264 bin_vc to sdcc
3265 \backslash
3266 bin before running SDCC.
3267
3268 \newline
3269
3270 \newline
3271 WARNING: Visual studio is very picky with line terminations; it expects
3272  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3273  When using the Subversion repository it's easiest to configure the svn
3274  client to convert automatically for you.
3275  If however you are getting a message such as "This makefile was not generated
3276  by Developer Studio etc.
3277  etc.
3278 \begin_inset Quotes srd
3279 \end_inset
3280
3281  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3282  need to convert the Unix style line endings to DOS style line endings.
3283  To do so you can use the
3284 \begin_inset Quotes sld
3285 \end_inset
3286
3287 unix2dos
3288 \begin_inset Quotes srd
3289 \end_inset
3290
3291  utility freely available on the internet.
3292  Doug Hawkins reported in the sdcc-user list that this works:
3293 \newline
3294
3295 \newline
3296 C:
3297 \backslash
3298 Programming
3299 \backslash
3300 SDCC> unix2dos sdcc.dsw
3301 \newline
3302 C:
3303 \backslash
3304 Programming
3305 \backslash
3306 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3307 \newline
3308
3309 \newline
3310 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3311  flex.exe, and gawk.exe.
3312  One good place to get them is
3313 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3314
3315 \end_inset
3316
3317
3318 \newline
3319
3320 \newline
3321 Download the file UnxUtils
3322 \begin_inset LatexCommand \index{UnxUtils}
3323
3324 \end_inset
3325
3326 .zip.
3327  Now you have to install the utilities and setup MSVC so it can locate the
3328  required programs.
3329  Here there are two alternatives (choose one!):
3330 \layout Enumerate
3331
3332 The easy way:
3333 \newline
3334
3335 \newline
3336 a) Extract UnxUtils.zip to your C:
3337 \backslash
3338  hard disk PRESERVING the original paths, otherwise bison won't work.
3339  (If you are using WinZip make certain that 'Use folder names' is selected)
3340 \newline
3341
3342 \newline
3343 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3344  in 'Show directories for:' select 'Executable files', and in the directories
3345  window add a new path: 'C:
3346 \backslash
3347 user
3348 \backslash
3349 local
3350 \backslash
3351 wbin', click ok.
3352 \newline
3353
3354 \newline
3355 (As a side effect, you get a bunch of Unix utilities that could be useful,
3356  such as diff and patch.)
3357 \layout Enumerate
3358
3359 A more compact way:
3360 \newline
3361
3362 \newline
3363 This one avoids extracting a bunch of files you may not use, but requires
3364  some extra work:
3365 \newline
3366
3367 \newline
3368 a) Create a directory were to put the tools needed, or use a directory already
3369  present.
3370  Say for example 'C:
3371 \backslash
3372 util'.
3373 \newline
3374
3375 \newline
3376 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3377  to such directory WITHOUT preserving the original paths.
3378  (If you are using WinZip make certain that 'Use folder names' is not selected)
3379 \newline
3380
3381 \newline
3382 c) Rename bison.exe to '_bison.exe'.
3383 \newline
3384
3385 \newline
3386 d) Create a batch file 'bison.bat' in 'C:
3387 \backslash
3388 util
3389 \backslash
3390 ' and add these lines:
3391 \newline
3392 \SpecialChar ~
3393 \SpecialChar ~
3394 set BISON_SIMPLE=C:
3395 \backslash
3396 util
3397 \backslash
3398 bison.simple
3399 \newline
3400 \SpecialChar ~
3401 \SpecialChar ~
3402 set BISON_HAIRY=C:
3403 \backslash
3404 util
3405 \backslash
3406 bison.hairy
3407 \newline
3408 \SpecialChar ~
3409 \SpecialChar ~
3410 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3411 \newline
3412
3413 \newline
3414 Steps 'c' and 'd' are needed because bison requires by default that the
3415  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3416  '/usr/local/share/' I think.
3417  So it is necessary to tell bison where those files are located if they
3418  are not in such directory.
3419  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3420 \newline
3421
3422 \newline
3423 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3424  in 'Show directories for:' select 'Executable files', and in the directories
3425  window add a new path: 'c:
3426 \backslash
3427 util', click ok.
3428  Note that you can use any other path instead of 'c:
3429 \backslash
3430 util', even the path where the Visual C++ tools are, probably: 'C:
3431 \backslash
3432 Program Files
3433 \backslash
3434 Microsoft Visual Studio
3435 \backslash
3436 Common
3437 \backslash
3438 Tools'.
3439  So you don't have to execute step 'e' :)
3440 \layout Standard
3441
3442 That is it.
3443  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3444  the executables from sdcc
3445 \backslash
3446 bin_vc to sdcc
3447 \backslash
3448 bin, and you can compile using SDCC.
3449 \layout Subsection
3450
3451 Building SDCC Using Borland
3452 \layout Enumerate
3453
3454 From the sdcc directory, run the command "make -f Makefile.bcc".
3455  This should regenerate all the .exe files in the bin directory except for
3456  sdcdb.exe (which currently doesn't build under Borland C++).
3457 \layout Enumerate
3458
3459 If you modify any source files and need to rebuild, be aware that the dependenci
3460 es may not be correctly calculated.
3461  The safest option is to delete all .obj files and run the build again.
3462  From a Cygwin BASH prompt, this can easily be done with the command (be
3463  sure you are in the sdcc directory):
3464 \newline
3465
3466 \newline
3467
3468 \family sans
3469 \series bold
3470 find .
3471
3472 \backslash
3473 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3474 \backslash
3475 ) -print -exec rm {}
3476 \backslash
3477 ;
3478 \family default
3479 \series default
3480
3481 \newline
3482
3483 \newline
3484 or on Windows NT/2000/XP from the command prompt with the command:
3485 \newline
3486
3487 \family sans
3488 \series bold
3489
3490 \newline
3491 del /s *.obj *.lib *.rul
3492 \family default
3493 \series default
3494  from the sdcc directory.
3495 \layout Subsection
3496
3497 Windows Install Using a ZIP Package
3498 \layout Enumerate
3499
3500 Download the binary zip package from
3501 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3502
3503 \end_inset
3504
3505  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3506  This should unpack to a group of sub-directories.
3507  An example directory structure after unpacking the mingw32 package is:
3508  c:
3509 \backslash
3510 sdcc
3511 \backslash
3512 bin for the executables, c:
3513 \backslash
3514 sdcc
3515 \backslash
3516 include and c:
3517 \backslash
3518 sdcc
3519 \backslash
3520 lib for the include and libraries.
3521 \layout Enumerate
3522
3523 Adjust your environment variable PATH to include the location of the bin
3524  directory or start sdcc using the full path.
3525 \layout Subsection
3526
3527 Windows Install Using the Setup Program
3528 \begin_inset LatexCommand \label{sub:Windows-Install}
3529
3530 \end_inset
3531
3532
3533 \layout Standard
3534
3535 Download the setup program
3536 \emph on
3537 sdcc-x.y.z-setup.exe
3538 \emph default
3539  for an official release from
3540 \newline
3541
3542 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3543
3544 \end_inset
3545
3546  or a setup program for one of the snapshots
3547 \emph on
3548 sdcc_yyyymmdd_setup.exe
3549 \emph default
3550  from
3551 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3552
3553 \end_inset
3554
3555  and execute it.
3556  A windows typical installer will guide you through the installation process.
3557 \layout Section
3558
3559 Building the Documentation
3560 \layout Standard
3561
3562 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3563  as changing into the doc directory and typing
3564 \family sans
3565 \series bold
3566
3567 \begin_inset Quotes srd
3568 \end_inset
3569
3570 make
3571 \begin_inset Quotes srd
3572 \end_inset
3573
3574
3575 \family default
3576 \series default
3577  there.
3578  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3579 x).
3580  Using LyX
3581 \begin_inset LatexCommand \url{http://www.lyx.org}
3582
3583 \end_inset
3584
3585  as editor this is straightforward.
3586  Prebuilt documentation in html and pdf format is available from
3587 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3588
3589 \end_inset
3590
3591 .
3592 \layout Section
3593
3594 Reading the Documentation
3595 \layout Standard
3596
3597 Currently reading the document in pdf format is recommended, as for unknown
3598  reason the hyperlinks are working there whereas in the html version they
3599  are not
3600 \begin_inset Foot
3601 collapsed false
3602
3603 \layout Standard
3604
3605 If you should know why please drop us a note
3606 \end_inset
3607
3608 .
3609
3610 \newline
3611 You'll find the pdf version
3612 \begin_inset LatexCommand \index{PDF version of this document}
3613
3614 \end_inset
3615
3616  at
3617 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
3618
3619 \end_inset
3620
3621 .
3622
3623 \newline
3624 A html version
3625 \begin_inset LatexCommand \index{HTML version of this document}
3626
3627 \end_inset
3628
3629  should be online at
3630 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
3631
3632 \end_inset
3633
3634 .
3635 \newline
3636 This documentation is in some aspects different from a commercial documentation:
3637
3638 \layout Itemize
3639
3640 It tries to document SDCC for several processor architectures in one document
3641  (commercially these probably would be separate documents/products).
3642  This document
3643 \begin_inset LatexCommand \index{Status of documentation}
3644
3645 \end_inset
3646
3647  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3648 on about f.e.
3649  Z80, PIC14, PIC16 and HC08.
3650 \layout Itemize
3651
3652 There are many references pointing away from this documentation.
3653  Don't let this distract you.
3654  If there f.e.
3655  was a reference like
3656 \begin_inset LatexCommand \url{http://www.opencores.org}
3657
3658 \end_inset
3659
3660  together with a statement
3661 \begin_inset Quotes sld
3662 \end_inset
3663
3664 some processors which are targetted by SDCC can be implemented in a
3665 \emph on
3666 f
3667 \emph default
3668 ield
3669 \emph on
3670 p
3671 \emph default
3672 rogrammable
3673 \emph on
3674 g
3675 \emph default
3676 ate
3677 \emph on
3678 a
3679 \emph default
3680 rray
3681 \begin_inset LatexCommand \index{FPGA (field programmable gate array)}
3682
3683 \end_inset
3684
3685
3686 \begin_inset Quotes srd
3687 \end_inset
3688
3689  or
3690 \begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
3691
3692 \end_inset
3693
3694
3695 \begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
3696
3697 \end_inset
3698
3699
3700 \begin_inset Quotes sld
3701 \end_inset
3702
3703 have you ever heard of an open source compiler that compiles a subset of
3704  C for an FPGA?
3705 \begin_inset Quotes srd
3706 \end_inset
3707
3708  we expect you to have a quick look there and come back.
3709  If you read this you are on the right track.
3710 \layout Itemize
3711
3712 Some sections attribute more space to problems, restrictions and warnings
3713  than to the solution.
3714 \layout Itemize
3715
3716 The installation section and the section about the debugger is intimidating.
3717 \layout Itemize
3718
3719 There are still lots of typos and there are more different writing styles
3720  than pictures.
3721 \layout Section
3722
3723 Testing the SDCC Compiler
3724 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3725
3726 \end_inset
3727
3728
3729 \layout Standard
3730
3731 The first thing you should do after installing your SDCC compiler is to
3732  see if it runs.
3733  Type
3734 \family sans
3735 \series bold
3736 "sdcc -
3737 \begin_inset ERT
3738 status Collapsed
3739
3740 \layout Standard
3741
3742 \backslash
3743 /
3744 \end_inset
3745
3746 -version"
3747 \begin_inset LatexCommand \index{version}
3748
3749 \end_inset
3750
3751
3752 \family default
3753 \series default
3754  at the prompt, and the program should run and tell you the version.
3755  If it doesn't run, or gives a message about not finding sdcc program, then
3756  you need to check over your installation.
3757  Make sure that the sdcc bin directory is in your executable search path
3758  defined by the PATH environment setting (
3759 \series medium
3760 see
3761 \series default
3762 section
3763 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3764
3765 \end_inset
3766
3767 \SpecialChar ~
3768
3769 \series medium
3770 Install trouble-shooting for suggestions
3771 \series default
3772 ).
3773  Make sure that the sdcc program is in the bin folder, if not perhaps something
3774  did not install correctly.
3775 \newline
3776
3777 \newline
3778
3779 \series medium
3780 SDCC
3781 \series default
3782 is commonly installed as described in section
3783 \begin_inset Quotes sld
3784 \end_inset
3785
3786 Install and search paths
3787 \begin_inset Quotes srd
3788 \end_inset
3789
3790 .
3791 \newline
3792
3793 \newline
3794
3795 \series medium
3796 Make sure the compiler works on a very simple example.
3797  Type in the following test.c program using your favorite
3798 \series default
3799 ASCII
3800 \series medium
3801 editor:
3802 \layout Verse
3803
3804
3805 \family typewriter
3806 char test;
3807 \newline
3808
3809 \newline
3810 void main(void) {
3811 \newline
3812 \SpecialChar ~
3813 \SpecialChar ~
3814 \SpecialChar ~
3815 \SpecialChar ~
3816 test=0;
3817 \newline
3818 }
3819 \layout Standard
3820
3821
3822 \series medium
3823 Compile this using the following command:
3824 \family sans
3825 \series bold
3826 "sdcc -c test.c".
3827
3828 \family default
3829 \series default
3830
3831 \series medium
3832 If all goes well, the compiler will generate a test.asm and test.rel file.
3833  Congratulations, you've just compiled your first program with SDCC.
3834  We used the -c option to tell SDCC not to link the generated code, just
3835  to keep things simple for this step.
3836 \series default
3837
3838 \newline
3839
3840 \newline
3841
3842 \series medium
3843 The next step is to try it with the linker.
3844  Type in
3845 \family sans
3846 \series bold
3847 "sdcc test.c
3848 \family default
3849 \series default
3850 "
3851 \series medium
3852 .
3853  If all goes well the compiler will link with the libraries and produce
3854  a test.ihx output file.
3855  If this step fails
3856 \series default
3857
3858 \series medium
3859 (no test.ihx, and the linker generates warnings), then the problem is most
3860  likely that
3861 \series default
3862 SDCC
3863 \series medium
3864  cannot find the
3865 \series default
3866 /
3867 \series medium
3868 usr/local/share/sdcc/lib directory
3869 \series default
3870
3871 \series medium
3872 (see
3873 \series default
3874 section
3875 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3876
3877 \end_inset
3878
3879 \SpecialChar ~
3880
3881 \series medium
3882 Install trouble-shooting for suggestions).
3883 \series default
3884
3885 \newline
3886
3887 \newline
3888
3889 \series medium
3890 The final test is to ensure
3891 \series default
3892 SDCC
3893 \series medium
3894  can use the
3895 \series default
3896 standard
3897 \series medium
3898  header files and libraries.
3899  Edit test.c and change it to the following:
3900 \layout Verse
3901
3902
3903 \family typewriter
3904 #include <string.h>
3905 \newline
3906
3907 \newline
3908 char str1[10];
3909 \newline
3910
3911 \newline
3912 void main(void) {
3913 \newline
3914 \SpecialChar ~
3915 \SpecialChar ~
3916 strcpy(str1, "testing");
3917 \newline
3918 }
3919 \layout Standard
3920
3921
3922 \series medium
3923 Compile this by typing
3924 \family sans
3925 \series bold
3926 "sdcc test.c"
3927 \family default
3928 \series medium
3929 .
3930  This should generate a test.ihx output file, and it should give no warnings
3931  such as not finding the string.h file.
3932  If it cannot find the string.h file, then the problem is that
3933 \series default
3934 SDCC
3935 \series medium
3936  cannot find the /usr/local/share/sdcc/include directory
3937 \series default
3938
3939 \series medium
3940 (see the
3941 \series default
3942 section
3943 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3944
3945 \end_inset
3946
3947 \SpecialChar ~
3948
3949 \series medium
3950 Install trouble-shooting section for suggestions).
3951
3952 \series default
3953  Use option
3954 \series bold
3955 -
3956 \begin_inset ERT
3957 status Collapsed
3958
3959 \layout Standard
3960
3961 \backslash
3962 /
3963 \end_inset
3964
3965 -print-search-dirs
3966 \series default
3967
3968 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3969
3970 \end_inset
3971
3972  to find exactly where SDCC is looking for the include and lib files.
3973 \layout Section
3974
3975 Install Trouble-shooting
3976 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3977
3978 \end_inset
3979
3980
3981 \begin_inset LatexCommand \index{Install trouble-shooting}
3982
3983 \end_inset
3984
3985
3986 \layout Subsection
3987
3988 If SDCC does not build correctly
3989 \layout Standard
3990
3991 A thing to try is starting from scratch by unpacking the .tgz source package
3992  again in an empty directory.
3993  Configure it like:
3994 \newline
3995
3996 \newline
3997
3998 \family sans
3999 \series bold
4000 ./configure 2>&1 | tee configure.log
4001 \family default
4002 \series default
4003
4004 \newline
4005
4006 \newline
4007 and build it like:
4008 \newline
4009
4010 \newline
4011
4012 \family sans
4013 \series bold
4014 make 2>&1 | tee make.log
4015 \family default
4016 \series default
4017
4018 \newline
4019
4020 \newline
4021 If anything goes wrong, you can review the log files to locate the problem.
4022  Or a relevant part of this can be attached to an email that could be helpful
4023  when requesting help from the mailing list.
4024 \layout Subsection
4025
4026 What the
4027 \begin_inset Quotes sld
4028 \end_inset
4029
4030 ./configure
4031 \begin_inset Quotes srd
4032 \end_inset
4033
4034  does
4035 \layout Standard
4036
4037 The
4038 \begin_inset Quotes sld
4039 \end_inset
4040
4041 ./configure
4042 \begin_inset Quotes srd
4043 \end_inset
4044
4045  command is a script that analyzes your system and performs some configuration
4046  to ensure the source package compiles on your system.
4047  It will take a few minutes to run, and will compile a few tests to determine
4048  what compiler features are installed.
4049 \layout Subsection
4050
4051 What the
4052 \begin_inset Quotes sld
4053 \end_inset
4054
4055 make
4056 \begin_inset Quotes srd
4057 \end_inset
4058
4059  does
4060 \layout Standard
4061
4062 This runs the GNU make tool, which automatically compiles all the source
4063  packages into the final installed binary executables.
4064 \layout Subsection
4065
4066 What the
4067 \begin_inset Quotes sld
4068 \end_inset
4069
4070 make install
4071 \begin_inset Quotes erd
4072 \end_inset
4073
4074  command does.
4075 \layout Standard
4076
4077 This will install the compiler, other executables libraries and include
4078  files into the appropriate directories.
4079  See sections
4080 \begin_inset LatexCommand \ref{sub:Install-paths}
4081
4082 \end_inset
4083
4084 ,\SpecialChar ~
4085
4086 \begin_inset LatexCommand \ref{sub:Search-Paths}
4087
4088 \end_inset
4089
4090 \SpecialChar ~
4091 about install and search paths.
4092 \newline
4093 On most systems you will need super-user privileges to do this.
4094 \layout Section
4095
4096 Components of SDCC
4097 \layout Standard
4098
4099 SDCC is not just a compiler, but a collection of tools by various developers.
4100  These include linkers, assemblers, simulators and other components.
4101  Here is a summary of some of the components.
4102  Note that the included simulator and assembler have separate documentation
4103  which you can find in the source package in their respective directories.
4104  As SDCC grows to include support for other processors, other packages from
4105  various developers are included and may have their own sets of documentation.
4106 \newline
4107
4108 \newline
4109 You might want to look at the files which are installed in <installdir>.
4110  At the time of this writing, we find the following programs for gcc-builds:
4111 \newline
4112
4113 \newline
4114 In <installdir>/bin:
4115 \layout Itemize
4116
4117 sdcc - The compiler.
4118 \layout Itemize
4119
4120 sdcpp - The C preprocessor.
4121 \layout Itemize
4122
4123 asx8051 - The assembler for 8051 type processors.
4124 \layout Itemize
4125
4126 as-z80
4127 \series bold
4128 ,
4129 \series default
4130 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4131 \layout Itemize
4132
4133 aslink -The linker for 8051 type processors.
4134 \layout Itemize
4135
4136 link-z80
4137 \series bold
4138 ,
4139 \series default
4140 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4141 \layout Itemize
4142
4143 s51 - The ucSim 8051 simulator.
4144  Not available on Win32 platforms.
4145 \layout Itemize
4146
4147 sdcdb - The source debugger.
4148  Not available on Win32 platforms.
4149 \layout Itemize
4150
4151 packihx - A tool to pack (compress) Intel hex files.
4152 \layout Standard
4153
4154 In <installdir>/share/sdcc/include
4155 \layout Itemize
4156
4157 the include files
4158 \layout Standard
4159
4160 In <installdir>/share/sdcc/lib
4161 \layout Itemize
4162
4163 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4164  relocatables.
4165 \layout Standard
4166
4167 In <installdir>/share/sdcc/doc
4168 \layout Itemize
4169
4170 the documentation
4171 \layout Standard
4172
4173 As development for other processors proceeds, this list will expand to include
4174  executables to support processors like AVR, PIC, etc.
4175 \layout Subsection
4176
4177 sdcc - The Compiler
4178 \layout Standard
4179
4180 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4181  the assembler and linkage editor.
4182 \layout Subsection
4183
4184 sdcpp - The C-Preprocessor
4185 \layout Standard
4186
4187 The preprocessor
4188 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4189
4190 \end_inset
4191
4192  is a modified version of the GNU preprocessor.
4193  The C preprocessor is used to pull in #include sources, process #ifdef
4194  statements, #defines and so on.
4195 \layout Subsection
4196
4197 as
4198 \emph on
4199 xxxx
4200 \emph default
4201 , aslink, link-
4202 \emph on
4203 xxx
4204 \emph default
4205  - The Assemblers and Linkage Editors
4206 \layout Standard
4207
4208 This is retargettable assembler & linkage editor, it was developed by Alan
4209  Baldwin.
4210  John Hartman created the version for 8051, and I (Sandeep) have made some
4211  enhancements and bug fixes for it to work properly with SDCC.
4212 \layout Subsection
4213
4214 s51 - The Simulator
4215 \layout Standard
4216
4217 S51
4218 \begin_inset LatexCommand \index{s51}
4219
4220 \end_inset
4221
4222  is a freeware, opensource simulator developed by Daniel Drotos.
4223  The simulator is built as part of the build process.
4224  For more information visit Daniel's web site at:
4225 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4226
4227 \end_inset
4228
4229 .
4230  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4231  XA51 family.
4232  S51 is currently not available on Win32 platfors.
4233 \layout Subsection
4234
4235 sdcdb - Source Level Debugger
4236 \layout Standard
4237
4238 Sdcdb
4239 \begin_inset LatexCommand \index{sdcdb (debugger)}
4240
4241 \end_inset
4242
4243  is the companion source level debugger.
4244  More about sdcdb in section
4245 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4246
4247 \end_inset
4248
4249 .
4250  The current version of the debugger uses Daniel's Simulator S51
4251 \begin_inset LatexCommand \index{s51}
4252
4253 \end_inset
4254
4255 , but can be easily changed to use other simulators.
4256  Sdcdb is currently not available on Win32 platfors.
4257 \layout Chapter
4258
4259 Using SDCC
4260 \layout Section
4261
4262 Compiling
4263 \layout Subsection
4264
4265 Single Source File Projects
4266 \layout Standard
4267
4268 For single source file 8051 projects the process is very simple.
4269  Compile your programs with the following command
4270 \family sans
4271 \series bold
4272 "sdcc sourcefile.c".
4273
4274 \family default
4275 \series default
4276  This will compile, assemble and link your source file.
4277  Output files are as follows:
4278 \layout Itemize
4279
4280 sourcefile.asm
4281 \begin_inset LatexCommand \index{<file>.asm}
4282
4283 \end_inset
4284
4285  - Assembler source
4286 \begin_inset LatexCommand \index{Assembler source}
4287
4288 \end_inset
4289
4290  file created by the compiler
4291 \layout Itemize
4292
4293 sourcefile.lst
4294 \begin_inset LatexCommand \index{<file>.lst}
4295
4296 \end_inset
4297
4298  - Assembler listing
4299 \begin_inset LatexCommand \index{Assembler listing}
4300
4301 \end_inset
4302
4303  file created by the Assembler
4304 \layout Itemize
4305
4306 sourcefile.rst
4307 \begin_inset LatexCommand \index{<file>.rst}
4308
4309 \end_inset
4310
4311  - Assembler listing
4312 \begin_inset LatexCommand \index{Assembler listing}
4313
4314 \end_inset
4315
4316  file updated with linkedit information, created by linkage editor
4317 \layout Itemize
4318
4319 sourcefile.sym
4320 \begin_inset LatexCommand \index{<file>.sym}
4321
4322 \end_inset
4323
4324  - symbol listing
4325 \begin_inset LatexCommand \index{Symbol listing}
4326
4327 \end_inset
4328
4329  for the sourcefile, created by the assembler
4330 \layout Itemize
4331
4332 sourcefile.rel
4333 \begin_inset LatexCommand \index{<file>.rel}
4334
4335 \end_inset
4336
4337  or sourcefile.o
4338 \begin_inset LatexCommand \index{<file>.o}
4339
4340 \end_inset
4341
4342  - Object file
4343 \begin_inset LatexCommand \index{Object file}
4344
4345 \end_inset
4346
4347  created by the assembler, input to Linkage editor
4348 \layout Itemize
4349
4350 sourcefile.map
4351 \begin_inset LatexCommand \index{<file>.map}
4352
4353 \end_inset
4354
4355  - The memory map
4356 \begin_inset LatexCommand \index{Memory map}
4357
4358 \end_inset
4359
4360  for the load module, created by the Linker
4361 \layout Itemize
4362
4363 sourcefile.mem
4364 \begin_inset LatexCommand \index{<file>.mem}
4365
4366 \end_inset
4367
4368  - A file with a summary of the memory usage
4369 \layout Itemize
4370
4371 sourcefile.ihx
4372 \begin_inset LatexCommand \index{<file>.ihx}
4373
4374 \end_inset
4375
4376  - The load module in Intel hex format
4377 \begin_inset LatexCommand \index{Intel hex format}
4378
4379 \end_inset
4380
4381  (you can select the Motorola S19 format
4382 \begin_inset LatexCommand \index{Motorola S19 format}
4383
4384 \end_inset
4385
4386  with -
4387 \begin_inset ERT
4388 status Collapsed
4389
4390 \layout Standard
4391
4392 \backslash
4393 /
4394 \end_inset
4395
4396 -out-fmt-s19
4397 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4398
4399 \end_inset
4400
4401 .
4402  If you need another format you might want to use
4403 \family sans
4404 \shape italic
4405 objdump
4406 \family default
4407 \shape default
4408
4409 \begin_inset LatexCommand \index{objdump (tool)}
4410
4411 \end_inset
4412
4413  or
4414 \family sans
4415 \shape italic
4416  srecord
4417 \family default
4418 \shape default
4419
4420 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4421
4422 \end_inset
4423
4424 ).
4425  Both formats are documented in the documentation of srecord
4426 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4427
4428 \end_inset
4429
4430
4431 \layout Itemize
4432
4433 sourcefile.adb
4434 \begin_inset LatexCommand \index{<file>.adb}
4435
4436 \end_inset
4437
4438  - An intermediate file containing debug information needed to create the
4439  .cdb file (with -
4440 \begin_inset ERT
4441 status Open
4442
4443 \layout Standard
4444
4445 \backslash
4446 /
4447 \end_inset
4448
4449 -debug
4450 \begin_inset LatexCommand \index{-\/-debug}
4451
4452 \end_inset
4453
4454 )
4455 \layout Itemize
4456
4457 sourcefile.cdb
4458 \begin_inset LatexCommand \index{<file>.cdb}
4459
4460 \end_inset
4461
4462  - An optional file (with -
4463 \begin_inset ERT
4464 status Collapsed
4465
4466 \layout Standard
4467
4468 \backslash
4469 /
4470 \end_inset
4471
4472 -debug) containing debug information.
4473  The format is documented in cdbfileformat.pdf
4474 \layout Itemize
4475
4476 sourcefile.
4477  - (no extension)
4478 \begin_inset LatexCommand \index{<file> (no extension)}
4479
4480 \end_inset
4481
4482  An optional AOMF or AOMF51
4483 \begin_inset LatexCommand \index{AOMF, AOMF51}
4484
4485 \end_inset
4486
4487  file containing debug information (generated with option -
4488 \begin_inset ERT
4489 status Collapsed
4490
4491 \layout Standard
4492
4493 \backslash
4494 /
4495 \end_inset
4496
4497 -debug).
4498  The (Intel)
4499 \emph on
4500  a
4501 \emph default
4502 bsolute
4503 \emph on
4504 o
4505 \emph default
4506 bject
4507 \emph on
4508 m
4509 \emph default
4510 odule
4511 \emph on
4512 f
4513 \emph default
4514 ormat is commonly used by third party tools (debuggers
4515 \begin_inset LatexCommand \index{Debugger}
4516
4517 \end_inset
4518
4519 , simulators, emulators)
4520 \layout Itemize
4521
4522 sourcefile.dump*
4523 \begin_inset LatexCommand \index{<file>.dump*}
4524
4525 \end_inset
4526
4527  - Dump file to debug the compiler it self (generated with option -
4528 \begin_inset ERT
4529 status Collapsed
4530
4531 \layout Standard
4532
4533 \backslash
4534 /
4535 \end_inset
4536
4537 -dumpall) (see section
4538 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4539
4540 \end_inset
4541
4542 \SpecialChar ~
4543  and section
4544 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4545
4546 \end_inset
4547
4548 \SpecialChar ~
4549
4550 \begin_inset Quotes sld
4551 \end_inset
4552
4553 Anatomy of the compiler
4554 \begin_inset Quotes srd
4555 \end_inset
4556
4557 ).
4558 \layout Subsection
4559
4560 Projects with Multiple Source Files
4561 \layout Standard
4562
4563 SDCC can compile only ONE file at a time.
4564  Let us for example assume that you have a project containing the following
4565  files:
4566 \newline
4567
4568 \newline
4569 foo1.c (contains some functions)
4570 \newline
4571 foo2.c (contains some more functions)
4572 \newline
4573 foomain.c (contains more functions and the function main)
4574 \newline
4575
4576 \size footnotesize
4577
4578 \newline
4579
4580 \size default
4581 The first two files will need to be compiled separately with the commands:
4582 \size footnotesize
4583
4584 \size default
4585
4586 \newline
4587
4588 \newline
4589
4590 \family sans
4591 \series bold
4592 sdcc\SpecialChar ~
4593 -c\SpecialChar ~
4594 foo1.c
4595 \family default
4596 \series default
4597 \size footnotesize
4598
4599 \newline
4600
4601 \family sans
4602 \series bold
4603 \size default
4604 sdcc\SpecialChar ~
4605 -c\SpecialChar ~
4606 foo2.c
4607 \family default
4608 \series default
4609
4610 \newline
4611
4612 \newline
4613 Then compile the source file containing the
4614 \emph on
4615 main()
4616 \emph default
4617  function and link
4618 \begin_inset LatexCommand \index{Linker}
4619
4620 \end_inset
4621
4622  the files together with the following command:
4623 \newline
4624
4625 \newline
4626
4627 \family sans
4628 \series bold
4629 sdcc\SpecialChar ~
4630 foomain.c\SpecialChar ~
4631 foo1.rel\SpecialChar ~
4632 foo2.rel
4633 \family default
4634 \series default
4635
4636 \begin_inset LatexCommand \index{<file>.rel}
4637
4638 \end_inset
4639
4640
4641 \newline
4642
4643 \newline
4644 Alternatively,
4645 \emph on
4646 foomain.c
4647 \emph default
4648 can be separately compiled as well:
4649 \family sans
4650 \series bold
4651
4652 \newline
4653
4654 \newline
4655 sdcc\SpecialChar ~
4656 -c\SpecialChar ~
4657 foomain.c
4658 \newline
4659 sdcc foomain.rel foo1.rel foo2.rel
4660 \newline
4661
4662 \newline
4663
4664 \family default
4665 \series default
4666 The file containing the
4667 \emph on
4668 main()
4669 \emph default
4670  function
4671 \emph on
4672
4673 \emph default
4674 \noun on
4675 must
4676 \noun default
4677  be the
4678 \noun on
4679 first
4680 \noun default
4681  file specified in the command line, since the linkage editor processes
4682  file in the order they are presented to it.
4683  The linker is invoked from SDCC using a script file with extension .lnk
4684 \begin_inset LatexCommand \index{<file>.lnk}
4685
4686 \end_inset
4687
4688 .
4689  You can view this file to troubleshoot linking problems such as those arising
4690  from missing libraries.
4691 \layout Subsection
4692
4693 Projects with Additional Libraries
4694 \begin_inset LatexCommand \index{Libraries}
4695
4696 \end_inset
4697
4698
4699 \layout Standard
4700
4701 Some reusable routines may be compiled into a library, see the documentation
4702  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4703  for how to create a
4704 \emph on
4705 .lib
4706 \begin_inset LatexCommand \index{<file>.lib}
4707
4708 \end_inset
4709
4710
4711 \emph default
4712  library file.
4713  Libraries created in this manner can be included in the command line.
4714  Make sure you include the -L <library-path> option to tell the linker where
4715  to look for these files if they are not in the current directory.
4716  Here is an example, assuming you have the source file
4717 \emph on
4718 foomain.c
4719 \emph default
4720  and a library
4721 \emph on
4722  foolib.lib
4723 \emph default
4724  in the directory
4725 \emph on
4726 mylib
4727 \emph default
4728  (if that is not the same as your current project):
4729 \newline
4730
4731 \newline
4732
4733 \family sans
4734 \series bold
4735 sdcc foomain.c foolib.lib -L mylib
4736 \newline
4737
4738 \newline
4739
4740 \family default
4741 \series default
4742 Note here that
4743 \emph on
4744  mylib
4745 \emph default
4746  must be an absolute path name.
4747 \newline
4748
4749 \newline
4750 The most efficient way to use libraries is to keep separate modules in separate
4751  source files.
4752  The lib file now should name all the modules.rel
4753 \begin_inset LatexCommand \index{<file>.rel}
4754
4755 \end_inset
4756
4757  files.
4758  For an example see the standard library file
4759 \emph on
4760 libsdcc.lib
4761 \emph default
4762  in the directory <installdir>/share/lib/small.
4763 \layout Subsection
4764
4765 Using sdcclib to Create and Manage Libraries
4766 \begin_inset LatexCommand \index{sdcclib}
4767
4768 \end_inset
4769
4770
4771 \layout Standard
4772
4773 Alternatively, instead of having a .rel file for each entry on the library
4774  file as described in the preceding section, sdcclib can be used to embed
4775  all the modules belonging to such library in the library file itself.
4776  This results in a larger library file, but it greatly reduces the number
4777  of disk files accessed by the linker.
4778   Additionally, the packed library file contains an index of all include
4779  modules and symbols that significantly speeds up the linking process.
4780  To display a list of options supported by sdcclib type:
4781 \newline
4782
4783 \layout Standard
4784
4785
4786 \family sans
4787 \series bold
4788 sdcclib -?
4789 \begin_inset LatexCommand \index{sdcclib}
4790
4791 \end_inset
4792
4793
4794 \newline
4795
4796 \newline
4797
4798 \family default
4799 \series default
4800 To create a new library file, start by compiling all the required modules.
4801  For example:
4802 \newline
4803
4804 \layout Standard
4805
4806
4807 \family sans
4808 \series bold
4809 sdcc -c _divsint.c
4810 \layout Standard
4811
4812
4813 \family sans
4814 \series bold
4815 sdcc -c _divuint.c
4816 \layout Standard
4817
4818
4819 \family sans
4820 \series bold
4821 sdcc -c _modsint.c
4822 \layout Standard
4823
4824
4825 \family sans
4826 \series bold
4827 sdcc -c _moduint.c
4828 \layout Standard
4829
4830
4831 \family sans
4832 \series bold
4833 sdcc -c _mulint.c
4834 \newline
4835
4836 \layout Standard
4837
4838 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4839  and _mulint.rel.
4840  The next step is to add the .rel files to the library file:
4841 \newline
4842
4843 \layout Standard
4844
4845
4846 \family sans
4847 \series bold
4848 sdcclib libint.lib _divsint.rel
4849 \family default
4850
4851 \begin_inset LatexCommand \index{sdcclib}
4852
4853 \end_inset
4854
4855
4856 \layout Standard
4857
4858
4859 \family sans
4860 \series bold
4861 sdcclib libint.lib _divuint.rel
4862 \layout Standard
4863
4864
4865 \family sans
4866 \series bold
4867 sdcclib libint.lib _modsint.rel
4868 \layout Standard
4869
4870
4871 \family sans
4872 \series bold
4873 sdcclib libint.lib _moduint.rel
4874 \layout Standard
4875
4876
4877 \family sans
4878 \series bold
4879 sdcclib libint.lib _mulint.rel
4880 \series default
4881
4882 \newline
4883
4884 \layout Standard
4885
4886 If the file already exists in the library, it will be replaced.
4887  To see what modules and symbols are included in the library, options -s
4888  and -m are available.
4889  For example:
4890 \newline
4891
4892 \newline
4893
4894 \family sans
4895 \series bold
4896 sdcclib -s libint.lib
4897 \family default
4898
4899 \begin_inset LatexCommand \index{sdcclib}
4900
4901 \end_inset
4902
4903
4904 \newline
4905
4906 \family typewriter
4907 \series default
4908 _divsint.rel:
4909 \layout Standard
4910
4911
4912 \family typewriter
4913 __divsint_a_1_1
4914 \layout Standard
4915
4916
4917 \family typewriter
4918 __divsint_PARM_2
4919 \layout Standard
4920
4921
4922 \family typewriter
4923 __divsint
4924 \newline
4925 _divuint.rel:
4926 \layout Standard
4927
4928
4929 \family typewriter
4930 __divuint_a_1_1
4931 \layout Standard
4932
4933
4934 \family typewriter
4935 __divuint_PARM_2
4936 \layout Standard
4937
4938
4939 \family typewriter
4940 __divuint_reste_1_1
4941 \layout Standard
4942
4943
4944 \family typewriter
4945 __divuint_count_1_1
4946 \layout Standard
4947
4948
4949 \family typewriter
4950 __divuint
4951 \newline
4952 _modsint.rel:
4953 \layout Standard
4954
4955
4956 \family typewriter
4957 __modsint_a_1_1
4958 \layout Standard
4959
4960
4961 \family typewriter
4962 __modsint_PARM_2
4963 \layout Standard
4964
4965
4966 \family typewriter
4967 __modsint
4968 \newline
4969 _moduint.rel:
4970 \layout Standard
4971
4972
4973 \family typewriter
4974 __moduint_a_1_1
4975 \layout Standard
4976
4977
4978 \family typewriter
4979 __moduint_PARM_2
4980 \layout Standard
4981
4982
4983 \family typewriter
4984 __moduint_count_1_1
4985 \layout Standard
4986
4987
4988 \family typewriter
4989 __moduint
4990 \newline
4991 _mulint.rel:
4992 \layout Standard
4993
4994
4995 \family typewriter
4996 __mulint_PARM_2
4997 \layout Standard
4998
4999
5000 \family typewriter
5001 __mulint
5002 \family default
5003 \series bold
5004
5005 \newline
5006
5007 \layout Standard
5008
5009 If the source files are compiled using -
5010 \begin_inset ERT
5011 status Open
5012
5013 \layout Standard
5014
5015 \backslash
5016 /
5017 \end_inset
5018
5019 -debug
5020 \begin_inset LatexCommand \index{-\/-debug}
5021
5022 \end_inset
5023
5024 , the corresponding debug information file .adb will be include in the library
5025  file as well.
5026  The library files created with sdcclib are plain text files, so they can
5027  be viewed with a text editor.
5028  It is not recomended to modify a library file created with sdcclib using
5029  a text editor, as there are file indexes numbers located accross the file
5030  used by the linker to quickly locate the required module to link.
5031  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5032  it can be safely deleted, since all the information required for linking
5033  is embedded in the library file itself.
5034  Library files created using sdcclib are used as described in the preceding
5035  sections.
5036 \layout Section
5037
5038 Command Line Options
5039 \begin_inset LatexCommand \index{Command Line Options}
5040
5041 \end_inset
5042
5043
5044 \layout Subsection
5045
5046 Processor Selection Options
5047 \begin_inset LatexCommand \index{Options processor selection}
5048
5049 \end_inset
5050
5051
5052 \begin_inset LatexCommand \index{Processor selection options}
5053
5054 \end_inset
5055
5056
5057 \layout List
5058 \labelwidthstring 00.00.0000
5059
5060
5061 \series bold
5062 -mmcs51
5063 \begin_inset LatexCommand \index{-mmcs51}
5064
5065 \end_inset
5066
5067
5068 \series default
5069  Generate code for the Intel MCS51
5070 \begin_inset LatexCommand \index{MCS51}
5071
5072 \end_inset
5073
5074  family of processors.
5075  This is the default processor target.
5076 \layout List
5077 \labelwidthstring 00.00.0000
5078
5079
5080 \series bold
5081 -mds390
5082 \begin_inset LatexCommand \index{-mds390}
5083
5084 \end_inset
5085
5086
5087 \series default
5088  Generate code for the Dallas DS80C390
5089 \begin_inset LatexCommand \index{DS80C390}
5090
5091 \end_inset
5092
5093  processor.
5094 \layout List
5095 \labelwidthstring 00.00.0000
5096
5097
5098 \series bold
5099 -mds400
5100 \begin_inset LatexCommand \index{-mds400}
5101
5102 \end_inset
5103
5104
5105 \series default
5106  Generate code for the Dallas DS80C400
5107 \begin_inset LatexCommand \index{DS80C400}
5108
5109 \end_inset
5110
5111  processor.
5112 \layout List
5113 \labelwidthstring 00.00.0000
5114
5115
5116 \series bold
5117 -mhc08
5118 \begin_inset LatexCommand \index{-mhc08}
5119
5120 \end_inset
5121
5122
5123 \series default
5124  Generate code for the Freescale/Motorola HC08
5125 \begin_inset LatexCommand \index{HC08}
5126
5127 \end_inset
5128
5129  family of processors.
5130 \layout List
5131 \labelwidthstring 00.00.0000
5132
5133
5134 \series bold
5135 -mz80
5136 \begin_inset LatexCommand \index{-mz80}
5137
5138 \end_inset
5139
5140
5141 \series default
5142  Generate code for the Zilog Z80
5143 \begin_inset LatexCommand \index{Z80}
5144
5145 \end_inset
5146
5147  family of processors.
5148 \layout List
5149 \labelwidthstring 00.00.0000
5150
5151
5152 \series bold
5153 -mgbz80
5154 \begin_inset LatexCommand \index{-mgbz80}
5155
5156 \end_inset
5157
5158
5159 \series default
5160  Generate code for the GameBoy Z80
5161 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5162
5163 \end_inset
5164
5165  processor (Not actively maintained).
5166 \layout List
5167 \labelwidthstring 00.00.0000
5168
5169
5170 \series bold
5171 -mavr
5172 \begin_inset LatexCommand \index{-mavr}
5173
5174 \end_inset
5175
5176
5177 \series default
5178  Generate code for the Atmel AVR
5179 \begin_inset LatexCommand \index{AVR}
5180
5181 \end_inset
5182
5183  processor (In development, not complete).
5184  AVR users should probably have a look at winavr
5185 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5186
5187 \end_inset
5188
5189  or
5190 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5191
5192 \end_inset
5193
5194 .
5195 \layout Comment
5196
5197 I think it is fair to direct users there for now.
5198  Open source is also about avoiding unnecessary work .
5199  But I didn't find the 'official' link.
5200 \layout List
5201 \labelwidthstring 00.00.0000
5202
5203
5204 \series bold
5205 -mpic14
5206 \begin_inset LatexCommand \index{-mpic14}
5207
5208 \end_inset
5209
5210
5211 \series default
5212  Generate code for the Microchip PIC 14
5213 \begin_inset LatexCommand \index{PIC14}
5214
5215 \end_inset
5216
5217 -bit processors (p16f84 and variants.
5218  In development, not complete).
5219 \layout Comment
5220
5221 p16f627 p16f628 p16f84 p16f873 p16f877?
5222 \layout List
5223 \labelwidthstring 00.00.0000
5224
5225
5226 \series bold
5227 -mpic16
5228 \begin_inset LatexCommand \index{-mpic16}
5229
5230 \end_inset
5231
5232
5233 \series default
5234  Generate code for the Microchip PIC 16
5235 \begin_inset LatexCommand \index{PIC16}
5236
5237 \end_inset
5238
5239 -bit processors (p18f452 and variants.
5240  In development, not complete).
5241 \layout List
5242 \labelwidthstring 00.00.0000
5243
5244
5245 \series bold
5246 -mtlcs900h
5247 \series default
5248  Generate code for the Toshiba TLCS-900H
5249 \begin_inset LatexCommand \index{TLCS-900H}
5250
5251 \end_inset
5252
5253  processor (Not maintained, not complete).
5254 \layout List
5255 \labelwidthstring 00.00.0000
5256
5257
5258 \series bold
5259 -mxa51
5260 \begin_inset LatexCommand \index{-mxa51}
5261
5262 \end_inset
5263
5264
5265 \series default
5266  Generate code for the Phillips XA51
5267 \begin_inset LatexCommand \index{XA51}
5268
5269 \end_inset
5270
5271  processor (Not maintained, not complete).
5272 \layout Subsection
5273
5274 Preprocessor Options
5275 \begin_inset LatexCommand \index{Options preprocessor}
5276
5277 \end_inset
5278
5279
5280 \begin_inset LatexCommand \index{Preprocessor options}
5281
5282 \end_inset
5283
5284
5285 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5286
5287 \end_inset
5288
5289
5290 \layout List
5291 \labelwidthstring 00.00.0000
5292
5293
5294 \series bold
5295 -I<path>
5296 \begin_inset LatexCommand \index{-I<path>}
5297
5298 \end_inset
5299
5300
5301 \series default
5302  The additional location where the pre processor will look for <..h> or
5303 \begin_inset Quotes eld
5304 \end_inset
5305
5306 ..h
5307 \begin_inset Quotes erd
5308 \end_inset
5309
5310  files.
5311 \layout List
5312 \labelwidthstring 00.00.0000
5313
5314
5315 \series bold
5316 -D<macro[=value]>
5317 \begin_inset LatexCommand \index{-D<macro[=value]>}
5318
5319 \end_inset
5320
5321
5322 \series default
5323  Command line definition of macros.
5324  Passed to the preprocessor.
5325 \layout List
5326 \labelwidthstring 00.00.0000
5327
5328
5329 \series bold
5330 -M
5331 \begin_inset LatexCommand \index{-M}
5332
5333 \end_inset
5334
5335
5336 \series default
5337  Tell the preprocessor to output a rule suitable for make describing the
5338  dependencies of each object file.
5339  For each source file, the preprocessor outputs one make-rule whose target
5340  is the object file name for that source file and whose dependencies are
5341  all the files `#include'd in it.
5342  This rule may be a single line or may be continued with `
5343 \backslash
5344 '-newline if it is long.
5345  The list of rules is printed on standard output instead of the preprocessed
5346  C program.
5347  `-M' implies `-E
5348 \begin_inset LatexCommand \index{-E}
5349
5350 \end_inset
5351
5352 '.
5353 \layout List
5354 \labelwidthstring 00.00.0000
5355
5356
5357 \series bold
5358 -C
5359 \begin_inset LatexCommand \index{-C}
5360
5361 \end_inset
5362
5363
5364 \series default
5365  Tell the preprocessor not to discard comments.
5366  Used with the `-E' option.
5367 \layout List
5368 \labelwidthstring 00.00.0000
5369
5370
5371 \series bold
5372 -MM
5373 \begin_inset LatexCommand \index{-MM}
5374
5375 \end_inset
5376
5377
5378 \size large
5379 \bar under
5380
5381 \series default
5382 \size default
5383 \bar default
5384 Like `-M' but the output mentions only the user header files included with
5385  `#include
5386 \begin_inset Quotes eld
5387 \end_inset
5388
5389 file"'.
5390  System header files included with `#include <file>' are omitted.
5391 \layout List
5392 \labelwidthstring 00.00.0000
5393
5394
5395 \series bold
5396 -Aquestion(answer)
5397 \begin_inset LatexCommand \index{-Aquestion(answer)}
5398
5399 \end_inset
5400
5401
5402 \series default
5403  Assert the answer answer for question, in case it is tested with a preprocessor
5404  conditional such as `#if #question(answer)'.
5405  `-A-' disables the standard assertions that normally describe the target
5406  machine.
5407 \layout List
5408 \labelwidthstring 00.00.0000
5409
5410
5411 \series bold
5412 -Umacro
5413 \begin_inset LatexCommand \index{-Umacro}
5414
5415 \end_inset
5416
5417
5418 \series default
5419  Undefine macro macro.
5420  `-U' options are evaluated after all `-D' options, but before any `-include'
5421  and `-imacros' options.
5422 \layout List
5423 \labelwidthstring 00.00.0000
5424
5425
5426 \series bold
5427 -dM
5428 \begin_inset LatexCommand \index{-dM}
5429
5430 \end_inset
5431
5432
5433 \series default
5434  Tell the preprocessor to output only a list of the macro definitions that
5435  are in effect at the end of preprocessing.
5436  Used with the `-E' option.
5437 \layout List
5438 \labelwidthstring 00.00.0000
5439
5440
5441 \series bold
5442 -dD
5443 \begin_inset LatexCommand \index{-dD}
5444
5445 \end_inset
5446
5447
5448 \series default
5449  Tell the preprocessor to pass all macro definitions into the output, in
5450  their proper sequence in the rest of the output.
5451 \layout List
5452 \labelwidthstring 00.00.0000
5453
5454
5455 \series bold
5456 -dN
5457 \begin_inset LatexCommand \index{-dN}
5458
5459 \end_inset
5460
5461
5462 \size large
5463 \bar under
5464
5465 \series default
5466 \size default
5467 \bar default
5468 Like `-dD' except that the macro arguments and contents are omitted.
5469  Only `#define name' is included in the output.
5470 \layout List
5471 \labelwidthstring 00.00.0000
5472
5473
5474 \series bold
5475 -Wp\SpecialChar ~
5476 preprocessorOption[,preprocessorOption]
5477 \series default
5478
5479 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5480
5481 \end_inset
5482
5483 ...
5484  Pass the preprocessorOption to the preprocessor
5485 \family typewriter
5486 sdcpp
5487 \family default
5488
5489 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5490
5491 \end_inset
5492
5493 .
5494  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5495  Collection (gcc), if you need more dedicated options please refer to the
5496  documentation at
5497 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5498
5499 \end_inset
5500
5501 .
5502 \layout Subsection
5503
5504 Linker Options
5505 \begin_inset LatexCommand \index{Options linker}
5506
5507 \end_inset
5508
5509
5510 \begin_inset LatexCommand \index{Linker options}
5511
5512 \end_inset
5513
5514
5515 \layout List
5516 \labelwidthstring 00.00.0000
5517
5518
5519 \series bold
5520 -L\SpecialChar ~
5521 -
5522 \series default
5523
5524 \begin_inset ERT
5525 status Collapsed
5526
5527 \layout Standard
5528
5529 \backslash
5530 /
5531 \end_inset
5532
5533
5534 \series bold
5535 -lib-path
5536 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5537
5538 \end_inset
5539
5540
5541 \begin_inset LatexCommand \index{-L -\/-lib-path}
5542
5543 \end_inset
5544
5545
5546 \series default
5547 \SpecialChar ~
5548 <absolute path to additional libraries> This option is passed to the linkage
5549  editor's additional libraries
5550 \begin_inset LatexCommand \index{Libraries}
5551
5552 \end_inset
5553
5554  search path.
5555  The path name must be absolute.
5556  Additional library files may be specified in the command line.
5557  See section Compiling programs for more details.
5558 \layout List
5559 \labelwidthstring 00.00.0000
5560
5561
5562 \series bold
5563 -
5564 \begin_inset ERT
5565 status Collapsed
5566
5567 \layout Standard
5568
5569 \backslash
5570 /
5571 \end_inset
5572
5573 -xram-loc
5574 \series default
5575
5576 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5577
5578 \end_inset
5579
5580 \SpecialChar ~
5581 <Value> The start location of the external ram
5582 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5583
5584 \end_inset
5585
5586 , default value is 0.
5587  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5588 \begin_inset ERT
5589 status Collapsed
5590
5591 \layout Standard
5592
5593 \backslash
5594 /
5595 \end_inset
5596
5597 -xram-loc 0x8000 or -
5598 \begin_inset ERT
5599 status Collapsed
5600
5601 \layout Standard
5602
5603 \backslash
5604 /
5605 \end_inset
5606
5607 -xram-loc 32768.
5608 \layout List
5609 \labelwidthstring 00.00.0000
5610
5611
5612 \series bold
5613 -
5614 \begin_inset ERT
5615 status Collapsed
5616
5617 \layout Standard
5618
5619 \backslash
5620 /
5621 \end_inset
5622
5623 -code-loc
5624 \series default
5625
5626 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5627
5628 \end_inset
5629
5630 \SpecialChar ~
5631 <Value> The start location of the code
5632 \begin_inset LatexCommand \index{code}
5633
5634 \end_inset
5635
5636  segment, default value 0.
5637  Note when this option is used the interrupt vector table is also relocated
5638  to the given address.
5639  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5640 \begin_inset ERT
5641 status Collapsed
5642
5643 \layout Standard
5644
5645 \backslash
5646 /
5647 \end_inset
5648
5649 -code-loc 0x8000 or -
5650 \begin_inset ERT
5651 status Collapsed
5652
5653 \layout Standard
5654
5655 \backslash
5656 /
5657 \end_inset
5658
5659 -code-loc 32768.
5660 \layout List
5661 \labelwidthstring 00.00.0000
5662
5663
5664 \series bold
5665 -
5666 \begin_inset ERT
5667 status Collapsed
5668
5669 \layout Standard
5670
5671 \backslash
5672 /
5673 \end_inset
5674
5675 -stack-loc
5676 \series default
5677
5678 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5679
5680 \end_inset
5681
5682 \SpecialChar ~
5683 <Value> By default the stack
5684 \begin_inset LatexCommand \index{stack}
5685
5686 \end_inset
5687
5688  is placed after the data segment.
5689  Using this option the stack can be placed anywhere in the internal memory
5690  space of the 8051.
5691  The value entered can be in Hexadecimal or Decimal format, e.g.
5692  -
5693 \begin_inset ERT
5694 status Collapsed
5695
5696 \layout Standard
5697
5698 \backslash
5699 /
5700 \end_inset
5701
5702 -stack-loc 0x20 or -
5703 \begin_inset ERT
5704 status Collapsed
5705
5706 \layout Standard
5707
5708 \backslash
5709 /
5710 \end_inset
5711
5712 -stack-loc 32.
5713  Since the sp register is incremented before a push or call, the initial
5714  sp will be set to one byte prior the provided value.
5715  The provided value should not overlap any other memory areas such as used
5716  register banks or the data segment and with enough space for the current
5717  application.
5718  The
5719 \series bold
5720 -
5721 \begin_inset ERT
5722 status Collapsed
5723
5724 \layout Standard
5725
5726 \backslash
5727 /
5728 \end_inset
5729
5730 -pack-iram
5731 \series default
5732 \SpecialChar ~
5733
5734 \begin_inset LatexCommand \index{-\/-pack-iram}
5735
5736 \end_inset
5737
5738  option (which is now a default setting) will override this setting, so
5739  you should also specify the
5740 \series bold
5741 -
5742 \begin_inset ERT
5743 status Collapsed
5744
5745 \layout Standard
5746
5747 \backslash
5748 /
5749 \end_inset
5750
5751 -no-pack-iram
5752 \series default
5753 \SpecialChar ~
5754
5755 \begin_inset LatexCommand \index{-\/-no-pack-iram}
5756
5757 \end_inset
5758
5759  option if you need to manually place the stack.
5760 \layout List
5761 \labelwidthstring 00.00.0000
5762
5763
5764 \series bold
5765 -
5766 \begin_inset ERT
5767 status Collapsed
5768
5769 \layout Standard
5770
5771 \backslash
5772 /
5773 \end_inset
5774
5775 -xstack-loc
5776 \series default
5777
5778 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
5779
5780 \end_inset
5781
5782 \SpecialChar ~
5783 <Value> By default the external stack
5784 \begin_inset LatexCommand \index{xstack}
5785
5786 \end_inset
5787
5788  is placed after the pdata segment.
5789  Using this option the xstack can be placed anywhere in the external memory
5790  space of the 8051.
5791  The value entered can be in Hexadecimal or Decimal format, e.g.
5792  -
5793 \begin_inset ERT
5794 status Collapsed
5795
5796 \layout Standard
5797
5798 \backslash
5799 /
5800 \end_inset
5801
5802 -xstack-loc 0x8000 or -
5803 \begin_inset ERT
5804 status Collapsed
5805
5806 \layout Standard
5807
5808 \backslash
5809 /
5810 \end_inset
5811
5812 -stack-loc 32768.
5813  The provided value should not overlap any other memory areas such as the
5814  pdata or xdata segment and with enough space for the current application.
5815 \layout List
5816 \labelwidthstring 00.00.0000
5817
5818
5819 \series bold
5820 -
5821 \begin_inset ERT
5822 status Collapsed
5823
5824 \layout Standard
5825
5826 \backslash
5827 /
5828 \end_inset
5829
5830 -data-loc
5831 \series default
5832
5833 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5834
5835 \end_inset
5836
5837 \SpecialChar ~
5838 <Value> The start location of the internal ram data
5839 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5840
5841 \end_inset
5842
5843  segment.
5844  The value entered can be in Hexadecimal or Decimal format, eg.
5845  -
5846 \begin_inset ERT
5847 status Collapsed
5848
5849 \layout Standard
5850
5851 \backslash
5852 /
5853 \end_inset
5854
5855 -data-loc 0x20 or -
5856 \begin_inset ERT
5857 status Collapsed
5858
5859 \layout Standard
5860
5861 \backslash
5862 /
5863 \end_inset
5864
5865 -data-loc 32.
5866  (By default, the start location of the internal ram data segment  is set
5867  as low as possible in memory, taking into account the used register banks
5868  and the bit segment at address 0x20.
5869  For example if register banks 0 and 1 are used without bit variables, the
5870  data segment will be set, if -
5871 \begin_inset ERT
5872 status Collapsed
5873
5874 \layout Standard
5875
5876 \backslash
5877 /
5878 \end_inset
5879
5880 -data-loc is not used, to location 0x10.)
5881 \layout List
5882 \labelwidthstring 00.00.0000
5883
5884
5885 \series bold
5886 -
5887 \begin_inset ERT
5888 status Collapsed
5889
5890 \layout Standard
5891
5892 \backslash
5893 /
5894 \end_inset
5895
5896 -idata-loc
5897 \series default
5898
5899 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5900
5901 \end_inset
5902
5903 \SpecialChar ~
5904 <Value> The start location of the indirectly addressable internal ram
5905 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5906
5907 \end_inset
5908
5909  of the 8051, default value is 0x80.
5910  The value entered can be in Hexadecimal or Decimal format, eg.
5911  -
5912 \begin_inset ERT
5913 status Collapsed
5914
5915 \layout Standard
5916
5917 \backslash
5918 /
5919 \end_inset
5920
5921 -idata-loc 0x88 or -
5922 \begin_inset ERT
5923 status Collapsed
5924
5925 \layout Standard
5926
5927 \backslash
5928 /
5929 \end_inset
5930
5931 -idata-loc 136.
5932 \layout List
5933 \labelwidthstring 00.00.0000
5934
5935
5936 \series bold
5937 -
5938 \begin_inset ERT
5939 status Collapsed
5940
5941 \layout Standard
5942
5943 \backslash
5944 /
5945 \end_inset
5946
5947 -bit-loc
5948 \series default
5949 \SpecialChar ~
5950 <Value> The start location of the bit
5951 \begin_inset LatexCommand \index{bit}
5952
5953 \end_inset
5954
5955  addressable internal ram of the 8051.
5956  This is
5957 \emph on
5958 not
5959 \emph default
5960  implemented yet.
5961  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5962 -bBSEG=<Value>.
5963 \layout List
5964 \labelwidthstring 00.00.0000
5965
5966
5967 \series bold
5968 -
5969 \begin_inset ERT
5970 status Collapsed
5971
5972 \layout Standard
5973
5974 \backslash
5975 /
5976 \end_inset
5977
5978 -out-fmt-ihx
5979 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5980
5981 \end_inset
5982
5983
5984 \bar under
5985
5986 \series default
5987 \bar default
5988 The linker output (final object code) is in Intel Hex format.
5989 \begin_inset LatexCommand \index{Intel hex format}
5990
5991 \end_inset
5992
5993  This is the default option.
5994  The format itself is documented in the documentation of srecord
5995 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5996
5997 \end_inset
5998
5999 .
6000 \layout List
6001 \labelwidthstring 00.00.0000
6002
6003
6004 \series bold
6005 -
6006 \begin_inset ERT
6007 status Collapsed
6008
6009 \layout Standard
6010
6011 \backslash
6012 /
6013 \end_inset
6014
6015 -out-fmt-s19
6016 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6017
6018 \end_inset
6019
6020
6021 \bar under
6022
6023 \series default
6024 \bar default
6025 The linker output (final object code) is in Motorola S19 format
6026 \begin_inset LatexCommand \index{Motorola S19 format}
6027
6028 \end_inset
6029
6030 .
6031  The format itself is documented in the documentation of srecord.
6032 \layout List
6033 \labelwidthstring 00.00.0000
6034
6035
6036 \series bold
6037 -
6038 \begin_inset ERT
6039 status Collapsed
6040
6041 \layout Standard
6042
6043 \backslash
6044 /
6045 \end_inset
6046
6047 -out-fmt-elf
6048 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6049
6050 \end_inset
6051
6052
6053 \bar under
6054
6055 \series default
6056 \bar default
6057 The linker output (final object code) is in ELF format
6058 \begin_inset LatexCommand \index{ELF format}
6059
6060 \end_inset
6061
6062 .
6063  (Currently only supported for the HC08 processors)
6064 \layout List
6065 \labelwidthstring 00.00.0000
6066
6067
6068 \series bold
6069 -Wl\SpecialChar ~
6070 linkOption[,linkOption]
6071 \series default
6072
6073 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
6074
6075 \end_inset
6076
6077 ...
6078  Pass the linkOption to the linker.
6079  See file sdcc/as/doc/asxhtm.html for more on linker options.
6080 \layout Subsection
6081
6082 MCS51 Options
6083 \begin_inset LatexCommand \index{Options MCS51}
6084
6085 \end_inset
6086
6087
6088 \begin_inset LatexCommand \index{MCS51 options}
6089
6090 \end_inset
6091
6092
6093 \layout List
6094 \labelwidthstring 00.00.0000
6095
6096
6097 \series bold
6098 -
6099 \begin_inset ERT
6100 status Collapsed
6101
6102 \layout Standard
6103
6104 \backslash
6105 /
6106 \end_inset
6107
6108 -model-small
6109 \begin_inset LatexCommand \index{-\/-model-small}
6110
6111 \end_inset
6112
6113
6114 \series default
6115 \size large
6116 \emph on
6117
6118 \size default
6119 \emph default
6120 Generate code for Small Model programs, see section Memory Models for more
6121  details.
6122  This is the default model.
6123 \layout List
6124 \labelwidthstring 00.00.0000
6125
6126
6127 \series bold
6128 -
6129 \begin_inset ERT
6130 status Collapsed
6131
6132 \layout Standard
6133
6134 \backslash
6135 /
6136 \end_inset
6137
6138 -model-medium
6139 \begin_inset LatexCommand \index{-\/-model-medium}
6140
6141 \end_inset
6142
6143
6144 \series default
6145  Generate code for Medium model programs, see section Memory Models for
6146  more details.
6147  If this option is used all source files in the project have to be compiled
6148  with this option.
6149  It must also be used when invoking the linker.
6150 \layout List
6151 \labelwidthstring 00.00.0000
6152
6153
6154 \series bold
6155 -
6156 \begin_inset ERT
6157 status Collapsed
6158
6159 \layout Standard
6160
6161 \backslash
6162 /
6163 \end_inset
6164
6165 -model-large
6166 \begin_inset LatexCommand \index{-\/-model-large}
6167
6168 \end_inset
6169
6170
6171 \series default
6172  Generate code for Large model programs, see section Memory Models for more
6173  details.
6174  If this option is used all source files in the project have to be compiled
6175  with this option.
6176  It must also be used when invoking the linker.
6177 \layout List
6178 \labelwidthstring 00.00.0000
6179
6180
6181 \series bold
6182 -
6183 \begin_inset ERT
6184 status Collapsed
6185
6186 \layout Standard
6187
6188 \backslash
6189 /
6190 \end_inset
6191
6192 -xstack
6193 \begin_inset LatexCommand \index{-\/-xstack}
6194
6195 \end_inset
6196
6197
6198 \series default
6199  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6200  variables and passing parameters.
6201  See section
6202 \begin_inset LatexCommand \ref{sub:External-Stack}
6203
6204 \end_inset
6205
6206 \SpecialChar ~
6207  External Stack for more details.
6208 \layout List
6209 \labelwidthstring 00.00.0000
6210
6211
6212 \series bold
6213 -
6214 \begin_inset ERT
6215 status Collapsed
6216
6217 \layout Standard
6218
6219 \backslash
6220 /
6221 \end_inset
6222
6223 -iram-size
6224 \series default
6225 \SpecialChar ~
6226 <Value>
6227 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6228
6229 \end_inset
6230
6231  Causes the linker to check if the internal ram usage is within limits of
6232  the given value.
6233 \layout List
6234 \labelwidthstring 00.00.0000
6235
6236
6237 \series bold
6238 -
6239 \begin_inset ERT
6240 status Collapsed
6241
6242 \layout Standard
6243
6244 \backslash
6245 /
6246 \end_inset
6247
6248 -xram-size
6249 \series default
6250 \SpecialChar ~
6251 <Value>
6252 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6253
6254 \end_inset
6255
6256  Causes the linker to check if the external ram usage is within limits of
6257  the given value.
6258 \layout List
6259 \labelwidthstring 00.00.0000
6260
6261
6262 \series bold
6263 -
6264 \begin_inset ERT
6265 status Collapsed
6266
6267 \layout Standard
6268
6269 \backslash
6270 /
6271 \end_inset
6272
6273 -code-size
6274 \series default
6275 \SpecialChar ~
6276 <Value>
6277 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6278
6279 \end_inset
6280
6281  Causes the linker to check if the code memory usage is within limits of
6282  the given value.
6283 \layout List
6284 \labelwidthstring 00.00.0000
6285
6286
6287 \series bold
6288 -
6289 \begin_inset ERT
6290 status Collapsed
6291
6292 \layout Standard
6293
6294 \backslash
6295 /
6296 \end_inset
6297
6298 -stack-size
6299 \series default
6300 \SpecialChar ~
6301 <Value>
6302 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6303
6304 \end_inset
6305
6306  Causes the linker to check if there is at minimum <Value> bytes for stack.
6307 \layout List
6308 \labelwidthstring 00.00.0000
6309
6310
6311 \series bold
6312 -
6313 \begin_inset ERT
6314 status Collapsed
6315
6316 \layout Standard
6317
6318 \backslash
6319 /
6320 \end_inset
6321
6322 -pack-iram
6323 \series default
6324 \SpecialChar ~
6325
6326 \begin_inset LatexCommand \index{-\/-pack-iram}
6327
6328 \end_inset
6329
6330  Causes the linker to use unused register banks for data variables and pack
6331  data, idata and stack together.
6332  This is the default now.
6333 \layout List
6334 \labelwidthstring 00.00.0000
6335
6336
6337 \series bold
6338 -
6339 \begin_inset ERT
6340 status Collapsed
6341
6342 \layout Standard
6343
6344 \backslash
6345 /
6346 \end_inset
6347
6348 -no-pack-iram
6349 \series default
6350 \SpecialChar ~
6351
6352 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6353
6354 \end_inset
6355
6356  Causes the linker to use old style for allocating memory areas.
6357 \layout Subsection
6358
6359 DS390 / DS400 Options
6360 \begin_inset LatexCommand \index{Options DS390}
6361
6362 \end_inset
6363
6364
6365 \begin_inset LatexCommand \index{DS390 options}
6366
6367 \end_inset
6368
6369
6370 \layout List
6371 \labelwidthstring 00.00.0000
6372
6373
6374 \series bold
6375 -
6376 \begin_inset ERT
6377 status Collapsed
6378
6379 \layout Standard
6380
6381 \backslash
6382 /
6383 \end_inset
6384
6385 -model-flat24
6386 \series default
6387
6388 \begin_inset LatexCommand \index{-\/-model-flat24}
6389
6390 \end_inset
6391
6392
6393 \size large
6394 \emph on
6395
6396 \size default
6397 \emph default
6398 Generate 24-bit flat mode code.
6399  This is the one and only that the ds390 code generator supports right now
6400  and is default when using
6401 \emph on
6402 -mds390
6403 \emph default
6404 .
6405  See section Memory Models for more details.
6406 \layout List
6407 \labelwidthstring 00.00.0000
6408
6409
6410 \series bold
6411 -
6412 \begin_inset ERT
6413 status Collapsed
6414
6415 \layout Standard
6416
6417 \backslash
6418 /
6419 \end_inset
6420
6421 -protect-sp-update
6422 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6423
6424 \end_inset
6425
6426
6427 \series default
6428  disable interrupts during ESP:SP updates.
6429 \layout List
6430 \labelwidthstring 00.00.0000
6431
6432
6433 \series bold
6434 -
6435 \begin_inset ERT
6436 status Collapsed
6437
6438 \layout Standard
6439
6440 \backslash
6441 /
6442 \end_inset
6443
6444 -stack-10bit
6445 \series default
6446
6447 \begin_inset LatexCommand \index{-\/-stack-10bit}
6448
6449 \end_inset
6450
6451  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6452  This is the one and only that the ds390 code generator supports right now
6453  and is default when using
6454 \emph on
6455 -mds390
6456 \emph default
6457 .
6458  In this mode, the stack is located in the lower 1K of the internal RAM,
6459  which is mapped to 0x400000.
6460  Note that the support is incomplete, since it still uses a single byte
6461  as the stack pointer.
6462  This means that only the lower 256 bytes of the potential 1K stack space
6463  will actually be used.
6464  However, this does allow you to reclaim the precious 256 bytes of low RAM
6465  for use for the DATA and IDATA segments.
6466  The compiler will not generate any code to put the processor into 10 bit
6467  stack mode.
6468  It is important to ensure that the processor is in this mode before calling
6469  any re-entrant functions compiled with this option.
6470  In principle, this should work with the
6471 \emph on
6472 -
6473 \begin_inset ERT
6474 status Collapsed
6475
6476 \layout Standard
6477
6478 \backslash
6479 /
6480 \end_inset
6481
6482 -stack-auto
6483 \begin_inset LatexCommand \index{-\/-stack-auto}
6484
6485 \end_inset
6486
6487
6488 \emph default
6489  option, but that has not been tested.
6490  It is incompatible with the
6491 \emph on
6492 -
6493 \begin_inset ERT
6494 status Collapsed
6495
6496 \layout Standard
6497
6498 \backslash
6499 /
6500 \end_inset
6501
6502 -xstack
6503 \begin_inset LatexCommand \index{-\/-xstack}
6504
6505 \end_inset
6506
6507
6508 \emph default
6509  option.
6510  It also only makes sense if the processor is in 24 bit contiguous addressing
6511  mode (see the
6512 \emph on
6513 -
6514 \begin_inset ERT
6515 status Collapsed
6516
6517 \layout Standard
6518
6519 \backslash
6520 /
6521 \end_inset
6522
6523 -model-flat24 option
6524 \emph default
6525 ).
6526 \layout List
6527 \labelwidthstring 00.00.0000
6528
6529
6530 \series bold
6531 -
6532 \begin_inset ERT
6533 status Collapsed
6534
6535 \layout Standard
6536
6537 \backslash
6538 /
6539 \end_inset
6540
6541 -stack-probe
6542 \begin_inset LatexCommand \index{-\/-stack-probe}
6543
6544 \end_inset
6545
6546
6547 \series default
6548  insert call to function __stack_probe at each function prologue.
6549 \layout List
6550 \labelwidthstring 00.00.0000
6551
6552
6553 \series bold
6554 -
6555 \begin_inset ERT
6556 status Collapsed
6557
6558 \layout Standard
6559
6560 \backslash
6561 /
6562 \end_inset
6563
6564 -tini-libid
6565 \begin_inset LatexCommand \index{-\/-tini-libid}
6566
6567 \end_inset
6568
6569
6570 \series default
6571  <nnnn> LibraryID used in -mTININative.
6572
6573 \layout List
6574 \labelwidthstring 00.00.0000
6575
6576
6577 \series bold
6578 -
6579 \begin_inset ERT
6580 status Collapsed
6581
6582 \layout Standard
6583
6584 \backslash
6585 /
6586 \end_inset
6587
6588 -use-accelerator
6589 \begin_inset LatexCommand \index{-\/-use-accelerator}
6590
6591 \end_inset
6592
6593
6594 \series default
6595  generate code for DS390 Arithmetic Accelerator.
6596
6597 \layout Subsection
6598
6599 Z80 Options
6600 \begin_inset LatexCommand \index{Options Z80}
6601
6602 \end_inset
6603
6604
6605 \begin_inset LatexCommand \index{Z80 options}
6606
6607 \end_inset
6608
6609
6610 \layout List
6611 \labelwidthstring 00.00.0000
6612
6613
6614 \series bold
6615 -
6616 \begin_inset ERT
6617 status Collapsed
6618
6619 \layout Standard
6620
6621 \backslash
6622 /
6623 \end_inset
6624
6625 -callee-saves-bc
6626 \series default
6627
6628 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6629
6630 \end_inset
6631
6632
6633 \size large
6634 \emph on
6635
6636 \size default
6637 \emph default
6638 Force a called function to always save BC.
6639 \layout List
6640 \labelwidthstring 00.00.0000
6641
6642
6643 \series bold
6644 -
6645 \begin_inset ERT
6646 status Collapsed
6647
6648 \layout Standard
6649
6650 \backslash
6651 /
6652 \end_inset
6653
6654 -no-std-crt0
6655 \series default
6656
6657 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6658
6659 \end_inset
6660
6661  When linking, skip the standard crt0.o object file.
6662  You must provide your own crt0.o for your system when linking.
6663
6664 \layout Subsection
6665
6666 Optimization Options
6667 \begin_inset LatexCommand \index{Options optimization}
6668
6669 \end_inset
6670
6671
6672 \begin_inset LatexCommand \index{Optimization options}
6673
6674 \end_inset
6675
6676
6677 \layout List
6678 \labelwidthstring 00.00.0000
6679
6680
6681 \series bold
6682 -
6683 \begin_inset ERT
6684 status Collapsed
6685
6686 \layout Standard
6687
6688 \backslash
6689 /
6690 \end_inset
6691
6692 -nogcse
6693 \begin_inset LatexCommand \index{-\/-nogcse}
6694
6695 \end_inset
6696
6697
6698 \series default
6699  Will not do global subexpression elimination, this option may be used when
6700  the compiler creates undesirably large stack/data spaces to store compiler
6701  temporaries (
6702 \emph on
6703 s
6704 \emph default
6705 pill
6706 \emph on
6707 loc
6708 \emph default
6709 ations, sloc
6710 \begin_inset LatexCommand \index{sloc (spill location)}
6711
6712 \end_inset
6713
6714 ).
6715  A warning message will be generated when this happens and the compiler
6716  will indicate the number of extra bytes it allocated.
6717  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6718 nogcse
6719 \begin_inset LatexCommand \index{\#pragma nogcse}
6720
6721 \end_inset
6722
6723  can be used to turn off global subexpression elimination
6724 \begin_inset LatexCommand \index{Subexpression elimination}
6725
6726 \end_inset
6727
6728  for a given function only.
6729 \layout List
6730 \labelwidthstring 00.00.0000
6731
6732
6733 \series bold
6734 -
6735 \begin_inset ERT
6736 status Collapsed
6737
6738 \layout Standard
6739
6740 \backslash
6741 /
6742 \end_inset
6743
6744 -noinvariant
6745 \begin_inset LatexCommand \index{-\/-noinvariant}
6746
6747 \end_inset
6748
6749
6750 \series default
6751  Will not do loop invariant optimizations, this may be turned off for reasons
6752  explained for the previous option.
6753  For more details of loop optimizations performed see Loop Invariants in
6754  section
6755 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6756
6757 \end_inset
6758
6759 .
6760  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6761 noinvariant
6762 \begin_inset LatexCommand \index{\#pragma noinvariant}
6763
6764 \end_inset
6765
6766  can be used to turn off invariant optimizations for a given function only.
6767 \layout List
6768 \labelwidthstring 00.00.0000
6769
6770
6771 \series bold
6772 -
6773 \begin_inset ERT
6774 status Collapsed
6775
6776 \layout Standard
6777
6778 \backslash
6779 /
6780 \end_inset
6781
6782 -noinduction
6783 \begin_inset LatexCommand \index{-\/-noinduction}
6784
6785 \end_inset
6786
6787
6788 \series default
6789  Will not do loop induction optimizations, see section strength reduction
6790  for more details.
6791  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6792 noinduction
6793 \begin_inset LatexCommand \index{\#pragma noinduction}
6794
6795 \end_inset
6796
6797  can be used to turn off induction optimizations for a given function only.
6798 \layout List
6799 \labelwidthstring 00.00.0000
6800
6801
6802 \series bold
6803 -
6804 \begin_inset ERT
6805 status Collapsed
6806
6807 \layout Standard
6808
6809 \backslash
6810 /
6811 \end_inset
6812
6813 -nojtbound
6814 \begin_inset LatexCommand \index{-\/-nojtbound}
6815
6816 \end_inset
6817
6818
6819 \size large
6820 \bar under
6821
6822 \series default
6823 \size default
6824 \bar default
6825  Will not generate boundary condition check when switch statements
6826 \begin_inset LatexCommand \index{switch statement}
6827
6828 \end_inset
6829
6830  are implemented using jump-tables.
6831  See section
6832 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6833
6834 \end_inset
6835
6836 \SpecialChar ~
6837 Switch Statements for more details.
6838  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6839 nojtbound
6840 \begin_inset LatexCommand \index{\#pragma nojtbound}
6841
6842 \end_inset
6843
6844  can be used to turn off boundary checking for jump tables for a given function
6845  only.
6846 \layout List
6847 \labelwidthstring 00.00.0000
6848
6849
6850 \series bold
6851 -
6852 \begin_inset ERT
6853 status Collapsed
6854
6855 \layout Standard
6856
6857 \backslash
6858 /
6859 \end_inset
6860
6861 -noloopreverse
6862 \begin_inset LatexCommand \index{-\/-noloopreverse}
6863
6864 \end_inset
6865
6866
6867 \series default
6868 \size large
6869
6870 \size default
6871 Will not do loop reversal
6872 \begin_inset LatexCommand \index{Loop reversing}
6873
6874 \end_inset
6875
6876 optimization.
6877 \layout List
6878 \labelwidthstring 00.00.0000
6879
6880 -
6881 \begin_inset ERT
6882 status Collapsed
6883
6884 \layout Standard
6885
6886 \backslash
6887 /
6888 \end_inset
6889
6890 -
6891 \series bold
6892 nolabelopt
6893 \series default
6894
6895 \begin_inset LatexCommand \index{-\/-nolabelopt }
6896
6897 \end_inset
6898
6899 Will not optimize labels (makes the dumpfiles more readable).
6900 \layout List
6901 \labelwidthstring 00.00.0000
6902
6903
6904 \series bold
6905 -
6906 \begin_inset ERT
6907 status Collapsed
6908
6909 \layout Standard
6910
6911 \backslash
6912 /
6913 \end_inset
6914
6915 -no-xinit-opt
6916 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6917
6918 \end_inset
6919
6920
6921 \series default
6922  Will not memcpy initialized data from code space into xdata space.
6923  This saves a few bytes in code space if you don't have initialized data
6924 \begin_inset LatexCommand \index{Variable initialization}
6925
6926 \end_inset
6927
6928 .
6929 \layout List
6930 \labelwidthstring 00.00.0000
6931
6932
6933 \series bold
6934 -
6935 \begin_inset ERT
6936 status Collapsed
6937
6938 \layout Standard
6939
6940 \backslash
6941 /
6942 \end_inset
6943
6944 -nooverlay
6945 \begin_inset LatexCommand \index{-\/-nooverlay}
6946
6947 \end_inset
6948
6949
6950 \series default
6951   The compiler will not overlay parameters and local variables of any function,
6952  see section Parameters and local variables for more details.
6953 \layout List
6954 \labelwidthstring 00.00.0000
6955
6956
6957 \series bold
6958 -
6959 \begin_inset ERT
6960 status Collapsed
6961
6962 \layout Standard
6963
6964 \backslash
6965 /
6966 \end_inset
6967
6968 -no-peep
6969 \begin_inset LatexCommand \index{-\/-no-peep}
6970
6971 \end_inset
6972
6973
6974 \series default
6975  Disable peep-hole optimization with built-in rules.
6976 \layout List
6977 \labelwidthstring 00.00.0000
6978
6979
6980 \series bold
6981 -
6982 \begin_inset ERT
6983 status Collapsed
6984
6985 \layout Standard
6986
6987 \backslash
6988 /
6989 \end_inset
6990
6991 -peep-file
6992 \series default
6993
6994 \begin_inset LatexCommand \index{-\/-peep-file}
6995
6996 \end_inset
6997
6998 \SpecialChar ~
6999 <filename> This option can be used to use additional rules to be used by
7000  the peep hole optimizer.
7001  See section
7002 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
7003
7004 \end_inset
7005
7006 \SpecialChar ~
7007 Peep Hole optimizations for details on how to write these rules.
7008 \layout List
7009 \labelwidthstring 00.00.0000
7010
7011
7012 \series bold
7013 -
7014 \begin_inset ERT
7015 status Collapsed
7016
7017 \layout Standard
7018
7019 \backslash
7020 /
7021 \end_inset
7022
7023 -peep-asm
7024 \begin_inset LatexCommand \index{-\/-peep-asm}
7025
7026 \end_inset
7027
7028
7029 \series default
7030  Pass the inline assembler code through the peep hole optimizer.
7031  This can cause unexpected changes to inline assembler code, please go through
7032  the peephole optimizer
7033 \begin_inset LatexCommand \index{Peephole optimizer}
7034
7035 \end_inset
7036
7037  rules defined in the source file tree '<target>/peeph.def' before using
7038  this option.
7039 \layout List
7040 \labelwidthstring 00.00.0000
7041
7042
7043 \series bold
7044 -
7045 \begin_inset ERT
7046 status Collapsed
7047
7048 \layout Standard
7049
7050 \backslash
7051 /
7052 \end_inset
7053
7054 -opt-code-speed
7055 \begin_inset LatexCommand \index{-\/-opt-code-speed}
7056
7057 \end_inset
7058
7059
7060 \series default
7061  The compiler will optimize code generation towards fast code, possibly
7062  at the expense of code size.
7063 \layout List
7064 \labelwidthstring 00.00.0000
7065
7066
7067 \series bold
7068 -
7069 \begin_inset ERT
7070 status Collapsed
7071
7072 \layout Standard
7073
7074 \backslash
7075 /
7076 \end_inset
7077
7078 -opt-code-size
7079 \begin_inset LatexCommand \index{-\/-opt-code-size}
7080
7081 \end_inset
7082
7083
7084 \series default
7085  The compiler will optimize code generation towards compact code, possibly
7086  at the expense of code speed.
7087 \layout Subsection
7088
7089 Other Options
7090 \begin_inset LatexCommand \index{Options other}
7091
7092 \end_inset
7093
7094
7095 \layout List
7096 \labelwidthstring 00.00.0000
7097
7098
7099 \series bold
7100 -c\SpecialChar ~
7101 -
7102 \begin_inset ERT
7103 status Collapsed
7104
7105 \layout Standard
7106
7107 \backslash
7108 /
7109 \end_inset
7110
7111 -compile-only
7112 \begin_inset LatexCommand \index{-\/-compile-only}
7113
7114 \end_inset
7115
7116
7117 \begin_inset LatexCommand \index{-c -\/-compile-only}
7118
7119 \end_inset
7120
7121
7122 \series default
7123  will compile and assemble the source, but will not call the linkage editor.
7124 \layout List
7125 \labelwidthstring 00.00.0000
7126
7127
7128 \series bold
7129 -
7130 \series default
7131
7132 \begin_inset ERT
7133 status Collapsed
7134
7135 \layout Standard
7136
7137 \backslash
7138 /
7139 \end_inset
7140
7141
7142 \series bold
7143 -c1mode
7144 \begin_inset LatexCommand \index{-\/-c1mode}
7145
7146 \end_inset
7147
7148
7149 \series default
7150  reads the preprocessed source from standard input and compiles it.
7151  The file name for the assembler output must be specified using the -o option.
7152 \layout List
7153 \labelwidthstring 00.00.0000
7154
7155
7156 \series bold
7157 -E
7158 \begin_inset LatexCommand \index{-E}
7159
7160 \end_inset
7161
7162
7163 \series default
7164  Run only the C preprocessor.
7165  Preprocess all the C source files specified and output the results to standard
7166  output.
7167 \layout List
7168 \labelwidthstring 00.00.0000
7169
7170
7171 \series bold
7172 -o\SpecialChar ~
7173 <path/file>
7174 \begin_inset LatexCommand \index{-o <path/file>}
7175
7176 \end_inset
7177
7178
7179 \series default
7180 The output path resp.
7181  file where everything will be placed.
7182  If the parameter is a path, it must have a trailing slash (or backslash
7183  for the Windows binaries) to be recognized as a path.
7184
7185 \layout List
7186 \labelwidthstring 00.00.0000
7187
7188
7189 \series bold
7190 -
7191 \begin_inset ERT
7192 status Collapsed
7193
7194 \layout Standard
7195
7196 \backslash
7197 /
7198 \end_inset
7199
7200 -stack-auto
7201 \begin_inset LatexCommand \index{-\/-stack-auto}
7202
7203 \end_inset
7204
7205
7206 \series default
7207 \size large
7208 \emph on
7209
7210 \size default
7211 \emph default
7212 All functions in the source file will be compiled as
7213 \emph on
7214 reentrant
7215 \emph default
7216
7217 \begin_inset LatexCommand \index{reentrant}
7218
7219 \end_inset
7220
7221 , i.e.
7222  the parameters and local variables will be allocated on the stack
7223 \begin_inset LatexCommand \index{stack}
7224
7225 \end_inset
7226
7227 .
7228  See section
7229 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7230
7231 \end_inset
7232
7233  Parameters and Local Variables for more details.
7234  If this option is used all source files in the project should be compiled
7235  with this option.
7236  It automatically implies --int-long-reent and --float-reent.
7237
7238 \layout List
7239 \labelwidthstring 00.00.0000
7240
7241
7242 \series bold
7243 -
7244 \begin_inset ERT
7245 status Collapsed
7246
7247 \layout Standard
7248
7249 \backslash
7250 /
7251 \end_inset
7252
7253 -callee-saves
7254 \begin_inset LatexCommand \index{-\/-callee-saves}
7255
7256 \end_inset
7257
7258  function1[,function2][,function3]....
7259
7260 \series default
7261  The compiler by default uses a caller saves convention for register saving
7262  across function calls, however this can cause unnecessary register pushing
7263  & popping when calling small functions from larger functions.
7264  This option can be used to switch the register saving convention for the
7265  function names specified.
7266  The compiler will not save registers when calling these functions, no extra
7267  code will be generated at the entry & exit (function prologue
7268 \series bold
7269
7270 \begin_inset LatexCommand \index{function prologue}
7271
7272 \end_inset
7273
7274
7275 \series default
7276  & epilogue
7277 \series bold
7278
7279 \begin_inset LatexCommand \index{function epilogue}
7280
7281 \end_inset
7282
7283
7284 \series default
7285 ) for these functions to save & restore the registers used by these functions,
7286  this can SUBSTANTIALLY reduce code & improve run time performance of the
7287  generated code.
7288  In the future the compiler (with inter procedural analysis) will be able
7289  to determine the appropriate scheme to use for each function call.
7290  DO NOT use this option for built-in functions such as _mulint..., if this
7291  option is used for a library function the appropriate library function
7292  needs to be recompiled with the same option.
7293  If the project consists of multiple source files then all the source file
7294  should be compiled with the same -
7295 \begin_inset ERT
7296 status Collapsed
7297
7298 \layout Standard
7299
7300 \backslash
7301 /
7302 \end_inset
7303
7304 -callee-saves option string.
7305  Also see #pragma\SpecialChar ~
7306 callee_saves
7307 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7308
7309 \end_inset
7310
7311 .
7312 \layout List
7313 \labelwidthstring 00.00.0000
7314
7315
7316 \series bold
7317 -
7318 \begin_inset ERT
7319 status Collapsed
7320
7321 \layout Standard
7322
7323 \backslash
7324 /
7325 \end_inset
7326
7327 -debug
7328 \begin_inset LatexCommand \index{-\/-debug}
7329
7330 \end_inset
7331
7332
7333 \bar under
7334
7335 \series default
7336 \bar default
7337 When this option is used the compiler will generate debug information.
7338  The debug information collected in a file with .cdb extension can be used
7339  with the SDCDB.
7340  For more information see documentation for SDCDB.
7341  Another file with no extension contains debug information in AOMF or AOMF51
7342 \begin_inset LatexCommand \index{AOMF, AOMF51}
7343
7344 \end_inset
7345
7346  format which is commonly used by third party tools.
7347 \layout List
7348 \labelwidthstring 00.00.0000
7349
7350
7351 \series bold
7352 -S
7353 \begin_inset LatexCommand \index{-S}
7354
7355 \end_inset
7356
7357
7358 \size large
7359 \bar under
7360
7361 \series default
7362 \size default
7363 \bar default
7364 Stop after the stage of compilation proper; do not assemble.
7365  The output is an assembler code file for the input file specified.
7366 \layout List
7367 \labelwidthstring 00.00.0000
7368
7369
7370 \series bold
7371 -
7372 \begin_inset ERT
7373 status Collapsed
7374
7375 \layout Standard
7376
7377 \backslash
7378 /
7379 \end_inset
7380
7381 -int-long-reent
7382 \begin_inset LatexCommand \index{-\/-int-long-reent}
7383
7384 \end_inset
7385
7386
7387 \series default
7388  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7389  Note by default these libraries are compiled as non-reentrant.
7390  See section Installation for more details.
7391 \layout List
7392 \labelwidthstring 00.00.0000
7393
7394
7395 \series bold
7396 -
7397 \begin_inset ERT
7398 status Collapsed
7399
7400 \layout Standard
7401
7402 \backslash
7403 /
7404 \end_inset
7405
7406 -cyclomatic
7407 \begin_inset LatexCommand \index{-\/-cyclomatic}
7408
7409 \end_inset
7410
7411
7412 \bar under
7413
7414 \series default
7415 \bar default
7416 This option will cause the compiler to generate an information message for
7417  each function in the source file.
7418  The message contains some
7419 \emph on
7420 important
7421 \emph default
7422  information about the function.
7423  The number of edges and nodes the compiler detected in the control flow
7424  graph of the function, and most importantly the
7425 \emph on
7426 cyclomatic complexity
7427 \begin_inset LatexCommand \index{Cyclomatic complexity}
7428
7429 \end_inset
7430
7431
7432 \emph default
7433  see section on Cyclomatic Complexity for more details.
7434 \layout List
7435 \labelwidthstring 00.00.0000
7436
7437
7438 \series bold
7439 -
7440 \begin_inset ERT
7441 status Collapsed
7442
7443 \layout Standard
7444
7445 \backslash
7446 /
7447 \end_inset
7448
7449 -float-reent
7450 \begin_inset LatexCommand \index{-\/-float-reent}
7451
7452 \end_inset
7453
7454
7455 \series default
7456  Floating point library is compiled as reentrant
7457 \begin_inset LatexCommand \index{reentrant}
7458
7459 \end_inset
7460
7461 .
7462  See section Installation for more details.
7463 \layout List
7464 \labelwidthstring 00.00.0000
7465
7466
7467 \series bold
7468 -
7469 \begin_inset ERT
7470 status Collapsed
7471
7472 \layout Standard
7473
7474 \backslash
7475 /
7476 \end_inset
7477
7478 -main-return
7479 \begin_inset LatexCommand \index{-\/-main-return}
7480
7481 \end_inset
7482
7483
7484 \series default
7485  This option can be used if the code generated is called by a monitor program
7486  or if the main routine includes an endless loop.
7487  This option might result in slightly smaller code and save two bytes of
7488  stack space.
7489  The return from the 'main'
7490 \begin_inset LatexCommand \index{main return}
7491
7492 \end_inset
7493
7494  function will return to the function calling main.
7495  The default setting is to lock up i.e.
7496  generate a '
7497 \family typewriter
7498 sjmp .
7499 \family default
7500 '.
7501 \layout List
7502 \labelwidthstring 00.00.0000
7503
7504
7505 \series bold
7506 -
7507 \begin_inset ERT
7508 status Collapsed
7509
7510 \layout Standard
7511
7512 \backslash
7513 /
7514 \end_inset
7515
7516 -nostdinc
7517 \begin_inset LatexCommand \index{-\/-nostdinc}
7518
7519 \end_inset
7520
7521
7522 \series default
7523  This will prevent the compiler from passing on the default include path
7524  to the preprocessor.
7525 \layout List
7526 \labelwidthstring 00.00.0000
7527
7528
7529 \series bold
7530 -
7531 \begin_inset ERT
7532 status Collapsed
7533
7534 \layout Standard
7535
7536 \backslash
7537 /
7538 \end_inset
7539
7540 -nostdlib
7541 \begin_inset LatexCommand \index{-\/-nostdlib}
7542
7543 \end_inset
7544
7545
7546 \series default
7547  This will prevent the compiler from passing on the default library
7548 \begin_inset LatexCommand \index{Libraries}
7549
7550 \end_inset
7551
7552  path to the linker.
7553 \layout List
7554 \labelwidthstring 00.00.0000
7555
7556
7557 \series bold
7558 -
7559 \begin_inset ERT
7560 status Collapsed
7561
7562 \layout Standard
7563
7564 \backslash
7565 /
7566 \end_inset
7567
7568 -verbose
7569 \begin_inset LatexCommand \index{-\/-verbose}
7570
7571 \end_inset
7572
7573
7574 \series default
7575  Shows the various actions the compiler is performing.
7576 \layout List
7577 \labelwidthstring 00.00.0000
7578
7579
7580 \series bold
7581 -V
7582 \begin_inset LatexCommand \index{-V}
7583
7584 \end_inset
7585
7586
7587 \series default
7588  Shows the actual commands the compiler is executing.
7589 \layout List
7590 \labelwidthstring 00.00.0000
7591
7592
7593 \series bold
7594 -
7595 \begin_inset ERT
7596 status Collapsed
7597
7598 \layout Standard
7599
7600 \backslash
7601 /
7602 \end_inset
7603
7604 -no-c-code-in-asm
7605 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7606
7607 \end_inset
7608
7609
7610 \series default
7611  Hides your ugly and inefficient c-code from the asm file, so you can always
7612  blame the compiler :)
7613 \layout List
7614 \labelwidthstring 00.00.0000
7615
7616
7617 \series bold
7618 -
7619 \begin_inset ERT
7620 status Collapsed
7621
7622 \layout Standard
7623
7624 \backslash
7625 /
7626 \end_inset
7627
7628 -no-peep-comments
7629 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7630
7631 \end_inset
7632
7633
7634 \series default
7635  Will not include peep-hole comments in the generated files.
7636 \layout List
7637 \labelwidthstring 00.00.0000
7638
7639
7640 \series bold
7641 -
7642 \begin_inset ERT
7643 status Collapsed
7644
7645 \layout Standard
7646
7647 \backslash
7648 /
7649 \end_inset
7650
7651 -i-code-in-asm
7652 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7653
7654 \end_inset
7655
7656
7657 \series default
7658  Include i-codes in the asm file.
7659  Sounds like noise but is most helpful for debugging the compiler itself.
7660 \layout List
7661 \labelwidthstring 00.00.0000
7662
7663
7664 \series bold
7665 -
7666 \begin_inset ERT
7667 status Collapsed
7668
7669 \layout Standard
7670
7671 \backslash
7672 /
7673 \end_inset
7674
7675 -less-pedantic
7676 \begin_inset LatexCommand \index{-\/-less-pedantic}
7677
7678 \end_inset
7679
7680
7681 \series default
7682  Disable some of the more pedantic warnings
7683 \begin_inset LatexCommand \index{Warnings}
7684
7685 \end_inset
7686
7687  (jwk burps: please be more specific here, please!).
7688 \layout List
7689 \labelwidthstring 00.00.0000
7690
7691
7692 \series bold
7693 -
7694 \begin_inset ERT
7695 status Collapsed
7696
7697 \layout Standard
7698
7699 \backslash
7700 /
7701 \end_inset
7702
7703 -disable-warning\SpecialChar ~
7704 <nnnn>
7705 \begin_inset LatexCommand \index{-\/-disable-warning}
7706
7707 \end_inset
7708
7709
7710 \series default
7711  Disable specific warning with number <nnnn>.
7712 \layout List
7713 \labelwidthstring 00.00.0000
7714
7715
7716 \series bold
7717 -
7718 \begin_inset ERT
7719 status Collapsed
7720
7721 \layout Standard
7722
7723 \backslash
7724 /
7725 \end_inset
7726
7727 -print-search-dirs
7728 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7729
7730 \end_inset
7731
7732
7733 \series default
7734  Display the directories in the compiler's search path
7735 \layout List
7736 \labelwidthstring 00.00.0000
7737
7738
7739 \series bold
7740 -
7741 \begin_inset ERT
7742 status Collapsed
7743
7744 \layout Standard
7745
7746 \backslash
7747 /
7748 \end_inset
7749
7750 -vc
7751 \begin_inset LatexCommand \index{-\/-vc}
7752
7753 \end_inset
7754
7755
7756 \series default
7757  Display errors and warnings using MSVC style, so you can use SDCC with
7758  visual studio.
7759 \layout List
7760 \labelwidthstring 00.00.0000
7761
7762
7763 \series bold
7764 -
7765 \begin_inset ERT
7766 status Collapsed
7767
7768 \layout Standard
7769
7770 \backslash
7771 /
7772 \end_inset
7773
7774 -use-stdout
7775 \begin_inset LatexCommand \index{-\/-use-stdout}
7776
7777 \end_inset
7778
7779
7780 \series default
7781  Send errors and warnings to stdout instead of stderr.
7782 \layout List
7783 \labelwidthstring 00.00.0000
7784
7785
7786 \series bold
7787 -Wa\SpecialChar ~
7788 asmOption[,asmOption]
7789 \series default
7790
7791 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7792
7793 \end_inset
7794
7795 ...
7796  Pass the asmOption to the assembler
7797 \begin_inset LatexCommand \index{Options assembler}
7798
7799 \end_inset
7800
7801
7802 \begin_inset LatexCommand \index{Assembler options}
7803
7804 \end_inset
7805
7806 .
7807  See file sdcc/as/doc/asxhtm.html for assembler options.cd
7808 \layout List
7809 \labelwidthstring 00.00.0000
7810
7811
7812 \series bold
7813 -
7814 \begin_inset ERT
7815 status Collapsed
7816
7817 \layout Standard
7818
7819 \backslash
7820 /
7821 \end_inset
7822
7823 -std-sdcc89
7824 \begin_inset LatexCommand \index{-\/-std-sdcc89}
7825
7826 \end_inset
7827
7828
7829 \series default
7830  Generally follow the C89 standard, but allow SDCC features that conflict
7831  with the standard (default).
7832 \layout List
7833 \labelwidthstring 00.00.0000
7834
7835
7836 \series bold
7837 -
7838 \begin_inset ERT
7839 status Collapsed
7840
7841 \layout Standard
7842
7843 \backslash
7844 /
7845 \end_inset
7846
7847 -std-c89
7848 \begin_inset LatexCommand \index{-\/-std-c89}
7849
7850 \end_inset
7851
7852
7853 \series default
7854  Follow the C89 standard and disable SDCC features that conflict with the
7855  standard.
7856 \layout List
7857 \labelwidthstring 00.00.0000
7858
7859
7860 \series bold
7861 -
7862 \begin_inset ERT
7863 status Collapsed
7864
7865 \layout Standard
7866
7867 \backslash
7868 /
7869 \end_inset
7870
7871 -std-sdcc99
7872 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7873
7874 \end_inset
7875
7876
7877 \series default
7878  Generally follow the C99 standard, but allow SDCC features that conflict
7879  with the standard (incomplete support).
7880 \layout List
7881 \labelwidthstring 00.00.0000
7882
7883
7884 \series bold
7885 -
7886 \begin_inset ERT
7887 status Collapsed
7888
7889 \layout Standard
7890
7891 \backslash
7892 /
7893 \end_inset
7894
7895 -std-c99
7896 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7897
7898 \end_inset
7899
7900
7901 \series default
7902  Follow the C99 standard and disable SDCC features that conflict with the
7903  standard (incomplete support).
7904 \layout List
7905 \labelwidthstring 00.00.0000
7906
7907
7908 \series bold
7909 -
7910 \begin_inset ERT
7911 status Collapsed
7912
7913 \layout Standard
7914
7915 \backslash
7916 /
7917 \end_inset
7918
7919 -codeseg
7920 \series default
7921
7922 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
7923
7924 \end_inset
7925
7926 \SpecialChar ~
7927 <Name> The name to be used for the code
7928 \begin_inset LatexCommand \index{code}
7929
7930 \end_inset
7931
7932  segment, default CSEG.
7933  This is useful if you need to tell the compiler to put the code in a special
7934  segment so you can later on tell the linker to put this segment in a special
7935  place in memory.
7936  Can be used for instance when using bank switching to put the code in a
7937  bank.
7938 \layout List
7939 \labelwidthstring 00.00.0000
7940
7941
7942 \series bold
7943 -
7944 \begin_inset ERT
7945 status Collapsed
7946
7947 \layout Standard
7948
7949 \backslash
7950 /
7951 \end_inset
7952
7953 -constseg
7954 \series default
7955
7956 \begin_inset LatexCommand \index{-\/-constseg <Value>}
7957
7958 \end_inset
7959
7960 \SpecialChar ~
7961 <Name> The name to be used for the const
7962 \begin_inset LatexCommand \index{code}
7963
7964 \end_inset
7965
7966  segment, default CONST.
7967  This is useful if you need to tell the compiler to put the const data in
7968  a special segment so you can later on tell the linker to put this segment
7969  in a special place in memory.
7970  Can be used for instance when using bank switching to put the const data
7971  in a bank.
7972 \layout List
7973 \labelwidthstring 00.00.0000
7974
7975
7976 \series bold
7977 more-pedantic
7978 \series default
7979  Actually this is
7980 \series bold
7981 \emph on
7982 not
7983 \series default
7984 \emph default
7985  a SDCC compiler option but if you want
7986 \emph on
7987 more
7988 \emph default
7989  warnings you can use a separate tool dedicated to syntax checking like
7990  splint
7991 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
7992
7993 \end_inset
7994
7995
7996 \begin_inset LatexCommand \index{lint (syntax checking tool)}
7997
7998 \end_inset
7999
8000
8001 \begin_inset LatexCommand \url{http://www.splint.org}
8002
8003 \end_inset
8004
8005 .
8006  To make your source files parseable by splint you will have to include
8007
8008 \family sans
8009 lint.h
8010 \family default
8011
8012 \begin_inset LatexCommand \index{splint (syntax checking tool)}
8013
8014 \end_inset
8015
8016  in your source file and add brackets around extended keywords (like
8017 \family sans
8018
8019 \begin_inset Quotes sld
8020 \end_inset
8021
8022 __at\SpecialChar ~
8023
8024 \series bold
8025 (
8026 \series default
8027 0xab
8028 \series bold
8029 )
8030 \series default
8031
8032 \begin_inset Quotes srd
8033 \end_inset
8034
8035
8036 \family default
8037  and
8038 \family sans
8039
8040 \begin_inset Quotes sld
8041 \end_inset
8042
8043 __interrupt\SpecialChar ~
8044 (2)
8045 \begin_inset Quotes srd
8046 \end_inset
8047
8048
8049 \family default
8050 ).
8051
8052 \newline
8053 Splint has an excellent on line manual at
8054 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
8055
8056 \end_inset
8057
8058  and it's capabilities go beyond pure syntax checking.
8059  You'll need to tell splint the location of SDCC's include files so a typical
8060  command line could look like this:
8061 \newline
8062
8063 \family sans
8064 splint\SpecialChar ~
8065 -I\SpecialChar ~
8066 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
8067 \SpecialChar ~
8068 myprogram.c
8069 \layout Subsection
8070
8071 Intermediate Dump Options
8072 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
8073
8074 \end_inset
8075
8076
8077 \begin_inset LatexCommand \index{Options intermediate dump}
8078
8079 \end_inset
8080
8081
8082 \begin_inset LatexCommand \index{Intermediate dump options}
8083
8084 \end_inset
8085
8086
8087 \layout Standard
8088
8089 The following options are provided for the purpose of retargetting and debugging
8090  the compiler.
8091  They provide a means to dump the intermediate code (iCode
8092 \begin_inset LatexCommand \index{iCode}
8093
8094 \end_inset
8095
8096 ) generated by the compiler in human readable form at various stages of
8097  the compilation process.
8098  More on iCodes see chapter
8099 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8100
8101 \end_inset
8102
8103
8104 \begin_inset Quotes srd
8105 \end_inset
8106
8107 The anatomy of the compiler
8108 \begin_inset Quotes srd
8109 \end_inset
8110
8111 .
8112 \layout List
8113 \labelwidthstring 00.00.0000
8114
8115
8116 \series bold
8117 -
8118 \begin_inset ERT
8119 status Collapsed
8120
8121 \layout Standard
8122
8123 \backslash
8124 /
8125 \end_inset
8126
8127 -dumpraw
8128 \begin_inset LatexCommand \index{-\/-dumpraw}
8129
8130 \end_inset
8131
8132
8133 \series default
8134  This option will cause the compiler to dump the intermediate code into
8135  a file of named
8136 \emph on
8137 <source filename>.dumpraw
8138 \emph default
8139  just after the intermediate code has been generated for a function, i.e.
8140  before any optimizations are done.
8141  The basic blocks
8142 \begin_inset LatexCommand \index{Basic blocks}
8143
8144 \end_inset
8145
8146  at this stage ordered in the depth first number, so they may not be in
8147  sequence of execution.
8148 \layout List
8149 \labelwidthstring 00.00.0000
8150
8151
8152 \series bold
8153 -
8154 \begin_inset ERT
8155 status Collapsed
8156
8157 \layout Standard
8158
8159 \backslash
8160 /
8161 \end_inset
8162
8163 -dumpgcse
8164 \begin_inset LatexCommand \index{-\/-dumpgcse}
8165
8166 \end_inset
8167
8168
8169 \series default
8170  Will create a dump of iCode's, after global subexpression elimination
8171 \begin_inset LatexCommand \index{Global subexpression elimination}
8172
8173 \end_inset
8174
8175 , into a file named
8176 \emph on
8177 <source filename>.dumpgcse.
8178 \layout List
8179 \labelwidthstring 00.00.0000
8180
8181
8182 \series bold
8183 -
8184 \begin_inset ERT
8185 status Collapsed
8186
8187 \layout Standard
8188
8189 \backslash
8190 /
8191 \end_inset
8192
8193 -dumpdeadcode
8194 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8195
8196 \end_inset
8197
8198
8199 \series default
8200  Will create a dump of iCode's, after deadcode elimination
8201 \begin_inset LatexCommand \index{Dead-code elimination}
8202
8203 \end_inset
8204
8205 , into a file named
8206 \emph on
8207 <source filename>.dumpdeadcode.
8208 \layout List
8209 \labelwidthstring 00.00.0000
8210
8211
8212 \series bold
8213 -
8214 \begin_inset ERT
8215 status Collapsed
8216
8217 \layout Standard
8218
8219 \backslash
8220 /
8221 \end_inset
8222
8223 -dumploop
8224 \begin_inset LatexCommand \index{-\/-dumploop}
8225
8226 \end_inset
8227
8228
8229 \series default
8230 \size large
8231
8232 \size default
8233 Will create a dump of iCode's, after loop optimizations
8234 \begin_inset LatexCommand \index{Loop optimization}
8235
8236 \end_inset
8237
8238 , into a file named
8239 \emph on
8240 <source filename>.dumploop.
8241 \layout List
8242 \labelwidthstring 00.00.0000
8243
8244
8245 \series bold
8246 -
8247 \begin_inset ERT
8248 status Collapsed
8249
8250 \layout Standard
8251
8252 \backslash
8253 /
8254 \end_inset
8255
8256 -dumprange
8257 \begin_inset LatexCommand \index{-\/-dumprange}
8258
8259 \end_inset
8260
8261
8262 \series default
8263 \size large
8264
8265 \size default
8266 Will create a dump of iCode's, after live range analysis
8267 \begin_inset LatexCommand \index{Live range analysis}
8268
8269 \end_inset
8270
8271 , into a file named
8272 \emph on
8273 <source filename>.dumprange.
8274 \layout List
8275 \labelwidthstring 00.00.0000
8276
8277
8278 \series bold
8279 -
8280 \begin_inset ERT
8281 status Collapsed
8282
8283 \layout Standard
8284
8285 \backslash
8286 /
8287 \end_inset
8288
8289 -dumlrange
8290 \begin_inset LatexCommand \index{-\/-dumlrange}
8291
8292 \end_inset
8293
8294
8295 \series default
8296  Will dump the life ranges
8297 \begin_inset LatexCommand \index{Live range analysis}
8298
8299 \end_inset
8300
8301  for all symbols.
8302 \layout List
8303 \labelwidthstring 00.00.0000
8304
8305
8306 \series bold
8307 -
8308 \begin_inset ERT
8309 status Collapsed
8310
8311 \layout Standard
8312
8313 \backslash
8314 /
8315 \end_inset
8316
8317 -dumpregassign
8318 \begin_inset LatexCommand \index{-\/-dumpregassign}
8319
8320 \end_inset
8321
8322
8323 \bar under
8324
8325 \series default
8326 \bar default
8327 Will create a dump of iCode's, after register assignment
8328 \begin_inset LatexCommand \index{Register assignment}
8329
8330 \end_inset
8331
8332 , into a file named
8333 \emph on
8334 <source filename>.dumprassgn.
8335 \layout List
8336 \labelwidthstring 00.00.0000
8337
8338
8339 \series bold
8340 -
8341 \begin_inset ERT
8342 status Collapsed
8343
8344 \layout Standard
8345
8346 \backslash
8347 /
8348 \end_inset
8349
8350 -dumplrange
8351 \begin_inset LatexCommand \index{-\/-dumplrange}
8352
8353 \end_inset
8354
8355
8356 \series default
8357  Will create a dump of the live ranges of iTemp's
8358 \layout List
8359 \labelwidthstring 00.00.0000
8360
8361
8362 \series bold
8363 -
8364 \begin_inset ERT
8365 status Collapsed
8366
8367 \layout Standard
8368
8369 \backslash
8370 /
8371 \end_inset
8372
8373 -dumpall
8374 \begin_inset LatexCommand \index{-\/-dumpall}
8375
8376 \end_inset
8377
8378
8379 \size large
8380 \bar under
8381
8382 \series default
8383 \size default
8384 \bar default
8385 Will cause all the above mentioned dumps to be created.
8386 \layout Subsection
8387
8388 Redirecting output on Windows Shells
8389 \layout Standard
8390
8391 By default SDCC writes it's error messages to
8392 \begin_inset Quotes sld
8393 \end_inset
8394
8395 standard error
8396 \begin_inset Quotes srd
8397 \end_inset
8398
8399 .
8400  To force all messages to
8401 \begin_inset Quotes sld
8402 \end_inset
8403
8404 standard output
8405 \begin_inset Quotes srd
8406 \end_inset
8407
8408  use
8409 \series bold
8410 -
8411 \series default
8412 \emph on
8413
8414 \begin_inset ERT
8415 status Collapsed
8416
8417 \layout Standard
8418
8419 \backslash
8420 /
8421 \end_inset
8422
8423
8424 \series bold
8425 \emph default
8426 -
8427 \series default
8428 use-stdout
8429 \begin_inset LatexCommand \index{-\/-use-stdout}
8430
8431 \end_inset
8432
8433 .
8434  Additionally, if you happen to have visual studio installed in your windows
8435  machine, you can use it to compile your sources using a custom build and
8436  the SDCC -
8437 \emph on
8438
8439 \begin_inset ERT
8440 status Collapsed
8441
8442 \layout Standard
8443
8444 \backslash
8445 /
8446 \end_inset
8447
8448
8449 \emph default
8450 -vc
8451 \begin_inset LatexCommand \index{-\/-vc}
8452
8453 \end_inset
8454
8455  option.
8456  Something like this should work:
8457 \newline
8458
8459 \newline
8460
8461 \series bold
8462 c:
8463 \backslash
8464 sdcc
8465 \backslash
8466 bin
8467 \backslash
8468 sdcc.exe -
8469 \series default
8470 \emph on
8471
8472 \begin_inset ERT
8473 status Collapsed
8474
8475 \layout Standard
8476
8477 \backslash
8478 /
8479 \end_inset
8480
8481
8482 \series bold
8483 \emph default
8484 -vc -
8485 \series default
8486 \emph on
8487
8488 \begin_inset ERT
8489 status Collapsed
8490
8491 \layout Standard
8492
8493 \backslash
8494 /
8495 \end_inset
8496
8497
8498 \series bold
8499 \emph default
8500 -model-large -c $(InputPath)
8501 \layout Section
8502
8503 Environment variables
8504 \begin_inset LatexCommand \index{Environment variables}
8505
8506 \end_inset
8507
8508
8509 \layout Standard
8510
8511 SDCC recognizes the following environment variables:
8512 \layout List
8513 \labelwidthstring 00.00.0000
8514
8515
8516 \series bold
8517 SDCC_LEAVE_SIGNALS
8518 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
8519
8520 \end_inset
8521
8522
8523 \series default
8524  SDCC installs a signal handler
8525 \begin_inset LatexCommand \index{signal handler}
8526
8527 \end_inset
8528
8529  to be able to delete temporary files after an user break (^C) or an exception.
8530  If this environment variable is set, SDCC won't install the signal handler
8531  in order to be able to debug SDCC.
8532 \layout List
8533 \labelwidthstring 00.00.0000
8534
8535
8536 \series bold
8537 TMP,\SpecialChar ~
8538 TEMP,\SpecialChar ~
8539 TMPDIR
8540 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
8541
8542 \end_inset
8543
8544
8545 \series default
8546  Path, where temporary files will be created.
8547  The order of the variables is the search order.
8548  In a standard *nix environment these variables are not set, and there's
8549  no need to set them.
8550  On Windows it's recommended to set one of them.
8551 \layout List
8552 \labelwidthstring 00.00.0000
8553
8554
8555 \series bold
8556 SDCC_HOME
8557 \begin_inset LatexCommand \index{SDCC\_HOME}
8558
8559 \end_inset
8560
8561
8562 \series default
8563  Path, see section
8564 \begin_inset LatexCommand \ref{sub:Install-paths}
8565
8566 \end_inset
8567
8568 \SpecialChar ~
8569
8570 \begin_inset Quotes sld
8571 \end_inset
8572
8573  Install Paths
8574 \begin_inset Quotes srd
8575 \end_inset
8576
8577 .
8578 \layout List
8579 \labelwidthstring 00.00.0000
8580
8581
8582 \series bold
8583 SDCC_INCLUDE
8584 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8585
8586 \end_inset
8587
8588
8589 \series default
8590  Path, see section
8591 \begin_inset LatexCommand \ref{sub:Search-Paths}
8592
8593 \end_inset
8594
8595 \SpecialChar ~
8596
8597 \begin_inset Quotes sld
8598 \end_inset
8599
8600 Search Paths
8601 \begin_inset Quotes srd
8602 \end_inset
8603
8604 .
8605 \layout List
8606 \labelwidthstring 00.00.0000
8607
8608
8609 \series bold
8610 SDCC_LIB
8611 \begin_inset LatexCommand \index{SDCC\_LIB}
8612
8613 \end_inset
8614
8615
8616 \series default
8617  Path, see section
8618 \begin_inset LatexCommand \ref{sub:Search-Paths}
8619
8620 \end_inset
8621
8622 \SpecialChar ~
8623
8624 \begin_inset Quotes sld
8625 \end_inset
8626
8627 Search Paths
8628 \begin_inset Quotes srd
8629 \end_inset
8630
8631 ..
8632 \layout Standard
8633
8634 There are some more environment variables recognized by SDCC, but these
8635  are solely used for debugging purposes.
8636  They can change or disappear very quickly, and will never be documented.
8637 \layout Section
8638
8639 Storage Class Language Extensions
8640 \layout Subsection
8641
8642 MCS51/DS390 Storage Class
8643 \begin_inset LatexCommand \index{Storage class}
8644
8645 \end_inset
8646
8647  Language Extensions
8648 \layout Standard
8649
8650 In addition to the ANSI storage classes SDCC allows the following MCS51
8651  specific storage classes:
8652 \layout Subsubsection
8653
8654 data
8655 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8656
8657 \end_inset
8658
8659
8660 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
8661
8662 \end_inset
8663
8664  / near
8665 \begin_inset LatexCommand \index{near (storage class)}
8666
8667 \end_inset
8668
8669
8670 \begin_inset LatexCommand \index{\_\_near (storage class)}
8671
8672 \end_inset
8673
8674
8675 \layout Standard
8676
8677 This is the
8678 \series bold
8679 default
8680 \series default
8681  storage class for the Small Memory model (
8682 \emph on
8683 data
8684 \emph default
8685  and
8686 \emph on
8687 near
8688 \emph default
8689  can be used synonymously).
8690  Variables declared with this storage class will be allocated in the directly
8691  addressable portion of the internal RAM of a 8051, e.g.:
8692 \layout Verse
8693
8694
8695 \family typewriter
8696 data unsigned char test_data;
8697 \layout Standard
8698
8699 Writing 0x01 to this variable generates the assembly code:
8700 \layout Verse
8701
8702
8703 \family typewriter
8704 75*00 01\SpecialChar ~
8705 \SpecialChar ~
8706 \SpecialChar ~
8707 mov\SpecialChar ~
8708 \SpecialChar ~
8709 _test_data,#0x01
8710 \layout Subsubsection
8711
8712 xdata
8713 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8714
8715 \end_inset
8716
8717
8718 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
8719
8720 \end_inset
8721
8722  / far
8723 \begin_inset LatexCommand \index{far (storage class)}
8724
8725 \end_inset
8726
8727
8728 \begin_inset LatexCommand \index{\_\_far (storage class)}
8729
8730 \end_inset
8731
8732
8733 \layout Standard
8734
8735 Variables declared with this storage class will be placed in the external
8736  RAM.
8737  This is the
8738 \series bold
8739 default
8740 \series default
8741  storage class for the Large Memory model, e.g.:
8742 \layout Verse
8743
8744
8745 \family typewriter
8746 xdata unsigned char test_xdata;
8747 \layout Standard
8748
8749 Writing 0x01 to this variable generates the assembly code:
8750 \layout Verse
8751
8752
8753 \family typewriter
8754 90s00r00\SpecialChar ~
8755 \SpecialChar ~
8756 \SpecialChar ~
8757 mov\SpecialChar ~
8758 \SpecialChar ~
8759 dptr,#_test_xdata
8760 \newline
8761 74\SpecialChar ~
8762 01\SpecialChar ~
8763 \SpecialChar ~
8764 \SpecialChar ~
8765 \SpecialChar ~
8766 \SpecialChar ~
8767 \SpecialChar ~
8768 mov\SpecialChar ~
8769 \SpecialChar ~
8770 a,#0x01
8771 \newline
8772 F0\SpecialChar ~
8773 \SpecialChar ~
8774 \SpecialChar ~
8775 \SpecialChar ~
8776 \SpecialChar ~
8777 \SpecialChar ~
8778 \SpecialChar ~
8779 \SpecialChar ~
8780 \SpecialChar ~
8781 movx\SpecialChar ~
8782 @dptr,a
8783 \layout Subsubsection
8784
8785 idata
8786 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8787
8788 \end_inset
8789
8790
8791 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
8792
8793 \end_inset
8794
8795
8796 \layout Standard
8797
8798 Variables declared with this storage class will be allocated into the indirectly
8799  addressable portion of the internal ram of a 8051, e.g.:
8800 \layout Verse
8801
8802
8803 \family typewriter
8804 idata unsigned char test_idata;
8805 \layout Standard
8806
8807 Writing 0x01 to this variable generates the assembly code:
8808 \layout Verse
8809
8810
8811 \family typewriter
8812 78r00\SpecialChar ~
8813 \SpecialChar ~
8814 \SpecialChar ~
8815 \SpecialChar ~
8816 \SpecialChar ~
8817 \SpecialChar ~
8818 \SpecialChar ~
8819 mov\SpecialChar ~
8820 \SpecialChar ~
8821 r0,#_test_idata
8822 \newline
8823 76\SpecialChar ~
8824 01\SpecialChar ~
8825 \SpecialChar ~
8826 \SpecialChar ~
8827 \SpecialChar ~
8828 \SpecialChar ~
8829 \SpecialChar ~
8830 \SpecialChar ~
8831 mov\SpecialChar ~
8832 \SpecialChar ~
8833 @r0,#0x01
8834 \layout Standard
8835
8836 Please note, the first 128 byte of idata physically access the same RAM
8837  as the data memory.
8838  The original 8051 had 128 byte idata memory, nowadays most devices have
8839  256 byte idata memory.
8840  The stack
8841 \begin_inset LatexCommand \index{stack}
8842
8843 \end_inset
8844
8845  is located in idata memory.
8846 \layout Subsubsection
8847
8848 pdata
8849 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8850
8851 \end_inset
8852
8853
8854 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
8855
8856 \end_inset
8857
8858
8859 \layout Standard
8860
8861 Paged xdata access is just as straightforward as using the other addressing
8862  modes of a 8051.
8863  It is typically located at the start of xdata and has a maximum size of
8864  256 bytes.
8865  The following example writes 0x01 to the pdata variable.
8866  Please note, pdata access physically accesses xdata memory.
8867  The high byte of the address is determined by port P2
8868 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8869
8870 \end_inset
8871
8872 (or in case of some 8051 variants by a separate Special Function Register,
8873  see section
8874 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8875
8876 \end_inset
8877
8878 ).
8879  This is the
8880 \series bold
8881 default
8882 \series default
8883  storage class for the Medium Memory model, e.g.:
8884 \layout Verse
8885
8886
8887 \family typewriter
8888 pdata unsigned char test_pdata;
8889 \layout Standard
8890
8891 Writing 0x01 to this variable generates the assembly code:
8892 \layout Verse
8893
8894
8895 \family typewriter
8896 78r00\SpecialChar ~
8897 \SpecialChar ~
8898 \SpecialChar ~
8899 \SpecialChar ~
8900 \SpecialChar ~
8901 \SpecialChar ~
8902 mov r0,#_test_pdata
8903 \newline
8904 74 01\SpecialChar ~
8905 \SpecialChar ~
8906 \SpecialChar ~
8907 \SpecialChar ~
8908 \SpecialChar ~
8909 \SpecialChar ~
8910 mov a,#0x01
8911 \newline
8912 F2\SpecialChar ~
8913 \SpecialChar ~
8914 \SpecialChar ~
8915 \SpecialChar ~
8916 \SpecialChar ~
8917 \SpecialChar ~
8918 \SpecialChar ~
8919 \SpecialChar ~
8920 \SpecialChar ~
8921 movx @r0,a
8922 \layout Standard
8923
8924 If the -
8925 \begin_inset ERT
8926 status Collapsed
8927
8928 \layout Standard
8929
8930 \backslash
8931 /
8932 \end_inset
8933
8934 -xstack
8935 \begin_inset LatexCommand \index{-\/-xstack}
8936
8937 \end_inset
8938
8939  option is used the pdata memory area is followed by the xstack memory area
8940  and the sum of their sizes is limited to 256 bytes.
8941 \layout Subsubsection
8942
8943 code
8944 \begin_inset LatexCommand \index{code}
8945
8946 \end_inset
8947
8948
8949 \begin_inset LatexCommand \index{\_\_code}
8950
8951 \end_inset
8952
8953
8954 \layout Standard
8955
8956 'Variables' declared with this storage class will be placed in the code
8957  memory:
8958 \layout Verse
8959
8960
8961 \family typewriter
8962 code unsigned char test_code;
8963 \layout Standard
8964
8965 Read access to this variable generates the assembly code:
8966 \layout Verse
8967
8968
8969 \family typewriter
8970 90s00r6F\SpecialChar ~
8971 \SpecialChar ~
8972 \SpecialChar ~
8973 mov dptr,#_test_code
8974 \newline
8975 E4\SpecialChar ~
8976 \SpecialChar ~
8977 \SpecialChar ~
8978 \SpecialChar ~
8979 \SpecialChar ~
8980 \SpecialChar ~
8981 \SpecialChar ~
8982 \SpecialChar ~
8983 \SpecialChar ~
8984 clr a
8985 \newline
8986 93\SpecialChar ~
8987 \SpecialChar ~
8988 \SpecialChar ~
8989 \SpecialChar ~
8990 \SpecialChar ~
8991 \SpecialChar ~
8992 \SpecialChar ~
8993 \SpecialChar ~
8994 \SpecialChar ~
8995 movc a,@a+dptr
8996 \layout Standard
8997
8998
8999 \family typewriter
9000 char
9001 \family default
9002  indexed arrays of characters in code memory can be accessed efficiently:
9003 \layout Verse
9004
9005
9006 \family typewriter
9007 code char test_array[] = {'c','h','e','a','p'};
9008 \layout Standard
9009
9010 Read access to this array using an 8-bit unsigned index generates the assembly
9011  code:
9012 \layout Verse
9013
9014
9015 \family typewriter
9016 E5*00\SpecialChar ~
9017 \SpecialChar ~
9018 \SpecialChar ~
9019 \SpecialChar ~
9020 \SpecialChar ~
9021 \SpecialChar ~
9022 mov a,_index
9023 \layout Verse
9024
9025
9026 \family typewriter
9027 90s00r41\SpecialChar ~
9028 \SpecialChar ~
9029 \SpecialChar ~
9030 mov dptr,#_test_array
9031 \layout Verse
9032
9033
9034 \family typewriter
9035 93\SpecialChar ~
9036 \SpecialChar ~
9037 \SpecialChar ~
9038 \SpecialChar ~
9039 \SpecialChar ~
9040 \SpecialChar ~
9041 \SpecialChar ~
9042 \SpecialChar ~
9043 \SpecialChar ~
9044 movc a,@a+dptr
9045 \layout Subsubsection
9046
9047 bit
9048 \begin_inset LatexCommand \index{bit}
9049
9050 \end_inset
9051
9052
9053 \begin_inset LatexCommand \index{\_\_bit}
9054
9055 \end_inset
9056
9057
9058 \layout Standard
9059
9060 This is a data-type and a storage class specifier.
9061  When a variable is declared as a bit, it is allocated into the bit addressable
9062  memory of 8051, e.g.:
9063 \layout Verse
9064
9065
9066 \family typewriter
9067 bit test_bit;
9068 \layout Standard
9069
9070 Writing 1 to this variable generates the assembly code:
9071 \layout Verse
9072
9073
9074 \family typewriter
9075 D2*00\SpecialChar ~
9076 \SpecialChar ~
9077 \SpecialChar ~
9078 \SpecialChar ~
9079 \SpecialChar ~
9080 \SpecialChar ~
9081 \SpecialChar ~
9082 setb\SpecialChar ~
9083 _test_bit
9084 \layout Standard
9085
9086 The bit addressable memory consists of 128 bits which are located from 0x20
9087  to 0x2f in data memory.
9088
9089 \newline
9090 Apart from this 8051 specific storage class most architectures support ANSI-C
9091  bitfields
9092 \begin_inset LatexCommand \index{bitfields}
9093
9094 \end_inset
9095
9096
9097 \begin_inset Foot
9098 collapsed false
9099
9100 \layout Standard
9101
9102 Not really meant as examples, but nevertheless showing what bitfields are
9103  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9104 \end_inset
9105
9106 .
9107  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9108  signed modifier are implemented as unsigned.
9109 \layout Subsubsection
9110
9111 sfr
9112 \begin_inset LatexCommand \index{sfr}
9113
9114 \end_inset
9115
9116
9117 \begin_inset LatexCommand \index{\_\_sfr}
9118
9119 \end_inset
9120
9121  / sfr16
9122 \begin_inset LatexCommand \index{sfr16}
9123
9124 \end_inset
9125
9126
9127 \begin_inset LatexCommand \index{\_\_sfr16}
9128
9129 \end_inset
9130
9131  / sfr32
9132 \begin_inset LatexCommand \index{sfr32}
9133
9134 \end_inset
9135
9136
9137 \begin_inset LatexCommand \index{\_\_sfr32}
9138
9139 \end_inset
9140
9141  / sbit
9142 \begin_inset LatexCommand \index{\_\_sbit}
9143
9144 \end_inset
9145
9146
9147 \layout Standard
9148
9149 Like the bit keyword,
9150 \emph on
9151 sfr / sfr16 / sfr32 / sbit
9152 \emph default
9153 signify both a data-type and storage class, they are used to describe the
9154
9155 \emph on
9156 s
9157 \emph default
9158 pecial
9159 \emph on
9160 f
9161 \emph default
9162 unction
9163 \emph on
9164 r
9165 \emph default
9166 egisters and
9167 \emph on
9168 s
9169 \emph default
9170 pecial
9171 \emph on
9172 bit
9173 \emph default
9174  variables of a 8051, eg:
9175 \layout Verse
9176
9177
9178 \family typewriter
9179 sfr at
9180 \begin_inset LatexCommand \index{at}
9181
9182 \end_inset
9183
9184
9185 \begin_inset LatexCommand \index{\_\_at}
9186
9187 \end_inset
9188
9189  0x80 P0;\SpecialChar ~
9190  /* special function register P0 at location 0x80 */
9191 \newline
9192 /* 16 bit special function register combination for timer 0 */
9193 \newline
9194 /* with the high byte at location 0x8C and the low byte at location 0x8A
9195  */
9196 \newline
9197 sfr16 at
9198 \begin_inset LatexCommand \index{at}
9199
9200 \end_inset
9201
9202
9203 \begin_inset LatexCommand \index{\_\_at}
9204
9205 \end_inset
9206
9207  0x8C8A TMR0;
9208 \newline
9209 sbit at 0xd7 CY; /* CY (Carry Flag
9210 \begin_inset LatexCommand \index{Flags}
9211
9212 \end_inset
9213
9214
9215 \begin_inset LatexCommand \index{Carry flag}
9216
9217 \end_inset
9218
9219 ) */
9220 \layout Standard
9221
9222 Special function registers which are located on an address dividable by
9223  8 are bit-addressable, an
9224 \emph on
9225  sbit
9226 \emph default
9227  addresses a specific bit within these sfr.
9228 \newline
9229 16 Bit and 32 bit special function register combinations which require a
9230  certain access order are better not declared using
9231 \emph on
9232 sfr16
9233 \emph default
9234  or
9235 \emph on
9236 sfr32.
9237
9238 \emph default
9239  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9240  this is not guaranteed.
9241 \layout Subsubsection
9242
9243 Pointers
9244 \begin_inset LatexCommand \index{Pointer}
9245
9246 \end_inset
9247
9248  to MCS51/DS390 specific memory spaces
9249 \layout Standard
9250
9251 SDCC allows (via language extensions) pointers to explicitly point to any
9252  of the memory spaces
9253 \begin_inset LatexCommand \index{Memory model}
9254
9255 \end_inset
9256
9257  of the 8051.
9258  In addition to the explicit pointers, the compiler uses (by default) generic
9259  pointers which can be used to point to any of the memory spaces.
9260 \newline
9261
9262 \newline
9263 Pointer declaration examples:
9264 \layout Verse
9265
9266
9267 \family typewriter
9268 /* pointer physically in internal ram pointing to object in external ram
9269  */
9270 \newline
9271 xdata unsigned char * data p;
9272 \newline
9273
9274 \newline
9275 /* pointer physically in external ram pointing to object in internal ram
9276  */
9277 \newline
9278 data unsigned char * xdata p;
9279 \newline
9280
9281 \newline
9282 /* pointer physically in code rom pointing to data in xdata space */
9283 \newline
9284 xdata unsigned char * code p;
9285 \newline
9286
9287 \newline
9288 /* pointer physically in code space pointing to data in code space */
9289 \newline
9290 code unsigned char * code p;
9291 \newline
9292
9293 \newline
9294 /* the following is a generic pointer physically located in xdata space
9295  */
9296 \newline
9297 char * xdata p;
9298 \newline
9299
9300 \newline
9301 /* the following is a function pointer physically located in data space
9302  */
9303 \newline
9304 char (* data fp)(void);
9305 \layout Standard
9306
9307 Well you get the idea.
9308
9309 \newline
9310
9311 \newline
9312 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9313 \emph on
9314 generic
9315 \emph default
9316  pointers.
9317
9318 \size small
9319
9320 \newline
9321
9322 \newline
9323
9324 \size default
9325 The highest order byte of the
9326 \emph on
9327 generic
9328 \emph default
9329  pointers contains the data space information.
9330  Assembler support routines are called whenever data is stored or retrieved
9331  using
9332 \emph on
9333 generic
9334 \emph default
9335  pointers.
9336  These are useful for developing reusable library
9337 \begin_inset LatexCommand \index{Libraries}
9338
9339 \end_inset
9340
9341  routines.
9342  Explicitly specifying the pointer type will generate the most efficient
9343  code.
9344 \layout Subsubsection
9345
9346 Notes on MCS51 memory
9347 \begin_inset LatexCommand \index{MCS51 memory}
9348
9349 \end_inset
9350
9351  layout
9352 \layout Standard
9353
9354 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9355  RAM memory which is structured as follows:
9356 \newline
9357
9358 \newline
9359 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9360
9361 \newline
9362 - Bytes 20-2F - 16 bytes to hold 128 bit
9363 \begin_inset LatexCommand \index{bit}
9364
9365 \end_inset
9366
9367  variables and,
9368 \newline
9369 - Bytes 30-7F - 80 bytes for general purpose use.
9370 \newline
9371
9372 \layout Standard
9373
9374 Additionally some members of the MCS51 family may have up to 128 bytes of
9375  additional, indirectly addressable, internal RAM memory (
9376 \emph on
9377 idata
9378 \emph default
9379
9380 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9381
9382 \end_inset
9383
9384
9385 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9386
9387 \end_inset
9388
9389 ).
9390  Furthermore, some chips may have some built in external memory (
9391 \emph on
9392 xdata
9393 \emph default
9394
9395 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9396
9397 \end_inset
9398
9399
9400 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9401
9402 \end_inset
9403
9404 ) which should not be confused with the internal, directly addressable RAM
9405  memory (
9406 \emph on
9407 data
9408 \emph default
9409
9410 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9411
9412 \end_inset
9413
9414
9415 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9416
9417 \end_inset
9418
9419 ).
9420  Sometimes this built in
9421 \emph on
9422 xdata
9423 \emph default
9424  memory has to be activated before using it (you can probably find this
9425  information on the datasheet of the microcontroller your are using, see
9426  also section
9427 \begin_inset LatexCommand \ref{sub:Startup-Code}
9428
9429 \end_inset
9430
9431 \SpecialChar ~
9432 Startup-Code).
9433 \layout Standard
9434
9435 Normally SDCC will only use the first bank
9436 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9437
9438 \end_inset
9439
9440  of registers (register bank 0), but it is possible to specify that other
9441  banks of registers (keyword
9442 \emph on
9443 using
9444 \emph default
9445
9446 \emph on
9447
9448 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9449
9450 \end_inset
9451
9452
9453 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9454
9455 \end_inset
9456
9457
9458 \emph default
9459 ) should be used in interrupt
9460 \begin_inset LatexCommand \index{interrupt}
9461
9462 \end_inset
9463
9464
9465 \begin_inset LatexCommand \index{\_\_interrupt}
9466
9467 \end_inset
9468
9469  routines.
9470  By default, the compiler will place the stack after the last byte of allocated
9471  memory for variables.
9472  For example, if the first 2 banks of registers are used, and only four
9473  bytes are used for
9474 \emph on
9475 data
9476 \emph default
9477  variables, it will position the base of the internal stack at address 20
9478  (0x14).
9479  This implies that as the stack
9480 \begin_inset LatexCommand \index{stack}
9481
9482 \end_inset
9483
9484  grows, it will use up the remaining register banks, and the 16 bytes used
9485  by the 128 bit variables, and 80 bytes for general purpose use.
9486  If any bit variables are used, the data variables will be placed in unused
9487  register banks and after the byte holding the last bit variable.
9488  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9489  (two bytes used),
9490 \emph on
9491 data
9492 \emph default
9493  variables will be placed starting from address 0x10 to 0x20 and continue
9494  at address 0x22.
9495  You can also use -
9496 \begin_inset ERT
9497 status Collapsed
9498
9499 \layout Standard
9500
9501 \backslash
9502 /
9503 \end_inset
9504
9505 -data-loc
9506 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
9507
9508 \end_inset
9509
9510  to specify the start address of the
9511 \emph on
9512 data
9513 \emph default
9514  and -
9515 \begin_inset ERT
9516 status Collapsed
9517
9518 \layout Standard
9519
9520 \backslash
9521 /
9522 \end_inset
9523
9524 -iram-size
9525 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
9526
9527 \end_inset
9528
9529  to specify the size of the total internal RAM (
9530 \emph on
9531 data
9532 \emph default
9533 +
9534 \emph on
9535 idata
9536 \emph default
9537 ).
9538
9539 \layout Standard
9540
9541 By default the 8051 linker will place the stack after the last byte of (i)data
9542  variables.
9543  Option -
9544 \begin_inset ERT
9545 status Collapsed
9546
9547 \layout Standard
9548
9549 \backslash
9550 /
9551 \end_inset
9552
9553 -stack-loc
9554 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
9555
9556 \end_inset
9557
9558  allows you to specify the start of the stack, i.e.
9559  you could start it after any data in the general purpose area.
9560  If your microcontroller has additional indirectly addressable internal
9561  RAM (
9562 \emph on
9563 idata
9564 \emph default
9565 ) you can place the stack on it.
9566  You may also need to use -
9567 \begin_inset ERT
9568 status Collapsed
9569
9570 \layout Standard
9571
9572 \backslash
9573 /
9574 \end_inset
9575
9576 -xdata-loc
9577 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
9578
9579 \end_inset
9580
9581  to set the start address of the external RAM (
9582 \emph on
9583 xdata
9584 \emph default
9585 ) and -
9586 \begin_inset ERT
9587 status Collapsed
9588
9589 \layout Standard
9590
9591 \backslash
9592 /
9593 \end_inset
9594
9595 -xram-size
9596 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
9597
9598 \end_inset
9599
9600  to specify its size.
9601  Same goes for the code memory, using -
9602 \begin_inset ERT
9603 status Collapsed
9604
9605 \layout Standard
9606
9607 \backslash
9608 /
9609 \end_inset
9610
9611 -code-loc
9612 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
9613
9614 \end_inset
9615
9616  and -
9617 \begin_inset ERT
9618 status Collapsed
9619
9620 \layout Standard
9621
9622 \backslash
9623 /
9624 \end_inset
9625
9626 -code-size
9627 \begin_inset LatexCommand \index{-\/-code-size <Value>}
9628
9629 \end_inset
9630
9631 .
9632  If in doubt, don't specify any options and see if the resulting memory
9633  layout is appropriate, then you can adjust it.
9634 \layout Standard
9635
9636 The linker generates two files with memory allocation information.
9637  The first, with extension .map
9638 \begin_inset LatexCommand \index{<file>.map}
9639
9640 \end_inset
9641
9642  shows all the variables and segments.
9643  The second with extension .mem
9644 \begin_inset LatexCommand \index{<file>.mem}
9645
9646 \end_inset
9647
9648  shows the final memory layout.
9649  The linker will complain either if memory segments overlap, there is not
9650  enough memory, or there is not enough space for stack.
9651  If you get any linking warnings and/or errors related to stack or segments
9652  allocation, take a look at either the .map or .mem files to find out what
9653  the problem is.
9654  The .mem file may even suggest a solution to the problem.
9655 \layout Subsection
9656
9657 Z80/Z180 Storage Class
9658 \begin_inset LatexCommand \index{Storage class}
9659
9660 \end_inset
9661
9662  Language Extensions
9663 \layout Subsubsection
9664
9665 sfr
9666 \begin_inset LatexCommand \index{sfr}
9667
9668 \end_inset
9669
9670
9671 \begin_inset LatexCommand \index{\_\_sfr}
9672
9673 \end_inset
9674
9675  (in/out to 8-bit addresses)
9676 \layout Standard
9677
9678 The Z80
9679 \begin_inset LatexCommand \index{Z80}
9680
9681 \end_inset
9682
9683  family has separate address spaces for memory and
9684 \emph on
9685 i
9686 \emph default
9687 nput/
9688 \emph on
9689 o
9690 \emph default
9691 utput memory.
9692  I/O memory
9693 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9694
9695 \end_inset
9696
9697  is accessed with special instructions, e.g.:
9698 \layout Verse
9699
9700
9701 \family typewriter
9702 sfr at 0x78 IoPort;\SpecialChar ~
9703 \SpecialChar ~
9704 /* define a var in I/O space at 78h called IoPort */
9705
9706 \layout Standard
9707
9708 Writing 0x01 to this variable generates the assembly code:
9709 \layout Verse
9710
9711
9712 \family typewriter
9713 3E 01\SpecialChar ~
9714 \SpecialChar ~
9715 \SpecialChar ~
9716 \SpecialChar ~
9717 \SpecialChar ~
9718 \SpecialChar ~
9719 ld a,#0x01
9720 \newline
9721 D3 78\SpecialChar ~
9722 \SpecialChar ~
9723 \SpecialChar ~
9724 \SpecialChar ~
9725 \SpecialChar ~
9726 \SpecialChar ~
9727 out (_IoPort),a
9728 \layout Subsubsection
9729
9730 banked sfr
9731 \begin_inset LatexCommand \index{sfr}
9732
9733 \end_inset
9734
9735
9736 \begin_inset LatexCommand \index{\_\_sfr}
9737
9738 \end_inset
9739
9740  (in/out to 16-bit addresses)
9741 \layout Standard
9742
9743 The keyword
9744 \emph on
9745 banked
9746 \emph default
9747  is used to support 16 bit addresses in I/O memory e.g.:
9748 \layout Verse
9749
9750
9751 \family typewriter
9752 sfr banked at
9753 \begin_inset LatexCommand \index{at}
9754
9755 \end_inset
9756
9757
9758 \begin_inset LatexCommand \index{\_\_at}
9759
9760 \end_inset
9761
9762  0x123 IoPort;
9763 \layout Standard
9764
9765 Writing 0x01 to this variable generates the assembly code:
9766 \layout Verse
9767
9768
9769 \family typewriter
9770 01 23 01\SpecialChar ~
9771 \SpecialChar ~
9772 \SpecialChar ~
9773 ld bc,#_IoPort
9774 \newline
9775 3E 01\SpecialChar ~
9776 \SpecialChar ~
9777 \SpecialChar ~
9778 \SpecialChar ~
9779 \SpecialChar ~
9780 \SpecialChar ~
9781 ld a,#0x01
9782 \newline
9783 ED 79\SpecialChar ~
9784 \SpecialChar ~
9785 \SpecialChar ~
9786 \SpecialChar ~
9787 \SpecialChar ~
9788 \SpecialChar ~
9789 out (c),a
9790 \layout Subsubsection
9791
9792 sfr
9793 \begin_inset LatexCommand \index{sfr}
9794
9795 \end_inset
9796
9797
9798 \begin_inset LatexCommand \index{\_\_sfr}
9799
9800 \end_inset
9801
9802  (in0/out0 to 8 bit addresses on Z180
9803 \begin_inset LatexCommand \index{Z180}
9804
9805 \end_inset
9806
9807 /HD64180
9808 \begin_inset LatexCommand \index{HD64180}
9809
9810 \end_inset
9811
9812 )
9813 \layout Standard
9814
9815 The compiler option -
9816 \begin_inset ERT
9817 status Collapsed
9818
9819 \layout Standard
9820
9821 \backslash
9822 /
9823 \end_inset
9824
9825 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9826 portmode
9827 \begin_inset LatexCommand \index{\#pragma portmode}
9828
9829 \end_inset
9830
9831 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9832 ns
9833 \family typewriter
9834 in0/out0
9835 \family default
9836  instead of
9837 \family typewriter
9838 in/out
9839 \family default
9840 .
9841  If you include the file z180.h this will be set automatically.
9842 \layout Subsection
9843
9844 HC08 Storage Class
9845 \begin_inset LatexCommand \index{Storage class}
9846
9847 \end_inset
9848
9849  Language Extensions
9850 \layout Subsubsection
9851
9852 data
9853 \begin_inset LatexCommand \index{data (hc08 storage class)}
9854
9855 \end_inset
9856
9857
9858 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
9859
9860 \end_inset
9861
9862
9863 \layout Standard
9864
9865 The data storage class declares a variable that resides in the first 256
9866  bytes of memory (the direct page).
9867  The HC08 is most efficient at accessing variables (especially pointers)
9868  stored here.
9869 \layout Subsubsection
9870
9871 xdata
9872 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
9873
9874 \end_inset
9875
9876
9877 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
9878
9879 \end_inset
9880
9881
9882 \layout Standard
9883
9884 The xdata storage class declares a variable that can reside anywhere in
9885  memory.
9886  This is the default if no storage class is specified.
9887
9888 \layout Section
9889
9890 Absolute Addressing
9891 \begin_inset LatexCommand \index{Absolute addressing}
9892
9893 \end_inset
9894
9895
9896 \layout Standard
9897
9898 Data items can be assigned an absolute address with the
9899 \emph on
9900 at
9901 \begin_inset LatexCommand \index{at}
9902
9903 \end_inset
9904
9905
9906 \begin_inset LatexCommand \index{\_\_at}
9907
9908 \end_inset
9909
9910  <address>
9911 \emph default
9912  keyword, in addition to a storage class, e.g.:
9913 \layout Verse
9914
9915
9916 \family typewriter
9917 xdata
9918 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9919
9920 \end_inset
9921
9922
9923 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9924
9925 \end_inset
9926
9927  at
9928 \begin_inset LatexCommand \index{at}
9929
9930 \end_inset
9931
9932
9933 \begin_inset LatexCommand \index{\_\_at}
9934
9935 \end_inset
9936
9937  0x7ffe unsigned int chksum;
9938 \layout Standard
9939
9940 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9941  of the external ram.
9942  The compiler does
9943 \emph on
9944 not
9945 \emph default
9946  reserve any space for variables declared in this way (they are implemented
9947  with an equate in the assembler).
9948  Thus it is left to the programmer to make sure there are no overlaps with
9949  other variables that are declared without the absolute address.
9950  The assembler listing file (.lst
9951 \begin_inset LatexCommand \index{<file>.lst}
9952
9953 \end_inset
9954
9955 ) and the linker output files (.rst
9956 \begin_inset LatexCommand \index{<file>.rst}
9957
9958 \end_inset
9959
9960 ) and (.map
9961 \begin_inset LatexCommand \index{<file>.map}
9962
9963 \end_inset
9964
9965 ) are good places to look for such overlaps.
9966  Variables with an absolute address are
9967 \emph on
9968 not
9969 \emph default
9970  initialized
9971 \begin_inset LatexCommand \index{Variable initialization}
9972
9973 \end_inset
9974
9975 .
9976 \layout Standard
9977
9978 In case of memory mapped I/O devices the keyword
9979 \emph on
9980 volatile
9981 \emph default
9982  has to be used to tell the compiler that accesses might not be removed:
9983 \layout Verse
9984
9985
9986 \family typewriter
9987 volatile
9988 \begin_inset LatexCommand \index{volatile}
9989
9990 \end_inset
9991
9992  xdata
9993 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9994
9995 \end_inset
9996
9997  at
9998 \begin_inset LatexCommand \index{at}
9999
10000 \end_inset
10001
10002  0x8000 unsigned char PORTA_8255;
10003 \layout Standard
10004
10005 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
10006 r) array
10007 \family typewriter
10008 \size footnotesize
10009
10010 \begin_inset LatexCommand \index{Aligned array}
10011
10012 \end_inset
10013
10014
10015 \family default
10016 \size default
10017  starts at a block (256 byte) boundary
10018 \begin_inset LatexCommand \index{block boundary}
10019
10020 \end_inset
10021
10022  (section
10023 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
10024
10025 \end_inset
10026
10027  has an example).
10028 \newline
10029 Absolute addresses can be specified for variables in all storage classes,
10030  e.g.:
10031 \layout Verse
10032
10033
10034 \family typewriter
10035 bit
10036 \begin_inset LatexCommand \index{bit}
10037
10038 \end_inset
10039
10040  at
10041 \begin_inset LatexCommand \index{at}
10042
10043 \end_inset
10044
10045  0x02 bvar;
10046 \layout Standard
10047
10048 The above example will allocate the variable at offset 0x02 in the bit-addressab
10049 le space.
10050  There is no real advantage to assigning absolute addresses to variables
10051  in this manner, unless you want strict control over all the variables allocated.
10052  One possible use would be to write hardware portable code.
10053  For example, if you have a routine that uses one or more of the microcontroller
10054  I/O pins, and such pins are different for two different hardwares, you
10055  can declare the I/O pins in your routine using:
10056 \layout Verse
10057
10058
10059 \family typewriter
10060 extern volatile
10061 \begin_inset LatexCommand \index{volatile}
10062
10063 \end_inset
10064
10065  bit MOSI;\SpecialChar ~
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 \SpecialChar ~
10069 /* master out, slave in */
10070 \newline
10071 extern volatile bit MISO;\SpecialChar ~
10072 \SpecialChar ~
10073 \SpecialChar ~
10074 \SpecialChar ~
10075 /* master in, slave out */
10076 \newline
10077 extern volatile bit MCLK;\SpecialChar ~
10078 \SpecialChar ~
10079 \SpecialChar ~
10080 \SpecialChar ~
10081 /* master clock */
10082 \newline
10083
10084 \newline
10085 /* Input and Output of a byte on a 3-wire serial bus.
10086 \newline
10087 \SpecialChar ~
10088 \SpecialChar ~
10089 \SpecialChar ~
10090 If needed adapt polarity of clock, polarity of data and bit order
10091 \newline
10092 \SpecialChar ~
10093 */
10094 \newline
10095 unsigned char spi_io(unsigned char out_byte)
10096 \newline
10097 {
10098 \newline
10099 \SpecialChar ~
10100 \SpecialChar ~
10101 \SpecialChar ~
10102 \SpecialChar ~
10103 unsigned char i=8;
10104 \newline
10105 \SpecialChar ~
10106 \SpecialChar ~
10107 \SpecialChar ~
10108 \SpecialChar ~
10109 do {
10110 \newline
10111 \SpecialChar ~
10112 \SpecialChar ~
10113 \SpecialChar ~
10114 \SpecialChar ~
10115 \SpecialChar ~
10116 \SpecialChar ~
10117 \SpecialChar ~
10118 \SpecialChar ~
10119 MOSI = out_byte & 0x80;
10120 \newline
10121 \SpecialChar ~
10122 \SpecialChar ~
10123 \SpecialChar ~
10124 \SpecialChar ~
10125 \SpecialChar ~
10126 \SpecialChar ~
10127 \SpecialChar ~
10128 \SpecialChar ~
10129 out_byte <<= 1;
10130 \newline
10131 \SpecialChar ~
10132 \SpecialChar ~
10133 \SpecialChar ~
10134 \SpecialChar ~
10135 \SpecialChar ~
10136 \SpecialChar ~
10137 \SpecialChar ~
10138 \SpecialChar ~
10139 MCLK = 1;
10140 \newline
10141 \SpecialChar ~
10142 \SpecialChar ~
10143 \SpecialChar ~
10144 \SpecialChar ~
10145 \SpecialChar ~
10146 \SpecialChar ~
10147 \SpecialChar ~
10148 \SpecialChar ~
10149 /* _asm nop _endasm; */\SpecialChar ~
10150 \SpecialChar ~
10151 \SpecialChar ~
10152 \SpecialChar ~
10153 \SpecialChar ~
10154 \SpecialChar ~
10155 \SpecialChar ~
10156 \SpecialChar ~
10157 /* for slow peripherals */
10158 \newline
10159 \SpecialChar ~
10160 \SpecialChar ~
10161 \SpecialChar ~
10162 \SpecialChar ~
10163 \SpecialChar ~
10164 \SpecialChar ~
10165 \SpecialChar ~
10166 \SpecialChar ~
10167 if(MISO)
10168 \newline
10169 \SpecialChar ~
10170 \SpecialChar ~
10171 \SpecialChar ~
10172 \SpecialChar ~
10173 \SpecialChar ~
10174 \SpecialChar ~
10175 \SpecialChar ~
10176 \SpecialChar ~
10177 \SpecialChar ~
10178 \SpecialChar ~
10179 \SpecialChar ~
10180 \SpecialChar ~
10181 out_byte += 1;
10182 \newline
10183 \SpecialChar ~
10184 \SpecialChar ~
10185 \SpecialChar ~
10186 \SpecialChar ~
10187 \SpecialChar ~
10188 \SpecialChar ~
10189 \SpecialChar ~
10190 \SpecialChar ~
10191 MCLK = 0;
10192 \newline
10193 \SpecialChar ~
10194 \SpecialChar ~
10195 \SpecialChar ~
10196 \SpecialChar ~
10197 } while(--i);
10198 \newline
10199 \SpecialChar ~
10200 \SpecialChar ~
10201 \SpecialChar ~
10202 \SpecialChar ~
10203 return out_byte;
10204 \newline
10205 }
10206 \layout Standard
10207
10208 Then, someplace in the code for the first hardware you would use
10209 \layout Verse
10210
10211
10212 \family typewriter
10213 bit at
10214 \begin_inset LatexCommand \index{at}
10215
10216 \end_inset
10217
10218
10219 \begin_inset LatexCommand \index{\_\_at}
10220
10221 \end_inset
10222
10223  0x80 MOSI;\SpecialChar ~
10224 \SpecialChar ~
10225 \SpecialChar ~
10226 \SpecialChar ~
10227 /* I/O port 0, bit 0 */
10228 \newline
10229 bit at 0x81 MISO;\SpecialChar ~
10230 \SpecialChar ~
10231 \SpecialChar ~
10232 \SpecialChar ~
10233 /* I/O port 0, bit 1 */
10234 \newline
10235 bit at 0x82 MCLK;\SpecialChar ~
10236 \SpecialChar ~
10237 \SpecialChar ~
10238 \SpecialChar ~
10239 /* I/O port 0, bit 2 */
10240 \layout Standard
10241
10242 Similarly, for the second hardware you would use
10243 \layout Verse
10244
10245
10246 \family typewriter
10247 bit at 0x83 MOSI;\SpecialChar ~
10248 \SpecialChar ~
10249 \SpecialChar ~
10250 \SpecialChar ~
10251 /* I/O port 0, bit 3 */
10252 \newline
10253 bit at 0x91 MISO;\SpecialChar ~
10254 \SpecialChar ~
10255 \SpecialChar ~
10256 \SpecialChar ~
10257 /* I/O port 1, bit 1 */
10258 \newline
10259 bit
10260 \begin_inset LatexCommand \index{bit}
10261
10262 \end_inset
10263
10264  at 0x92 MCLK;\SpecialChar ~
10265 \SpecialChar ~
10266 \SpecialChar ~
10267 \SpecialChar ~
10268 /* I/O port 1, bit 2 */
10269 \layout Standard
10270
10271 and you can use the same hardware dependent routine without changes, as
10272  for example in a library.
10273  This is somehow similar to sbit, but only one absolute address has to be
10274  specified in the whole project.
10275 \layout Section
10276
10277 Parameters
10278 \begin_inset LatexCommand \index{Parameters}
10279
10280 \end_inset
10281
10282
10283 \begin_inset LatexCommand \index{function parameter}
10284
10285 \end_inset
10286
10287  & Local Variables
10288 \begin_inset LatexCommand \index{local variables}
10289
10290 \end_inset
10291
10292
10293 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10294
10295 \end_inset
10296
10297
10298 \layout Standard
10299
10300 Automatic (local) variables and parameters to functions can either be placed
10301  on the stack or in data-space.
10302  The default action of the compiler is to place these variables in the internal
10303  RAM (for small model) or external RAM (for large model).
10304  This in fact makes them similar to
10305 \emph on
10306 static
10307 \begin_inset LatexCommand \index{static}
10308
10309 \end_inset
10310
10311
10312 \emph default
10313  so by default functions are non-reentrant
10314 \begin_inset LatexCommand \index{reentrant}
10315
10316 \end_inset
10317
10318 .
10319
10320 \newline
10321
10322 \newline
10323 They can be placed on the stack
10324 \begin_inset LatexCommand \index{stack}
10325
10326 \end_inset
10327
10328  by using the
10329 \emph on
10330  -
10331 \begin_inset ERT
10332 status Collapsed
10333
10334 \layout Standard
10335
10336 \backslash
10337 /
10338 \end_inset
10339
10340 -stack-auto
10341 \begin_inset LatexCommand \index{-\/-stack-auto}
10342
10343 \end_inset
10344
10345
10346 \emph default
10347  option, by using
10348 \emph on
10349 #pragma\SpecialChar ~
10350 stackauto
10351 \emph default
10352
10353 \begin_inset LatexCommand \index{\#pragma stackauto}
10354
10355 \end_inset
10356
10357  or by using the
10358 \emph on
10359 reentrant
10360 \begin_inset LatexCommand \index{reentrant}
10361
10362 \end_inset
10363
10364
10365 \emph default
10366  keyword in the function declaration, e.g.:
10367 \layout Verse
10368
10369
10370 \family typewriter
10371 unsigned char foo(char i) reentrant
10372 \newline
10373 {
10374 \newline
10375 \SpecialChar ~
10376 \SpecialChar ~
10377 \SpecialChar ~
10378 \SpecialChar ~
10379 ...
10380
10381 \newline
10382 }
10383 \layout Standard
10384
10385 Since stack space on 8051 is limited, the
10386 \emph on
10387 reentrant
10388 \emph default
10389 keyword or the
10390 \emph on
10391  -
10392 \begin_inset ERT
10393 status Collapsed
10394
10395 \layout Standard
10396
10397 \backslash
10398 /
10399 \end_inset
10400
10401 -stack-auto
10402 \emph default
10403  option should be used sparingly.
10404  Note that the reentrant keyword just means that the parameters & local
10405  variables will be allocated to the stack, it
10406 \emph on
10407 does not
10408 \emph default
10409  mean that the function is register bank
10410 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10411
10412 \end_inset
10413
10414  independent.
10415 \newline
10416
10417 \newline
10418 Local variables
10419 \begin_inset LatexCommand \index{local variables}
10420
10421 \end_inset
10422
10423  can be assigned storage classes and absolute
10424 \begin_inset LatexCommand \index{Absolute addressing}
10425
10426 \end_inset
10427
10428  addresses, e.g.:
10429 \layout Verse
10430
10431
10432 \family typewriter
10433 unsigned char foo()
10434 \newline
10435 {
10436 \newline
10437 \SpecialChar ~
10438 \SpecialChar ~
10439 \SpecialChar ~
10440 \SpecialChar ~
10441 xdata unsigned char i;
10442 \newline
10443 \SpecialChar ~
10444 \SpecialChar ~
10445 \SpecialChar ~
10446 \SpecialChar ~
10447 bit bvar;
10448 \newline
10449 \SpecialChar ~
10450 \SpecialChar ~
10451 \SpecialChar ~
10452 \SpecialChar ~
10453 data at
10454 \begin_inset LatexCommand \index{at}
10455
10456 \end_inset
10457
10458  0x31 unsigned char j;
10459 \newline
10460 \SpecialChar ~
10461 \SpecialChar ~
10462 \SpecialChar ~
10463 \SpecialChar ~
10464 ...
10465
10466 \newline
10467 }
10468 \layout Standard
10469
10470 In the above example the variable
10471 \emph on
10472 i
10473 \emph default
10474  will be allocated in the external ram,
10475 \emph on
10476 bvar
10477 \emph default
10478  in bit addressable space and
10479 \emph on
10480  j
10481 \emph default
10482  in internal ram.
10483  When compiled with
10484 \emph on
10485 -
10486 \begin_inset ERT
10487 status Collapsed
10488
10489 \layout Standard
10490
10491 \backslash
10492 /
10493 \end_inset
10494
10495 -stack-auto
10496 \emph default
10497  or when a function is declared as
10498 \emph on
10499 reentrant
10500 \emph default
10501  this should only be done for static variables.
10502 \layout Standard
10503
10504 Parameters
10505 \begin_inset LatexCommand \index{function parameter}
10506
10507 \end_inset
10508
10509  however are not allowed any storage class
10510 \begin_inset LatexCommand \index{Storage class}
10511
10512 \end_inset
10513
10514 , (storage classes for parameters will be ignored), their allocation is
10515  governed by the memory model in use, and the reentrancy options.
10516 \layout Standard
10517
10518 It is however allowed to use bit parameters in reentrant functions and also
10519  non-static local bit variables are supported.
10520  Efficient use is limited to 8 semi-bitregisters in bit space.
10521  They are pushed and popped to stack as a single byte just like the normal
10522  registers.
10523 \layout Section
10524
10525 Overlaying
10526 \begin_inset LatexCommand \label{sub:Overlaying}
10527
10528 \end_inset
10529
10530
10531 \begin_inset LatexCommand \index{Overlaying}
10532
10533 \end_inset
10534
10535
10536 \layout Standard
10537
10538 For non-reentrant
10539 \begin_inset LatexCommand \index{reentrant}
10540
10541 \end_inset
10542
10543  functions SDCC will try to reduce internal ram space usage by overlaying
10544  parameters and local variables of a function (if possible).
10545  Parameters and local variables
10546 \begin_inset LatexCommand \index{local variables}
10547
10548 \end_inset
10549
10550  of a function will be allocated to an overlayable segment if the function
10551  has
10552 \emph on
10553 no other function calls and the function is non-reentrant and the memory
10554  model
10555 \begin_inset LatexCommand \index{Memory model}
10556
10557 \end_inset
10558
10559  is small.
10560
10561 \emph default
10562  If an explicit storage class
10563 \begin_inset LatexCommand \index{Storage class}
10564
10565 \end_inset
10566
10567  is specified for a local variable, it will NOT be overlayed.
10568 \layout Standard
10569
10570 Note that the compiler (not the linkage editor) makes the decision for overlayin
10571 g the data items.
10572  Functions that are called from an interrupt service routine should be preceded
10573  by a #pragma\SpecialChar ~
10574 nooverlay
10575 \begin_inset LatexCommand \index{\#pragma nooverlay}
10576
10577 \end_inset
10578
10579  if they are not reentrant.
10580 \layout Standard
10581
10582 Also note that the compiler does not do any processing of inline assembler
10583  code, so the compiler might incorrectly assign local variables and parameters
10584  of a function into the overlay segment if the inline assembler code calls
10585  other c-functions that might use the overlay.
10586  In that case the #pragma\SpecialChar ~
10587 nooverlay should be used.
10588 \layout Standard
10589
10590 Parameters and local variables of functions that contain 16 or 32 bit multiplica
10591 tion
10592 \begin_inset LatexCommand \index{Multiplication}
10593
10594 \end_inset
10595
10596  or division
10597 \begin_inset LatexCommand \index{Division}
10598
10599 \end_inset
10600
10601  will NOT be overlayed since these are implemented using external functions,
10602  e.g.:
10603 \layout Verse
10604
10605
10606 \family typewriter
10607 #pragma save
10608 \newline
10609 #pragma nooverlay
10610 \begin_inset LatexCommand \index{\#pragma nooverlay}
10611
10612 \end_inset
10613
10614
10615 \newline
10616 void set_error(unsigned char errcd)
10617 \newline
10618 {
10619 \newline
10620 \SpecialChar ~
10621 \SpecialChar ~
10622 \SpecialChar ~
10623 \SpecialChar ~
10624 P3 = errcd;
10625 \newline
10626 }
10627 \newline
10628 #pragma restore
10629 \newline
10630
10631 \newline
10632 void some_isr () interrupt
10633 \begin_inset LatexCommand \index{interrupt}
10634
10635 \end_inset
10636
10637  2
10638 \newline
10639 {
10640 \newline
10641 \SpecialChar ~
10642 \SpecialChar ~
10643 \SpecialChar ~
10644 \SpecialChar ~
10645 ...
10646 \newline
10647 \SpecialChar ~
10648 \SpecialChar ~
10649 \SpecialChar ~
10650 \SpecialChar ~
10651 set_error(10);
10652 \newline
10653 \SpecialChar ~
10654 \SpecialChar ~
10655 \SpecialChar ~
10656 \SpecialChar ~
10657 ...
10658
10659 \newline
10660 }
10661 \layout Standard
10662
10663 In the above example the parameter
10664 \emph on
10665 errcd
10666 \emph default
10667  for the function
10668 \emph on
10669 set_error
10670 \emph default
10671  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
10672 nooverlay was
10673  not present, this could cause unpredictable runtime behavior when called
10674  from an interrupt service routine.
10675  The #pragma\SpecialChar ~
10676 nooverlay ensures that the parameters and local variables for
10677  the function are NOT overlayed.
10678 \layout Section
10679
10680 Interrupt Service Routines
10681 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
10682
10683 \end_inset
10684
10685
10686 \layout Subsection
10687
10688 General Information
10689 \layout Standard
10690
10691 SDCC allows
10692 \emph on
10693 i
10694 \emph default
10695 nterrupt
10696 \emph on
10697 s
10698 \emph default
10699 ervice
10700 \emph on
10701 r
10702 \emph default
10703 outines to be coded in C, with some extended keywords.
10704 \layout Verse
10705
10706
10707 \family typewriter
10708 void timer_isr (void) interrupt 1 using 1
10709 \newline
10710 {
10711 \newline
10712 \SpecialChar ~
10713 \SpecialChar ~
10714 \SpecialChar ~
10715 \SpecialChar ~
10716 ...
10717
10718 \newline
10719 }
10720 \layout Standard
10721
10722 The optional number following the
10723 \emph on
10724 interrupt
10725 \begin_inset LatexCommand \index{interrupt}
10726
10727 \end_inset
10728
10729
10730 \begin_inset LatexCommand \index{\_\_interrupt}
10731
10732 \end_inset
10733
10734
10735 \emph default
10736  keyword is the interrupt number this routine will service.
10737  When present, the compiler will insert a call to this routine in the interrupt
10738  vector table for the interrupt number specified.
10739  If you have multiple source files in your project, interrupt service routines
10740  can be present in any of them, but a prototype of the isr MUST be present
10741  or included in the file that contains the function
10742 \emph on
10743 main
10744 \emph default
10745 .
10746  The optional
10747 \emph on
10748 using
10749 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10750
10751 \end_inset
10752
10753
10754 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10755
10756 \end_inset
10757
10758
10759 \emph default
10760  keyword can be used to tell the compiler to use the specified register
10761  bank (8051 specific) when generating code for this function.
10762
10763 \newline
10764
10765 \layout Standard
10766
10767 Interrupt service routines open the door for some very interesting bugs:
10768 \newline
10769 If an interrupt service routine changes variables which are accessed by
10770  other functions these variables have to be declared
10771 \emph on
10772 volatile
10773 \emph default
10774
10775 \begin_inset LatexCommand \index{volatile}
10776
10777 \end_inset
10778
10779 .
10780
10781 \layout Standard
10782
10783 If the access to these variables is not
10784 \emph on
10785 atomic
10786 \begin_inset LatexCommand \index{atomic}
10787
10788 \end_inset
10789
10790
10791 \emph default
10792  (i.e.
10793  the processor needs more than one instruction for the access and could
10794  be interrupted while accessing the variable) the interrupt must be disabled
10795  during the access to avoid inconsistent data.
10796  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10797  and should be protected by disabling interrupts.
10798  You're not automatically on the safe side if you use 8 bit variables though.
10799  We need an example here: f.e.
10800  on the 8051 the harmless looking
10801 \begin_inset Quotes srd
10802 \end_inset
10803
10804
10805 \family typewriter
10806 flags\SpecialChar ~
10807 |=\SpecialChar ~
10808 0x80;
10809 \family default
10810
10811 \begin_inset Quotes sld
10812 \end_inset
10813
10814  is not atomic if
10815 \family typewriter
10816 flags
10817 \family default
10818  resides in xdata.
10819  Setting
10820 \begin_inset Quotes srd
10821 \end_inset
10822
10823
10824 \family typewriter
10825 flags\SpecialChar ~
10826 |=\SpecialChar ~
10827 0x40;
10828 \family default
10829
10830 \begin_inset Quotes sld
10831 \end_inset
10832
10833  from within an interrupt routine might get lost if the interrupt occurs
10834  at the wrong time.
10835
10836 \begin_inset Quotes sld
10837 \end_inset
10838
10839
10840 \family typewriter
10841 counter\SpecialChar ~
10842 +=\SpecialChar ~
10843 8;
10844 \family default
10845
10846 \begin_inset Quotes srd
10847 \end_inset
10848
10849  is not atomic on the 8051 even if
10850 \family typewriter
10851 counter
10852 \family default
10853  is located in data memory.
10854  Bugs like these are hard to reproduce and can cause a lot of trouble.
10855
10856 \layout Standard
10857
10858 The return address and the registers used in the interrupt service routine
10859  are saved on the stack
10860 \begin_inset LatexCommand \index{stack}
10861
10862 \end_inset
10863
10864  so there must be sufficient stack space.
10865  If there isn't variables or registers (or even the return address itself)
10866  will be corrupted.
10867  This
10868 \emph on
10869 stack overflow
10870 \emph default
10871
10872 \begin_inset LatexCommand \index{stack overflow}
10873
10874 \end_inset
10875
10876  is most likely to happen if the interrupt occurs during the
10877 \begin_inset Quotes sld
10878 \end_inset
10879
10880 deepest
10881 \begin_inset Quotes srd
10882 \end_inset
10883
10884  subroutine when the stack is already in use for f.e.
10885  many return addresses.
10886 \layout Standard
10887
10888 A special note here, int (16 bit) and long (32 bit) integer division
10889 \begin_inset LatexCommand \index{Division}
10890
10891 \end_inset
10892
10893 , multiplication
10894 \begin_inset LatexCommand \index{Multiplication}
10895
10896 \end_inset
10897
10898  & modulus
10899 \begin_inset LatexCommand \index{Modulus}
10900
10901 \end_inset
10902
10903  and floating-point
10904 \begin_inset LatexCommand \index{Floating point support}
10905
10906 \end_inset
10907
10908  operations are implemented using external support routines developed in
10909  ANSI-C.
10910  If an interrupt service routine needs to do any of these operations then
10911  the support routines (as mentioned in a following section) will have to
10912  be recompiled using the
10913 \emph on
10914  -
10915 \begin_inset ERT
10916 status Collapsed
10917
10918 \layout Standard
10919
10920 \backslash
10921 /
10922 \end_inset
10923
10924 -stack-auto
10925 \begin_inset LatexCommand \index{-\/-stack-auto}
10926
10927 \end_inset
10928
10929
10930 \emph default
10931  option and the source file will need to be compiled using the
10932 \emph on
10933 -
10934 \begin_inset ERT
10935 status Collapsed
10936
10937 \layout Standard
10938
10939 \backslash
10940 /
10941 \end_inset
10942
10943 -int-long-reent
10944 \emph default
10945
10946 \begin_inset LatexCommand \index{-\/-int-long-reent}
10947
10948 \end_inset
10949
10950  compiler option.
10951 \layout Standard
10952
10953 Calling other functions from an interrupt service routine is not recommended,
10954  avoid it if possible.
10955  Note that when some function is called from an interrupt service routine
10956  it should be preceded by a #pragma\SpecialChar ~
10957 nooverlay
10958 \begin_inset LatexCommand \index{\#pragma nooverlay}
10959
10960 \end_inset
10961
10962  if it is not reentrant.
10963  Furthermore nonreentrant functions should not be called from the main program
10964  while the interrupt service routine might be active.
10965  They also must not be called from low priority interrupt service routines
10966  while a high priority interrupt service routine might be active.
10967  You could use semaphores or make the function
10968 \emph on
10969  critical
10970 \emph default
10971  if all parameters are passed in registers.
10972 \newline
10973
10974 \newline
10975 Also see section
10976 \begin_inset LatexCommand \ref{sub:Overlaying}
10977
10978 \end_inset
10979
10980 \SpecialChar ~
10981 about Overlaying and section
10982 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10983
10984 \end_inset
10985
10986 \SpecialChar ~
10987 about Functions using private register banks.
10988 \layout Subsection
10989
10990 MCS51/DS390 Interrupt Service Routines
10991 \layout Standard
10992
10993 Interrupt numbers and the corresponding address & descriptions for the Standard
10994  8051/8052 are listed below.
10995  SDCC will automatically adjust the interrupt vector table to the maximum
10996  interrupt number specified.
10997 \newline
10998
10999 \layout Standard
11000 \align center
11001
11002 \begin_inset  Tabular
11003 <lyxtabular version="3" rows="7" columns="3">
11004 <features>
11005 <column alignment="center" valignment="top" leftline="true" width="0in">
11006 <column alignment="center" valignment="top" leftline="true" width="0in">
11007 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
11008 <row topline="true" bottomline="true">
11009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11010 \begin_inset Text
11011
11012 \layout Standard
11013
11014 Interrupt #
11015 \end_inset
11016 </cell>
11017 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11018 \begin_inset Text
11019
11020 \layout Standard
11021
11022 Description
11023 \end_inset
11024 </cell>
11025 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11026 \begin_inset Text
11027
11028 \layout Standard
11029
11030 Vector Address
11031 \end_inset
11032 </cell>
11033 </row>
11034 <row topline="true">
11035 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11036 \begin_inset Text
11037
11038 \layout Standard
11039
11040 0
11041 \end_inset
11042 </cell>
11043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11044 \begin_inset Text
11045
11046 \layout Standard
11047
11048 External 0
11049 \end_inset
11050 </cell>
11051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11052 \begin_inset Text
11053
11054 \layout Standard
11055
11056 0x0003
11057 \end_inset
11058 </cell>
11059 </row>
11060 <row topline="true">
11061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11062 \begin_inset Text
11063
11064 \layout Standard
11065
11066 1
11067 \end_inset
11068 </cell>
11069 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11070 \begin_inset Text
11071
11072 \layout Standard
11073
11074 Timer 0
11075 \end_inset
11076 </cell>
11077 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11078 \begin_inset Text
11079
11080 \layout Standard
11081
11082 0x000B
11083 \end_inset
11084 </cell>
11085 </row>
11086 <row topline="true">
11087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11088 \begin_inset Text
11089
11090 \layout Standard
11091
11092 2
11093 \end_inset
11094 </cell>
11095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11096 \begin_inset Text
11097
11098 \layout Standard
11099
11100 External 1
11101 \end_inset
11102 </cell>
11103 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11104 \begin_inset Text
11105
11106 \layout Standard
11107
11108 0x0013
11109 \end_inset
11110 </cell>
11111 </row>
11112 <row topline="true">
11113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11114 \begin_inset Text
11115
11116 \layout Standard
11117
11118 3
11119 \end_inset
11120 </cell>
11121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11122 \begin_inset Text
11123
11124 \layout Standard
11125
11126 Timer 1
11127 \end_inset
11128 </cell>
11129 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11130 \begin_inset Text
11131
11132 \layout Standard
11133
11134 0x001B
11135 \end_inset
11136 </cell>
11137 </row>
11138 <row topline="true">
11139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11140 \begin_inset Text
11141
11142 \layout Standard
11143
11144 4
11145 \end_inset
11146 </cell>
11147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11148 \begin_inset Text
11149
11150 \layout Standard
11151
11152 Serial
11153 \end_inset
11154 </cell>
11155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11156 \begin_inset Text
11157
11158 \layout Standard
11159
11160 0x0023
11161 \end_inset
11162 </cell>
11163 </row>
11164 <row topline="true" bottomline="true">
11165 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11166 \begin_inset Text
11167
11168 \layout Standard
11169
11170 5
11171 \end_inset
11172 </cell>
11173 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11174 \begin_inset Text
11175
11176 \layout Standard
11177
11178 Timer 2 (8052)
11179 \end_inset
11180 </cell>
11181 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11182 \begin_inset Text
11183
11184 \layout Standard
11185
11186 0x002B
11187 \end_inset
11188 </cell>
11189 </row>
11190 </lyxtabular>
11191
11192 \end_inset
11193
11194
11195 \newline
11196
11197 \layout Standard
11198
11199 If the interrupt service routine is defined without
11200 \emph on
11201 using
11202 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11203
11204 \end_inset
11205
11206
11207 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11208
11209 \end_inset
11210
11211
11212 \emph default
11213  a register bank or with register bank 0 (
11214 \emph on
11215 using
11216 \emph default
11217  0), the compiler will save the registers used by itself on the stack upon
11218  entry and restore them at exit, however if such an interrupt service routine
11219  calls another function then the entire register bank will be saved on the
11220  stack.
11221  This scheme may be advantageous for small interrupt service routines which
11222  have low register usage.
11223 \layout Standard
11224
11225 If the interrupt service routine is defined to be using a specific register
11226  bank then only
11227 \emph on
11228 a, b, dptr
11229 \emph default
11230  & psw are saved and restored, if such an interrupt service routine calls
11231  another function (using another register bank) then the entire register
11232  bank of the called function will be saved on the stack.
11233  This scheme is recommended for larger interrupt service routines.
11234 \layout Subsection
11235
11236 HC08 Interrupt Service Routines
11237 \layout Standard
11238
11239 Since the number of interrupts available is chip specific and the interrupt
11240  vector table always ends at the last byte of memory, the interrupt numbers
11241  corresponds to the interrupt vectors in reverse order of address.
11242  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11243  2 will use the interrupt vector at 0xfffa, and so on.
11244  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11245  this way; instead see section
11246 \begin_inset LatexCommand \ref{sub:Startup-Code}
11247
11248 \end_inset
11249
11250  for details on customizing startup.
11251 \layout Subsection
11252
11253 Z80 Interrupt Service Routines
11254 \layout Standard
11255
11256 The Z80 uses several different methods for determining the correct interrupt
11257  vector depending on the hardware implementation.
11258  Therefore, SDCC ignores the optional interrupt number and does not attempt
11259  to generate an interrupt vector table.
11260 \layout Standard
11261
11262 By default, SDCC generates code for a maskable interrupt, which uses a RETI
11263  instruction to return from the interrupt.
11264  To write an interrupt handler for the non-maskable interrupt, which needs
11265  a RETN instruction instead, add the
11266 \emph on
11267 critical
11268 \emph default
11269  keyword:
11270 \layout Verse
11271
11272
11273 \family typewriter
11274 void nmi_isr (void) critical interrupt
11275 \newline
11276 {
11277 \newline
11278 \SpecialChar ~
11279 \SpecialChar ~
11280 \SpecialChar ~
11281 \SpecialChar ~
11282 ...
11283
11284 \newline
11285 }
11286 \layout Standard
11287
11288 However if you need to create a non-interruptable interrupt service routine
11289  you would also require the
11290 \emph on
11291 critical
11292 \emph default
11293  keyword.
11294  To distinguish between this and an nmi_isr you must provide an interrupt
11295  number.
11296 \layout Section
11297
11298 Enabling and Disabling Interrupts
11299 \layout Subsection
11300
11301 Critical Functions and Critical Statements
11302 \layout Standard
11303
11304 A special keyword may be associated with a block or a function declaring
11305  it as
11306 \emph on
11307 critical
11308 \emph default
11309 .
11310  SDCC will generate code to disable all interrupts
11311 \begin_inset LatexCommand \index{interrupt}
11312
11313 \end_inset
11314
11315  upon entry to a critical function and restore the interrupt enable to the
11316  previous state before returning.
11317  Nesting critical functions will need one additional byte on the stack
11318 \begin_inset LatexCommand \index{stack}
11319
11320 \end_inset
11321
11322  for each call.
11323 \layout Verse
11324
11325
11326 \family typewriter
11327 int foo () critical
11328 \begin_inset LatexCommand \index{critical}
11329
11330 \end_inset
11331
11332
11333 \begin_inset LatexCommand \index{\_\_critical}
11334
11335 \end_inset
11336
11337
11338 \newline
11339 {
11340 \newline
11341 \SpecialChar ~
11342 \SpecialChar ~
11343 \SpecialChar ~
11344 \SpecialChar ~
11345 ...
11346
11347 \newline
11348 \SpecialChar ~
11349 \SpecialChar ~
11350 \SpecialChar ~
11351 \SpecialChar ~
11352 ...
11353
11354 \newline
11355 }
11356 \layout Standard
11357
11358 The critical attribute maybe used with other attributes like
11359 \emph on
11360 reentrant.
11361 \emph default
11362
11363 \newline
11364 The keyword
11365 \emph on
11366 critical
11367 \emph default
11368  may also be used to disable interrupts more locally:
11369 \layout Verse
11370
11371
11372 \family typewriter
11373 critical{ i++; }
11374 \layout Standard
11375
11376 More than one statement could have been included in the block.
11377 \layout Subsection
11378
11379 Enabling and Disabling Interrupts directly
11380 \layout Standard
11381
11382 Interrupts
11383 \begin_inset LatexCommand \index{interrupt}
11384
11385 \end_inset
11386
11387  can also be disabled and enabled directly (8051):
11388 \layout Verse
11389
11390
11391 \family typewriter
11392 EA = 0;\SpecialChar ~
11393 \SpecialChar ~
11394 \SpecialChar ~
11395 \SpecialChar ~
11396 \SpecialChar ~
11397 \SpecialChar ~
11398 \SpecialChar ~
11399 \SpecialChar ~
11400 \SpecialChar ~
11401 \SpecialChar ~
11402 \SpecialChar ~
11403 \SpecialChar ~
11404 or:\SpecialChar ~
11405 \SpecialChar ~
11406 \SpecialChar ~
11407 \SpecialChar ~
11408 \SpecialChar ~
11409 \SpecialChar ~
11410 \SpecialChar ~
11411 \SpecialChar ~
11412 \SpecialChar ~
11413 \SpecialChar ~
11414 \SpecialChar ~
11415 EA_SAVE = EA;
11416 \layout Verse
11417
11418
11419 \family typewriter
11420 ...\SpecialChar ~
11421 \SpecialChar ~
11422 \SpecialChar ~
11423 \SpecialChar ~
11424 \SpecialChar ~
11425 \SpecialChar ~
11426 \SpecialChar ~
11427 \SpecialChar ~
11428 \SpecialChar ~
11429 \SpecialChar ~
11430 \SpecialChar ~
11431 \SpecialChar ~
11432 \SpecialChar ~
11433 \SpecialChar ~
11434 \SpecialChar ~
11435 \SpecialChar ~
11436 \SpecialChar ~
11437 \SpecialChar ~
11438 \SpecialChar ~
11439 \SpecialChar ~
11440 \SpecialChar ~
11441 \SpecialChar ~
11442 \SpecialChar ~
11443 \SpecialChar ~
11444 \SpecialChar ~
11445 \SpecialChar ~
11446 \SpecialChar ~
11447 \SpecialChar ~
11448 \SpecialChar ~
11449 \SpecialChar ~
11450 EA = 0;
11451 \layout Verse
11452
11453
11454 \family typewriter
11455 EA = 1;\SpecialChar ~
11456 \SpecialChar ~
11457 \SpecialChar ~
11458 \SpecialChar ~
11459 \SpecialChar ~
11460 \SpecialChar ~
11461 \SpecialChar ~
11462 \SpecialChar ~
11463 \SpecialChar ~
11464 \SpecialChar ~
11465 \SpecialChar ~
11466 \SpecialChar ~
11467 \SpecialChar ~
11468 \SpecialChar ~
11469 \SpecialChar ~
11470 \SpecialChar ~
11471 \SpecialChar ~
11472 \SpecialChar ~
11473 \SpecialChar ~
11474 \SpecialChar ~
11475 \SpecialChar ~
11476 \SpecialChar ~
11477 \SpecialChar ~
11478 \SpecialChar ~
11479 \SpecialChar ~
11480 \SpecialChar ~
11481 ...
11482 \layout Verse
11483
11484
11485 \family typewriter
11486 \SpecialChar ~
11487 \SpecialChar ~
11488 \SpecialChar ~
11489 \SpecialChar ~
11490 \SpecialChar ~
11491 \SpecialChar ~
11492 \SpecialChar ~
11493 \SpecialChar ~
11494 \SpecialChar ~
11495 \SpecialChar ~
11496 \SpecialChar ~
11497 \SpecialChar ~
11498 \SpecialChar ~
11499 \SpecialChar ~
11500 \SpecialChar ~
11501 \SpecialChar ~
11502 \SpecialChar ~
11503 \SpecialChar ~
11504 \SpecialChar ~
11505 \SpecialChar ~
11506 \SpecialChar ~
11507 \SpecialChar ~
11508 \SpecialChar ~
11509 \SpecialChar ~
11510 \SpecialChar ~
11511 \SpecialChar ~
11512 \SpecialChar ~
11513 \SpecialChar ~
11514 \SpecialChar ~
11515 \SpecialChar ~
11516 \SpecialChar ~
11517 \SpecialChar ~
11518 \SpecialChar ~
11519 EA = EA_SAVE;
11520 \layout Standard
11521
11522 On other architectures which have seperate opcodes for enabling and disabling
11523  interrupts you might want to make use of defines with inline assembly
11524 \begin_inset LatexCommand \index{Assembler routines}
11525
11526 \end_inset
11527
11528  (HC08):
11529 \layout Verse
11530
11531
11532 \family typewriter
11533 #define CLI _asm
11534 \begin_inset LatexCommand \index{\_asm}
11535
11536 \end_inset
11537
11538 \SpecialChar ~
11539 \SpecialChar ~
11540 cli\SpecialChar ~
11541 \SpecialChar ~
11542 _endasm
11543 \begin_inset LatexCommand \index{\_endasm}
11544
11545 \end_inset
11546
11547 ;
11548 \layout Verse
11549
11550
11551 \family typewriter
11552 #define SEI _asm\SpecialChar ~
11553 \SpecialChar ~
11554 sei\SpecialChar ~
11555 \SpecialChar ~
11556 _endasm;
11557 \layout Verse
11558
11559
11560 \family typewriter
11561 ...
11562 \layout Standard
11563
11564 Note: it is sometimes sufficient to disable only a specific interrupt source
11565  like f.e.
11566  a timer or serial interrupt by manipulating an
11567 \emph on
11568 interrupt mask
11569 \begin_inset LatexCommand \index{interrupt mask}
11570
11571 \end_inset
11572
11573
11574 \emph default
11575  register.
11576
11577 \layout Standard
11578
11579 Usually the time during which interrupts are disabled should be kept as
11580  short as possible.
11581  This minimizes both
11582 \emph on
11583 interrupt latency
11584 \emph default
11585
11586 \begin_inset LatexCommand \index{interrupt latency}
11587
11588 \end_inset
11589
11590  (the time between the occurrence of the interrupt and the execution of
11591  the first code in the interrupt routine) and
11592 \emph on
11593 interrupt jitter
11594 \emph default
11595
11596 \begin_inset LatexCommand \index{interrupt jitter}
11597
11598 \end_inset
11599
11600  (the difference between the shortest and the longest interrupt latency).
11601  These really are something different, f.e.
11602  a serial interrupt has to be served before its buffer overruns so it cares
11603  for the maximum interrupt latency, whereas it does not care about jitter.
11604  On a loudspeaker driven via a digital to analog converter which is fed
11605  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11606  a much smaller jitter will be very audible.
11607 \layout Standard
11608
11609 You can reenable interrupts within an interrupt routine and on some architecture
11610 s you can make use of two (or more) levels of
11611 \emph on
11612 interrupt priorities
11613 \emph default
11614
11615 \begin_inset LatexCommand \index{interrupt priority}
11616
11617 \end_inset
11618
11619 .
11620  On some architectures which don't support interrupt priorities these can
11621  be implemented by manipulating the interrupt mask and reenabling interrupts
11622  within the interrupt routine.
11623  Check there is sufficient space on the stack
11624 \begin_inset LatexCommand \index{stack}
11625
11626 \end_inset
11627
11628  and don't add complexity unless you have to.
11629
11630 \layout Subsection
11631
11632 Semaphore
11633 \begin_inset LatexCommand \index{semaphore}
11634
11635 \end_inset
11636
11637  locking (mcs51/ds390)
11638 \layout Standard
11639
11640 Some architectures (mcs51/ds390) have an atomic
11641 \begin_inset LatexCommand \index{atomic}
11642
11643 \end_inset
11644
11645  bit test and
11646 \emph on
11647
11648 \emph default
11649 clear
11650 \emph on
11651
11652 \emph default
11653 instruction.
11654  These type of instructions are typically used in preemptive multitasking
11655  systems, where a routine f.e.
11656  claims the use of a data structure ('acquires a lock
11657 \begin_inset LatexCommand \index{lock}
11658
11659 \end_inset
11660
11661  on it'), makes some modifications and then releases the lock when the data
11662  structure is consistent again.
11663  The instruction may also be used if interrupt and non-interrupt code have
11664  to compete for a resource.
11665  With the atomic bit test and clear instruction interrupts
11666 \begin_inset LatexCommand \index{interrupt}
11667
11668 \end_inset
11669
11670  don't have to be disabled for the locking operation.
11671
11672 \layout Standard
11673
11674 SDCC generates this instruction if the source follows this pattern:
11675 \layout Verse
11676
11677
11678 \family typewriter
11679 volatile
11680 \begin_inset LatexCommand \index{volatile}
11681
11682 \end_inset
11683
11684  bit resource_is_free;
11685 \newline
11686
11687 \newline
11688 if (resource_is_free)
11689 \newline
11690 \SpecialChar ~
11691 \SpecialChar ~
11692 {
11693 \newline
11694 \SpecialChar ~
11695 \SpecialChar ~
11696 \SpecialChar ~
11697 \SpecialChar ~
11698 resource_is_free=0;
11699 \newline
11700 \SpecialChar ~
11701 \SpecialChar ~
11702 \SpecialChar ~
11703 \SpecialChar ~
11704 ...
11705
11706 \newline
11707 \SpecialChar ~
11708 \SpecialChar ~
11709 \SpecialChar ~
11710 \SpecialChar ~
11711 resource_is_free=1;
11712 \newline
11713 \SpecialChar ~
11714 \SpecialChar ~
11715 }
11716 \layout Standard
11717
11718 Note, mcs51 and ds390 support only an atomic
11719 \begin_inset LatexCommand \index{atomic}
11720
11721 \end_inset
11722
11723  bit test and
11724 \emph on
11725 clear
11726 \emph default
11727  instruction (as opposed to atomic bit test and
11728 \emph on
11729 set).
11730 \layout Section
11731
11732 Functions using private register banks
11733 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11734
11735 \end_inset
11736
11737  (mcs51/ds390)
11738 \layout Standard
11739
11740 Some architectures have support for quickly changing register sets.
11741  SDCC supports this feature with the
11742 \emph on
11743 using
11744 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11745
11746 \end_inset
11747
11748
11749 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11750
11751 \end_inset
11752
11753
11754 \emph default
11755  attribute (which tells the compiler to use a register bank
11756 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11757
11758 \end_inset
11759
11760  other than the default bank zero).
11761  It should only be applied to
11762 \emph on
11763 interrupt
11764 \begin_inset LatexCommand \index{interrupt}
11765
11766 \end_inset
11767
11768
11769 \emph default
11770  functions (see footnote below).
11771  This will in most circumstances make the generated ISR code more efficient
11772  since it will not have to save registers on the stack.
11773 \layout Standard
11774
11775 The
11776 \emph on
11777 using
11778 \emph default
11779  attribute will have no effect on the generated code for a
11780 \emph on
11781 non-interrupt
11782 \emph default
11783  function (but may occasionally be useful anyway
11784 \begin_inset Foot
11785 collapsed false
11786
11787 \layout Standard
11788
11789 possible exception: if a function is called ONLY from 'interrupt' functions
11790  using a particular bank, it can be declared with the same 'using' attribute
11791  as the calling 'interrupt' functions.
11792  For instance, if you have several ISRs using bank one, and all of them
11793  call memcpy(), it might make sense to create a specialized version of memcpy()
11794  'using 1', since this would prevent the ISR from having to save bank zero
11795  to the stack on entry and switch to bank zero before calling the function
11796 \end_inset
11797
11798 ).
11799 \newline
11800
11801 \emph on
11802 (pending: I don't think this has been done yet)
11803 \layout Standard
11804
11805 An
11806 \emph on
11807 interrupt
11808 \emph default
11809  function using a non-zero bank will assume that it can trash that register
11810  bank, and will not save it.
11811  Since high-priority interrupts
11812 \begin_inset LatexCommand \index{interrupts}
11813
11814 \end_inset
11815
11816
11817 \begin_inset LatexCommand \index{interrupt priority}
11818
11819 \end_inset
11820
11821  can interrupt low-priority ones on the 8051 and friends, this means that
11822  if a high-priority ISR
11823 \emph on
11824 using
11825 \emph default
11826  a particular bank occurs while processing a low-priority ISR
11827 \emph on
11828 using
11829 \emph default
11830  the same bank, terrible and bad things can happen.
11831  To prevent this, no single register bank should be
11832 \emph on
11833 used
11834 \emph default
11835  by both a high priority and a low priority ISR.
11836  This is probably most easily done by having all high priority ISRs use
11837  one bank and all low priority ISRs use another.
11838  If you have an ISR which can change priority at runtime, you're on your
11839  own: I suggest using the default bank zero and taking the small performance
11840  hit.
11841 \layout Standard
11842
11843 It is most efficient if your ISR calls no other functions.
11844  If your ISR must call other functions, it is most efficient if those functions
11845  use the same bank as the ISR (see note 1 below); the next best is if the
11846  called functions use bank zero.
11847  It is very inefficient to call a function using a different, non-zero bank
11848  from an ISR.
11849
11850 \layout Section
11851
11852 Startup Code
11853 \begin_inset LatexCommand \label{sub:Startup-Code}
11854
11855 \end_inset
11856
11857
11858 \begin_inset LatexCommand \index{Startup code}
11859
11860 \end_inset
11861
11862
11863 \layout Subsection
11864
11865 MCS51/DS390 Startup Code
11866 \layout Standard
11867
11868 The compiler inserts a call to the C routine
11869 \emph on
11870 _sdcc_external_startup()
11871 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11872
11873 \end_inset
11874
11875
11876 \series bold
11877 \emph default
11878
11879 \series default
11880 at the start of the CODE area.
11881  This routine is in the runtime library
11882 \begin_inset LatexCommand \index{Runtime library}
11883
11884 \end_inset
11885
11886 .
11887  By default this routine returns 0, if this routine returns a non-zero value,
11888  the static & global variable initialization will be skipped and the function
11889  main will be invoked.
11890  Otherwise static & global variables will be initialized before the function
11891  main is invoked.
11892  You could add a
11893 \emph on
11894 _sdcc_external_startup()
11895 \emph default
11896  routine to your program to override the default if you need to setup hardware
11897  or perform some other critical operation prior to static & global variable
11898  initialization
11899 \begin_inset LatexCommand \index{Variable initialization}
11900
11901 \end_inset
11902
11903 .
11904  On some mcs51 variants xdata
11905 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11906
11907 \end_inset
11908
11909  memory has to be explicitly enabled before it can be accessed or if the
11910  watchdog needs to be disabled, this is the place to do it.
11911  The startup code clears all internal data memory, 256 bytes by default,
11912  but from 0 to n-1 if
11913 \emph on
11914 -
11915 \begin_inset ERT
11916 status Collapsed
11917
11918 \layout Standard
11919
11920 \backslash
11921 /
11922 \end_inset
11923
11924 -iram-size
11925 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
11926
11927 \end_inset
11928
11929 n
11930 \emph default
11931  is used.
11932  (recommended for Chipcon CC1010).
11933 \layout Standard
11934
11935 See also the compiler option
11936 \emph on
11937 -
11938 \begin_inset ERT
11939 status Collapsed
11940
11941 \layout Standard
11942
11943 \backslash
11944 /
11945 \end_inset
11946
11947 -no-xinit
11948 \emph default
11949 -
11950 \emph on
11951 opt
11952 \emph default
11953
11954 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11955
11956 \end_inset
11957
11958  and section
11959 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11960
11961 \end_inset
11962
11963 \SpecialChar ~
11964 about MCS51-variants.
11965 \layout Subsection
11966
11967 HC08 Startup Code
11968 \layout Standard
11969
11970 The HC08 startup code follows the same scheme as the MCS51 startup code.
11971 \layout Subsection
11972
11973 Z80 Startup Code
11974 \layout Standard
11975
11976 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11977  from sdcc/device/lib/z80/crt0.s.
11978  If you need a different startup code you can use the compiler option
11979 \emph on
11980 -
11981 \series bold
11982 \emph default
11983
11984 \begin_inset ERT
11985 status Collapsed
11986
11987 \layout Standard
11988
11989 \backslash
11990 /
11991 \end_inset
11992
11993
11994 \series default
11995 \emph on
11996 -no-std-crt0
11997 \emph default
11998
11999 \begin_inset LatexCommand \index{-\/-no-std-crt0}
12000
12001 \end_inset
12002
12003  and provide your own crt0.o.
12004
12005 \layout Section
12006
12007 Inline Assembler Code
12008 \begin_inset LatexCommand \index{Assembler routines}
12009
12010 \end_inset
12011
12012
12013 \layout Subsection
12014
12015 A Step by Step Introduction
12016 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
12017
12018 \end_inset
12019
12020
12021 \layout Standard
12022
12023 Starting from a small snippet of c-code this example shows for the MCS51
12024  how to use inline assembly, access variables, a function parameter and
12025  an array in xdata memory.
12026  The example uses an MCS51 here but is easily adapted for other architectures.
12027  This is a buffer routine which should be optimized:
12028 \layout Verse
12029
12030
12031 \family typewriter
12032 \size footnotesize
12033 unsigned char far
12034 \begin_inset LatexCommand \index{far (storage class)}
12035
12036 \end_inset
12037
12038
12039 \begin_inset LatexCommand \index{\_\_far (storage class)}
12040
12041 \end_inset
12042
12043  at
12044 \begin_inset LatexCommand \index{at}
12045
12046 \end_inset
12047
12048
12049 \begin_inset LatexCommand \index{\_\_at}
12050
12051 \end_inset
12052
12053  0x7f00 buf[0x100];
12054 \begin_inset LatexCommand \index{Aligned array}
12055
12056 \end_inset
12057
12058
12059 \newline
12060 unsigned char head,tail;
12061 \newline
12062
12063 \newline
12064 void to_buffer( unsigned char c )
12065 \newline
12066 {
12067 \newline
12068 \SpecialChar ~
12069 \SpecialChar ~
12070 \SpecialChar ~
12071 \SpecialChar ~
12072 if( head != tail-1 )
12073 \newline
12074 \SpecialChar ~
12075 \SpecialChar ~
12076 \SpecialChar ~
12077 \SpecialChar ~
12078 \SpecialChar ~
12079 \SpecialChar ~
12080 \SpecialChar ~
12081 \SpecialChar ~
12082 buf[ head++ ] = c;\SpecialChar ~
12083 \SpecialChar ~
12084 \SpecialChar ~
12085 \SpecialChar ~
12086 /* access to a 256 byte aligned array */
12087 \newline
12088 }
12089 \layout Standard
12090
12091 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
12092  then a corresponding buffer.asm file is generated.
12093  We define a new function
12094 \family typewriter
12095 to_buffer_asm()
12096 \family default
12097  in file buffer.c in which we cut and paste the generated code, removing
12098  unwanted comments and some ':'.
12099  Then add
12100 \begin_inset Quotes sld
12101 \end_inset
12102
12103 _asm
12104 \begin_inset Quotes srd
12105 \end_inset
12106
12107  and
12108 \begin_inset Quotes sld
12109 \end_inset
12110
12111 _endasm;
12112 \begin_inset Quotes srd
12113 \end_inset
12114
12115  to the beginning and the end of the function body:
12116 \layout Verse
12117
12118
12119 \family typewriter
12120 \size footnotesize
12121 /* With a cut and paste from the .asm file, we have something to start with.
12122 \newline
12123 \SpecialChar ~
12124 \SpecialChar ~
12125 \SpecialChar ~
12126 The function is not yet OK! (registers aren't saved) */
12127 \newline
12128 void to_buffer_asm( unsigned char c )
12129 \newline
12130 {
12131 \newline
12132 \SpecialChar ~
12133 \SpecialChar ~
12134 \SpecialChar ~
12135 \SpecialChar ~
12136 _asm
12137 \begin_inset LatexCommand \index{\_asm}
12138
12139 \end_inset
12140
12141
12142 \begin_inset LatexCommand \index{\_\_asm}
12143
12144 \end_inset
12145
12146
12147 \newline
12148 \SpecialChar ~
12149 \SpecialChar ~
12150 \SpecialChar ~
12151 \SpecialChar ~
12152 mov\SpecialChar ~
12153 \SpecialChar ~
12154 r2,dpl
12155 \newline
12156 ;buffer.c if( head != tail-1 )
12157 \newline
12158 \SpecialChar ~
12159 \SpecialChar ~
12160 \SpecialChar ~
12161 \SpecialChar ~
12162 mov\SpecialChar ~
12163 \SpecialChar ~
12164 a,_tail
12165 \newline
12166 \SpecialChar ~
12167 \SpecialChar ~
12168 \SpecialChar ~
12169 \SpecialChar ~
12170 dec\SpecialChar ~
12171 \SpecialChar ~
12172 a
12173 \newline
12174 \SpecialChar ~
12175 \SpecialChar ~
12176 \SpecialChar ~
12177 \SpecialChar ~
12178 mov\SpecialChar ~
12179 \SpecialChar ~
12180 r3,a
12181 \newline
12182 \SpecialChar ~
12183 \SpecialChar ~
12184 \SpecialChar ~
12185 \SpecialChar ~
12186 mov\SpecialChar ~
12187 \SpecialChar ~
12188 a,_head
12189 \newline
12190 \SpecialChar ~
12191 \SpecialChar ~
12192 \SpecialChar ~
12193 \SpecialChar ~
12194 cjne a,ar3,00106$
12195 \newline
12196 \SpecialChar ~
12197 \SpecialChar ~
12198 \SpecialChar ~
12199 \SpecialChar ~
12200 ret
12201 \newline
12202 00106$:
12203 \newline
12204 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12205 \begin_inset LatexCommand \index{Aligned array}
12206
12207 \end_inset
12208
12209
12210 \newline
12211 \SpecialChar ~
12212 \SpecialChar ~
12213 \SpecialChar ~
12214 \SpecialChar ~
12215 mov\SpecialChar ~
12216 \SpecialChar ~
12217 r3,_head
12218 \newline
12219 \SpecialChar ~
12220 \SpecialChar ~
12221 \SpecialChar ~
12222 \SpecialChar ~
12223 inc\SpecialChar ~
12224 \SpecialChar ~
12225 _head
12226 \newline
12227 \SpecialChar ~
12228 \SpecialChar ~
12229 \SpecialChar ~
12230 \SpecialChar ~
12231 mov\SpecialChar ~
12232 \SpecialChar ~
12233 dpl,r3
12234 \newline
12235 \SpecialChar ~
12236 \SpecialChar ~
12237 \SpecialChar ~
12238 \SpecialChar ~
12239 mov\SpecialChar ~
12240 \SpecialChar ~
12241 dph,#(_buf >> 8)
12242 \newline
12243 \SpecialChar ~
12244 \SpecialChar ~
12245 \SpecialChar ~
12246 \SpecialChar ~
12247 mov\SpecialChar ~
12248 \SpecialChar ~
12249 a,r2
12250 \newline
12251 \SpecialChar ~
12252 \SpecialChar ~
12253 \SpecialChar ~
12254 \SpecialChar ~
12255 movx @dptr,a
12256 \newline
12257 00103$:
12258 \newline
12259 \SpecialChar ~
12260 \SpecialChar ~
12261 \SpecialChar ~
12262 \SpecialChar ~
12263 ret
12264 \newline
12265 \SpecialChar ~
12266 \SpecialChar ~
12267 \SpecialChar ~
12268 \SpecialChar ~
12269 _endasm
12270 \begin_inset LatexCommand \index{\_endasm}
12271
12272 \end_inset
12273
12274
12275 \begin_inset LatexCommand \index{\_\_endasm}
12276
12277 \end_inset
12278
12279 ;
12280 \newline
12281 }
12282 \layout Standard
12283
12284 The new file buffer.c should compile with only one warning about the unreferenced
12285  function argument 'c'.
12286  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12287  (1) and finally have:
12288 \layout Verse
12289
12290
12291 \family typewriter
12292 \size footnotesize
12293 unsigned char far at 0x7f00 buf[0x100];
12294 \newline
12295 unsigned char head,tail;
12296 \newline
12297 #define USE_ASSEMBLY (1)
12298 \newline
12299
12300 \newline
12301 #if !USE_ASSEMBLY
12302 \newline
12303
12304 \newline
12305 void to_buffer( unsigned char c )
12306 \newline
12307 {
12308 \newline
12309 \SpecialChar ~
12310 \SpecialChar ~
12311 \SpecialChar ~
12312 \SpecialChar ~
12313 if( head != tail-1 )
12314 \newline
12315 \SpecialChar ~
12316 \SpecialChar ~
12317 \SpecialChar ~
12318 \SpecialChar ~
12319 \SpecialChar ~
12320 \SpecialChar ~
12321 \SpecialChar ~
12322 \SpecialChar ~
12323 buf[ head++ ] = c;
12324 \newline
12325 }
12326 \newline
12327
12328 \newline
12329 #else
12330 \newline
12331
12332 \newline
12333 void to_buffer( unsigned char c )
12334 \newline
12335 {
12336 \newline
12337 \SpecialChar ~
12338 \SpecialChar ~
12339 \SpecialChar ~
12340 \SpecialChar ~
12341 c; // to avoid warning: unreferenced function argument
12342 \newline
12343 \SpecialChar ~
12344 \SpecialChar ~
12345 \SpecialChar ~
12346 \SpecialChar ~
12347 _asm
12348 \begin_inset LatexCommand \index{\_asm}
12349
12350 \end_inset
12351
12352
12353 \begin_inset LatexCommand \index{\_\_asm}
12354
12355 \end_inset
12356
12357
12358 \newline
12359 \SpecialChar ~
12360 \SpecialChar ~
12361 \SpecialChar ~
12362 \SpecialChar ~
12363 \SpecialChar ~
12364 \SpecialChar ~
12365 \SpecialChar ~
12366 \SpecialChar ~
12367 ; save used registers here.
12368
12369 \newline
12370 \SpecialChar ~
12371 \SpecialChar ~
12372 \SpecialChar ~
12373 \SpecialChar ~
12374 \SpecialChar ~
12375 \SpecialChar ~
12376 \SpecialChar ~
12377 \SpecialChar ~
12378 ; If we were still using r2,r3 we would have to push them here.
12379
12380 \newline
12381 ; if( head != tail-1 )
12382 \newline
12383 \SpecialChar ~
12384 \SpecialChar ~
12385 \SpecialChar ~
12386 \SpecialChar ~
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 mov\SpecialChar ~
12392  a,_tail
12393 \newline
12394 \SpecialChar ~
12395 \SpecialChar ~
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 \SpecialChar ~
12399 \SpecialChar ~
12400 \SpecialChar ~
12401 \SpecialChar ~
12402 dec\SpecialChar ~
12403  a
12404 \newline
12405 \SpecialChar ~
12406 \SpecialChar ~
12407 \SpecialChar ~
12408 \SpecialChar ~
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 xrl\SpecialChar ~
12414  a,_head
12415 \newline
12416 \SpecialChar ~
12417 \SpecialChar ~
12418 \SpecialChar ~
12419 \SpecialChar ~
12420 \SpecialChar ~
12421 \SpecialChar ~
12422 \SpecialChar ~
12423 \SpecialChar ~
12424 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
12425 \newline
12426 \SpecialChar ~
12427 \SpecialChar ~
12428 \SpecialChar ~
12429 \SpecialChar ~
12430 \SpecialChar ~
12431 \SpecialChar ~
12432 \SpecialChar ~
12433 \SpecialChar ~
12434 jz\SpecialChar ~
12435 \SpecialChar ~
12436  t_b_end$
12437 \newline
12438 \SpecialChar ~
12439 \SpecialChar ~
12440 \SpecialChar ~
12441 \SpecialChar ~
12442 \SpecialChar ~
12443 \SpecialChar ~
12444 \SpecialChar ~
12445 \SpecialChar ~
12446 ;
12447 \newline
12448 ; buf[ head++ ] = c;
12449 \newline
12450 \SpecialChar ~
12451 \SpecialChar ~
12452 \SpecialChar ~
12453 \SpecialChar ~
12454 \SpecialChar ~
12455 \SpecialChar ~
12456 \SpecialChar ~
12457 \SpecialChar ~
12458 mov\SpecialChar ~
12459  a,dpl \SpecialChar ~
12460 \SpecialChar ~
12461 \SpecialChar ~
12462 \SpecialChar ~
12463 \SpecialChar ~
12464 \SpecialChar ~
12465 \SpecialChar ~
12466 ; dpl holds lower byte of function argument
12467 \newline
12468 \SpecialChar ~
12469 \SpecialChar ~
12470 \SpecialChar ~
12471 \SpecialChar ~
12472 \SpecialChar ~
12473 \SpecialChar ~
12474 \SpecialChar ~
12475 \SpecialChar ~
12476 mov\SpecialChar ~
12477  dpl,_head \SpecialChar ~
12478 \SpecialChar ~
12479 \SpecialChar ~
12480 ; buf is 0x100 byte aligned so head can be used directly
12481 \newline
12482 \SpecialChar ~
12483 \SpecialChar ~
12484 \SpecialChar ~
12485 \SpecialChar ~
12486 \SpecialChar ~
12487 \SpecialChar ~
12488 \SpecialChar ~
12489 \SpecialChar ~
12490 mov\SpecialChar ~
12491  dph,#(_buf>>8)
12492 \newline
12493 \SpecialChar ~
12494 \SpecialChar ~
12495 \SpecialChar ~
12496 \SpecialChar ~
12497 \SpecialChar ~
12498 \SpecialChar ~
12499 \SpecialChar ~
12500 \SpecialChar ~
12501 movx @dptr,a
12502 \newline
12503 \SpecialChar ~
12504 \SpecialChar ~
12505 \SpecialChar ~
12506 \SpecialChar ~
12507 \SpecialChar ~
12508 \SpecialChar ~
12509 \SpecialChar ~
12510 \SpecialChar ~
12511 inc \SpecialChar ~
12512 _head
12513 \newline
12514 \SpecialChar ~
12515 \SpecialChar ~
12516 \SpecialChar ~
12517 \SpecialChar ~
12518 \SpecialChar ~
12519 \SpecialChar ~
12520 \SpecialChar ~
12521 \SpecialChar ~
12522 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
12523 \newline
12524 t_b_end$:
12525 \newline
12526 \SpecialChar ~
12527 \SpecialChar ~
12528 \SpecialChar ~
12529 \SpecialChar ~
12530 \SpecialChar ~
12531 \SpecialChar ~
12532 \SpecialChar ~
12533 \SpecialChar ~
12534 ; restore used registers here
12535 \newline
12536 \SpecialChar ~
12537 \SpecialChar ~
12538 \SpecialChar ~
12539 \SpecialChar ~
12540 _endasm
12541 \begin_inset LatexCommand \index{\_endasm}
12542
12543 \end_inset
12544
12545
12546 \begin_inset LatexCommand \index{\_\_endasm}
12547
12548 \end_inset
12549
12550 ;
12551 \newline
12552 }
12553 \newline
12554 #endif
12555 \layout Standard
12556
12557 The inline assembler code can contain any valid code understood by the assembler
12558 , this includes any assembler directives and comment lines
12559 \begin_inset Foot
12560 collapsed false
12561
12562 \layout Standard
12563
12564 The assembler does not like some characters like ':' or ''' in comments.
12565  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
12566 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
12567
12568 \end_inset
12569
12570
12571 \begin_inset LatexCommand \index{Assembler documentation}
12572
12573 \end_inset
12574
12575
12576 \end_inset
12577
12578 .
12579  The compiler does not do any validation of the code within the
12580 \family typewriter
12581 _asm
12582 \begin_inset LatexCommand \index{\_asm}
12583
12584 \end_inset
12585
12586
12587 \begin_inset LatexCommand \index{\_\_asm}
12588
12589 \end_inset
12590
12591  ...
12592  _endasm
12593 \size footnotesize
12594
12595 \begin_inset LatexCommand \index{\_endasm}
12596
12597 \end_inset
12598
12599
12600 \begin_inset LatexCommand \index{\_\_endasm}
12601
12602 \end_inset
12603
12604
12605 \size default
12606 ;
12607 \family default
12608  keyword pair.
12609  Specifically it will not know which registers are used and thus register
12610  pushing/popping
12611 \begin_inset LatexCommand \index{push/pop}
12612
12613 \end_inset
12614
12615  has to be done manually.
12616
12617 \layout Standard
12618
12619 It is recommended that each assembly instruction (including labels) be placed
12620  in a separate line (as the example shows).
12621  When the -
12622 \begin_inset ERT
12623 status Collapsed
12624
12625 \layout Standard
12626
12627 \backslash
12628 /
12629 \end_inset
12630
12631 -
12632 \emph on
12633 peep-asm
12634 \begin_inset LatexCommand \index{-\/-peep-asm}
12635
12636 \end_inset
12637
12638
12639 \emph default
12640  command line option is used, the inline assembler code will be passed through
12641  the peephole optimizer
12642 \begin_inset LatexCommand \index{Peephole optimizer}
12643
12644 \end_inset
12645
12646 .
12647  There are only a few (if any) cases where this option makes sense, it might
12648  cause some unexpected changes in the inline assembler code.
12649  Please go through the peephole optimizer rules defined in file
12650 \emph on
12651 SDCCpeeph.def
12652 \emph default
12653  before using this option.
12654 \layout Subsection
12655
12656 Naked Functions
12657 \begin_inset LatexCommand \label{sub:Naked-Functions}
12658
12659 \end_inset
12660
12661
12662 \begin_inset LatexCommand \index{Naked functions}
12663
12664 \end_inset
12665
12666
12667 \layout Standard
12668
12669 A special keyword may be associated with a function declaring it as
12670 \emph on
12671 _naked
12672 \begin_inset LatexCommand \index{\_naked}
12673
12674 \end_inset
12675
12676
12677 \begin_inset LatexCommand \index{\_\_naked}
12678
12679 \end_inset
12680
12681 .
12682
12683 \emph default
12684 The
12685 \emph on
12686 _naked
12687 \emph default
12688  function modifier attribute prevents the compiler from generating prologue
12689 \begin_inset LatexCommand \index{function prologue}
12690
12691 \end_inset
12692
12693  and epilogue
12694 \begin_inset LatexCommand \index{function epilogue}
12695
12696 \end_inset
12697
12698  code for that function.
12699  This means that the user is entirely responsible for such things as saving
12700  any registers that may need to be preserved, selecting the proper register
12701  bank, generating the
12702 \emph on
12703 return
12704 \emph default
12705  instruction at the end, etc.
12706  Practically, this means that the contents of the function must be written
12707  in inline assembler.
12708  This is particularly useful for interrupt functions, which can have a large
12709  (and often unnecessary) prologue/epilogue.
12710  For example, compare the code generated by these two functions:
12711 \layout Verse
12712
12713
12714 \family typewriter
12715 volatile
12716 \begin_inset LatexCommand \index{volatile}
12717
12718 \end_inset
12719
12720  data unsigned char counter;
12721 \newline
12722
12723 \newline
12724 void simpleInterrupt(void) interrupt
12725 \begin_inset LatexCommand \index{interrupt}
12726
12727 \end_inset
12728
12729
12730 \begin_inset LatexCommand \index{\_\_interrupt}
12731
12732 \end_inset
12733
12734  1
12735 \newline
12736 {
12737 \newline
12738 \SpecialChar ~
12739 \SpecialChar ~
12740 \SpecialChar ~
12741 \SpecialChar ~
12742 counter++;
12743 \newline
12744 }
12745 \newline
12746
12747 \newline
12748 void nakedInterrupt(void) interrupt 2 _naked
12749 \newline
12750 {
12751 \newline
12752 \SpecialChar ~
12753 \SpecialChar ~
12754 \SpecialChar ~
12755 \SpecialChar ~
12756 _asm
12757 \begin_inset LatexCommand \index{\_asm}
12758
12759 \end_inset
12760
12761
12762 \begin_inset LatexCommand \index{\_\_asm}
12763
12764 \end_inset
12765
12766
12767 \newline
12768 \SpecialChar ~
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 \SpecialChar ~
12773 \SpecialChar ~
12774 inc\SpecialChar ~
12775 \SpecialChar ~
12776 \SpecialChar ~
12777 \SpecialChar ~
12778 \SpecialChar ~
12779 _counter ; does not change flags, no need to save psw
12780 \newline
12781 \SpecialChar ~
12782 \SpecialChar ~
12783 \SpecialChar ~
12784 \SpecialChar ~
12785 \SpecialChar ~
12786 \SpecialChar ~
12787 reti\SpecialChar ~
12788 \SpecialChar ~
12789 \SpecialChar ~
12790 \SpecialChar ~
12791 ; MUST explicitly include ret or reti in _naked function.
12792 \newline
12793 \SpecialChar ~
12794 \SpecialChar ~
12795 \SpecialChar ~
12796 \SpecialChar ~
12797 _endasm
12798 \begin_inset LatexCommand \index{\_endasm}
12799
12800 \end_inset
12801
12802
12803 \begin_inset LatexCommand \index{\_\_endasm}
12804
12805 \end_inset
12806
12807 ;
12808 \newline
12809 }
12810 \layout Standard
12811
12812 For an 8051 target, the generated simpleInterrupt looks like:
12813 \layout Verse
12814
12815
12816 \family typewriter
12817 _simpleInterrupt:
12818 \newline
12819 \SpecialChar ~
12820 \SpecialChar ~
12821 \SpecialChar ~
12822 \SpecialChar ~
12823 push\SpecialChar ~
12824 \SpecialChar ~
12825 \SpecialChar ~
12826 \SpecialChar ~
12827 acc
12828 \newline
12829 \SpecialChar ~
12830 \SpecialChar ~
12831 \SpecialChar ~
12832 \SpecialChar ~
12833 push\SpecialChar ~
12834 \SpecialChar ~
12835 \SpecialChar ~
12836 \SpecialChar ~
12837 b
12838 \newline
12839 \SpecialChar ~
12840 \SpecialChar ~
12841 \SpecialChar ~
12842 \SpecialChar ~
12843 push\SpecialChar ~
12844 \SpecialChar ~
12845 \SpecialChar ~
12846 \SpecialChar ~
12847 dpl
12848 \newline
12849 \SpecialChar ~
12850 \SpecialChar ~
12851 \SpecialChar ~
12852 \SpecialChar ~
12853 push\SpecialChar ~
12854 \SpecialChar ~
12855 \SpecialChar ~
12856 \SpecialChar ~
12857 dph
12858 \newline
12859 \SpecialChar ~
12860 \SpecialChar ~
12861 \SpecialChar ~
12862 \SpecialChar ~
12863 push\SpecialChar ~
12864 \SpecialChar ~
12865 \SpecialChar ~
12866 \SpecialChar ~
12867 psw
12868 \newline
12869 \SpecialChar ~
12870 \SpecialChar ~
12871 \SpecialChar ~
12872 \SpecialChar ~
12873 mov\SpecialChar ~
12874 \SpecialChar ~
12875 \SpecialChar ~
12876 \SpecialChar ~
12877 \SpecialChar ~
12878 psw,#0x00
12879 \newline
12880 \SpecialChar ~
12881 \SpecialChar ~
12882 \SpecialChar ~
12883 \SpecialChar ~
12884 inc\SpecialChar ~
12885 \SpecialChar ~
12886 \SpecialChar ~
12887 \SpecialChar ~
12888 \SpecialChar ~
12889 _counter
12890 \newline
12891 \SpecialChar ~
12892 \SpecialChar ~
12893 \SpecialChar ~
12894 \SpecialChar ~
12895 pop\SpecialChar ~
12896 \SpecialChar ~
12897 \SpecialChar ~
12898 \SpecialChar ~
12899 \SpecialChar ~
12900 psw
12901 \newline
12902 \SpecialChar ~
12903 \SpecialChar ~
12904 \SpecialChar ~
12905 \SpecialChar ~
12906 pop\SpecialChar ~
12907 \SpecialChar ~
12908 \SpecialChar ~
12909 \SpecialChar ~
12910 \SpecialChar ~
12911 dph
12912 \newline
12913 \SpecialChar ~
12914 \SpecialChar ~
12915 \SpecialChar ~
12916 \SpecialChar ~
12917 pop\SpecialChar ~
12918 \SpecialChar ~
12919 \SpecialChar ~
12920 \SpecialChar ~
12921 \SpecialChar ~
12922 dpl
12923 \newline
12924 \SpecialChar ~
12925 \SpecialChar ~
12926 \SpecialChar ~
12927 \SpecialChar ~
12928 pop\SpecialChar ~
12929 \SpecialChar ~
12930 \SpecialChar ~
12931 \SpecialChar ~
12932 \SpecialChar ~
12933 b
12934 \newline
12935 \SpecialChar ~
12936 \SpecialChar ~
12937 \SpecialChar ~
12938 \SpecialChar ~
12939 pop\SpecialChar ~
12940 \SpecialChar ~
12941 \SpecialChar ~
12942 \SpecialChar ~
12943 \SpecialChar ~
12944 acc
12945 \newline
12946 \SpecialChar ~
12947 \SpecialChar ~
12948 \SpecialChar ~
12949 \SpecialChar ~
12950 reti
12951 \layout Standard
12952
12953 whereas nakedInterrupt looks like:
12954 \layout Verse
12955
12956
12957 \family typewriter
12958 _nakedInterrupt:
12959 \newline
12960 \SpecialChar ~
12961 \SpecialChar ~
12962 \SpecialChar ~
12963 \SpecialChar ~
12964 inc\SpecialChar ~
12965 \SpecialChar ~
12966 \SpecialChar ~
12967 \SpecialChar ~
12968 _counter ; does not change flags, no need to save psw
12969 \newline
12970 \SpecialChar ~
12971 \SpecialChar ~
12972 \SpecialChar ~
12973 \SpecialChar ~
12974 reti\SpecialChar ~
12975 \SpecialChar ~
12976 \SpecialChar ~
12977 \SpecialChar ~
12978 \SpecialChar ~
12979 \SpecialChar ~
12980 \SpecialChar ~
12981 \SpecialChar ~
12982 \SpecialChar ~
12983 \SpecialChar ~
12984 \SpecialChar ~
12985 \SpecialChar ~
12986 ; MUST explicitly include ret or reti in _naked function
12987 \layout Standard
12988
12989 The related directive #pragma exclude
12990 \begin_inset LatexCommand \index{\#pragma exclude}
12991
12992 \end_inset
12993
12994  allows a more fine grained control over pushing & popping
12995 \begin_inset LatexCommand \index{push/pop}
12996
12997 \end_inset
12998
12999  the registers.
13000 \layout Standard
13001
13002 While there is nothing preventing you from writing C code inside a
13003 \family typewriter
13004 _naked
13005 \family default
13006  function, there are many ways to shoot yourself in the foot doing this,
13007  and it is recommended that you stick to inline assembler.
13008 \layout Subsection
13009
13010 Use of Labels within Inline Assembler
13011 \layout Standard
13012
13013 SDCC allows the use of in-line assembler with a few restrictions regarding
13014  labels.
13015  In older versions of the compiler all labels defined within inline assembler
13016  code
13017 \emph on
13018 had to be
13019 \emph default
13020  of the form
13021 \emph on
13022 nnnnn$
13023 \emph default
13024  where nnnn is a number less than 100 (which implies a limit of utmost 100
13025  inline assembler labels
13026 \emph on
13027 per function
13028 \emph default
13029 \noun on
13030 )
13031 \noun default
13032 .
13033
13034 \layout Verse
13035
13036
13037 \family typewriter
13038 _asm
13039 \begin_inset LatexCommand \index{\_asm}
13040
13041 \end_inset
13042
13043
13044 \begin_inset LatexCommand \index{\_\_asm}
13045
13046 \end_inset
13047
13048
13049 \newline
13050 \SpecialChar ~
13051 \SpecialChar ~
13052 \SpecialChar ~
13053 \SpecialChar ~
13054 mov\SpecialChar ~
13055 \SpecialChar ~
13056 \SpecialChar ~
13057 \SpecialChar ~
13058 \SpecialChar ~
13059 b,#10
13060 \newline
13061 00001$:
13062 \newline
13063 \SpecialChar ~
13064 \SpecialChar ~
13065 \SpecialChar ~
13066 \SpecialChar ~
13067 djnz\SpecialChar ~
13068 \SpecialChar ~
13069 \SpecialChar ~
13070 \SpecialChar ~
13071 b,00001$
13072 \newline
13073 _endasm
13074 \begin_inset LatexCommand \index{\_endasm}
13075
13076 \end_inset
13077
13078
13079 \begin_inset LatexCommand \index{\_\_endasm}
13080
13081 \end_inset
13082
13083  ;
13084 \layout Standard
13085
13086 Inline assembler code cannot reference any C-Labels, however it can reference
13087  labels
13088 \begin_inset LatexCommand \index{Labels}
13089
13090 \end_inset
13091
13092  defined by the inline assembler, e.g.:
13093 \layout Verse
13094
13095
13096 \family typewriter
13097 foo() {
13098 \newline
13099 \SpecialChar ~
13100 \SpecialChar ~
13101 \SpecialChar ~
13102 \SpecialChar ~
13103 /* some c code */
13104 \newline
13105 \SpecialChar ~
13106 \SpecialChar ~
13107 \SpecialChar ~
13108 \SpecialChar ~
13109 _asm
13110 \newline
13111 \SpecialChar ~
13112 \SpecialChar ~
13113 \SpecialChar ~
13114 \SpecialChar ~
13115 \SpecialChar ~
13116 \SpecialChar ~
13117 ; some assembler code
13118 \newline
13119 \SpecialChar ~
13120 \SpecialChar ~
13121 \SpecialChar ~
13122 \SpecialChar ~
13123 \SpecialChar ~
13124 \SpecialChar ~
13125 ljmp $0003
13126 \newline
13127 \SpecialChar ~
13128 \SpecialChar ~
13129 \SpecialChar ~
13130 \SpecialChar ~
13131 _endasm;
13132 \newline
13133 \SpecialChar ~
13134 \SpecialChar ~
13135 \SpecialChar ~
13136 \SpecialChar ~
13137 /* some more c code */
13138 \newline
13139 clabel:\SpecialChar ~
13140 \SpecialChar ~
13141 /* inline assembler cannot reference this label */
13142 \newline
13143 \SpecialChar ~
13144 \SpecialChar ~
13145 \SpecialChar ~
13146 \SpecialChar ~
13147 _asm
13148 \newline
13149 \SpecialChar ~
13150 \SpecialChar ~
13151 \SpecialChar ~
13152 \SpecialChar ~
13153 $0003: ;label (can be referenced by inline assembler only)
13154 \newline
13155 \SpecialChar ~
13156 \SpecialChar ~
13157 \SpecialChar ~
13158 \SpecialChar ~
13159 _endasm
13160 \begin_inset LatexCommand \index{\_endasm}
13161
13162 \end_inset
13163
13164
13165 \begin_inset LatexCommand \index{\_\_endasm}
13166
13167 \end_inset
13168
13169  ;
13170 \newline
13171 \SpecialChar ~
13172 \SpecialChar ~
13173 \SpecialChar ~
13174 \SpecialChar ~
13175 /* some more c code */
13176 \newline
13177 }
13178 \layout Standard
13179
13180 In other words inline assembly code can access labels defined in inline
13181  assembly within the scope of the function.
13182  The same goes the other way, i.e.
13183  labels defines in inline assembly can not be accessed by C statements.
13184 \layout Section
13185
13186 Interfacing with Assembler Code
13187 \begin_inset LatexCommand \index{Assembler routines}
13188
13189 \end_inset
13190
13191
13192 \layout Subsection
13193
13194 Global Registers used for Parameter Passing
13195 \begin_inset LatexCommand \index{Parameter passing}
13196
13197 \end_inset
13198
13199
13200 \layout Standard
13201
13202 The compiler always uses the global registers
13203 \emph on
13204 DPL, DPH
13205 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13206
13207 \end_inset
13208
13209
13210 \begin_inset LatexCommand \index{DPTR}
13211
13212 \end_inset
13213
13214 , B
13215 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13216
13217 \end_inset
13218
13219
13220 \emph default
13221 and
13222 \emph on
13223  ACC
13224 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13225
13226 \end_inset
13227
13228
13229 \emph default
13230  to pass the first parameter to a routine.
13231  The second parameter onwards is either allocated on the stack (for reentrant
13232  routines or if -
13233 \begin_inset ERT
13234 status Collapsed
13235
13236 \layout Standard
13237
13238 \backslash
13239 /
13240 \end_inset
13241
13242 -stack-auto is used) or in data / xdata memory (depending on the memory
13243  model).
13244
13245 \layout Subsection
13246
13247 Assembler Routine (non-reentrant)
13248 \layout Standard
13249
13250 In the following example
13251 \begin_inset LatexCommand \index{reentrant}
13252
13253 \end_inset
13254
13255
13256 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13257
13258 \end_inset
13259
13260  the function c_func calls an assembler routine asm_func, which takes two
13261  parameters
13262 \begin_inset LatexCommand \index{function parameter}
13263
13264 \end_inset
13265
13266 .
13267 \layout Verse
13268
13269
13270 \family typewriter
13271 extern int asm_func(unsigned char, unsigned char);
13272 \newline
13273
13274 \newline
13275 int c_func (unsigned char i, unsigned char j)
13276 \newline
13277 {
13278 \newline
13279 \SpecialChar ~
13280 \SpecialChar ~
13281 \SpecialChar ~
13282 \SpecialChar ~
13283 return asm_func(i,j);
13284 \newline
13285 }
13286 \newline
13287
13288 \newline
13289 int main()
13290 \newline
13291 {
13292 \newline
13293 \SpecialChar ~
13294 \SpecialChar ~
13295 \SpecialChar ~
13296 \SpecialChar ~
13297 return c_func(10,9);
13298 \newline
13299 }
13300 \layout Standard
13301
13302 The corresponding assembler function is:
13303 \layout Verse
13304
13305
13306 \family typewriter
13307 .globl _asm_func_PARM_2
13308 \newline
13309 \SpecialChar ~
13310 \SpecialChar ~
13311 \SpecialChar ~
13312 \SpecialChar ~
13313 \SpecialChar ~
13314 \SpecialChar ~
13315 \SpecialChar ~
13316 \SpecialChar ~
13317 .globl _asm_func
13318 \newline
13319 \SpecialChar ~
13320 \SpecialChar ~
13321 \SpecialChar ~
13322 \SpecialChar ~
13323 \SpecialChar ~
13324 \SpecialChar ~
13325 \SpecialChar ~
13326 \SpecialChar ~
13327 .area OSEG
13328 \newline
13329 _asm_func_PARM_2:
13330 \newline
13331 \SpecialChar ~
13332 \SpecialChar ~
13333 \SpecialChar ~
13334 \SpecialChar ~
13335 \SpecialChar ~
13336 \SpecialChar ~
13337 \SpecialChar ~
13338 \SpecialChar ~
13339 .ds    1
13340 \newline
13341 \SpecialChar ~
13342 \SpecialChar ~
13343 \SpecialChar ~
13344 \SpecialChar ~
13345 \SpecialChar ~
13346 \SpecialChar ~
13347 \SpecialChar ~
13348 \SpecialChar ~
13349 .area CSEG
13350 \newline
13351 _asm_func:
13352 \newline
13353 \SpecialChar ~
13354 \SpecialChar ~
13355 \SpecialChar ~
13356 \SpecialChar ~
13357 \SpecialChar ~
13358 \SpecialChar ~
13359 \SpecialChar ~
13360 \SpecialChar ~
13361 mov\SpecialChar ~
13362 \SpecialChar ~
13363 \SpecialChar ~
13364 \SpecialChar ~
13365 a,dpl
13366 \newline
13367 \SpecialChar ~
13368 \SpecialChar ~
13369 \SpecialChar ~
13370 \SpecialChar ~
13371 \SpecialChar ~
13372 \SpecialChar ~
13373 \SpecialChar ~
13374 \SpecialChar ~
13375 add\SpecialChar ~
13376 \SpecialChar ~
13377 \SpecialChar ~
13378 \SpecialChar ~
13379 a,_asm_func_PARM_2
13380 \newline
13381 \SpecialChar ~
13382 \SpecialChar ~
13383 \SpecialChar ~
13384 \SpecialChar ~
13385 \SpecialChar ~
13386 \SpecialChar ~
13387 \SpecialChar ~
13388 \SpecialChar ~
13389 mov\SpecialChar ~
13390 \SpecialChar ~
13391 \SpecialChar ~
13392 \SpecialChar ~
13393 dpl,a
13394 \newline
13395 \SpecialChar ~
13396 \SpecialChar ~
13397 \SpecialChar ~
13398 \SpecialChar ~
13399 \SpecialChar ~
13400 \SpecialChar ~
13401 \SpecialChar ~
13402 \SpecialChar ~
13403 mov\SpecialChar ~
13404 \SpecialChar ~
13405 \SpecialChar ~
13406 \SpecialChar ~
13407 dph
13408 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13409
13410 \end_inset
13411
13412 ,#0x00
13413 \newline
13414 \SpecialChar ~
13415 \SpecialChar ~
13416 \SpecialChar ~
13417 \SpecialChar ~
13418 \SpecialChar ~
13419 \SpecialChar ~
13420 \SpecialChar ~
13421 \SpecialChar ~
13422 ret
13423 \layout Standard
13424
13425 Note here that the return values
13426 \begin_inset LatexCommand \index{return value}
13427
13428 \end_inset
13429
13430  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
13431  two byte values.
13432  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
13433 b' & 'acc' for four byte values.
13434 \layout Standard
13435
13436 The parameter naming convention is _<function_name>_PARM_<n>, where n is
13437  the parameter number starting from 1, and counting from the left.
13438  The first parameter is passed in
13439 \begin_inset Quotes eld
13440 \end_inset
13441
13442 dpl
13443 \begin_inset Quotes erd
13444 \end_inset
13445
13446  for a one byte parameter,
13447 \begin_inset Quotes eld
13448 \end_inset
13449
13450 dptr
13451 \begin_inset Quotes erd
13452 \end_inset
13453
13454  for two bytes,
13455 \begin_inset Quotes eld
13456 \end_inset
13457
13458 b,dptr
13459 \begin_inset Quotes erd
13460 \end_inset
13461
13462  for three bytes and
13463 \begin_inset Quotes eld
13464 \end_inset
13465
13466 acc,b,dptr
13467 \begin_inset Quotes erd
13468 \end_inset
13469
13470  for a four bytes parameter.
13471  The variable name for the second parameter will be _<function_name>_PARM_2.
13472 \newline
13473
13474 \newline
13475 Assemble the assembler routine with the following command:
13476 \newline
13477
13478 \newline
13479
13480 \family sans
13481 \series bold
13482 asx8051 -losg asmfunc.asm
13483 \newline
13484
13485 \newline
13486
13487 \family default
13488 \series default
13489 Then compile and link the assembler routine to the C source file with the
13490  following command:
13491 \newline
13492
13493 \newline
13494
13495 \family sans
13496 \series bold
13497 sdcc cfunc.c asmfunc.rel
13498 \layout Subsection
13499
13500 Assembler Routine (reentrant)
13501 \layout Standard
13502
13503 In this case
13504 \begin_inset LatexCommand \index{reentrant}
13505
13506 \end_inset
13507
13508
13509 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
13510
13511 \end_inset
13512
13513  the second parameter
13514 \begin_inset LatexCommand \index{function parameter}
13515
13516 \end_inset
13517
13518  onwards will be passed on the stack, the parameters are pushed from right
13519  to left i.e.
13520  after the call the leftmost parameter will be on the top of the stack.
13521  Here is an example:
13522 \layout Verse
13523
13524
13525 \family typewriter
13526 extern int asm_func(unsigned char, unsigned char);
13527 \newline
13528
13529 \newline
13530 int c_func (unsigned char i, unsigned char j) reentrant
13531 \newline
13532 {
13533 \newline
13534 \SpecialChar ~
13535 \SpecialChar ~
13536 \SpecialChar ~
13537 \SpecialChar ~
13538 return asm_func(i,j);
13539 \newline
13540 }
13541 \newline
13542
13543 \newline
13544 int main()
13545 \newline
13546 {
13547 \newline
13548 \SpecialChar ~
13549 \SpecialChar ~
13550 \SpecialChar ~
13551 \SpecialChar ~
13552 return c_func(10,9);
13553 \newline
13554 }
13555 \layout Standard
13556
13557 The corresponding assembler routine is:
13558 \layout Verse
13559
13560
13561 \family typewriter
13562 .globl _asm_func
13563 \newline
13564 _asm_func:
13565 \newline
13566 \SpecialChar ~
13567 \SpecialChar ~
13568 \SpecialChar ~
13569 \SpecialChar ~
13570 push  _bp
13571 \newline
13572 \SpecialChar ~
13573 \SpecialChar ~
13574 \SpecialChar ~
13575 \SpecialChar ~
13576 mov _bp,sp
13577 \newline
13578 \SpecialChar ~
13579 \SpecialChar ~
13580 \SpecialChar ~
13581 \SpecialChar ~
13582 mov r2,dpl
13583 \newline
13584 \SpecialChar ~
13585 \SpecialChar ~
13586 \SpecialChar ~
13587 \SpecialChar ~
13588 mov a,_bp
13589 \newline
13590 \SpecialChar ~
13591 \SpecialChar ~
13592 \SpecialChar ~
13593 \SpecialChar ~
13594 add a,#0xfd
13595 \newline
13596 \SpecialChar ~
13597 \SpecialChar ~
13598 \SpecialChar ~
13599 \SpecialChar ~
13600 mov r0,a
13601 \newline
13602 \SpecialChar ~
13603 \SpecialChar ~
13604 \SpecialChar ~
13605 \SpecialChar ~
13606 add  a,#0xfc ;?
13607 \newline
13608 \SpecialChar ~
13609 \SpecialChar ~
13610 \SpecialChar ~
13611 \SpecialChar ~
13612 mov  r1,a
13613 \newline
13614 \SpecialChar ~
13615 \SpecialChar ~
13616 \SpecialChar ~
13617 \SpecialChar ~
13618 mov  a,@r0
13619 \newline
13620 \SpecialChar ~
13621 \SpecialChar ~
13622 \SpecialChar ~
13623 \SpecialChar ~
13624 add  a,r2 ;?
13625 \newline
13626 \SpecialChar ~
13627 \SpecialChar ~
13628 \SpecialChar ~
13629 \SpecialChar ~
13630 mov  dpl,a
13631 \newline
13632 \SpecialChar ~
13633 \SpecialChar ~
13634 \SpecialChar ~
13635 \SpecialChar ~
13636 mov  dph,#0x00
13637 \newline
13638 \SpecialChar ~
13639 \SpecialChar ~
13640 \SpecialChar ~
13641 \SpecialChar ~
13642 mov  sp,_bp
13643 \newline
13644 \SpecialChar ~
13645 \SpecialChar ~
13646 \SpecialChar ~
13647 \SpecialChar ~
13648 pop  _bp
13649 \newline
13650 \SpecialChar ~
13651 \SpecialChar ~
13652 \SpecialChar ~
13653 \SpecialChar ~
13654 ret
13655 \layout Standard
13656
13657 The compiling and linking procedure remains the same, however note the extra
13658  entry & exit linkage required for the assembler code, _bp is the stack
13659  frame pointer and is used to compute the offset into the stack for parameters
13660  and local variables.
13661 \layout Section
13662
13663 int (16 bit)
13664 \begin_inset LatexCommand \index{int (16 bit)}
13665
13666 \end_inset
13667
13668  and long (32 bit)
13669 \begin_inset LatexCommand \index{long (32 bit)}
13670
13671 \end_inset
13672
13673  Support
13674 \layout Standard
13675
13676 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
13677  multiplication and modulus operations are implemented by support routines.
13678  These support routines are all developed in ANSI-C to facilitate porting
13679  to other MCUs, although some model specific assembler optimizations are
13680  used.
13681  The following files contain the described routines, all of them can be
13682  found in <installdir>/share/sdcc/lib.
13683 \newline
13684
13685 \layout Standard
13686 \align center
13687
13688 \begin_inset  Tabular
13689 <lyxtabular version="3" rows="11" columns="2">
13690 <features>
13691 <column alignment="center" valignment="top" leftline="true" width="0">
13692 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13693 <row topline="true" bottomline="true">
13694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13695 \begin_inset Text
13696
13697 \layout Standard
13698
13699
13700 \series bold
13701 Function
13702 \end_inset
13703 </cell>
13704 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13705 \begin_inset Text
13706
13707 \layout Standard
13708
13709
13710 \series bold
13711 Description
13712 \end_inset
13713 </cell>
13714 </row>
13715 <row topline="true">
13716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13717 \begin_inset Text
13718
13719 \layout Standard
13720
13721 _mulint.c
13722 \end_inset
13723 </cell>
13724 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13725 \begin_inset Text
13726
13727 \layout Standard
13728
13729 16 bit multiplication
13730 \end_inset
13731 </cell>
13732 </row>
13733 <row topline="true">
13734 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13735 \begin_inset Text
13736
13737 \layout Standard
13738
13739 _divsint.c
13740 \end_inset
13741 </cell>
13742 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13743 \begin_inset Text
13744
13745 \layout Standard
13746
13747  signed 16 bit division (calls _divuint)
13748 \end_inset
13749 </cell>
13750 </row>
13751 <row topline="true">
13752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13753 \begin_inset Text
13754
13755 \layout Standard
13756
13757 _divuint.c
13758 \end_inset
13759 </cell>
13760 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13761 \begin_inset Text
13762
13763 \layout Standard
13764
13765  unsigned 16 bit division
13766 \end_inset
13767 </cell>
13768 </row>
13769 <row topline="true">
13770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13771 \begin_inset Text
13772
13773 \layout Standard
13774
13775 _modsint.c
13776 \end_inset
13777 </cell>
13778 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13779 \begin_inset Text
13780
13781 \layout Standard
13782
13783 signed 16 bit modulus (calls _moduint)
13784 \end_inset
13785 </cell>
13786 </row>
13787 <row topline="true">
13788 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13789 \begin_inset Text
13790
13791 \layout Standard
13792
13793 _moduint.c
13794 \end_inset
13795 </cell>
13796 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13797 \begin_inset Text
13798
13799 \layout Standard
13800
13801 unsigned 16 bit modulus
13802 \end_inset
13803 </cell>
13804 </row>
13805 <row topline="true">
13806 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13807 \begin_inset Text
13808
13809 \layout Standard
13810
13811 _mullong.c
13812 \end_inset
13813 </cell>
13814 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13815 \begin_inset Text
13816
13817 \layout Standard
13818
13819 32 bit multiplication
13820 \end_inset
13821 </cell>
13822 </row>
13823 <row topline="true">
13824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13825 \begin_inset Text
13826
13827 \layout Standard
13828
13829 _divslong.c
13830 \end_inset
13831 </cell>
13832 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13833 \begin_inset Text
13834
13835 \layout Standard
13836
13837  signed 32 division (calls _divulong)
13838 \end_inset
13839 </cell>
13840 </row>
13841 <row topline="true">
13842 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13843 \begin_inset Text
13844
13845 \layout Standard
13846
13847 _divulong.c
13848 \end_inset
13849 </cell>
13850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13851 \begin_inset Text
13852
13853 \layout Standard
13854
13855 unsigned 32 division
13856 \end_inset
13857 </cell>
13858 </row>
13859 <row topline="true">
13860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13861 \begin_inset Text
13862
13863 \layout Standard
13864
13865 _modslong.c
13866 \end_inset
13867 </cell>
13868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13869 \begin_inset Text
13870
13871 \layout Standard
13872
13873  signed 32 bit modulus (calls _modulong)
13874 \end_inset
13875 </cell>
13876 </row>
13877 <row topline="true" bottomline="true">
13878 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13879 \begin_inset Text
13880
13881 \layout Standard
13882
13883 _modulong.c
13884 \end_inset
13885 </cell>
13886 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13887 \begin_inset Text
13888
13889 \layout Standard
13890
13891 unsigned 32 bit modulus
13892 \end_inset
13893 </cell>
13894 </row>
13895 </lyxtabular>
13896
13897 \end_inset
13898
13899
13900 \newline
13901
13902 \layout Standard
13903
13904 Since they are compiled as
13905 \emph on
13906 non-reentrant
13907 \emph default
13908
13909 \begin_inset LatexCommand \index{reentrant}
13910
13911 \end_inset
13912
13913 , interrupt
13914 \begin_inset LatexCommand \index{interrupt}
13915
13916 \end_inset
13917
13918  service routines should not do any of the above operations.
13919  If this is unavoidable then the above routines will need to be compiled
13920  with the
13921 \emph on
13922 -
13923 \begin_inset ERT
13924 status Collapsed
13925
13926 \layout Standard
13927
13928 \backslash
13929 /
13930 \end_inset
13931
13932 -stack-auto
13933 \begin_inset LatexCommand \index{-\/-stack-auto}
13934
13935 \end_inset
13936
13937
13938 \emph default
13939  option, after which the source program will have to be compiled with
13940 \emph on
13941 -
13942 \begin_inset ERT
13943 status Collapsed
13944
13945 \layout Standard
13946
13947 \backslash
13948 /
13949 \end_inset
13950
13951 -int-long-reent
13952 \begin_inset LatexCommand \index{-\/-int-long-reent}
13953
13954 \end_inset
13955
13956
13957 \emph default
13958  option.
13959  Notice that you don't have to call these routines directly.
13960  The compiler will use them automatically every time an integer operation
13961  is required.
13962 \layout Section
13963
13964 Floating Point Support
13965 \begin_inset LatexCommand \index{Floating point support}
13966
13967 \end_inset
13968
13969
13970 \layout Standard
13971
13972 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13973  floating point support routines are derived from gcc's floatlib.c and consist
13974  of the following routines:
13975 \newline
13976
13977 \layout Standard
13978 \align center
13979
13980 \size footnotesize
13981
13982 \begin_inset  Tabular
13983 <lyxtabular version="3" rows="17" columns="2">
13984 <features>
13985 <column alignment="center" valignment="top" leftline="true" width="0">
13986 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13987 <row topline="true" bottomline="true">
13988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13989 \begin_inset Text
13990
13991 \layout Standard
13992
13993
13994 \family roman
13995 \series medium
13996 \shape up
13997 \size normal
13998 \emph off
13999 \bar no
14000 \noun off
14001 \color none
14002 Function
14003 \end_inset
14004 </cell>
14005 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14006 \begin_inset Text
14007
14008 \layout Standard
14009
14010 Description
14011 \end_inset
14012 </cell>
14013 </row>
14014 <row topline="true">
14015 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14016 \begin_inset Text
14017
14018 \layout Standard
14019
14020
14021 \family roman
14022 \series medium
14023 \shape up
14024 \size normal
14025 \emph off
14026 \bar no
14027 \noun off
14028 \color none
14029 _fsadd.c
14030 \end_inset
14031 </cell>
14032 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14033 \begin_inset Text
14034
14035 \layout Standard
14036
14037
14038 \family roman
14039 \series medium
14040 \shape up
14041 \size normal
14042 \emph off
14043 \bar no
14044 \noun off
14045 \color none
14046 add floating point numbers
14047 \end_inset
14048 </cell>
14049 </row>
14050 <row topline="true">
14051 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14052 \begin_inset Text
14053
14054 \layout Standard
14055
14056
14057 \family roman
14058 \series medium
14059 \shape up
14060 \size normal
14061 \emph off
14062 \bar no
14063 \noun off
14064 \color none
14065 _fssub.c
14066 \end_inset
14067 </cell>
14068 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14069 \begin_inset Text
14070
14071 \layout Standard
14072
14073
14074 \family roman
14075 \series medium
14076 \shape up
14077 \size normal
14078 \emph off
14079 \bar no
14080 \noun off
14081 \color none
14082 subtract floating point numbers
14083 \end_inset
14084 </cell>
14085 </row>
14086 <row topline="true">
14087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14088 \begin_inset Text
14089
14090 \layout Standard
14091
14092
14093 \family roman
14094 \series medium
14095 \shape up
14096 \size normal
14097 \emph off
14098 \bar no
14099 \noun off
14100 \color none
14101 _fsdiv.c
14102 \end_inset
14103 </cell>
14104 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14105 \begin_inset Text
14106
14107 \layout Standard
14108
14109
14110 \family roman
14111 \series medium
14112 \shape up
14113 \size normal
14114 \emph off
14115 \bar no
14116 \noun off
14117 \color none
14118 divide floating point numbers
14119 \end_inset
14120 </cell>
14121 </row>
14122 <row topline="true">
14123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14124 \begin_inset Text
14125
14126 \layout Standard
14127
14128
14129 \family roman
14130 \series medium
14131 \shape up
14132 \size normal
14133 \emph off
14134 \bar no
14135 \noun off
14136 \color none
14137 _fsmul.c
14138 \end_inset
14139 </cell>
14140 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14141 \begin_inset Text
14142
14143 \layout Standard
14144
14145
14146 \family roman
14147 \series medium
14148 \shape up
14149 \size normal
14150 \emph off
14151 \bar no
14152 \noun off
14153 \color none
14154 multiply floating point numbers
14155 \end_inset
14156 </cell>
14157 </row>
14158 <row topline="true">
14159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14160 \begin_inset Text
14161
14162 \layout Standard
14163
14164
14165 \family roman
14166 \series medium
14167 \shape up
14168 \size normal
14169 \emph off
14170 \bar no
14171 \noun off
14172 \color none
14173 _fs2uchar.c
14174 \end_inset
14175 </cell>
14176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14177 \begin_inset Text
14178
14179 \layout Standard
14180
14181
14182 \family roman
14183 \series medium
14184 \shape up
14185 \size normal
14186 \emph off
14187 \bar no
14188 \noun off
14189 \color none
14190 convert floating point to unsigned char
14191 \end_inset
14192 </cell>
14193 </row>
14194 <row topline="true">
14195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14196 \begin_inset Text
14197
14198 \layout Standard
14199
14200
14201 \family roman
14202 \series medium
14203 \shape up
14204 \size normal
14205 \emph off
14206 \bar no
14207 \noun off
14208 \color none
14209 _fs2char.c
14210 \end_inset
14211 </cell>
14212 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14213 \begin_inset Text
14214
14215 \layout Standard
14216
14217
14218 \family roman
14219 \series medium
14220 \shape up
14221 \size normal
14222 \emph off
14223 \bar no
14224 \noun off
14225 \color none
14226 convert floating point to signed char
14227 \end_inset
14228 </cell>
14229 </row>
14230 <row topline="true">
14231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14232 \begin_inset Text
14233
14234 \layout Standard
14235
14236
14237 \family roman
14238 \series medium
14239 \shape up
14240 \size normal
14241 \emph off
14242 \bar no
14243 \noun off
14244 \color none
14245 _fs2uint.c
14246 \end_inset
14247 </cell>
14248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14249 \begin_inset Text
14250
14251 \layout Standard
14252
14253
14254 \family roman
14255 \series medium
14256 \shape up
14257 \size normal
14258 \emph off
14259 \bar no
14260 \noun off
14261 \color none
14262 convert floating point to unsigned int
14263 \end_inset
14264 </cell>
14265 </row>
14266 <row topline="true">
14267 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14268 \begin_inset Text
14269
14270 \layout Standard
14271
14272
14273 \family roman
14274 \series medium
14275 \shape up
14276 \size normal
14277 \emph off
14278 \bar no
14279 \noun off
14280 \color none
14281 _fs2int.c
14282 \end_inset
14283 </cell>
14284 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14285 \begin_inset Text
14286
14287 \layout Standard
14288
14289
14290 \family roman
14291 \series medium
14292 \shape up
14293 \size normal
14294 \emph off
14295 \bar no
14296 \noun off
14297 \color none
14298 convert floating point to signed int
14299 \end_inset
14300 </cell>
14301 </row>
14302 <row topline="true">
14303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14304 \begin_inset Text
14305
14306 \layout Standard
14307
14308
14309 \family roman
14310 \series medium
14311 \shape up
14312 \size normal
14313 \emph off
14314 \bar no
14315 \noun off
14316 \color none
14317 _fs2ulong.
14318 \family default
14319 \series default
14320 \shape default
14321 \size default
14322 \emph default
14323 \bar default
14324 \noun default
14325 \color default
14326 c
14327 \end_inset
14328 </cell>
14329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14330 \begin_inset Text
14331
14332 \layout Standard
14333
14334
14335 \family roman
14336 \series medium
14337 \shape up
14338 \size normal
14339 \emph off
14340 \bar no
14341 \noun off
14342 \color none
14343 convert floating point to unsigned long
14344 \end_inset
14345 </cell>
14346 </row>
14347 <row topline="true">
14348 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14349 \begin_inset Text
14350
14351 \layout Standard
14352
14353
14354 \family roman
14355 \series medium
14356 \shape up
14357 \size normal
14358 \emph off
14359 \bar no
14360 \noun off
14361 \color none
14362 _fs2long.c
14363 \end_inset
14364 </cell>
14365 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14366 \begin_inset Text
14367
14368 \layout Standard
14369
14370
14371 \family roman
14372 \series medium
14373 \shape up
14374 \size normal
14375 \emph off
14376 \bar no
14377 \noun off
14378 \color none
14379 convert floating point to signed long
14380 \end_inset
14381 </cell>
14382 </row>
14383 <row topline="true">
14384 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14385 \begin_inset Text
14386
14387 \layout Standard
14388
14389
14390 \family roman
14391 \series medium
14392 \shape up
14393 \size normal
14394 \emph off
14395 \bar no
14396 \noun off
14397 \color none
14398 _uchar2fs.c
14399 \end_inset
14400 </cell>
14401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14402 \begin_inset Text
14403
14404 \layout Standard
14405
14406
14407 \family roman
14408 \series medium
14409 \shape up
14410 \size normal
14411 \emph off
14412 \bar no
14413 \noun off
14414 \color none
14415 convert unsigned char to floating point
14416 \end_inset
14417 </cell>
14418 </row>
14419 <row topline="true">
14420 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14421 \begin_inset Text
14422
14423 \layout Standard
14424
14425
14426 \family roman
14427 \series medium
14428 \shape up
14429 \size normal
14430 \emph off
14431 \bar no
14432 \noun off
14433 \color none
14434 _char2fs.c
14435 \end_inset
14436 </cell>
14437 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14438 \begin_inset Text
14439
14440 \layout Standard
14441
14442
14443 \family roman
14444 \series medium
14445 \shape up
14446 \size normal
14447 \emph off
14448 \bar no
14449 \noun off
14450 \color none
14451 convert char to floating point number
14452 \end_inset
14453 </cell>
14454 </row>
14455 <row topline="true">
14456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14457 \begin_inset Text
14458
14459 \layout Standard
14460
14461
14462 \family roman
14463 \series medium
14464 \shape up
14465 \size normal
14466 \emph off
14467 \bar no
14468 \noun off
14469 \color none
14470 _uint2fs.c
14471 \end_inset
14472 </cell>
14473 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14474 \begin_inset Text
14475
14476 \layout Standard
14477
14478
14479 \family roman
14480 \series medium
14481 \shape up
14482 \size normal
14483 \emph off
14484 \bar no
14485 \noun off
14486 \color none
14487 convert unsigned int to floating point
14488 \end_inset
14489 </cell>
14490 </row>
14491 <row topline="true">
14492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14493 \begin_inset Text
14494
14495 \layout Standard
14496
14497
14498 \family roman
14499 \series medium
14500 \shape up
14501 \size normal
14502 \emph off
14503 \bar no
14504 \noun off
14505 \color none
14506 _int2fs.c
14507 \end_inset
14508 </cell>
14509 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14510 \begin_inset Text
14511
14512 \layout Standard
14513
14514
14515 \family roman
14516 \series medium
14517 \shape up
14518 \size normal
14519 \emph off
14520 \bar no
14521 \noun off
14522 \color none
14523 convert int to floating point numbers
14524 \end_inset
14525 </cell>
14526 </row>
14527 <row topline="true">
14528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14529 \begin_inset Text
14530
14531 \layout Standard
14532
14533
14534 \family roman
14535 \series medium
14536 \shape up
14537 \size normal
14538 \emph off
14539 \bar no
14540 \noun off
14541 \color none
14542 _ulong2fs.c
14543 \end_inset
14544 </cell>
14545 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14546 \begin_inset Text
14547
14548 \layout Standard
14549
14550
14551 \family roman
14552 \series medium
14553 \shape up
14554 \size normal
14555 \emph off
14556 \bar no
14557 \noun off
14558 \color none
14559 convert unsigned long to floating point number
14560 \end_inset
14561 </cell>
14562 </row>
14563 <row topline="true" bottomline="true">
14564 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14565 \begin_inset Text
14566
14567 \layout Standard
14568
14569
14570 \family roman
14571 \series medium
14572 \shape up
14573 \size normal
14574 \emph off
14575 \bar no
14576 \noun off
14577 \color none
14578 _long2fs.c
14579 \end_inset
14580 </cell>
14581 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14582 \begin_inset Text
14583
14584 \layout Standard
14585
14586
14587 \family roman
14588 \series medium
14589 \shape up
14590 \size normal
14591 \emph off
14592 \bar no
14593 \noun off
14594 \color none
14595 convert long to floating point number
14596 \end_inset
14597 </cell>
14598 </row>
14599 </lyxtabular>
14600
14601 \end_inset
14602
14603
14604 \newline
14605
14606 \layout Standard
14607
14608 These support routines are developed in ANSI-C so there is room for space
14609  and speed improvement
14610 \begin_inset Foot
14611 collapsed false
14612
14613 \layout Standard
14614
14615 The floating point routines for the mcs51 are implemented in assembler
14616 \end_inset
14617
14618 .
14619  Note if all these routines are used simultaneously the data space might
14620  overflow.
14621  For serious floating point usage the large model might be needed.
14622  Also notice that you don't have to call this routines directly.
14623  The compiler will use them automatically every time a floating point operation
14624  is required.
14625 \layout Section
14626
14627 Library Routines
14628 \begin_inset LatexCommand \index{Libraries}
14629
14630 \end_inset
14631
14632
14633 \layout Standard
14634
14635
14636 \emph on
14637 <pending: this is messy and incomplete - a little more information is in
14638  sdcc/doc/libdoc.txt
14639 \emph default
14640  >
14641 \layout Subsection
14642
14643 Compiler support routines (_gptrget, _mulint etc.)
14644 \layout Subsection
14645
14646 Stdclib functions (puts, printf, strcat etc.)
14647 \layout Subsubsection
14648
14649 <stdio.h>
14650 \layout Standard
14651
14652
14653 \begin_inset LatexCommand \index{<stdio.h>}
14654
14655 \end_inset
14656
14657 As usual on embedded systems you have to provide your own
14658 \family typewriter
14659 getchar()
14660 \begin_inset LatexCommand \index{getchar()}
14661
14662 \end_inset
14663
14664
14665 \family default
14666 and
14667 \family typewriter
14668 putchar()
14669 \begin_inset LatexCommand \index{putchar()}
14670
14671 \end_inset
14672
14673
14674 \family default
14675  routines.
14676  SDCC does not know whether the system connects to a serial line with or
14677  without handshake, LCD, keyboard or other device.
14678  You'll find examples for serial routines f.e.
14679  in sdcc/device/lib.
14680 \layout Standard
14681
14682 The default
14683 \family typewriter
14684  printf()
14685 \begin_inset LatexCommand \index{printf()}
14686
14687 \end_inset
14688
14689
14690 \family default
14691 implementation in
14692 \family typewriter
14693  printf_large.c
14694 \family default
14695  does not support float (except on ds390).
14696  To enable this recompile it with the option
14697 \emph on
14698 -
14699 \begin_inset ERT
14700 status Collapsed
14701
14702 \layout Standard
14703
14704 \backslash
14705 /
14706 \end_inset
14707
14708 DUSE_FLOATS=1
14709 \begin_inset LatexCommand \index{USE\_FLOATS}
14710
14711 \end_inset
14712
14713
14714 \emph default
14715  on the command line.
14716  Use
14717 \emph on
14718 -
14719 \begin_inset ERT
14720 status Collapsed
14721
14722 \layout Standard
14723
14724 \backslash
14725 /
14726 \end_inset
14727
14728 -model-large
14729 \begin_inset LatexCommand \index{-\/-model-large}
14730
14731 \end_inset
14732
14733
14734 \emph default
14735  for the mcs51 port, since this uses a lot of memory.
14736 \layout Standard
14737
14738 If you're short on memory you might want to use
14739 \family typewriter
14740 printf_small()
14741 \begin_inset LatexCommand \index{printf\_small()}
14742
14743 \end_inset
14744
14745
14746 \family default
14747
14748 \emph on
14749 instead
14750 \emph default
14751  of
14752 \family typewriter
14753  printf().
14754
14755 \family default
14756  For the mcs51 there additionally are assembly versions
14757 \family typewriter
14758 printf_tiny()
14759 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
14760
14761 \end_inset
14762
14763
14764 \family default
14765  and
14766 \family typewriter
14767 printf_fast()
14768 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
14769
14770 \end_inset
14771
14772
14773 \family default
14774 and
14775 \family typewriter
14776  printf_fast_f()
14777 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
14778
14779 \end_inset
14780
14781
14782 \family default
14783  which should fit the requirements of many embedded systems (printf_fast()
14784  can be customized by unsetting #defines to
14785 \emph on
14786 not
14787 \emph default
14788  support long variables and field widths).
14789 \layout Subsection
14790
14791 Math functions (sin, pow, sqrt etc.)
14792 \layout Subsection
14793
14794 Other libraries
14795 \layout Standard
14796
14797 Libraries
14798 \begin_inset LatexCommand \index{Libraries}
14799
14800 \end_inset
14801
14802  included in SDCC should have a license at least as liberal as the GNU Lesser
14803  General Public License
14804 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14805
14806 \end_inset
14807
14808
14809 \emph on
14810 LGPL
14811 \emph default
14812 .
14813 \layout Comment
14814
14815 license statements for the libraries are missing.
14816  sdcc/device/lib/ser_ir.c
14817 \layout Comment
14818
14819 or _decdptr f.e.
14820  come with a GPL (as opposed to LGPL) License - this will not be liberal
14821  enough for many embedded programmers.
14822 \layout Standard
14823
14824 If you have ported some library or want to share experience about some code
14825  which f.e.
14826  falls into any of these categories Busses (I
14827 \begin_inset Formula $^{\textrm{2}}$
14828 \end_inset
14829
14830 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14831  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14832  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14833 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14834
14835 \end_inset
14836
14837 \SpecialChar ~
14838 would certainly like to hear about it.
14839  Programmers coding for embedded systems are not especially famous for being
14840  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14841 e these references are very valuable.
14842  Let's help to create a climate where information is shared.
14843 \layout Section
14844
14845 Memory Models
14846 \layout Subsection
14847
14848 MCS51 Memory Models
14849 \begin_inset LatexCommand \index{Memory model}
14850
14851 \end_inset
14852
14853
14854 \begin_inset LatexCommand \index{MCS51 memory model}
14855
14856 \end_inset
14857
14858
14859 \layout Subsubsection
14860
14861 Small, Medium and Large
14862 \layout Standard
14863
14864 SDCC allows three memory models for MCS51 code,
14865 \shape slanted
14866 small, medium
14867 \shape default
14868  and
14869 \shape slanted
14870 large
14871 \shape default
14872 .
14873  Modules compiled with different memory models should
14874 \emph on
14875 never
14876 \emph default
14877  be combined together or the results would be unpredictable.
14878  The library routines supplied with the compiler are compiled as small,
14879  medium and large.
14880  The compiled library modules are contained in separate directories as small,
14881  medium and large so that you can link to the appropriate set.
14882 \layout Standard
14883
14884 When the medium or large model is used all variables declared without a
14885  storage class will be allocated into the external ram, this includes all
14886  parameters and local variables (for non-reentrant
14887 \begin_inset LatexCommand \index{reentrant}
14888
14889 \end_inset
14890
14891  functions).
14892  When the small model is used variables without storage class are allocated
14893  in the internal ram.
14894 \layout Standard
14895
14896 Judicious usage of the processor specific storage classes
14897 \begin_inset LatexCommand \index{Storage class}
14898
14899 \end_inset
14900
14901  and the 'reentrant' function type will yield much more efficient code,
14902  than using the large model.
14903  Several optimizations are disabled when the program is compiled using the
14904  large model, it is therefore recommended that the small model be used unless
14905  absolutely required.
14906 \layout Subsubsection
14907
14908 External Stack
14909 \begin_inset LatexCommand \label{sub:External-Stack}
14910
14911 \end_inset
14912
14913
14914 \begin_inset LatexCommand \index{stack}
14915
14916 \end_inset
14917
14918
14919 \begin_inset LatexCommand \index{External stack (mcs51)}
14920
14921 \end_inset
14922
14923
14924 \layout Standard
14925
14926 The external stack (-
14927 \begin_inset ERT
14928 status Collapsed
14929
14930 \layout Standard
14931
14932 \backslash
14933 /
14934 \end_inset
14935
14936 -xstack option
14937 \begin_inset LatexCommand \index{-\/-xstack}
14938
14939 \end_inset
14940
14941 ) is located in pdata
14942 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14943
14944 \end_inset
14945
14946  memory (usually at the start of the external ram segment) and uses all
14947  unused space in pdata (max.
14948  256 bytes).
14949  When -
14950 \begin_inset ERT
14951 status Collapsed
14952
14953 \layout Standard
14954
14955 \backslash
14956 /
14957 \end_inset
14958
14959 -xstack option is used to compile the program, the parameters and local
14960  variables
14961 \begin_inset LatexCommand \index{local variables}
14962
14963 \end_inset
14964
14965  of all reentrant functions are allocated in this area.
14966  This option is provided for programs with large stack space requirements.
14967  When used with the -
14968 \begin_inset ERT
14969 status Collapsed
14970
14971 \layout Standard
14972
14973 \backslash
14974 /
14975 \end_inset
14976
14977 -stack-auto
14978 \begin_inset LatexCommand \index{-\/-stack-auto}
14979
14980 \end_inset
14981
14982  option, all parameters and local variables are allocated on the external
14983  stack (note: support libraries will need to be recompiled with the same
14984  options.
14985  There is a predefined target in the library makefile).
14986 \layout Standard
14987
14988 The compiler outputs the higher order address byte of the external ram segment
14989  into port P2
14990 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14991
14992 \end_inset
14993
14994  (see also section
14995 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14996
14997 \end_inset
14998
14999 ), therefore when using the External Stack option, this port
15000 \emph on
15001 may not
15002 \emph default
15003  be used by the application program.
15004 \layout Subsection
15005
15006 DS390 Memory Model
15007 \begin_inset LatexCommand \index{Memory model}
15008
15009 \end_inset
15010
15011
15012 \begin_inset LatexCommand \index{DS390 memory model}
15013
15014 \end_inset
15015
15016
15017 \layout Standard
15018
15019 The only model supported is Flat 24
15020 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
15021
15022 \end_inset
15023
15024 .
15025  This generates code for the 24 bit contiguous addressing mode of the Dallas
15026  DS80C390 part.
15027  In this mode, up to four meg of external RAM or code space can be directly
15028  addressed.
15029  See the data sheets at www.dalsemi.com for further information on this part.
15030 \newline
15031
15032 \newline
15033 Note that the compiler does not generate any code to place the processor
15034  into 24 bitmode (although
15035 \emph on
15036 tinibios
15037 \emph default
15038  in the ds390 libraries will do that for you).
15039  If you don't use
15040 \emph on
15041 tinibios
15042 \emph default
15043
15044 \begin_inset LatexCommand \index{Tinibios (DS390)}
15045
15046 \end_inset
15047
15048 , the boot loader or similar code must ensure that the processor is in 24
15049  bit contiguous addressing mode before calling the SDCC startup code.
15050 \newline
15051
15052 \newline
15053 Like the
15054 \emph on
15055 -
15056 \begin_inset ERT
15057 status Collapsed
15058
15059 \layout Standard
15060
15061 \backslash
15062 /
15063 \end_inset
15064
15065 -model-large
15066 \emph default
15067  option, variables will by default be placed into the XDATA segment.
15068
15069 \newline
15070
15071 \newline
15072 Segments may be placed anywhere in the 4 meg address space using the usual
15073  -
15074 \begin_inset ERT
15075 status Collapsed
15076
15077 \layout Standard
15078
15079 \backslash
15080 /
15081 \end_inset
15082
15083 -*-loc options.
15084  Note that if any segments are located above 64K, the -r flag must be passed
15085  to the linker to generate the proper segment relocations, and the Intel
15086  HEX output format must be used.
15087  The -r flag can be passed to the linker by using the option
15088 \emph on
15089 -Wl-r
15090 \emph default
15091  on the SDCC command line.
15092  However, currently the linker can not handle code segments > 64k.
15093 \layout Section
15094
15095 Pragmas
15096 \begin_inset LatexCommand \index{Pragmas}
15097
15098 \end_inset
15099
15100
15101 \layout Standard
15102
15103 SDCC supports the following #pragma directives:
15104 \layout Itemize
15105
15106 save
15107 \begin_inset LatexCommand \index{\#pragma save}
15108
15109 \end_inset
15110
15111  - this will save all current options to the save/restore stack.
15112  See #pragma\SpecialChar ~
15113 restore.
15114 \layout Itemize
15115
15116 restore
15117 \begin_inset LatexCommand \index{\#pragma restore}
15118
15119 \end_inset
15120
15121  - will restore saved options from the last save.
15122  saves & restores can be nested.
15123  SDCC uses a save/restore stack: save pushes current options to the stack,
15124  restore pulls current options from the stack.
15125  See #pragma\SpecialChar ~
15126 save.
15127 \newline
15128
15129 \layout Itemize
15130
15131 callee_saves
15132 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15133
15134 \end_inset
15135
15136
15137 \begin_inset LatexCommand \index{function prologue}
15138
15139 \end_inset
15140
15141  function1[,function2[,function3...]] - The compiler by default uses a caller
15142  saves convention for register saving across function calls, however this
15143  can cause unnecessary register pushing & popping
15144 \begin_inset LatexCommand \index{push/pop}
15145
15146 \end_inset
15147
15148  when calling small functions from larger functions.
15149  This option can be used to switch off the register saving convention for
15150  the function names specified.
15151  The compiler will not save registers when calling these functions, extra
15152  code need to be manually inserted at the entry & exit for these functions
15153  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15154  reduce code & improve run time performance of the generated code.
15155  In the future the compiler (with inter procedural analysis) may be able
15156  to determine the appropriate scheme to use for each function call.
15157  If -
15158 \begin_inset ERT
15159 status Collapsed
15160
15161 \layout Standard
15162
15163 \backslash
15164 /
15165 \end_inset
15166
15167 -callee-saves command line option is used, the function names specified
15168  in #pragma\SpecialChar ~
15169 callee_saves
15170 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15171
15172 \end_inset
15173
15174  is appended to the list of functions specified in the command line.
15175 \layout Itemize
15176
15177 exclude
15178 \begin_inset LatexCommand \index{\#pragma exclude}
15179
15180 \end_inset
15181
15182  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15183  of pairs of push/pop
15184 \begin_inset LatexCommand \index{push/pop}
15185
15186 \end_inset
15187
15188  instructions in
15189 \emph on
15190 I
15191 \emph default
15192 nterrupt
15193 \begin_inset LatexCommand \index{interrupt}
15194
15195 \end_inset
15196
15197
15198 \emph on
15199 S
15200 \emph default
15201 ervice
15202 \emph on
15203 R
15204 \emph default
15205 outines.
15206  The directive should be placed immediately before the ISR function definition
15207  and it affects ALL ISR functions following it.
15208  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15209 exclude\SpecialChar ~
15210 none
15211 \begin_inset LatexCommand \index{\#pragma exclude}
15212
15213 \end_inset
15214
15215 .
15216  See also the related keyword _naked
15217 \begin_inset LatexCommand \index{\_naked}
15218
15219 \end_inset
15220
15221
15222 \begin_inset LatexCommand \index{\_\_naked}
15223
15224 \end_inset
15225
15226 .
15227 \layout Itemize
15228
15229 less_pedantic
15230 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15231
15232 \end_inset
15233
15234  - the compiler will not warn you anymore for obvious mistakes, you'r on
15235  your own now ;-(
15236 \layout Itemize
15237
15238 disable_warning <nnnn>
15239 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15240
15241 \end_inset
15242
15243  - the compiler will not warn you anymore about warning number <nnnn>.
15244 \layout Itemize
15245
15246 nogcse
15247 \begin_inset LatexCommand \index{\#pragma nogcse}
15248
15249 \end_inset
15250
15251  - will stop global common subexpression elimination.
15252 \layout Itemize
15253
15254 noinduction
15255 \begin_inset LatexCommand \index{\#pragma noinduction}
15256
15257 \end_inset
15258
15259  - will stop loop induction optimizations.
15260 \layout Itemize
15261
15262 noinvariant
15263 \begin_inset LatexCommand \index{\#pragma noinvariant}
15264
15265 \end_inset
15266
15267  - will not do loop invariant optimizations.
15268  For more details see Loop Invariants in section
15269 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15270
15271 \end_inset
15272
15273 .
15274 \layout Itemize
15275
15276 noiv
15277 \begin_inset LatexCommand \index{\#pragma noiv}
15278
15279 \end_inset
15280
15281  - Do not generate interrupt
15282 \begin_inset LatexCommand \index{interrupt}
15283
15284 \end_inset
15285
15286  vector table entries for all ISR functions defined after the pragma.
15287  This is useful in cases where the interrupt vector table must be defined
15288  manually, or when there is a secondary, manually defined interrupt vector
15289  table (e.g.
15290  for the autovector feature of the Cypress EZ-USB FX2).
15291  More elegantly this can be achieved by obmitting the optional interrupt
15292  number after the interrupt keyword, see section
15293 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15294
15295 \end_inset
15296
15297 \SpecialChar ~
15298 about interrupts.
15299 \layout Itemize
15300
15301 nojtbound
15302 \begin_inset LatexCommand \index{\#pragma nojtbound}
15303
15304 \end_inset
15305
15306  - will not generate code for boundary value checking, when switch statements
15307  are turned into jump-tables (dangerous).
15308  For more details see section
15309 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15310
15311 \end_inset
15312
15313 .
15314 \layout Itemize
15315
15316 noloopreverse
15317 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15318
15319 \end_inset
15320
15321  - Will not do loop reversal optimization
15322 \layout Itemize
15323
15324 nooverlay
15325 \begin_inset LatexCommand \index{\#pragma nooverlay}
15326
15327 \end_inset
15328
15329  - the compiler will not overlay the parameters and local variables of a
15330  function.
15331 \layout Itemize
15332
15333 stackauto
15334 \begin_inset LatexCommand \index{\#pragma stackauto}
15335
15336 \end_inset
15337
15338 - See option -
15339 \begin_inset ERT
15340 status Collapsed
15341
15342 \layout Standard
15343
15344 \backslash
15345 /
15346 \end_inset
15347
15348 -stack-auto
15349 \begin_inset LatexCommand \index{-\/-stack-auto}
15350
15351 \end_inset
15352
15353  and section
15354 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
15355
15356 \end_inset
15357
15358  Parameters and Local Variables.
15359 \layout Itemize
15360
15361 opt_code_speed
15362 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
15363
15364 \end_inset
15365
15366 - The compiler will optimize code generation towards fast code, possibly
15367  at the expense of code size.
15368 \layout Itemize
15369
15370 opt_code_size
15371 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
15372
15373 \end_inset
15374
15375 - The compiler will optimize code generation towards compact code, possibly
15376  at the expense of code speed.
15377 \layout Itemize
15378
15379 opt_code_balanced
15380 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
15381
15382 \end_inset
15383
15384 - The compiler will attempt to generate code that is both compact and fast,
15385  as long as meeting one goal is not a detriment to the other (this is the
15386  default).
15387
15388 \layout Itemize
15389
15390 std_sdcc89
15391 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
15392
15393 \end_inset
15394
15395 - Generally follow the C89 standard, but allow SDCC features that conflict
15396  with the standard (default).
15397 \layout Itemize
15398
15399 std_c89
15400 \begin_inset LatexCommand \index{\#pragma std\_c89}
15401
15402 \end_inset
15403
15404 - Follow the C89 standard and disable SDCC features that conflict with the
15405  standard.
15406 \layout Itemize
15407
15408 std_sdcc99
15409 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
15410
15411 \end_inset
15412
15413 - Generally follow the C99 standard, but allow SDCC features that conflict
15414  with the standard (incomplete support).
15415 \layout Itemize
15416
15417 std_c99
15418 \begin_inset LatexCommand \index{\#pragma std\_c99}
15419
15420 \end_inset
15421
15422 - Follow the C99 standard and disable SDCC features that conflict with the
15423  standard (incomplete support).
15424 \layout Itemize
15425
15426 codeseg <name>
15427 \begin_inset LatexCommand \index{\#pragma codeseg}
15428
15429 \end_inset
15430
15431 - Use this name (max.
15432  8 characters) for the code segment.
15433 \layout Itemize
15434
15435 constseg <name>
15436 \begin_inset LatexCommand \index{\#pragma constseg}
15437
15438 \end_inset
15439
15440 - Use this name (max.
15441  8 characters) for the const segment.
15442 \layout Standard
15443
15444 SDCPP supports the following #pragma directives:
15445 \layout Itemize
15446
15447 preproc_asm
15448 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
15449
15450 \end_inset
15451
15452  (+ | -) - switch _asm _endasm block preprocessing on / off.
15453  Default is on.
15454 \layout Standard
15455
15456 The pragma's are intended to be used to turn-on or off certain optimizations
15457  which might cause the compiler to generate extra stack / data space to
15458  store compiler generated temporary variables.
15459  This usually happens in large functions.
15460  Pragma directives should be used as shown in the following example, they
15461  are used to control options & optimizations for a given function; pragmas
15462  should be placed before and/or after a function, placing pragma's inside
15463  a function body could have unpredictable results.
15464 \layout Verse
15465
15466
15467 \family typewriter
15468 #pragma save
15469 \begin_inset LatexCommand \index{\#pragma save}
15470
15471 \end_inset
15472
15473  \SpecialChar ~
15474 \SpecialChar ~
15475 \SpecialChar ~
15476 \SpecialChar ~
15477 \SpecialChar ~
15478 \SpecialChar ~
15479 \SpecialChar ~
15480 /* save the current settings */
15481 \newline
15482 #pragma nogcse
15483 \begin_inset LatexCommand \index{\#pragma nogcse}
15484
15485 \end_inset
15486
15487  \SpecialChar ~
15488 \SpecialChar ~
15489 \SpecialChar ~
15490 \SpecialChar ~
15491 \SpecialChar ~
15492 /* turnoff global subexpression elimination */
15493 \newline
15494 #pragma noinduction
15495 \begin_inset LatexCommand \index{\#pragma noinduction}
15496
15497 \end_inset
15498
15499  /* turn off induction optimizations */
15500 \newline
15501 int foo ()
15502 \newline
15503 {
15504 \newline
15505 \SpecialChar ~
15506  \SpecialChar ~
15507  ...
15508
15509 \newline
15510 \SpecialChar ~
15511  \SpecialChar ~
15512  /* large code */
15513 \newline
15514 \SpecialChar ~
15515  \SpecialChar ~
15516  ...
15517
15518 \newline
15519 }
15520 \newline
15521 #pragma restore
15522 \begin_inset LatexCommand \index{\#pragma restore}
15523
15524 \end_inset
15525
15526  /* turn the optimizations back on */
15527 \layout Standard
15528
15529 The compiler will generate a warning message when extra space is allocated.
15530  It is strongly recommended that the save and restore pragma's be used when
15531  changing options for a function.
15532 \layout Section
15533
15534 Defines Created by the Compiler
15535 \layout Standard
15536
15537 The compiler creates the following #defines
15538 \begin_inset LatexCommand \index{\#defines}
15539
15540 \end_inset
15541
15542
15543 \begin_inset LatexCommand \index{Defines created by the compiler}
15544
15545 \end_inset
15546
15547 :
15548 \newline
15549
15550 \layout Standard
15551
15552
15553 \begin_inset  Tabular
15554 <lyxtabular version="3" rows="11" columns="2">
15555 <features>
15556 <column alignment="center" valignment="top" leftline="true" width="0">
15557 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15558 <row topline="true" bottomline="true">
15559 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15560 \begin_inset Text
15561
15562 \layout Standard
15563
15564
15565 \series bold
15566 #define
15567 \end_inset
15568 </cell>
15569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15570 \begin_inset Text
15571
15572 \layout Standard
15573
15574
15575 \series bold
15576 Description
15577 \end_inset
15578 </cell>
15579 </row>
15580 <row topline="true">
15581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15582 \begin_inset Text
15583
15584 \layout Standard
15585
15586 SDCC
15587 \begin_inset LatexCommand \index{SDCC}
15588
15589 \end_inset
15590
15591
15592 \end_inset
15593 </cell>
15594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15595 \begin_inset Text
15596
15597 \layout Standard
15598
15599 this Symbol is always defined.
15600  Since version 2.5.6 it's this version number as an int (ex.
15601  256)
15602 \end_inset
15603 </cell>
15604 </row>
15605 <row topline="true">
15606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15607 \begin_inset Text
15608
15609 \layout Standard
15610
15611 SDCC_mcs51
15612 \begin_inset LatexCommand \index{SDCC\_mcs51}
15613
15614 \end_inset
15615
15616  or SDCC_ds390
15617 \begin_inset LatexCommand \index{SDCC\_ds390}
15618
15619 \end_inset
15620
15621  or SDCC_z80
15622 \begin_inset LatexCommand \index{SDCC\_z80}
15623
15624 \end_inset
15625
15626 , etc
15627 \end_inset
15628 </cell>
15629 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15630 \begin_inset Text
15631
15632 \layout Standard
15633
15634 depending on the model used (e.g.: -mds390
15635 \end_inset
15636 </cell>
15637 </row>
15638 <row topline="true">
15639 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15640 \begin_inset Text
15641
15642 \layout Standard
15643
15644 __mcs51
15645 \begin_inset LatexCommand \index{\_\_mcs51}
15646
15647 \end_inset
15648
15649 , __ds390
15650 \begin_inset LatexCommand \index{\_\_ds390}
15651
15652 \end_inset
15653
15654 , __hc08
15655 \begin_inset LatexCommand \index{\_\_hc08}
15656
15657 \end_inset
15658
15659 , __z80
15660 \begin_inset LatexCommand \index{\_\_z80}
15661
15662 \end_inset
15663
15664 , etc
15665 \end_inset
15666 </cell>
15667 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15668 \begin_inset Text
15669
15670 \layout Standard
15671
15672 depending on the model used (e.g.
15673  -mz80)
15674 \end_inset
15675 </cell>
15676 </row>
15677 <row topline="true">
15678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15679 \begin_inset Text
15680
15681 \layout Standard
15682
15683 SDCC_STACK_AUTO
15684 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
15685
15686 \end_inset
15687
15688
15689 \end_inset
15690 </cell>
15691 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15692 \begin_inset Text
15693
15694 \layout Standard
15695
15696 when
15697 \emph on
15698 -
15699 \begin_inset ERT
15700 status Collapsed
15701
15702 \layout Standard
15703
15704 \backslash
15705 /
15706 \end_inset
15707
15708 -stack-auto
15709 \emph default
15710  option is used
15711 \end_inset
15712 </cell>
15713 </row>
15714 <row topline="true">
15715 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15716 \begin_inset Text
15717
15718 \layout Standard
15719
15720 SDCC_MODEL_SMALL
15721 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
15722
15723 \end_inset
15724
15725
15726 \end_inset
15727 </cell>
15728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15729 \begin_inset Text
15730
15731 \layout Standard
15732
15733 when
15734 \emph on
15735 -
15736 \begin_inset ERT
15737 status Collapsed
15738
15739 \layout Standard
15740
15741 \backslash
15742 /
15743 \end_inset
15744
15745 -model-small
15746 \emph default
15747  is used
15748 \end_inset
15749 </cell>
15750 </row>
15751 <row topline="true">
15752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15753 \begin_inset Text
15754
15755 \layout Standard
15756
15757 SDCC_MODEL_MEDIUM
15758 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
15759
15760 \end_inset
15761
15762
15763 \end_inset
15764 </cell>
15765 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15766 \begin_inset Text
15767
15768 \layout Standard
15769
15770 when
15771 \emph on
15772 -
15773 \begin_inset ERT
15774 status Collapsed
15775
15776 \layout Standard
15777
15778 \backslash
15779 /
15780 \end_inset
15781
15782 -model-medium
15783 \emph default
15784  is used
15785 \end_inset
15786 </cell>
15787 </row>
15788 <row topline="true">
15789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15790 \begin_inset Text
15791
15792 \layout Standard
15793
15794 SDCC_MODEL_LARGE
15795 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
15796
15797 \end_inset
15798
15799
15800 \end_inset
15801 </cell>
15802 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15803 \begin_inset Text
15804
15805 \layout Standard
15806
15807 when
15808 \emph on
15809 -
15810 \begin_inset ERT
15811 status Collapsed
15812
15813 \layout Standard
15814
15815 \backslash
15816 /
15817 \end_inset
15818
15819 -model-large
15820 \emph default
15821  is used
15822 \end_inset
15823 </cell>
15824 </row>
15825 <row topline="true">
15826 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15827 \begin_inset Text
15828
15829 \layout Standard
15830
15831 SDCC_USE_XSTACK
15832 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15833
15834 \end_inset
15835
15836
15837 \end_inset
15838 </cell>
15839 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15840 \begin_inset Text
15841
15842 \layout Standard
15843
15844 when
15845 \emph on
15846 -
15847 \begin_inset ERT
15848 status Collapsed
15849
15850 \layout Standard
15851
15852 \backslash
15853 /
15854 \end_inset
15855
15856 -xstack
15857 \emph default
15858  option is used
15859 \end_inset
15860 </cell>
15861 </row>
15862 <row topline="true">
15863 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15864 \begin_inset Text
15865
15866 \layout Standard
15867
15868 SDCC_STACK_TENBIT
15869 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
15870
15871 \end_inset
15872
15873
15874 \end_inset
15875 </cell>
15876 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15877 \begin_inset Text
15878
15879 \layout Standard
15880
15881 when
15882 \emph on
15883 -mds390
15884 \emph default
15885  is used
15886 \end_inset
15887 </cell>
15888 </row>
15889 <row topline="true" bottomline="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_FLAT24
15896 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
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 -mds390
15911 \emph default
15912  is used
15913 \end_inset
15914 </cell>
15915 </row>
15916 </lyxtabular>
15917
15918 \end_inset
15919
15920
15921 \layout Chapter
15922
15923 Notes on supported Processors
15924 \layout Section
15925
15926 MCS51 variants
15927 \begin_inset LatexCommand \label{sub:MCS51-variants}
15928
15929 \end_inset
15930
15931
15932 \begin_inset LatexCommand \index{MCS51 variants}
15933
15934 \end_inset
15935
15936
15937 \layout Standard
15938
15939 MCS51 processors are available from many vendors and come in many different
15940  flavours.
15941  While they might differ considerably in respect to Special Function Registers
15942  the core MCS51 is usually not modified or is kept compatible.
15943
15944 \layout Subsection
15945
15946 pdata access by SFR
15947 \layout Standard
15948
15949 With the upcome of devices with internal xdata and flash memory devices
15950  using port P2
15951 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15952
15953 \end_inset
15954
15955  as dedicated I/O port is becoming more popular.
15956  Switching the high byte for pdata
15957 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15958
15959 \end_inset
15960
15961  access which was formerly done by port P2 is then achieved by a Special
15962  Function Register
15963 \begin_inset LatexCommand \index{sfr}
15964
15965 \end_inset
15966
15967 .
15968  In well-established MCS51 tradition the address of this
15969 \emph on
15970 sfr
15971 \emph default
15972  is where the chip designers decided to put it.
15973  Needless to say that they didn't agree on a common name either.
15974  So that the startup code can correctly initialize xdata variables, you
15975  should define an sfr with the name _XPAGE
15976 \family typewriter
15977
15978 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
15979
15980 \end_inset
15981
15982
15983 \family default
15984  at the appropriate location if the default, port P2, is not used for this.
15985  Some examples are:
15986 \layout Verse
15987
15988
15989 \family typewriter
15990 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
15991 \layout Verse
15992
15993
15994 \family typewriter
15995 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
15996 \layout Verse
15997
15998
15999 \family typewriter
16000 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
16001 \layout Standard
16002
16003 For more exotic implementations further customizations may be needed.
16004  See section
16005 \begin_inset LatexCommand \ref{sub:Startup-Code}
16006
16007 \end_inset
16008
16009  for other possibilities.
16010 \layout Subsection
16011
16012 Other Features available by SFR
16013 \layout Standard
16014
16015 Some MCS51 variants offer features like Double DPTR
16016 \begin_inset LatexCommand \index{DPTR}
16017
16018 \end_inset
16019
16020 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
16021  These are currently not used for the MCS51 port.
16022  If you absolutely need them you can fall back to inline assembly or submit
16023  a patch to SDCC.
16024 \layout Section
16025
16026 DS400 port
16027 \layout Standard
16028
16029 The DS80C400 microcontroller has a rich set of peripherals.
16030  In its built-in ROM library it includes functions to access some of the
16031  features, among them is a TCP stack with IP4 and IP6 support.
16032  Library headers (currently in beta status) and other files are provided
16033  at
16034 \size footnotesize
16035
16036 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
16037
16038 \end_inset
16039
16040 .
16041
16042 \layout Section
16043
16044 The Z80 and gbz80 port
16045 \layout Standard
16046
16047 SDCC can target both the Zilog
16048 \begin_inset LatexCommand \index{Z80}
16049
16050 \end_inset
16051
16052  and the Nintendo Gameboy's Z80-like gbz80
16053 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
16054
16055 \end_inset
16056
16057 .
16058  The Z80 port is passed through the same
16059 \emph on
16060 regressions tests
16061 \begin_inset LatexCommand \index{Regression test}
16062
16063 \end_inset
16064
16065
16066 \emph default
16067  as the MCS51 and DS390 ports, so floating point support, support for long
16068  variables and bitfield support is fine.
16069  See mailing lists and forums about interrupt routines.
16070 \layout Standard
16071
16072 As always, the code is the authoritative reference - see z80/ralloc.c and
16073  z80/gen.c.
16074  The stack
16075 \begin_inset LatexCommand \index{stack}
16076
16077 \end_inset
16078
16079  frame is similar to that generated by the IAR Z80 compiler.
16080  IX is used as the base pointer, HL and IY are used as a temporary registers,
16081  and BC and DE are available for holding variables.
16082  Return values
16083 \begin_inset LatexCommand \index{return value}
16084
16085 \end_inset
16086
16087  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
16088  bytes).
16089  The gbz80 port use the same set of registers for the return values, but
16090  in a different order of significance: E (one byte), DE (two bytes), or
16091  HLDE (four bytes).
16092 \layout Section
16093
16094 The HC08 port
16095 \layout Standard
16096
16097 The port to the Motorola HC08
16098 \begin_inset LatexCommand \index{HC08}
16099
16100 \end_inset
16101
16102  family has been added in October 2003, and is still undergoing some basic
16103  development.
16104  The code generator is complete, but the register allocation is still quite
16105  unoptimized.
16106  Some of the SDCC's standard C library functions have embedded non-HC08
16107  inline assembly and so are not yet usable.
16108 \newline
16109
16110 \newline
16111
16112 \layout Section
16113
16114 The PIC14 port
16115 \layout Standard
16116
16117 The 14bit PIC
16118 \begin_inset LatexCommand \index{PIC14}
16119
16120 \end_inset
16121
16122  port still requires a major effort from the development community.
16123  However it can work for very simple code.
16124 \layout Subsection
16125
16126 C code and 14bit PIC code page
16127 \begin_inset LatexCommand \index{code page (pic14)}
16128
16129 \end_inset
16130
16131  and RAM banks
16132 \begin_inset LatexCommand \index{RAM bank (pic14)}
16133
16134 \end_inset
16135
16136
16137 \layout Standard
16138
16139 The linker organizes allocation for the code page and RAM banks.
16140  It does not have intimate knowledge of the code flow.
16141  It will put all the code section of a single asm file into a single code
16142  page.
16143  In order to make use of multiple code pages, separate asm files must be
16144  used.
16145  The compiler treats all functions of a single C file as being in the same
16146  code page unless it is non static.
16147  The compiler treats all local variables of a single C file as being in
16148  the same RAM bank unless it is an extern.
16149 \newline
16150
16151 \newline
16152 To get the best follow these guide lines:
16153 \layout Enumerate
16154
16155 make local functions static, as non static functions require code page selection
16156  overhead.
16157 \layout Enumerate
16158
16159 Make local variables static as extern variables require RAM bank selection
16160  overhead.
16161 \layout Enumerate
16162
16163 For devices that have multiple code pages it is more efficient to use the
16164  same number of files as pages, i.e.
16165  for the 16F877 use 4 separate files and i.e.
16166  for the 16F874 use 2 separate files.
16167  This way the linker can put the code for each file into different code
16168  pages and the compiler can allocate reusable variables more efficiently
16169  and there's less page selection overhead.
16170  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
16171  instruction set) use 'unsigned char' whereever possible instead of 'int'.
16172 \layout Subsection
16173
16174 Creating a device include file
16175 \layout Standard
16176
16177 For generating a device include file use the support perl script inc2h.pl
16178  kept in directory support/script.
16179 \layout Subsection
16180
16181 Interrupt code
16182 \layout Standard
16183
16184 For the interrupt function, use the keyword 'interrupt'
16185 \begin_inset LatexCommand \index{interrupt}
16186
16187 \end_inset
16188
16189  with level number of 0 (PIC14 only has 1 interrupt so this number is only
16190  there to avoid a syntax error - it ought to be fixed).
16191  E.g.:
16192 \layout Verse
16193
16194
16195 \family typewriter
16196 void Intr(void) interrupt 0
16197 \newline
16198 {
16199 \newline
16200 \SpecialChar ~
16201 \SpecialChar ~
16202 T0IF = 0; /* Clear timer interrupt */
16203 \newline
16204 }
16205 \layout Subsection
16206
16207 Linking and assembling
16208 \layout Standard
16209
16210 For assembling you can use either GPUTILS'
16211 \begin_inset LatexCommand \index{gputils (pic tools)}
16212
16213 \end_inset
16214
16215  gpasm.exe or MPLAB's mpasmwin.exe.
16216  GPUTILS is available from
16217 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
16218
16219 \end_inset
16220
16221 .
16222  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
16223  If you use MPLAB and an interrupt function then the linker script file
16224  vectors section will need to be enlarged to link with mplink.
16225 \newline
16226
16227 \newline
16228 Here is a
16229 \family typewriter
16230 Makefile
16231 \family default
16232  using GPUTILS:
16233 \layout Verse
16234
16235
16236 \family typewriter
16237 .c.o:
16238 \newline
16239 \SpecialChar ~
16240 \SpecialChar ~
16241 \SpecialChar ~
16242 \SpecialChar ~
16243 \SpecialChar ~
16244 \SpecialChar ~
16245 \SpecialChar ~
16246 \SpecialChar ~
16247 sdcc -S -V -mpic14 -p16F877 $<
16248 \newline
16249 \SpecialChar ~
16250 \SpecialChar ~
16251 \SpecialChar ~
16252 \SpecialChar ~
16253 \SpecialChar ~
16254 \SpecialChar ~
16255 \SpecialChar ~
16256 \SpecialChar ~
16257 gpasm -c $*.asm
16258 \newline
16259
16260 \newline
16261 $(PRJ).hex: $(OBJS)
16262 \newline
16263 \SpecialChar ~
16264 \SpecialChar ~
16265 \SpecialChar ~
16266 \SpecialChar ~
16267 \SpecialChar ~
16268 \SpecialChar ~
16269 \SpecialChar ~
16270 \SpecialChar ~
16271 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
16272 \layout Standard
16273
16274 Here is a
16275 \family typewriter
16276 Makefile
16277 \family default
16278  using MPLAB:
16279 \layout Verse
16280
16281
16282 \family typewriter
16283 .c.o:
16284 \newline
16285 \SpecialChar ~
16286 \SpecialChar ~
16287 \SpecialChar ~
16288 \SpecialChar ~
16289 \SpecialChar ~
16290 \SpecialChar ~
16291 \SpecialChar ~
16292 \SpecialChar ~
16293 sdcc -S -V -mpic14 -p16F877 $<
16294 \newline
16295 \SpecialChar ~
16296 \SpecialChar ~
16297 \SpecialChar ~
16298 \SpecialChar ~
16299 \SpecialChar ~
16300 \SpecialChar ~
16301 \SpecialChar ~
16302 \SpecialChar ~
16303 mpasmwin /q /o $*.asm
16304 \newline
16305
16306 \newline
16307 $(PRJ).hex: $(OBJS)
16308 \newline
16309 \SpecialChar ~
16310 \SpecialChar ~
16311 \SpecialChar ~
16312 \SpecialChar ~
16313 \SpecialChar ~
16314 \SpecialChar ~
16315 \SpecialChar ~
16316 \SpecialChar ~
16317 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
16318 \layout Standard
16319
16320 Please note that indentations within a
16321 \family typewriter
16322  Makefile
16323 \family default
16324  have to be done with a tabulator character.
16325 \layout Subsection
16326
16327 Command-line options
16328 \layout Standard
16329
16330 Besides the switches common to all SDCC backends, the PIC14 port accepts
16331  the following options (for an updated list see sdcc -
16332 \begin_inset ERT
16333 status Collapsed
16334
16335 \layout Standard
16336
16337 \backslash
16338 /
16339 \end_inset
16340
16341 -help):
16342 \layout List
16343 \labelwidthstring 00.00.0000
16344
16345 -
16346 \begin_inset ERT
16347 status Collapsed
16348
16349 \layout Standard
16350
16351 \backslash
16352 /
16353 \end_inset
16354
16355 -debug-extra emit debug info in assembly output
16356 \layout List
16357 \labelwidthstring 00.00.0000
16358
16359 -
16360 \begin_inset ERT
16361 status Collapsed
16362
16363 \layout Standard
16364
16365 \backslash
16366 /
16367 \end_inset
16368
16369 -no-pcode-opt disable (slightly faulty) optimization on pCode
16370 \layout Subsection
16371
16372 The library
16373 \layout Subsubsection
16374
16375 error: missing definition for symbol
16376 \begin_inset Quotes sld
16377 \end_inset
16378
16379 __gptrget1
16380 \begin_inset Quotes srd
16381 \end_inset
16382
16383
16384 \layout Standard
16385
16386 The PIC14 port uses library routines to provide more complex operations
16387  like multiplication, division/modulus and (generic) pointer dereferencing.
16388  In order to add these routines to your project, you must link with PIC14's
16389
16390 \family typewriter
16391 libsdcc.lib
16392 \family default
16393 .
16394  For single source file projects this is done automatically, more complex
16395  projects must add
16396 \family typewriter
16397 libsdcc.lib
16398 \family default
16399  to the linker's arguments.
16400  Make sure you also add an include path for the library (using the -I switch
16401  to the linker)!
16402 \layout Subsubsection
16403
16404 Processor mismatch in file
16405 \begin_inset Quotes sld
16406 \end_inset
16407
16408 XXX
16409 \begin_inset Quotes srd
16410 \end_inset
16411
16412 .
16413 \layout Standard
16414
16415 This warning can usually be ignored due to the very good compatibility amongst
16416  14 bit PIC devices.
16417 \layout Standard
16418
16419 You might also consider recompiling the library for your specific device
16420  by changing the ARCH=p16f877 (default target) entry in
16421 \family typewriter
16422 device/lib/pic/Makefile.in
16423 \family default
16424  and
16425 \family typewriter
16426 device/lib/pic/Makefile
16427 \family default
16428  to reflect your device.
16429  This might even improve performance for smaller devices as unneccesary
16430  BANKSELs migth be removed.
16431 \layout Subsection
16432
16433 Known bugs
16434 \layout Subsubsection
16435
16436 initialized data
16437 \layout Standard
16438
16439 Currently, data can only be initialized if it resides in the source file
16440  together with
16441 \emph on
16442 main()
16443 \emph default
16444 .
16445  Data in other source files will silently
16446 \series bold
16447 not
16448 \series default
16449  be initialized.
16450 \layout Section
16451
16452 The PIC16
16453 \begin_inset LatexCommand \index{PIC16}
16454
16455 \end_inset
16456
16457  port
16458 \layout Standard
16459
16460 The PIC16
16461 \begin_inset LatexCommand \index{PIC16}
16462
16463 \end_inset
16464
16465  port is the portion of SDCC that is responsible to produce code for the
16466  Microchip
16467 \begin_inset LatexCommand \index{Microchip}
16468
16469 \end_inset
16470
16471 (TM) microcontrollers with 16 bit core.
16472  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
16473  Currently supported devices are:
16474 \layout Standard
16475 \align center
16476
16477 \begin_inset  Tabular
16478 <lyxtabular version="3" rows="4" columns="6">
16479 <features>
16480 <column alignment="center" valignment="top" leftline="true" width="0">
16481 <column alignment="center" valignment="top" leftline="true" width="0">
16482 <column alignment="center" valignment="top" leftline="true" width="0">
16483 <column alignment="center" valignment="top" leftline="true" width="0">
16484 <column alignment="center" valignment="top" leftline="true" width="0">
16485 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16486 <row topline="true">
16487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16488 \begin_inset Text
16489
16490 \layout Standard
16491
16492 18F242
16493 \end_inset
16494 </cell>
16495 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16496 \begin_inset Text
16497
16498 \layout Standard
16499
16500 18F248
16501 \end_inset
16502 </cell>
16503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16504 \begin_inset Text
16505
16506 \layout Standard
16507
16508 18F252
16509 \end_inset
16510 </cell>
16511 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16512 \begin_inset Text
16513
16514 \layout Standard
16515
16516 18F258
16517 \end_inset
16518 </cell>
16519 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16520 \begin_inset Text
16521
16522 \layout Standard
16523
16524 18F442
16525 \end_inset
16526 </cell>
16527 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16528 \begin_inset Text
16529
16530 \layout Standard
16531
16532 18F448
16533 \end_inset
16534 </cell>
16535 </row>
16536 <row topline="true">
16537 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16538 \begin_inset Text
16539
16540 \layout Standard
16541
16542 18F452
16543 \end_inset
16544 </cell>
16545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16546 \begin_inset Text
16547
16548 \layout Standard
16549
16550 18F458
16551 \end_inset
16552 </cell>
16553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16554 \begin_inset Text
16555
16556 \layout Standard
16557
16558 18F1220
16559 \end_inset
16560 </cell>
16561 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16562 \begin_inset Text
16563
16564 \layout Standard
16565
16566 18F2220
16567 \end_inset
16568 </cell>
16569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16570 \begin_inset Text
16571
16572 \layout Standard
16573
16574 18F2550
16575 \end_inset
16576 </cell>
16577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16578 \begin_inset Text
16579
16580 \layout Standard
16581
16582 18F4331
16583 \end_inset
16584 </cell>
16585 </row>
16586 <row topline="true">
16587 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16588 \begin_inset Text
16589
16590 \layout Standard
16591
16592 18F4455
16593 \end_inset
16594 </cell>
16595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16596 \begin_inset Text
16597
16598 \layout Standard
16599
16600 18F6520
16601 \end_inset
16602 </cell>
16603 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16604 \begin_inset Text
16605
16606 \layout Standard
16607
16608 18F6620
16609 \end_inset
16610 </cell>
16611 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16612 \begin_inset Text
16613
16614 \layout Standard
16615
16616 18F6680
16617 \end_inset
16618 </cell>
16619 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16620 \begin_inset Text
16621
16622 \layout Standard
16623
16624 18F6720
16625 \end_inset
16626 </cell>
16627 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16628 \begin_inset Text
16629
16630 \layout Standard
16631
16632 18F8520
16633 \end_inset
16634 </cell>
16635 </row>
16636 <row topline="true" bottomline="true">
16637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16638 \begin_inset Text
16639
16640 \layout Standard
16641
16642 18F8620
16643 \end_inset
16644 </cell>
16645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16646 \begin_inset Text
16647
16648 \layout Standard
16649
16650 18F8680
16651 \end_inset
16652 </cell>
16653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16654 \begin_inset Text
16655
16656 \layout Standard
16657
16658 18F8720
16659 \end_inset
16660 </cell>
16661 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16662 \begin_inset Text
16663
16664 \layout Standard
16665
16666 \end_inset
16667 </cell>
16668 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16669 \begin_inset Text
16670
16671 \layout Standard
16672
16673 \end_inset
16674 </cell>
16675 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16676 \begin_inset Text
16677
16678 \layout Standard
16679
16680 \end_inset
16681 </cell>
16682 </row>
16683 </lyxtabular>
16684
16685 \end_inset
16686
16687
16688 \layout Subsection
16689
16690 Global Options
16691 \layout Standard
16692
16693 PIC16 port supports the standard command line arguments as supposed, with
16694  the exception of certain cases that will be mentioned in the following
16695  list:
16696 \layout List
16697 \labelwidthstring 00.00.0000
16698
16699 -
16700 \begin_inset ERT
16701 status Collapsed
16702
16703 \layout Standard
16704
16705 \backslash
16706 /
16707 \end_inset
16708
16709 -callee-saves See -
16710 \begin_inset ERT
16711 status Collapsed
16712
16713 \layout Standard
16714
16715 \backslash
16716 /
16717 \end_inset
16718
16719 -all-callee-saves
16720 \layout List
16721 \labelwidthstring 00.00.0000
16722
16723 -
16724 \begin_inset ERT
16725 status Collapsed
16726
16727 \layout Standard
16728
16729 \backslash
16730 /
16731 \end_inset
16732
16733 -all-callee-saves All function arguments are passed on stack by default.
16734
16735 \emph on
16736 There is no need to specify this in the command line.
16737 \layout List
16738 \labelwidthstring 00.00.0000
16739
16740 -
16741 \begin_inset ERT
16742 status Collapsed
16743
16744 \layout Standard
16745
16746 \backslash
16747 /
16748 \end_inset
16749
16750 -fommit-frame-pointer Frame pointer will be omitted when the function uses
16751  no local variables.
16752 \layout Subsection
16753
16754 Port Specific Options
16755 \begin_inset LatexCommand \index{Options PIC16}
16756
16757 \end_inset
16758
16759
16760 \layout Standard
16761
16762 The port specific options appear after the global options in the sdcc --help
16763  output.
16764 \layout Subsubsection
16765
16766 General Options
16767 \layout Standard
16768
16769 General options enable certain port features and optimizations.
16770 \layout List
16771 \labelwidthstring 00.00.0000
16772
16773 -
16774 \begin_inset ERT
16775 status Collapsed
16776
16777 \layout Standard
16778
16779 \backslash
16780 /
16781 \end_inset
16782
16783 -stack-model=[model] Used in conjuction with the command above.
16784  Defines the stack model to be used, valid stack models are :
16785 \begin_deeper
16786 \layout List
16787 \labelwidthstring 00.00.0000
16788
16789
16790 \emph on
16791 small
16792 \emph default
16793  Selects small stack model.
16794  8 bit stack and frame pointers.
16795  Supports 256 bytes stack size.
16796 \layout List
16797 \labelwidthstring 00.00.0000
16798
16799
16800 \emph on
16801 large
16802 \emph default
16803  Selects large stack model.
16804  16 bit stack and frame pointers.
16805  Supports 65536 bytes stack size.
16806 \end_deeper
16807 \layout List
16808 \labelwidthstring 00.00.0000
16809
16810 -
16811 \begin_inset ERT
16812 status Collapsed
16813
16814 \layout Standard
16815
16816 \backslash
16817 /
16818 \end_inset
16819
16820 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
16821  unitialized data variables with [kword].
16822  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
16823 \layout List
16824 \labelwidthstring 00.00.0000
16825
16826 -
16827 \begin_inset ERT
16828 status Collapsed
16829
16830 \layout Standard
16831
16832 \backslash
16833 /
16834 \end_inset
16835
16836 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
16837  Useful for bootloaders.
16838 \layout List
16839 \labelwidthstring 00.00.0000
16840
16841 -
16842 \begin_inset ERT
16843 status Collapsed
16844
16845 \layout Standard
16846
16847 \backslash
16848 /
16849 \end_inset
16850
16851 -asm= sets the full path and name of an external assembler to call.
16852 \layout List
16853 \labelwidthstring 00.00.0000
16854
16855 -
16856 \begin_inset ERT
16857 status Collapsed
16858
16859 \layout Standard
16860
16861 \backslash
16862 /
16863 \end_inset
16864
16865 -link= sets the full path and name of an external linker to call.
16866 \layout List
16867 \labelwidthstring 00.00.0000
16868
16869 -
16870 \begin_inset ERT
16871 status Collapsed
16872
16873 \layout Standard
16874
16875 \backslash
16876 /
16877 \end_inset
16878
16879 -mplab-comp MPLAB compatibility option.
16880  Currently only suppresses special gpasm directives.
16881 \layout Subsubsection
16882
16883 Optimization Options
16884 \layout List
16885 \labelwidthstring 00.00.0000
16886
16887 -
16888 \begin_inset ERT
16889 status Collapsed
16890
16891 \layout Standard
16892
16893 \backslash
16894 /
16895 \end_inset
16896
16897 -optimize-goto Try to use (conditional) BRA instead of GOTO
16898 \layout List
16899 \labelwidthstring 00.00.0000
16900
16901 -
16902 \begin_inset ERT
16903 status Collapsed
16904
16905 \layout Standard
16906
16907 \backslash
16908 /
16909 \end_inset
16910
16911 -optimize-cmp Try to optimize some compares.
16912 \layout List
16913 \labelwidthstring 00.00.0000
16914
16915 -
16916 \begin_inset ERT
16917 status Collapsed
16918
16919 \layout Standard
16920
16921 \backslash
16922 /
16923 \end_inset
16924
16925 -optimize-df Analyze the dataflow of the generated code and improve it.
16926 \layout List
16927 \labelwidthstring 00.00.0000
16928
16929 -
16930 \begin_inset ERT
16931 status Collapsed
16932
16933 \layout Standard
16934
16935 \backslash
16936 /
16937 \end_inset
16938
16939 -obanksel=nn Set optimization level for inserting BANKSELs.
16940 \newline
16941
16942 \begin_deeper
16943 \layout List
16944 \labelwidthstring 00.00.0000
16945
16946 0 no optimization
16947 \layout List
16948 \labelwidthstring 00.00.0000
16949
16950 1 checks previous used register and if it is the same then does not emit
16951  BANKSEL, accounts only for labels.
16952 \layout List
16953 \labelwidthstring 00.00.0000
16954
16955 2 tries to check the location of (even different) symbols and removes BANKSELs
16956  if they are in the same bank.
16957
16958 \newline
16959
16960 \emph on
16961 Important: There might be problems if the linker script has data sections
16962  across bank borders!
16963 \end_deeper
16964 \layout Subsubsection
16965
16966 Linking Options
16967 \layout List
16968 \labelwidthstring 00.00.0000
16969
16970 -
16971 \begin_inset ERT
16972 status Collapsed
16973
16974 \layout Standard
16975
16976 \backslash
16977 /
16978 \end_inset
16979
16980 -nodefaultlibs do not link default libraries when linking
16981 \layout List
16982 \labelwidthstring 00.00.0000
16983
16984 -
16985 \begin_inset ERT
16986 status Collapsed
16987
16988 \layout Standard
16989
16990 \backslash
16991 /
16992 \end_inset
16993
16994 -no-crt Don't link the default run-time modules
16995 \layout List
16996 \labelwidthstring 00.00.0000
16997
16998 -
16999 \begin_inset ERT
17000 status Collapsed
17001
17002 \layout Standard
17003
17004 \backslash
17005 /
17006 \end_inset
17007
17008 -use-crt= Use a custom run-time module instead of the defaults.
17009 \layout Subsubsection
17010
17011 Debugging Options
17012 \layout Standard
17013
17014 Debugging options enable extra debugging information in the output files.
17015 \layout List
17016 \labelwidthstring 00.00.0000
17017
17018 -
17019 \begin_inset ERT
17020 status Collapsed
17021
17022 \layout Standard
17023
17024 \backslash
17025 /
17026 \end_inset
17027
17028 -debug-xtra Similar to -
17029 \begin_inset ERT
17030 status Collapsed
17031
17032 \layout Standard
17033
17034 \backslash
17035 /
17036 \end_inset
17037
17038 -debug
17039 \begin_inset LatexCommand \index{-\/-debug}
17040
17041 \end_inset
17042
17043 , but dumps more information.
17044 \layout List
17045 \labelwidthstring 00.00.0000
17046
17047 -
17048 \begin_inset ERT
17049 status Collapsed
17050
17051 \layout Standard
17052
17053 \backslash
17054 /
17055 \end_inset
17056
17057 -debug-ralloc Force register allocator to dump <source>.d file with debugging
17058  information.
17059  <source> is the name of the file compiled.
17060 \layout List
17061 \labelwidthstring 00.00.0000
17062
17063 -
17064 \begin_inset ERT
17065 status Collapsed
17066
17067 \layout Standard
17068
17069 \backslash
17070 /
17071 \end_inset
17072
17073 -pcode-verbose Enable pcode debugging information in translation.
17074 \layout List
17075 \labelwidthstring 00.00.0000
17076
17077 -
17078 \begin_inset ERT
17079 status Collapsed
17080
17081 \layout Standard
17082
17083 \backslash
17084 /
17085 \end_inset
17086
17087 -denable-peeps Force the usage of peepholes.
17088  Use with care.
17089 \layout List
17090 \labelwidthstring 00.00.0000
17091
17092 -
17093 \begin_inset ERT
17094 status Collapsed
17095
17096 \layout Standard
17097
17098 \backslash
17099 /
17100 \end_inset
17101
17102 -gstack Trace push/pops for stack pointer overflow
17103 \layout List
17104 \labelwidthstring 00.00.0000
17105
17106 -
17107 \begin_inset ERT
17108 status Collapsed
17109
17110 \layout Standard
17111
17112 \backslash
17113 /
17114 \end_inset
17115
17116 -call-tree dump call tree in .calltree file
17117 \layout Subsection
17118
17119 Enviromental Variables
17120 \layout Standard
17121
17122 There is a number of enviromental variables that can be used when running
17123  SDCC to enable certain optimizations or force a specific program behaviour.
17124  these variables are primarily for debugging purposes so they can be enabled/dis
17125 abled at will.
17126 \layout Standard
17127
17128 Currently there is only two such variables available:
17129 \layout List
17130 \labelwidthstring 00.00.0000
17131
17132 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
17133  bitfields is optimized by directly loading FSR0 with the address of the
17134  bitfield structure.
17135  Normally SDCC will cast the bitfield structure to a bitfield pointer and
17136  then load FSR0.
17137  This step saves data ram and code space for functions that perform heavy
17138  use of bitfields.
17139  (ie.
17140  80 bytes of code space are saved when compiling malloc.c with this option).
17141
17142 \layout List
17143 \labelwidthstring 00.00.0000
17144
17145 NO_REG_OPT do not perform pCode registers optimization.
17146  This should be used for debugging purposes.
17147  In some where bugs in the pcode optimizer are found, users can benefit
17148  from temporarily disabling the optimizer until the bug is fixed.
17149 \layout Subsection
17150
17151 Preprocessor Macros
17152 \layout Standard
17153
17154 PIC16 port defines the following preprocessor macros while translating a
17155  source.
17156 \layout Standard
17157 \align center
17158
17159 \begin_inset  Tabular
17160 <lyxtabular version="3" rows="6" columns="2">
17161 <features>
17162 <column alignment="center" valignment="top" leftline="true" width="0">
17163 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17164 <row topline="true" bottomline="true">
17165 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17166 \begin_inset Text
17167
17168 \layout Standard
17169
17170 Macro
17171 \end_inset
17172 </cell>
17173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17174 \begin_inset Text
17175
17176 \layout Standard
17177
17178 Description
17179 \end_inset
17180 </cell>
17181 </row>
17182 <row topline="true">
17183 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17184 \begin_inset Text
17185
17186 \layout Standard
17187
17188 SDCC_pic16
17189 \end_inset
17190 </cell>
17191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17192 \begin_inset Text
17193
17194 \layout Standard
17195
17196 Port identification
17197 \end_inset
17198 </cell>
17199 </row>
17200 <row topline="true">
17201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17202 \begin_inset Text
17203
17204 \layout Standard
17205
17206 _
17207 \begin_inset ERT
17208 status Collapsed
17209
17210 \layout Standard
17211
17212 \backslash
17213 /
17214 \end_inset
17215
17216 _pic16
17217 \end_inset
17218 </cell>
17219 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17220 \begin_inset Text
17221
17222 \layout Standard
17223
17224 Port identification (same as above)
17225 \end_inset
17226 </cell>
17227 </row>
17228 <row topline="true">
17229 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17230 \begin_inset Text
17231
17232 \layout Standard
17233
17234 pic18fxxxx
17235 \end_inset
17236 </cell>
17237 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17238 \begin_inset Text
17239
17240 \layout Standard
17241
17242 MCU Identification.
17243
17244 \emph on
17245 xxxx
17246 \emph default
17247  is the microcontrol identification number, i.e.
17248  452, 6620, etc
17249 \end_inset
17250 </cell>
17251 </row>
17252 <row topline="true">
17253 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17254 \begin_inset Text
17255
17256 \layout Standard
17257
17258 _
17259 \begin_inset ERT
17260 status Collapsed
17261
17262 \layout Standard
17263
17264 \backslash
17265 /
17266 \end_inset
17267
17268 _18Fxxxx
17269 \end_inset
17270 </cell>
17271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17272 \begin_inset Text
17273
17274 \layout Standard
17275
17276 MCU Identification (same as above)
17277 \end_inset
17278 </cell>
17279 </row>
17280 <row topline="true" bottomline="true">
17281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17282 \begin_inset Text
17283
17284 \layout Standard
17285
17286 STACK_MODEL_nnn
17287 \end_inset
17288 </cell>
17289 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17290 \begin_inset Text
17291
17292 \layout Standard
17293
17294 nnn = SMALL or LARGE respectively according to the stack model used
17295 \end_inset
17296 </cell>
17297 </row>
17298 </lyxtabular>
17299
17300 \end_inset
17301
17302
17303 \layout Standard
17304
17305 In addition the following macros are defined when calling assembler:
17306 \layout Standard
17307 \align center
17308
17309 \begin_inset  Tabular
17310 <lyxtabular version="3" rows="4" columns="2">
17311 <features>
17312 <column alignment="center" valignment="top" leftline="true" width="0">
17313 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17314 <row topline="true" bottomline="true">
17315 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17316 \begin_inset Text
17317
17318 \layout Standard
17319
17320 Macro
17321 \end_inset
17322 </cell>
17323 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17324 \begin_inset Text
17325
17326 \layout Standard
17327
17328 Description
17329 \end_inset
17330 </cell>
17331 </row>
17332 <row topline="true">
17333 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17334 \begin_inset Text
17335
17336 \layout Standard
17337
17338 __18Fxxxx
17339 \end_inset
17340 </cell>
17341 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17342 \begin_inset Text
17343
17344 \layout Standard
17345
17346 MCU Identification.
17347
17348 \emph on
17349 xxxx
17350 \emph default
17351  is the microcontrol identification number, i.e.
17352  452, 6620, etc
17353 \end_inset
17354 </cell>
17355 </row>
17356 <row topline="true">
17357 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17358 \begin_inset Text
17359
17360 \layout Standard
17361
17362 SDCC_MODEL_nnn
17363 \end_inset
17364 </cell>
17365 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17366 \begin_inset Text
17367
17368 \layout Standard
17369
17370 nnn = SMALL or LARGE respectively according to the memory model used for
17371  SDCC
17372 \end_inset
17373 </cell>
17374 </row>
17375 <row topline="true" bottomline="true">
17376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17377 \begin_inset Text
17378
17379 \layout Standard
17380
17381 STACK_MODEL_nnn
17382 \end_inset
17383 </cell>
17384 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17385 \begin_inset Text
17386
17387 \layout Standard
17388
17389 nnn = SMALL or LARGE respectively according to the stack model used
17390 \end_inset
17391 </cell>
17392 </row>
17393 </lyxtabular>
17394
17395 \end_inset
17396
17397
17398 \layout Subsection
17399
17400 Directories
17401 \layout Standard
17402
17403 PIC16
17404 \begin_inset LatexCommand \index{PIC16}
17405
17406 \end_inset
17407
17408  port uses the following directories for searching header files and libraries.
17409 \layout Standard
17410 \align center
17411
17412 \begin_inset  Tabular
17413 <lyxtabular version="3" rows="3" columns="4">
17414 <features>
17415 <column alignment="center" valignment="top" leftline="true" width="0">
17416 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17417 <column alignment="center" valignment="top" width="0">
17418 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17419 <row topline="true" bottomline="true">
17420 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17421 \begin_inset Text
17422
17423 \layout Standard
17424
17425 Directory
17426 \end_inset
17427 </cell>
17428 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17429 \begin_inset Text
17430
17431 \layout Standard
17432
17433 Description
17434 \end_inset
17435 </cell>
17436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17437 \begin_inset Text
17438
17439 \layout Standard
17440
17441 Target
17442 \end_inset
17443 </cell>
17444 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17445 \begin_inset Text
17446
17447 \layout Standard
17448
17449 Command prefix
17450 \end_inset
17451 </cell>
17452 </row>
17453 <row topline="true">
17454 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17455 \begin_inset Text
17456
17457 \layout Standard
17458
17459 PREFIX/sdcc/include/pic16
17460 \end_inset
17461 </cell>
17462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17463 \begin_inset Text
17464
17465 \layout Standard
17466
17467 PIC16 specific headers
17468 \end_inset
17469 </cell>
17470 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17471 \begin_inset Text
17472
17473 \layout Standard
17474
17475 Compiler
17476 \end_inset
17477 </cell>
17478 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17479 \begin_inset Text
17480
17481 \layout Standard
17482
17483 -I
17484 \end_inset
17485 </cell>
17486 </row>
17487 <row topline="true" bottomline="true">
17488 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17489 \begin_inset Text
17490
17491 \layout Standard
17492
17493 PREFIX/sdcc/lib/pic16
17494 \end_inset
17495 </cell>
17496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17497 \begin_inset Text
17498
17499 \layout Standard
17500
17501 PIC16 specific libraries
17502 \end_inset
17503 </cell>
17504 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17505 \begin_inset Text
17506
17507 \layout Standard
17508
17509 Linker
17510 \end_inset
17511 </cell>
17512 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17513 \begin_inset Text
17514
17515 \layout Standard
17516
17517 -L
17518 \end_inset
17519 </cell>
17520 </row>
17521 </lyxtabular>
17522
17523 \end_inset
17524
17525
17526 \layout Subsection
17527
17528 Pragmas
17529 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
17530
17531 \end_inset
17532
17533
17534 \layout Standard
17535
17536 PIC16 port currently supports the following pragmas:
17537 \layout List
17538 \labelwidthstring 00.00.0000
17539
17540 stack pragma stack forces the code generator to initialize the stack & frame
17541  pointers at a specific address.
17542  This is an adhoc solution for cases where no STACK directive is available
17543  in the linker script or gplink is not instructed to create a stack section.
17544 \newline
17545 The stack pragma should be used only once in a project.
17546  Multiple pragmas may result in indeterminate behaviour of the program.
17547 \begin_inset Foot
17548 collapsed false
17549
17550 \layout Standard
17551
17552 The old format (ie.
17553  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
17554  cross page boundaries (or even exceed the available data RAM) and crash
17555  the program.
17556  Make sure that stack does not cross page boundaries when using the SMALL
17557  stack model.
17558 \end_inset
17559
17560
17561 \newline
17562 The format is as follows:
17563 \layout LyX-Code
17564
17565 #pragma stack bottom_address [stack_size]
17566 \layout Standard
17567
17568
17569 \emph on
17570 bottom_address
17571 \emph default
17572  is the lower bound of the stack section.
17573  The stack pointer initially will point at address (bottom_address+stack_size-1).
17574 \layout LyX-Code
17575
17576 Example:
17577 \layout LyX-Code
17578
17579 \layout LyX-Code
17580
17581 /* initializes stack of 100 bytes at RAM address 0x200 */
17582 \layout LyX-Code
17583
17584 #pragma stack 0x200 100
17585 \layout Standard
17586
17587 If the stack_size field is omitted then a stack is created with the default
17588  size of 64.
17589  This size might be enough for most programs, but its not enough for operations
17590  with deep function nesting or excessive stack usage.
17591 \layout List
17592 \labelwidthstring 00.00.0000
17593
17594 wparam
17595 \emph on
17596 This pragma is deprecated.
17597  Its use will cause a warning message to be issued.
17598 \emph default
17599
17600 \newline
17601
17602 \layout List
17603 \labelwidthstring 00.00.0000
17604
17605 code place a function symbol at static FLASH address
17606 \layout LyX-Code
17607
17608 Example:
17609 \layout LyX-Code
17610
17611 \layout LyX-Code
17612
17613 /* place function test_func at 0x4000 */
17614 \layout LyX-Code
17615
17616 #pragma code test_func 0x4000
17617 \layout LyX-Code
17618
17619 \layout List
17620 \labelwidthstring 00.00.0000
17621
17622 library instructs the linker to use a library module.
17623 \newline
17624 Usage:
17625 \layout LyX-Code
17626
17627 #pragma library module_name
17628 \layout Standard
17629
17630
17631 \emph on
17632 module_name
17633 \emph default
17634  can be any library or object file (including its path).
17635  Note that there are four reserved keywords which have special meaning.
17636  These are:
17637 \layout Standard
17638 \align center
17639
17640 \begin_inset  Tabular
17641 <lyxtabular version="3" rows="6" columns="3">
17642 <features>
17643 <column alignment="center" valignment="top" leftline="true" width="0">
17644 <column alignment="block" valignment="top" leftline="true" width="20page%">
17645 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
17646 <row topline="true" bottomline="true">
17647 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17648 \begin_inset Text
17649
17650 \layout Standard
17651
17652 Keyword
17653 \end_inset
17654 </cell>
17655 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17656 \begin_inset Text
17657
17658 \layout Standard
17659
17660 Description
17661 \end_inset
17662 </cell>
17663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17664 \begin_inset Text
17665
17666 \layout Standard
17667
17668 Module to link
17669 \end_inset
17670 </cell>
17671 </row>
17672 <row topline="true">
17673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17674 \begin_inset Text
17675
17676 \layout Standard
17677
17678
17679 \series bold
17680 ignore
17681 \end_inset
17682 </cell>
17683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17684 \begin_inset Text
17685
17686 \layout Standard
17687
17688 ignore all library pragmas
17689 \end_inset
17690 </cell>
17691 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17692 \begin_inset Text
17693
17694 \layout Standard
17695
17696
17697 \emph on
17698 (none)
17699 \end_inset
17700 </cell>
17701 </row>
17702 <row topline="true">
17703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17704 \begin_inset Text
17705
17706 \layout Standard
17707
17708
17709 \series bold
17710 c
17711 \end_inset
17712 </cell>
17713 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17714 \begin_inset Text
17715
17716 \layout Standard
17717
17718 link the C library
17719 \end_inset
17720 </cell>
17721 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17722 \begin_inset Text
17723
17724 \layout Standard
17725
17726
17727 \emph on
17728 libc18f
17729 \emph default
17730 .lib
17731 \end_inset
17732 </cell>
17733 </row>
17734 <row topline="true">
17735 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17736 \begin_inset Text
17737
17738 \layout Standard
17739
17740
17741 \series bold
17742 math
17743 \end_inset
17744 </cell>
17745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17746 \begin_inset Text
17747
17748 \layout Standard
17749
17750 link the Math libarary
17751 \end_inset
17752 </cell>
17753 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17754 \begin_inset Text
17755
17756 \layout Standard
17757
17758
17759 \emph on
17760 libm18f
17761 \emph default
17762 .lib
17763 \end_inset
17764 </cell>
17765 </row>
17766 <row topline="true">
17767 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17768 \begin_inset Text
17769
17770 \layout Standard
17771
17772
17773 \series bold
17774 io
17775 \end_inset
17776 </cell>
17777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17778 \begin_inset Text
17779
17780 \layout Standard
17781
17782 link the I/O library
17783 \end_inset
17784 </cell>
17785 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17786 \begin_inset Text
17787
17788 \layout Standard
17789
17790
17791 \emph on
17792 libio18f*
17793 \emph default
17794 .lib
17795 \end_inset
17796 </cell>
17797 </row>
17798 <row topline="true" bottomline="true">
17799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17800 \begin_inset Text
17801
17802 \layout Standard
17803
17804
17805 \series bold
17806 debug
17807 \end_inset
17808 </cell>
17809 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17810 \begin_inset Text
17811
17812 \layout Standard
17813
17814 link the debug library
17815 \end_inset
17816 </cell>
17817 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17818 \begin_inset Text
17819
17820 \layout Standard
17821
17822
17823 \emph on
17824 libdebug
17825 \emph default
17826 .lib
17827 \end_inset
17828 </cell>
17829 </row>
17830 </lyxtabular>
17831
17832 \end_inset
17833
17834
17835 \newline
17836 * is the device number, i.e.
17837  452 for PIC18F452 MCU.
17838 \layout Standard
17839
17840 This feature allows for linking with specific libraries withoug having to
17841  explicit name them in the command line.
17842  Note that the
17843 \noun on
17844 ignore
17845 \noun default
17846  keyword will reject all modules specified by the library pragma.
17847 \layout List
17848 \labelwidthstring 00.00.0000
17849
17850 udata pragma udata instructs the compiler to emit code so that linker will
17851  place a variable at a specific memory bank
17852 \layout LyX-Code
17853
17854 Example:
17855 \layout LyX-Code
17856
17857 \layout LyX-Code
17858
17859 /* places variable foo at bank2 */
17860 \layout LyX-Code
17861
17862 #pragma udata bank2 foo
17863 \layout LyX-Code
17864
17865 char foo;
17866 \layout Standard
17867
17868 In order for this pragma to work extra SECTION directives should be added
17869  in the .lkr script.
17870  In the following example a sample .lkr file is shown:
17871 \layout LyX-Code
17872
17873 \layout LyX-Code
17874
17875 // Sample linker script for the PIC18F452 processor
17876 \layout LyX-Code
17877
17878 LIBPATH .
17879 \layout LyX-Code
17880
17881 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
17882 \layout LyX-Code
17883
17884 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
17885 \layout LyX-Code
17886
17887 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
17888 \layout LyX-Code
17889
17890 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
17891 \layout LyX-Code
17892
17893 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
17894 \layout LyX-Code
17895
17896 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
17897 \layout LyX-Code
17898
17899 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
17900 \layout LyX-Code
17901
17902 \layout LyX-Code
17903
17904 DATABANK   NAME=gpr0       START=0x80           END=0xFF
17905 \layout LyX-Code
17906
17907 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
17908 \layout LyX-Code
17909
17910 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
17911 \layout LyX-Code
17912
17913 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
17914 \layout LyX-Code
17915
17916 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
17917 \layout LyX-Code
17918
17919 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
17920 \layout LyX-Code
17921
17922 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
17923 \layout LyX-Code
17924
17925 \layout LyX-Code
17926
17927 SECTION    NAME=CONFIG     ROM=config
17928 \layout LyX-Code
17929
17930 \layout LyX-Code
17931
17932 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
17933 \layout LyX-Code
17934
17935 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
17936 \layout LyX-Code
17937
17938 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
17939 \layout LyX-Code
17940
17941 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
17942 \layout LyX-Code
17943
17944 SECTION    NAME=bank4      RAM=gpr4
17945 \layout LyX-Code
17946
17947 SECTION    NAME=bank5      RAM=gpr5
17948 \layout Standard
17949
17950 The linker will recognise the section name set in the pragma statement and
17951  will position the variable at the memory bank set with the RAM field at
17952  the SECTION line in the linker script file.
17953 \layout Subsection
17954
17955 Header Files
17956 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
17957
17958 \end_inset
17959
17960
17961 \layout Standard
17962
17963 There is one main header file that can be included to the source files using
17964  the pic16 port.
17965  That file is the
17966 \series bold
17967 pic18fregs.h
17968 \series default
17969 .
17970  This header file contains the definitions for the processor special registers,
17971  so it is necessary if the source accesses them.
17972  It can be included by adding the following line in the beginning of the
17973  file:
17974 \layout LyX-Code
17975
17976 #include <pic18fregs.h>
17977 \layout Standard
17978
17979 The specific microcontroller is selected within the pic18fregs.h automatically,
17980  so the same source can be used with a variety of devices.
17981 \layout Subsection
17982
17983 Libraries
17984 \layout Standard
17985
17986 The libraries that PIC16
17987 \begin_inset LatexCommand \index{PIC16}
17988
17989 \end_inset
17990
17991  port depends on are the microcontroller device libraries which contain
17992  the symbol definitions for the microcontroller special function registers.
17993  These libraries have the format pic18fxxxx.lib, where
17994 \emph on
17995 xxxx
17996 \emph default
17997  is the microcontroller identification number.
17998  The specific library is selected automatically by the compiler at link
17999  stage according to the selected device.
18000 \layout Standard
18001
18002 Libraries are created with gplib which is part of the gputils package
18003 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
18004
18005 \end_inset
18006
18007 .
18008 \layout Subsubsection*
18009
18010 Building the libraries
18011 \layout Standard
18012
18013 Before using SDCC/pic16 there are some libraries that need to be compiled.
18014  This process is not done automatically by SDCC since not all users use
18015  SDCC for pic16 projects.
18016  So each user should compile the libraries separately.
18017 \layout Standard
18018
18019 The steps to compile the pic16 libraries under Linux are:
18020 \layout LyX-Code
18021
18022 cd device/lib/pic16
18023 \layout LyX-Code
18024
18025 ./configure
18026 \layout LyX-Code
18027
18028 make
18029 \layout LyX-Code
18030
18031 cd ..
18032 \layout LyX-Code
18033
18034 make model-pic16
18035 \layout LyX-Code
18036
18037 su -c 'make install'     # install the libraries, you need the root password
18038 \layout Standard
18039
18040 If you need to install the headers too, do:
18041 \layout LyX-Code
18042
18043 cd device/include
18044 \layout LyX-Code
18045
18046 su -c 'make install'     # install the headers, you need the root password
18047 \layout Standard
18048
18049 There exist a special target to build the I/O libraries.
18050  This target is not automatically build because it will build the I/O library
18051  for
18052 \emph on
18053 every
18054 \emph default
18055  supported device.
18056  This way building will take quite a lot of time.
18057  Users are advised to edit the
18058 \series bold
18059 device/lib/pic16/pics.build
18060 \series default
18061  file and then execute:
18062 \layout LyX-Code
18063
18064 make lib-io
18065 \layout Subsection
18066
18067 Memory Models
18068 \layout Standard
18069
18070 The following memory models are supported by the PIC16 port:
18071 \layout Itemize
18072
18073 small model
18074 \layout Itemize
18075
18076 large model
18077 \layout Standard
18078
18079 Memory model affects the default size of pointers within the source.
18080  The sizes are shown in the next table:
18081 \layout Standard
18082 \align center
18083
18084 \begin_inset  Tabular
18085 <lyxtabular version="3" rows="3" columns="3">
18086 <features>
18087 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18088 <column alignment="center" valignment="top" leftline="true" width="0">
18089 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18090 <row topline="true" bottomline="true">
18091 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18092 \begin_inset Text
18093
18094 \layout Standard
18095
18096 Pointer sizes according to memory model
18097 \end_inset
18098 </cell>
18099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18100 \begin_inset Text
18101
18102 \layout Standard
18103
18104 small model
18105 \end_inset
18106 </cell>
18107 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18108 \begin_inset Text
18109
18110 \layout Standard
18111
18112 large model
18113 \end_inset
18114 </cell>
18115 </row>
18116 <row topline="true" bottomline="true">
18117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18118 \begin_inset Text
18119
18120 \layout Standard
18121
18122 code pointers
18123 \end_inset
18124 </cell>
18125 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18126 \begin_inset Text
18127
18128 \layout Standard
18129
18130 16-bits
18131 \end_inset
18132 </cell>
18133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18134 \begin_inset Text
18135
18136 \layout Standard
18137
18138 24-bits
18139 \end_inset
18140 </cell>
18141 </row>
18142 <row topline="true" bottomline="true">
18143 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18144 \begin_inset Text
18145
18146 \layout Standard
18147
18148 data pointers
18149 \end_inset
18150 </cell>
18151 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
18152 \begin_inset Text
18153
18154 \layout Standard
18155
18156 16-bits
18157 \end_inset
18158 </cell>
18159 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18160 \begin_inset Text
18161
18162 \layout Standard
18163
18164 16-bits
18165 \end_inset
18166 </cell>
18167 </row>
18168 </lyxtabular>
18169
18170 \end_inset
18171
18172
18173 \layout Standard
18174
18175 It is advisable that all sources within a project are compiled with the
18176  same memory model.
18177  If one wants to override the default memory model, this can be done by
18178  declaring a pointer as
18179 \series bold
18180 far
18181 \series default
18182  or
18183 \series bold
18184 near
18185 \series default
18186 .
18187  Far selects large memory model's pointers, while near selects small memory
18188  model's pointers.
18189 \layout Standard
18190
18191 The standard device libraries (see
18192 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
18193
18194 \end_inset
18195
18196 ) contain no reference to pointers, so they can be used with both memory
18197  models.
18198 \layout Subsection
18199
18200 Stack
18201 \layout Standard
18202
18203 The stack implementation for the PIC16 port uses two indirect registers,
18204  FSR1 and FSR2.
18205 \layout List
18206 \labelwidthstring 00.00.0000
18207
18208 FSR1 is assigned as stack pointer
18209 \layout List
18210 \labelwidthstring 00.00.0000
18211
18212 FSR2 is assigned as frame pointer
18213 \layout Standard
18214
18215 The following stack models are supported by the PIC16 port
18216 \layout Itemize
18217
18218
18219 \noun on
18220 small
18221 \noun default
18222  model
18223 \layout Itemize
18224
18225
18226 \noun on
18227 large
18228 \noun default
18229  model
18230 \layout Standard
18231
18232
18233 \noun on
18234 Small
18235 \noun default
18236  model means that only the FSRxL byte is used to access stack and frame,
18237  while
18238 \emph on
18239 \noun on
18240 large
18241 \emph default
18242 \noun default
18243  uses both FSRxL and FSRxH registers.
18244  The following table shows the stack/frame pointers sizes according to stack
18245  model and the maximum space they can address:
18246 \layout Standard
18247 \align center
18248
18249 \begin_inset  Tabular
18250 <lyxtabular version="3" rows="3" columns="3">
18251 <features>
18252 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18253 <column alignment="center" valignment="top" leftline="true" width="0">
18254 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18255 <row topline="true" bottomline="true">
18256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18257 \begin_inset Text
18258
18259 \layout Standard
18260
18261 Stack & Frame pointer sizes according to stack model
18262 \end_inset
18263 </cell>
18264 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18265 \begin_inset Text
18266
18267 \layout Standard
18268
18269 small
18270 \end_inset
18271 </cell>
18272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18273 \begin_inset Text
18274
18275 \layout Standard
18276
18277 large
18278 \end_inset
18279 </cell>
18280 </row>
18281 <row topline="true">
18282 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18283 \begin_inset Text
18284
18285 \layout Standard
18286
18287 Stack pointer FSR1
18288 \end_inset
18289 </cell>
18290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18291 \begin_inset Text
18292
18293 \layout Standard
18294
18295 8-bits
18296 \end_inset
18297 </cell>
18298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18299 \begin_inset Text
18300
18301 \layout Standard
18302
18303 16-bits
18304 \end_inset
18305 </cell>
18306 </row>
18307 <row topline="true" bottomline="true">
18308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18309 \begin_inset Text
18310
18311 \layout Standard
18312
18313 Frame pointer FSR2
18314 \end_inset
18315 </cell>
18316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18317 \begin_inset Text
18318
18319 \layout Standard
18320
18321 8-bits
18322 \end_inset
18323 </cell>
18324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18325 \begin_inset Text
18326
18327 \layout Standard
18328
18329 16-bits
18330 \end_inset
18331 </cell>
18332 </row>
18333 </lyxtabular>
18334
18335 \end_inset
18336
18337
18338 \layout Standard
18339
18340
18341 \noun on
18342 Large
18343 \noun default
18344 stack model is currently not working properly throughout the code generator.
18345  So its use is not advised.
18346  Also there are some other points that need special care:
18347 \newline
18348
18349 \layout Enumerate
18350
18351 Do not create stack sections with size more than one physical bank (that
18352  is 256 bytes)
18353 \layout Enumerate
18354
18355 Stack sections should no cross physical bank limits (i.e.
18356  #pragma stack 0x50 0x100)
18357 \layout Standard
18358
18359 These limitations are caused by the fact that only FSRxL is modified when
18360  using SMALL stack model, so no more than 256 bytes of stack can be used.
18361  This problem will disappear after LARGE model is fully implemented.
18362 \layout Subsection
18363
18364 Functions
18365 \layout Standard
18366
18367 In addition to the standard SDCC function keywords, PIC16 port makes available
18368  two more:
18369 \layout List
18370 \labelwidthstring 00.00.0000
18371
18372 wparam Use the WREG to pass one byte of the first function argument.
18373  This improves speed but you may not use this for functions with arguments
18374  that are called via function pointers, otherwise the first byte of the
18375  first parameter will get lost.
18376  Usage:
18377 \layout LyX-Code
18378
18379 void func_wparam(int a) wparam
18380 \layout LyX-Code
18381
18382 {
18383 \layout LyX-Code
18384
18385     /* WREG hold the lower part of a */
18386 \layout LyX-Code
18387
18388     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
18389  */
18390 \layout LyX-Code
18391
18392 ...
18393 \layout LyX-Code
18394
18395 }
18396 \layout Standard
18397
18398 This keyword replaces the deprecated wparam pragma.
18399 \layout List
18400 \labelwidthstring 00.00.0000
18401
18402 shadowregs When entering/exiting an ISR, it is possible to take advantage
18403  of the PIC18F hardware shadow registers which hold the values of WREG,
18404  STATUS and BSR registers.
18405  This can be done by adding the keyword
18406 \emph on
18407 shadowregs
18408 \emph default
18409  before the
18410 \emph on
18411 interrupt
18412 \emph default
18413  keyword in the function's header.
18414 \layout LyX-Code
18415
18416 void isr_shadow(void) shadowregs interrupt 1
18417 \layout LyX-Code
18418
18419 {
18420 \layout LyX-Code
18421
18422 ...
18423 \layout LyX-Code
18424
18425 }
18426 \layout Standard
18427
18428
18429 \emph on
18430 shadowregs
18431 \emph default
18432  instructs the code generator not to store/restore WREG, STATUS, BSR when
18433  entering/exiting the ISR.
18434 \layout Subsection
18435
18436 Function return values
18437 \layout Standard
18438
18439 Return values from functions are placed to the appropriate registers following
18440  a modified Microchip policy optimized for SDCC.
18441  The following table shows these registers:
18442 \layout Standard
18443 \align center
18444
18445 \begin_inset  Tabular
18446 <lyxtabular version="3" rows="6" columns="2">
18447 <features>
18448 <column alignment="center" valignment="top" leftline="true" width="0">
18449 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18450 <row topline="true" bottomline="true">
18451 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18452 \begin_inset Text
18453
18454 \layout Standard
18455
18456 size
18457 \end_inset
18458 </cell>
18459 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18460 \begin_inset Text
18461
18462 \layout Standard
18463
18464 destination register
18465 \end_inset
18466 </cell>
18467 </row>
18468 <row topline="true">
18469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18470 \begin_inset Text
18471
18472 \layout Standard
18473
18474 8 bits
18475 \end_inset
18476 </cell>
18477 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18478 \begin_inset Text
18479
18480 \layout Standard
18481
18482 WREG
18483 \end_inset
18484 </cell>
18485 </row>
18486 <row topline="true">
18487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18488 \begin_inset Text
18489
18490 \layout Standard
18491
18492 16 bits
18493 \end_inset
18494 </cell>
18495 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18496 \begin_inset Text
18497
18498 \layout Standard
18499
18500 PRODL:WREG
18501 \end_inset
18502 </cell>
18503 </row>
18504 <row topline="true">
18505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18506 \begin_inset Text
18507
18508 \layout Standard
18509
18510 24 bits
18511 \end_inset
18512 </cell>
18513 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18514 \begin_inset Text
18515
18516 \layout Standard
18517
18518 PRODH:PRODL:WREG
18519 \end_inset
18520 </cell>
18521 </row>
18522 <row topline="true">
18523 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18524 \begin_inset Text
18525
18526 \layout Standard
18527
18528 32 bits
18529 \end_inset
18530 </cell>
18531 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18532 \begin_inset Text
18533
18534 \layout Standard
18535
18536 FSR0L:PRODH:PRODL:WREG
18537 \end_inset
18538 </cell>
18539 </row>
18540 <row topline="true" bottomline="true">
18541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18542 \begin_inset Text
18543
18544 \layout Standard
18545
18546 >32 bits
18547 \end_inset
18548 </cell>
18549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18550 \begin_inset Text
18551
18552 \layout Standard
18553
18554 on stack, FSR0 points to the beginning
18555 \end_inset
18556 </cell>
18557 </row>
18558 </lyxtabular>
18559
18560 \end_inset
18561
18562
18563 \layout Subsection
18564
18565 Interrupts
18566 \layout Standard
18567
18568 An interrupt servive routine (ISR) is declared using the
18569 \emph on
18570 interrupt
18571 \emph default
18572  keyword.
18573 \layout LyX-Code
18574
18575 void isr(void) interrupt
18576 \emph on
18577 n
18578 \layout LyX-Code
18579
18580 {
18581 \layout LyX-Code
18582
18583 ...
18584 \layout LyX-Code
18585
18586 }
18587 \layout Standard
18588
18589
18590 \emph on
18591 n
18592 \emph default
18593  is the interrupt number, which for PIC18F devices can be:
18594 \layout Standard
18595 \align center
18596
18597 \begin_inset  Tabular
18598 <lyxtabular version="3" rows="4" columns="3">
18599 <features>
18600 <column alignment="center" valignment="top" leftline="true" width="0">
18601 <column alignment="center" valignment="top" leftline="true" width="0">
18602 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18603 <row topline="true" bottomline="true">
18604 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18605 \begin_inset Text
18606
18607 \layout Standard
18608
18609
18610 \emph on
18611 n
18612 \end_inset
18613 </cell>
18614 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18615 \begin_inset Text
18616
18617 \layout Standard
18618
18619 Interrupt Vector
18620 \end_inset
18621 </cell>
18622 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18623 \begin_inset Text
18624
18625 \layout Standard
18626
18627 Interrupt Vector Address
18628 \end_inset
18629 </cell>
18630 </row>
18631 <row topline="true">
18632 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18633 \begin_inset Text
18634
18635 \layout Standard
18636
18637 0
18638 \end_inset
18639 </cell>
18640 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18641 \begin_inset Text
18642
18643 \layout Standard
18644
18645 RESET vector
18646 \end_inset
18647 </cell>
18648 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18649 \begin_inset Text
18650
18651 \layout Standard
18652
18653 0x000000
18654 \end_inset
18655 </cell>
18656 </row>
18657 <row topline="true">
18658 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18659 \begin_inset Text
18660
18661 \layout Standard
18662
18663
18664 \family roman
18665 \series medium
18666 \shape up
18667 \size normal
18668 \emph off
18669 \bar no
18670 \noun off
18671 \color none
18672 1
18673 \end_inset
18674 </cell>
18675 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18676 \begin_inset Text
18677
18678 \layout Standard
18679
18680
18681 \family roman
18682 \series medium
18683 \shape up
18684 \size normal
18685 \emph off
18686 \bar no
18687 \noun off
18688 \color none
18689 HIGH priority interrupts
18690 \end_inset
18691 </cell>
18692 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18693 \begin_inset Text
18694
18695 \layout Standard
18696
18697 0x000008
18698 \end_inset
18699 </cell>
18700 </row>
18701 <row topline="true" bottomline="true">
18702 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18703 \begin_inset Text
18704
18705 \layout Standard
18706
18707 2
18708 \end_inset
18709 </cell>
18710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18711 \begin_inset Text
18712
18713 \layout Standard
18714
18715 LOW priority interrupts
18716 \end_inset
18717 </cell>
18718 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18719 \begin_inset Text
18720
18721 \layout Standard
18722
18723 0x000018
18724 \end_inset
18725 </cell>
18726 </row>
18727 </lyxtabular>
18728
18729 \end_inset
18730
18731
18732 \layout Standard
18733
18734 When generating assembly code for ISR the code generator places a
18735 \noun on
18736 goto
18737 \noun default
18738 instruction at the
18739 \emph on
18740 Interrupt Vector Address
18741 \emph default
18742  which points at the genetated ISR.
18743  This single GOTO instruction is part of an automatically generated
18744 \emph on
18745 interrupt entry point
18746 \emph default
18747  function.
18748  The actuall ISR code is placed as normally would in the code space.
18749  Upon interrupt request, the GOTO instruction is executed which jumps to
18750  the ISR code.
18751  When declaring interrupt functions as _naked this GOTO instruction is
18752 \series bold
18753 not
18754 \series default
18755  generated.
18756  The whole interrupt functions is therefore placed at the Interrupt Vector
18757  Address of the specific interrupt.
18758  This is not a problem for the LOW priority interrupts, but it is a problem
18759  for the RESET and the HIGH priority interrupts because code may be written
18760  at the next interrupt´s vector address and cause undeterminate program
18761  behaviour if that interrupt is raised.
18762 \begin_inset Foot
18763 collapsed false
18764
18765 \layout Standard
18766
18767 This is not a problem when
18768 \layout Enumerate
18769
18770 this is a HIGH interrupt ISR and LOW interrupts are
18771 \emph on
18772 disabled
18773 \emph default
18774  or not used.
18775 \layout Enumerate
18776
18777 when the ISR is small enough not to reach the next interrupt´s vector address.
18778 \end_inset
18779
18780
18781 \layout Standard
18782
18783
18784 \emph on
18785 n
18786 \emph default
18787  is possible to be omitted.
18788  This way a function is generated similar to an ISR, but it is not assigned
18789  to any interrupt.
18790 \layout Standard
18791
18792 When entering an interrupt, currently the PIC16
18793 \begin_inset LatexCommand \index{PIC16}
18794
18795 \end_inset
18796
18797  port automatically saves the following registers:
18798 \layout Itemize
18799
18800 WREG
18801 \layout Itemize
18802
18803 STATUS
18804 \layout Itemize
18805
18806 BSR
18807 \layout Itemize
18808
18809 PROD (PRODL and PRODH)
18810 \layout Itemize
18811
18812 FSR0 (FSR0L and FSR0H)
18813 \layout Standard
18814
18815 These registers are restored upon return from the interrupt routine.
18816 \begin_inset Foot
18817 collapsed false
18818
18819 \layout Standard
18820
18821 NOTE that when the _naked attribute is specified for an interrupt routine,
18822  then NO registers are stored or restored.
18823 \end_inset
18824
18825
18826 \layout Subsection
18827
18828 Generic Pointers
18829 \layout Standard
18830
18831 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
18832  There are 3 types of generic pointers currently implemented data, code
18833  and eeprom pointers.
18834  They are differentiated by the value of the 7th and 6th bits of the upper
18835  byte:
18836 \layout Standard
18837 \align center
18838
18839 \begin_inset  Tabular
18840 <lyxtabular version="3" rows="5" columns="5">
18841 <features>
18842 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18843 <column alignment="center" valignment="top" width="0">
18844 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18845 <column alignment="center" valignment="top" width="0">
18846 <column alignment="left" valignment="top" rightline="true" width="0">
18847 <row topline="true" bottomline="true">
18848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18849 \begin_inset Text
18850
18851 \layout Standard
18852
18853 pointer type
18854 \end_inset
18855 </cell>
18856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18857 \begin_inset Text
18858
18859 \layout Standard
18860
18861 7th bit
18862 \end_inset
18863 </cell>
18864 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18865 \begin_inset Text
18866
18867 \layout Standard
18868
18869 6th bit
18870 \end_inset
18871 </cell>
18872 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18873 \begin_inset Text
18874
18875 \layout Standard
18876
18877 rest of the pointer
18878 \end_inset
18879 </cell>
18880 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18881 \begin_inset Text
18882
18883 \layout Standard
18884
18885 descrption
18886 \end_inset
18887 </cell>
18888 </row>
18889 <row topline="true" bottomline="true">
18890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18891 \begin_inset Text
18892
18893 \layout Standard
18894
18895 data
18896 \end_inset
18897 </cell>
18898 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18899 \begin_inset Text
18900
18901 \layout Standard
18902
18903 1
18904 \end_inset
18905 </cell>
18906 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18907 \begin_inset Text
18908
18909 \layout Standard
18910
18911 0
18912 \end_inset
18913 </cell>
18914 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18915 \begin_inset Text
18916
18917 \layout Standard
18918
18919
18920 \family typewriter
18921 \shape slanted
18922 \emph on
18923 uuuuuu uuuuxxxx xxxxxxxx
18924 \end_inset
18925 </cell>
18926 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18927 \begin_inset Text
18928
18929 \layout Standard
18930
18931 a 12-bit data pointer in data RAM memory
18932 \end_inset
18933 </cell>
18934 </row>
18935 <row bottomline="true">
18936 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18937 \begin_inset Text
18938
18939 \layout Standard
18940
18941 code
18942 \end_inset
18943 </cell>
18944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18945 \begin_inset Text
18946
18947 \layout Standard
18948
18949 0
18950 \end_inset
18951 </cell>
18952 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18953 \begin_inset Text
18954
18955 \layout Standard
18956
18957 0
18958 \end_inset
18959 </cell>
18960 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18961 \begin_inset Text
18962
18963 \layout Standard
18964
18965
18966 \family typewriter
18967 \shape slanted
18968 \emph on
18969 uxxxxx xxxxxxxx xxxxxxxx
18970 \end_inset
18971 </cell>
18972 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18973 \begin_inset Text
18974
18975 \layout Standard
18976
18977 a 21-bit code pointer in FLASH memory
18978 \end_inset
18979 </cell>
18980 </row>
18981 <row bottomline="true">
18982 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18983 \begin_inset Text
18984
18985 \layout Standard
18986
18987 eeprom
18988 \end_inset
18989 </cell>
18990 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18991 \begin_inset Text
18992
18993 \layout Standard
18994
18995 0
18996 \end_inset
18997 </cell>
18998 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18999 \begin_inset Text
19000
19001 \layout Standard
19002
19003 1
19004 \end_inset
19005 </cell>
19006 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19007 \begin_inset Text
19008
19009 \layout Standard
19010
19011
19012 \family typewriter
19013 \shape slanted
19014 \emph on
19015 uuuuuu uuuuuuxx xxxxxxxx
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 a 10-bit eeprom pointer in EEPROM memory
19024 \end_inset
19025 </cell>
19026 </row>
19027 <row bottomline="true">
19028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19029 \begin_inset Text
19030
19031 \layout Standard
19032
19033 (unimplemented)
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 1
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 xxxxxx xxxxxxxx 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 unimplemented pointer type
19070 \end_inset
19071 </cell>
19072 </row>
19073 </lyxtabular>
19074
19075 \end_inset
19076
19077
19078 \layout Standard
19079
19080 Generic pointer are read and written with a set of library functions which
19081  read/write 1, 2, 3, 4 bytes.
19082 \layout Subsection
19083
19084 PIC16 C Libraries
19085 \layout Subsubsection
19086
19087 Standard I/O Streams
19088 \layout Standard
19089
19090 In the
19091 \emph on
19092 stdio.h
19093 \emph default
19094  the type FILE is defined as:
19095 \layout LyX-Code
19096
19097 typedef char * FILE;
19098 \layout Standard
19099
19100 This type is the stream type implemented I/O in the PIC18F devices.
19101  Also the standard input and output streams are declared in stdio.h:
19102 \layout LyX-Code
19103
19104 extern FILE * stdin;
19105 \layout LyX-Code
19106
19107 extern FILE * stdout;
19108 \layout Standard
19109
19110 The FILE type is actually a generic pointer which defines one more type
19111  of generic pointers, the
19112 \emph on
19113 stream
19114 \emph default
19115 pointer.
19116  This new type has the format:
19117 \layout Standard
19118 \align center
19119
19120 \begin_inset  Tabular
19121 <lyxtabular version="3" rows="2" columns="7">
19122 <features>
19123 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19124 <column alignment="center" valignment="top" width="0">
19125 <column alignment="center" valignment="top" leftline="true" width="0">
19126 <column alignment="center" valignment="top" leftline="true" width="0">
19127 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19128 <column alignment="center" valignment="top" width="0">
19129 <column alignment="left" valignment="top" rightline="true" width="0">
19130 <row topline="true" bottomline="true">
19131 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19132 \begin_inset Text
19133
19134 \layout Standard
19135
19136 pointer type
19137 \end_inset
19138 </cell>
19139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19140 \begin_inset Text
19141
19142 \layout Standard
19143
19144 <7:6>
19145 \end_inset
19146 </cell>
19147 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19148 \begin_inset Text
19149
19150 \layout Standard
19151
19152 <5>
19153 \end_inset
19154 </cell>
19155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19156 \begin_inset Text
19157
19158 \layout Standard
19159
19160 <4>
19161 \end_inset
19162 </cell>
19163 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19164 \begin_inset Text
19165
19166 \layout Standard
19167
19168 <3:0>
19169 \end_inset
19170 </cell>
19171 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19172 \begin_inset Text
19173
19174 \layout Standard
19175
19176 rest of the pointer
19177 \end_inset
19178 </cell>
19179 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19180 \begin_inset Text
19181
19182 \layout Standard
19183
19184 descrption
19185 \end_inset
19186 </cell>
19187 </row>
19188 <row topline="true" bottomline="true">
19189 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19190 \begin_inset Text
19191
19192 \layout Standard
19193
19194 stream
19195 \end_inset
19196 </cell>
19197 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19198 \begin_inset Text
19199
19200 \layout Standard
19201
19202 00
19203 \end_inset
19204 </cell>
19205 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19206 \begin_inset Text
19207
19208 \layout Standard
19209
19210 1
19211 \end_inset
19212 </cell>
19213 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19214 \begin_inset Text
19215
19216 \layout Standard
19217
19218 0
19219 \end_inset
19220 </cell>
19221 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19222 \begin_inset Text
19223
19224 \layout Standard
19225
19226 nnnn
19227 \end_inset
19228 </cell>
19229 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19230 \begin_inset Text
19231
19232 \layout Standard
19233
19234
19235 \family typewriter
19236 \shape slanted
19237 \emph on
19238 uuuuuuuu uuuuuuuu
19239 \end_inset
19240 </cell>
19241 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19242 \begin_inset Text
19243
19244 \layout Standard
19245
19246 upper byte high nubble is 0x2n, the rest are zeroes
19247 \end_inset
19248 </cell>
19249 </row>
19250 </lyxtabular>
19251
19252 \end_inset
19253
19254
19255 \layout Standard
19256
19257 Currently implemented there are 3 types of streams defined:
19258 \layout Standard
19259 \align center
19260
19261 \begin_inset  Tabular
19262 <lyxtabular version="3" rows="4" columns="4">
19263 <features>
19264 <column alignment="center" valignment="top" leftline="true" width="0">
19265 <column alignment="center" valignment="top" leftline="true" width="0">
19266 <column alignment="center" valignment="top" leftline="true" width="0">
19267 <column alignment="center" valignment="top" leftline="true" 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 stream 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 value
19283 \end_inset
19284 </cell>
19285 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19286 \begin_inset Text
19287
19288 \layout Standard
19289
19290 module
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 description
19299 \end_inset
19300 </cell>
19301 </row>
19302 <row topline="true">
19303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19304 \begin_inset Text
19305
19306 \layout Standard
19307
19308 STREAM_USART
19309 \end_inset
19310 </cell>
19311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19312 \begin_inset Text
19313
19314 \layout Standard
19315
19316
19317 \family typewriter
19318 0x200000UL
19319 \end_inset
19320 </cell>
19321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19322 \begin_inset Text
19323
19324 \layout Standard
19325
19326 USART
19327 \end_inset
19328 </cell>
19329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19330 \begin_inset Text
19331
19332 \layout Standard
19333
19334 Writes/Reads characters via the USART peripheral
19335 \end_inset
19336 </cell>
19337 </row>
19338 <row topline="true">
19339 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19340 \begin_inset Text
19341
19342 \layout Standard
19343
19344 STREAM_MSSP
19345 \end_inset
19346 </cell>
19347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19348 \begin_inset Text
19349
19350 \layout Standard
19351
19352
19353 \family typewriter
19354 0x210000UL
19355 \end_inset
19356 </cell>
19357 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19358 \begin_inset Text
19359
19360 \layout Standard
19361
19362 MSSP
19363 \end_inset
19364 </cell>
19365 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19366 \begin_inset Text
19367
19368 \layout Standard
19369
19370 Writes/Reads characters via the MSSP peripheral
19371 \end_inset
19372 </cell>
19373 </row>
19374 <row topline="true" bottomline="true">
19375 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19376 \begin_inset Text
19377
19378 \layout Standard
19379
19380 STREAM_USER
19381 \end_inset
19382 </cell>
19383 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19384 \begin_inset Text
19385
19386 \layout Standard
19387
19388
19389 \family typewriter
19390 0x2f0000UL
19391 \end_inset
19392 </cell>
19393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19394 \begin_inset Text
19395
19396 \layout Standard
19397
19398 (none)
19399 \end_inset
19400 </cell>
19401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19402 \begin_inset Text
19403
19404 \layout Standard
19405
19406 Writes/Reads characters via used defined functions
19407 \end_inset
19408 </cell>
19409 </row>
19410 </lyxtabular>
19411
19412 \end_inset
19413
19414
19415 \layout Standard
19416
19417 The stream identifiers are declared as macros in the stdio.h header.
19418 \layout Standard
19419
19420 In the libc library there exist the functions that are used to write to
19421  each of the above streams.
19422  These are
19423 \layout List
19424 \labelwidthstring 00.00.0000
19425
19426 _
19427 \begin_inset ERT
19428 status Collapsed
19429
19430 \layout Standard
19431
19432 \backslash
19433 /
19434 \end_inset
19435
19436 _stream_usart_putchar writes a character at the USART stream
19437 \layout List
19438 \labelwidthstring 00.00.0000
19439
19440 _
19441 \begin_inset ERT
19442 status Collapsed
19443
19444 \layout Standard
19445
19446 \backslash
19447 /
19448 \end_inset
19449
19450 _stream_mssp_putchar writes a character at the MSSP stream
19451 \layout List
19452 \labelwidthstring 00.00.0000
19453
19454 putchar dummy function.
19455  This writes a character to a user specified manner.
19456 \layout Standard
19457
19458 In order to increase performance
19459 \emph on
19460 putchar
19461 \emph default
19462 is declared in stdio.h as having its parameter in WREG (it has the wparam
19463  keyword).
19464  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
19465  in a user-friendly way.
19466
19467 \emph on
19468 arg
19469 \emph default
19470  is the name of the variable that holds the character to print.
19471  An example follows:
19472 \layout LyX-Code
19473
19474 #include <pic18fregs.h>
19475 \newline
19476 #include <stdio.h>
19477 \newline
19478
19479 \newline
19480 PUTCHAR( c )
19481 \layout LyX-Code
19482
19483 {
19484 \layout LyX-Code
19485
19486     PORTA = c;    /* dump character c to PORTA */
19487 \layout LyX-Code
19488
19489 }
19490 \newline
19491
19492 \newline
19493 void main(void)
19494 \layout LyX-Code
19495
19496 {
19497 \layout LyX-Code
19498
19499     stdout = STREAM_USER;    /* this is not necessery, since stdout points
19500 \layout LyX-Code
19501
19502                               * by default to STREAM_USER */
19503 \layout LyX-Code
19504
19505     printf (¨This is a printf test
19506 \backslash
19507 n¨);
19508 \layout LyX-Code
19509
19510 }
19511 \layout LyX-Code
19512
19513 \layout Subsubsection
19514
19515 Printing functions
19516 \layout Standard
19517
19518 PIC16 contains an implementation of the printf-family of functions.
19519  There exist the following functions:
19520 \layout LyX-Code
19521
19522 extern unsigned int sprintf(char *buf, char *fmt, ...);
19523 \layout LyX-Code
19524
19525 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
19526 \layout LyX-Code
19527
19528 \layout LyX-Code
19529
19530 extern unsigned int printf(char *fmt, ...);
19531 \layout LyX-Code
19532
19533 extern unsigned int vprintf(char *fmt, va_lista ap);
19534 \layout LyX-Code
19535
19536 \layout LyX-Code
19537
19538 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
19539 \layout LyX-Code
19540
19541 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
19542 \layout Standard
19543
19544 For sprintf and vsprintf
19545 \emph on
19546 buf
19547 \emph default
19548 should normally be a data pointer where the resulting string will be placed.
19549  No range checking is done so the user should allocate the necessery buffer.
19550  For fprintf and vfprintf
19551 \emph on
19552 fp
19553 \emph default
19554  should be a stream pointer (i.e.
19555  stdout, STREAM_MSSP, etc...).
19556 \layout Subsubsection
19557
19558 Signals
19559 \layout Standard
19560
19561 The PIC18F family of microcontrollers supports a number of interrupt sources.
19562  A list of these interrupts is shown in the following table:
19563 \layout Standard
19564 \align center
19565
19566 \begin_inset  Tabular
19567 <lyxtabular version="3" rows="11" columns="4">
19568 <features>
19569 <column alignment="left" valignment="top" leftline="true" width="0">
19570 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19571 <column alignment="left" valignment="top" leftline="true" width="0">
19572 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19573 <row topline="true" bottomline="true">
19574 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19575 \begin_inset Text
19576
19577 \layout Standard
19578
19579 signal name
19580 \end_inset
19581 </cell>
19582 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19583 \begin_inset Text
19584
19585 \layout Standard
19586
19587 description
19588 \end_inset
19589 </cell>
19590 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19591 \begin_inset Text
19592
19593 \layout Standard
19594
19595 signal name
19596 \end_inset
19597 </cell>
19598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19599 \begin_inset Text
19600
19601 \layout Standard
19602
19603 descritpion
19604 \end_inset
19605 </cell>
19606 </row>
19607 <row topline="true">
19608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19609 \begin_inset Text
19610
19611 \layout Standard
19612
19613 SIG_RB
19614 \end_inset
19615 </cell>
19616 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19617 \begin_inset Text
19618
19619 \layout Standard
19620
19621 PORTB change interrupt
19622 \end_inset
19623 </cell>
19624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19625 \begin_inset Text
19626
19627 \layout Standard
19628
19629 SIG_EE
19630 \end_inset
19631 </cell>
19632 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19633 \begin_inset Text
19634
19635 \layout Standard
19636
19637 EEPROM/FLASH write complete interrupt
19638 \end_inset
19639 </cell>
19640 </row>
19641 <row topline="true">
19642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19643 \begin_inset Text
19644
19645 \layout Standard
19646
19647 SIG_INT0
19648 \end_inset
19649 </cell>
19650 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19651 \begin_inset Text
19652
19653 \layout Standard
19654
19655 INT0 external interrupt
19656 \end_inset
19657 </cell>
19658 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19659 \begin_inset Text
19660
19661 \layout Standard
19662
19663 SIG_BCOL
19664 \end_inset
19665 </cell>
19666 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19667 \begin_inset Text
19668
19669 \layout Standard
19670
19671 Bus collision interrupt
19672 \end_inset
19673 </cell>
19674 </row>
19675 <row topline="true">
19676 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19677 \begin_inset Text
19678
19679 \layout Standard
19680
19681 SIG_INT1
19682 \end_inset
19683 </cell>
19684 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19685 \begin_inset Text
19686
19687 \layout Standard
19688
19689 INT1 external interrupt
19690 \end_inset
19691 </cell>
19692 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19693 \begin_inset Text
19694
19695 \layout Standard
19696
19697 SIG_LVD
19698 \end_inset
19699 </cell>
19700 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19701 \begin_inset Text
19702
19703 \layout Standard
19704
19705 Low voltage detect interrupt
19706 \end_inset
19707 </cell>
19708 </row>
19709 <row topline="true">
19710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19711 \begin_inset Text
19712
19713 \layout Standard
19714
19715 SIG_INT2
19716 \end_inset
19717 </cell>
19718 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19719 \begin_inset Text
19720
19721 \layout Standard
19722
19723 INT2 external interrupt
19724 \end_inset
19725 </cell>
19726 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19727 \begin_inset Text
19728
19729 \layout Standard
19730
19731 SIG_PSP
19732 \end_inset
19733 </cell>
19734 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19735 \begin_inset Text
19736
19737 \layout Standard
19738
19739 Parallel slave port interrupt
19740 \end_inset
19741 </cell>
19742 </row>
19743 <row topline="true">
19744 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19745 \begin_inset Text
19746
19747 \layout Standard
19748
19749 SIG_CCP1
19750 \end_inset
19751 </cell>
19752 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19753 \begin_inset Text
19754
19755 \layout Standard
19756
19757 CCP1 module interrupt
19758 \end_inset
19759 </cell>
19760 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19761 \begin_inset Text
19762
19763 \layout Standard
19764
19765 SIG_AD
19766 \end_inset
19767 </cell>
19768 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19769 \begin_inset Text
19770
19771 \layout Standard
19772
19773 AD convertion complete interrupt
19774 \end_inset
19775 </cell>
19776 </row>
19777 <row topline="true">
19778 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19779 \begin_inset Text
19780
19781 \layout Standard
19782
19783 SIG_CCP2
19784 \end_inset
19785 </cell>
19786 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19787 \begin_inset Text
19788
19789 \layout Standard
19790
19791 CCP2 module interrupt
19792 \end_inset
19793 </cell>
19794 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19795 \begin_inset Text
19796
19797 \layout Standard
19798
19799 SIG_RC
19800 \end_inset
19801 </cell>
19802 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19803 \begin_inset Text
19804
19805 \layout Standard
19806
19807 USART receive interrupt
19808 \end_inset
19809 </cell>
19810 </row>
19811 <row topline="true">
19812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19813 \begin_inset Text
19814
19815 \layout Standard
19816
19817 SIG_TMR0
19818 \end_inset
19819 </cell>
19820 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19821 \begin_inset Text
19822
19823 \layout Standard
19824
19825 TMR0 overflow interrupt
19826 \end_inset
19827 </cell>
19828 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19829 \begin_inset Text
19830
19831 \layout Standard
19832
19833 SIG_TX
19834 \end_inset
19835 </cell>
19836 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19837 \begin_inset Text
19838
19839 \layout Standard
19840
19841 USART transmit interrupt
19842 \end_inset
19843 </cell>
19844 </row>
19845 <row topline="true">
19846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19847 \begin_inset Text
19848
19849 \layout Standard
19850
19851 SIG_TMR1
19852 \end_inset
19853 </cell>
19854 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19855 \begin_inset Text
19856
19857 \layout Standard
19858
19859 TMR1 overflow interrupt
19860 \end_inset
19861 </cell>
19862 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19863 \begin_inset Text
19864
19865 \layout Standard
19866
19867 SIG_MSSP
19868 \end_inset
19869 </cell>
19870 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19871 \begin_inset Text
19872
19873 \layout Standard
19874
19875 SSP receive/transmit interrupt
19876 \end_inset
19877 </cell>
19878 </row>
19879 <row topline="true">
19880 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19881 \begin_inset Text
19882
19883 \layout Standard
19884
19885 SIG_TMR2
19886 \end_inset
19887 </cell>
19888 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19889 \begin_inset Text
19890
19891 \layout Standard
19892
19893 TMR2 matches PR2 interrupt
19894 \end_inset
19895 </cell>
19896 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19897 \begin_inset Text
19898
19899 \layout Standard
19900
19901 \end_inset
19902 </cell>
19903 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19904 \begin_inset Text
19905
19906 \layout Standard
19907
19908 \end_inset
19909 </cell>
19910 </row>
19911 <row topline="true" bottomline="true">
19912 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19913 \begin_inset Text
19914
19915 \layout Standard
19916
19917 SIG_TMR3
19918 \end_inset
19919 </cell>
19920 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19921 \begin_inset Text
19922
19923 \layout Standard
19924
19925 TMR3 overflow interrupt
19926 \end_inset
19927 </cell>
19928 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19929 \begin_inset Text
19930
19931 \layout Standard
19932
19933 \end_inset
19934 </cell>
19935 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19936 \begin_inset Text
19937
19938 \layout Standard
19939
19940 \end_inset
19941 </cell>
19942 </row>
19943 </lyxtabular>
19944
19945 \end_inset
19946
19947
19948 \layout Standard
19949
19950 The prototypes for these names are defined in the header file
19951 \emph on
19952 signal.h
19953 \emph default
19954  .
19955 \layout Standard
19956
19957 In order to simplify signal handling, a number of macros is provided:
19958 \layout List
19959 \labelwidthstring 00.00.0000
19960
19961 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
19962  high priority interrupts.
19963
19964 \emph on
19965 name
19966 \emph default
19967  is the function name to use.
19968 \layout List
19969 \labelwidthstring 00.00.0000
19970
19971 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
19972  low priority interrupt.
19973
19974 \emph on
19975 name
19976 \emph default
19977  is the function name to use.
19978 \layout List
19979 \labelwidthstring 00.00.0000
19980
19981 DEF_HANDLER(sig,handler) define a handler for signal
19982 \emph on
19983 sig.
19984 \layout List
19985 \labelwidthstring 00.00.0000
19986
19987 END_DEF end the declaration of the dispatch table.
19988 \layout Standard
19989
19990 Additionally there are two more macros to simplify the declaration of the
19991  signal handler:
19992 \layout List
19993 \labelwidthstring 00.00.0000
19994
19995
19996 \series medium
19997 SIGHANDLER(handler)
19998 \series default
19999 this declares the function prototype for the
20000 \emph on
20001 handler
20002 \emph default
20003  function.
20004 \layout List
20005 \labelwidthstring 00.00.0000
20006
20007 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
20008 \layout Standard
20009
20010 An example of using the macros above is shown below:
20011 \layout LyX-Code
20012
20013 #include <pic18fregs.h>
20014 \layout LyX-Code
20015
20016 #include <signal.h>
20017 \newline
20018
20019 \newline
20020 DEF_INTHIGH(high_int)
20021 \layout LyX-Code
20022
20023 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
20024 \layout LyX-Code
20025
20026 DEF_HANDLER(SIG_BCOL, _bcol_handler)
20027 \layout LyX-Code
20028
20029 END_DEF
20030 \newline
20031
20032 \newline
20033 SIGHANDLER(_tmr0_handler)
20034 \layout LyX-Code
20035
20036 {
20037 \layout LyX-Code
20038
20039   /* action to be taken when timer 0 overflows */
20040 \layout LyX-Code
20041
20042 }
20043 \newline
20044
20045 \newline
20046 SIGHANDLERNAKED(_bcol_handler)
20047 \layout LyX-Code
20048
20049 {
20050 \layout LyX-Code
20051
20052   _asm
20053 \layout LyX-Code
20054
20055     /* action to be taken when bus collision occurs */
20056 \layout LyX-Code
20057
20058     retfie
20059 \layout LyX-Code
20060
20061  _endasm;
20062 \layout LyX-Code
20063
20064 }
20065 \layout Standard
20066
20067
20068 \series bold
20069 NOTES:
20070 \series default
20071  Special care should be taken when using the above scheme:
20072 \layout Itemize
20073
20074 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
20075 \layout Itemize
20076
20077 when declaring SIGHANDLERNAKED handler never forget to use
20078 \emph on
20079 retfie
20080 \emph default
20081  for proper returning.
20082 \layout Subsection
20083
20084 PIC16 Port -- Tips
20085 \layout Standard
20086
20087 Here you can find some general tips for compiling programs with SDCC/pic16.
20088 \layout Subsubsection
20089
20090 Stack size
20091 \layout Standard
20092
20093 The default stack size (that is 64 bytes) probably is enough for many programs.
20094  One must take care that when there are many levels of function nesting,
20095  or there is excessive usage of stack, its size should be extended.
20096  An example of such a case is the printf/sprintf family of functions.
20097  If you encounter problems like not being able to print integers, then you
20098  need to set the stack size around the maximum (256 for small stack model).
20099  The following diagram shows what happens when calling printf to print an
20100  integer:
20101 \layout LyX-Code
20102
20103 printf () --> ltoa () --> ultoa () --> divschar ()
20104 \layout Standard
20105
20106 It is should be understood that stack is easily consumed when calling complicate
20107 d functions.
20108  Using command line arguments like -
20109 \begin_inset ERT
20110 status Collapsed
20111
20112 \layout Standard
20113
20114 \backslash
20115 /
20116 \end_inset
20117
20118 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
20119  stack frames.
20120  Other ways to reduce stack usage may exist.
20121 \layout Chapter
20122
20123 Debugging with SDCDB
20124 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
20125
20126 \end_inset
20127
20128
20129 \begin_inset LatexCommand \index{sdcdb (debugger)}
20130
20131 \end_inset
20132
20133
20134 \layout Standard
20135
20136 SDCC is distributed with a source level debugger
20137 \begin_inset LatexCommand \index{Debugger}
20138
20139 \end_inset
20140
20141 .
20142  The debugger uses a command line interface, the command repertoire of the
20143  debugger has been kept as close to gdb
20144 \begin_inset LatexCommand \index{gdb}
20145
20146 \end_inset
20147
20148  (the GNU debugger) as possible.
20149  The configuration and build process is part of the standard compiler installati
20150 on, which also builds and installs the debugger in the target directory
20151  specified during configuration.
20152  The debugger allows you debug BOTH at the C source and at the ASM source
20153  level.
20154  Sdcdb is currently not available on Win32 platforms.
20155 \layout Section
20156
20157 Compiling for Debugging
20158 \layout Standard
20159
20160 The -
20161 \begin_inset ERT
20162 status Collapsed
20163
20164 \layout Standard
20165
20166 \backslash
20167 /
20168 \end_inset
20169
20170 -debug
20171 \begin_inset LatexCommand \index{-\/-debug}
20172
20173 \end_inset
20174
20175  option must be specified for all files for which debug information is to
20176  be generated.
20177  The complier generates a .adb file for each of these files.
20178  The linker creates the .cdb
20179 \begin_inset LatexCommand \index{<file>.cdb}
20180
20181 \end_inset
20182
20183  file from the .adb
20184 \begin_inset LatexCommand \index{<file>.adb}
20185
20186 \end_inset
20187
20188  files and the address information.
20189  This .cdb is used by the debugger.
20190 \layout Section
20191
20192 How the Debugger Works
20193 \layout Standard
20194
20195 When the -
20196 \begin_inset ERT
20197 status Collapsed
20198
20199 \layout Standard
20200
20201 \backslash
20202 /
20203 \end_inset
20204
20205 -debug option is specified the compiler generates extra symbol information
20206  some of which are put into the assembler source and some are put into the
20207  .adb file.
20208   Then the linker creates the .cdb file from the individual .adb files with
20209  the address information for the symbols.
20210  The debugger reads the symbolic information generated by the compiler &
20211  the address information generated by the linker.
20212  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
20213  execution is controlled by the debugger.
20214  When a command is issued for the debugger, it translates it into appropriate
20215  commands for the simulator.
20216 \layout Section
20217
20218 Starting the Debugger
20219 \layout Standard
20220
20221 The debugger can be started using the following command line.
20222  (Assume the file you are debugging has the file name foo).
20223 \newline
20224
20225 \newline
20226
20227 \family sans
20228 \series bold
20229 sdcdb foo
20230 \newline
20231
20232 \family default
20233 \series default
20234
20235 \newline
20236 The debugger will look for the following files.
20237 \layout Itemize
20238
20239 foo.c - the source file.
20240 \layout Itemize
20241
20242 foo.cdb - the debugger symbol information file.
20243 \layout Itemize
20244
20245 foo.ihx - the Intel hex format
20246 \begin_inset LatexCommand \index{Intel hex format}
20247
20248 \end_inset
20249
20250  object file.
20251 \layout Section
20252
20253 Command Line Options
20254 \layout Itemize
20255
20256 -
20257 \begin_inset ERT
20258 status Collapsed
20259
20260 \layout Standard
20261
20262 \backslash
20263 /
20264 \end_inset
20265
20266 -directory=<source file directory> this option can used to specify the directory
20267  search list.
20268  The debugger will look into the directory list specified for source, cdb
20269  & ihx files.
20270  The items in the directory list must be separated by ':', e.g.
20271  if the source files can be in the directories /home/src1 and /home/src2,
20272  the -
20273 \begin_inset ERT
20274 status Collapsed
20275
20276 \layout Standard
20277
20278 \backslash
20279 /
20280 \end_inset
20281
20282 -directory option should be -
20283 \begin_inset ERT
20284 status Collapsed
20285
20286 \layout Standard
20287
20288 \backslash
20289 /
20290 \end_inset
20291
20292 -directory=/home/src1:/home/src2.
20293  Note there can be no spaces in the option.
20294
20295 \layout Itemize
20296
20297 -cd <directory> - change to the <directory>.
20298 \layout Itemize
20299
20300 -fullname - used by GUI front ends.
20301 \layout Itemize
20302
20303 -cpu <cpu-type> - this argument is passed to the simulator please see the
20304  simulator docs for details.
20305 \layout Itemize
20306
20307 -X <Clock frequency > this options is passed to the simulator please see
20308  the simulator docs for details.
20309 \layout Itemize
20310
20311 -s <serial port file> passed to simulator see the simulator docs for details.
20312 \layout Itemize
20313
20314 -S <serial in,out> passed to simulator see the simulator docs for details.
20315 \layout Itemize
20316
20317 -k <port number> passed to simulator see the simulator docs for details.
20318 \layout Section
20319
20320 Debugger Commands
20321 \layout Standard
20322
20323 As mentioned earlier the command interface for the debugger has been deliberatel
20324 y kept as close the GNU debugger gdb, as possible.
20325  This will help the integration with existing graphical user interfaces
20326  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
20327  If you use a graphical user interface for the debugger you can skip this
20328  section.
20329 \layout Subsubsection*
20330
20331 break [line | file:line | function | file:function]
20332 \layout Standard
20333
20334 Set breakpoint at specified line or function:
20335 \newline
20336
20337 \newline
20338
20339 \family sans
20340 \series bold
20341 sdcdb>break 100
20342 \newline
20343 sdcdb>break foo.c:100
20344 \newline
20345 sdcdb>break funcfoo
20346 \newline
20347 sdcdb>break foo.c:funcfoo
20348 \layout Subsubsection*
20349
20350 clear [line | file:line | function | file:function ]
20351 \layout Standard
20352
20353 Clear breakpoint at specified line or function:
20354 \newline
20355
20356 \newline
20357
20358 \family sans
20359 \series bold
20360 sdcdb>clear 100
20361 \newline
20362 sdcdb>clear foo.c:100
20363 \newline
20364 sdcdb>clear funcfoo
20365 \newline
20366 sdcdb>clear foo.c:funcfoo
20367 \layout Subsubsection*
20368
20369 continue
20370 \layout Standard
20371
20372 Continue program being debugged, after breakpoint.
20373 \layout Subsubsection*
20374
20375 finish
20376 \layout Standard
20377
20378 Execute till the end of the current function.
20379 \layout Subsubsection*
20380
20381 delete [n]
20382 \layout Standard
20383
20384 Delete breakpoint number 'n'.
20385  If used without any option clear ALL user defined break points.
20386 \layout Subsubsection*
20387
20388 info [break | stack | frame | registers ]
20389 \layout Itemize
20390
20391 info break - list all breakpoints
20392 \layout Itemize
20393
20394 info stack - show the function call stack.
20395 \layout Itemize
20396
20397 info frame - show information about the current execution frame.
20398 \layout Itemize
20399
20400 info registers - show content of all registers.
20401 \layout Subsubsection*
20402
20403 step
20404 \layout Standard
20405
20406 Step program until it reaches a different source line.
20407  Note: pressing <return> repeats the last command.
20408 \layout Subsubsection*
20409
20410 next
20411 \layout Standard
20412
20413 Step program, proceeding through subroutine calls.
20414 \layout Subsubsection*
20415
20416 run
20417 \layout Standard
20418
20419 Start debugged program.
20420 \layout Subsubsection*
20421
20422 ptype variable
20423 \layout Standard
20424
20425 Print type information of the variable.
20426 \layout Subsubsection*
20427
20428 print variable
20429 \layout Standard
20430
20431 print value of variable.
20432 \layout Subsubsection*
20433
20434 file filename
20435 \layout Standard
20436
20437 load the given file name.
20438  Note this is an alternate method of loading file for debugging.
20439 \layout Subsubsection*
20440
20441 frame
20442 \layout Standard
20443
20444 print information about current frame.
20445 \layout Subsubsection*
20446
20447 set srcmode
20448 \layout Standard
20449
20450 Toggle between C source & assembly source.
20451 \layout Subsubsection*
20452
20453 ! simulator command
20454 \layout Standard
20455
20456 Send the string following '!' to the simulator, the simulator response is
20457  displayed.
20458  Note the debugger does not interpret the command being sent to the simulator,
20459  so if a command like 'go' is sent the debugger can loose its execution
20460  context and may display incorrect values.
20461 \layout Subsubsection*
20462
20463 quit
20464 \layout Standard
20465
20466 "Watch me now.
20467  Iam going Down.
20468  My name is Bobby Brown"
20469 \layout Section
20470
20471 Interfacing with DDD
20472 \layout Comment
20473
20474 The screenshot was converted from png to eps with:
20475 \begin_inset Quotes sld
20476 \end_inset
20477
20478 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
20479 \begin_inset Quotes srd
20480 \end_inset
20481
20482  which produces a pretty compact eps file which is free from compression
20483  artifacts.
20484 \layout Comment
20485
20486 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
20487  as this broke the build system on Sourceforge (pdf-file was broken).
20488 \layout Standard
20489
20490 The .eps File
20491 \size footnotesize
20492
20493 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.eps}
20494
20495 \end_inset
20496
20497
20498 \size default
20499  shows a screenshot of a debugging session with DDD
20500 \begin_inset LatexCommand \index{DDD (debugger)}
20501
20502 \end_inset
20503
20504  (Unix only) on a simulated 8032.
20505  The debugging session might not run as smoothly as the screenshot suggests.
20506  The debugger allows setting of breakpoints, displaying and changing variables,
20507  single stepping through C and assembler code.
20508
20509 \newline
20510 The source was compiled with
20511 \family sans
20512 \series bold
20513
20514 \newline
20515
20516 \newline
20517 sdcc -
20518 \family default
20519 \series default
20520
20521 \begin_inset ERT
20522 status Collapsed
20523
20524 \layout Standard
20525
20526 \backslash
20527 /
20528 \end_inset
20529
20530
20531 \family sans
20532 \series bold
20533 -debug ddd_example.c
20534 \family default
20535 \series default
20536
20537 \family sans
20538 \series bold
20539
20540 \newline
20541
20542 \family default
20543 \series default
20544
20545 \newline
20546 and DDD was invoked with
20547 \family sans
20548 \series bold
20549
20550 \newline
20551
20552 \newline
20553 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
20554 \layout Section
20555
20556 Interfacing with XEmacs
20557 \begin_inset LatexCommand \index{XEmacs}
20558
20559 \end_inset
20560
20561
20562 \begin_inset LatexCommand \index{Emacs}
20563
20564 \end_inset
20565
20566
20567 \layout Standard
20568
20569 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
20570  sdcdb.el and sdcdbsrc.el.
20571  These two files can be found in the $(prefix)/bin directory after the installat
20572 ion is complete.
20573  These files need to be loaded into XEmacs for the interface to work.
20574  This can be done at XEmacs startup time by inserting the following into
20575  your '.xemacs' file (which can be found in your HOME directory):
20576 \newline
20577
20578 \newline
20579
20580 \family typewriter
20581 (load-file sdcdbsrc.el)
20582 \family default
20583
20584 \newline
20585
20586 \newline
20587 .xemacs is a lisp file so the () around the command is REQUIRED.
20588  The files can also be loaded dynamically while XEmacs is running, set the
20589  environment variable 'EMACSLOADPATH' to the installation bin directory
20590  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
20591  To start the interface enter the following command:
20592 \newline
20593
20594 \newline
20595
20596 \family sans
20597 \series bold
20598 ESC-x sdcdbsrc
20599 \family default
20600 \series default
20601
20602 \newline
20603
20604 \newline
20605 You will prompted to enter the file name to be debugged.
20606
20607 \newline
20608
20609 \newline
20610 The command line options that are passed to the simulator directly are bound
20611  to default values in the file sdcdbsrc.el.
20612  The variables are listed below, these values maybe changed as required.
20613 \layout Itemize
20614
20615 sdcdbsrc-cpu-type '51
20616 \layout Itemize
20617
20618 sdcdbsrc-frequency '11059200
20619 \layout Itemize
20620
20621 sdcdbsrc-serial nil
20622 \layout Standard
20623
20624 The following is a list of key mapping for the debugger interface.
20625 \layout Standard
20626
20627 \SpecialChar ~
20628
20629 \family typewriter
20630
20631 \newline
20632 ;;\SpecialChar ~
20633 Current Listing ::
20634 \newline
20635 ;;key\SpecialChar ~
20636 \SpecialChar ~
20637 \SpecialChar ~
20638 \SpecialChar ~
20639 \SpecialChar ~
20640 \SpecialChar ~
20641 \SpecialChar ~
20642 \SpecialChar ~
20643 \SpecialChar ~
20644 \SpecialChar ~
20645 \SpecialChar ~
20646 \SpecialChar ~
20647 \SpecialChar ~
20648 \SpecialChar ~
20649 binding\SpecialChar ~
20650 \SpecialChar ~
20651 \SpecialChar ~
20652 \SpecialChar ~
20653 \SpecialChar ~
20654 \SpecialChar ~
20655 \SpecialChar ~
20656 \SpecialChar ~
20657 \SpecialChar ~
20658 \SpecialChar ~
20659 \SpecialChar ~
20660 \SpecialChar ~
20661 \SpecialChar ~
20662 \SpecialChar ~
20663 \SpecialChar ~
20664 \SpecialChar ~
20665 \SpecialChar ~
20666 \SpecialChar ~
20667 \SpecialChar ~
20668 \SpecialChar ~
20669 \SpecialChar ~
20670 \SpecialChar ~
20671 Comment
20672 \newline
20673 ;;---\SpecialChar ~
20674 \SpecialChar ~
20675 \SpecialChar ~
20676 \SpecialChar ~
20677 \SpecialChar ~
20678 \SpecialChar ~
20679 \SpecialChar ~
20680 \SpecialChar ~
20681 \SpecialChar ~
20682 \SpecialChar ~
20683 \SpecialChar ~
20684 \SpecialChar ~
20685 \SpecialChar ~
20686 \SpecialChar ~
20687 -------\SpecialChar ~
20688 \SpecialChar ~
20689 \SpecialChar ~
20690 \SpecialChar ~
20691 \SpecialChar ~
20692 \SpecialChar ~
20693 \SpecialChar ~
20694 \SpecialChar ~
20695 \SpecialChar ~
20696 \SpecialChar ~
20697 \SpecialChar ~
20698 \SpecialChar ~
20699 \SpecialChar ~
20700 \SpecialChar ~
20701 \SpecialChar ~
20702 \SpecialChar ~
20703 \SpecialChar ~
20704 \SpecialChar ~
20705 \SpecialChar ~
20706 \SpecialChar ~
20707 \SpecialChar ~
20708 \SpecialChar ~
20709 -------
20710 \newline
20711 ;;
20712 \newline
20713 ;;\SpecialChar ~
20714 n\SpecialChar ~
20715 \SpecialChar ~
20716 \SpecialChar ~
20717 \SpecialChar ~
20718 \SpecialChar ~
20719 \SpecialChar ~
20720 \SpecialChar ~
20721 \SpecialChar ~
20722 \SpecialChar ~
20723 \SpecialChar ~
20724 \SpecialChar ~
20725 \SpecialChar ~
20726 \SpecialChar ~
20727 \SpecialChar ~
20728 \SpecialChar ~
20729 sdcdb-next-from-src\SpecialChar ~
20730 \SpecialChar ~
20731 \SpecialChar ~
20732 \SpecialChar ~
20733 \SpecialChar ~
20734 \SpecialChar ~
20735 \SpecialChar ~
20736 \SpecialChar ~
20737 \SpecialChar ~
20738 \SpecialChar ~
20739 SDCDB next command
20740 \newline
20741 ;;\SpecialChar ~
20742 b\SpecialChar ~
20743 \SpecialChar ~
20744 \SpecialChar ~
20745 \SpecialChar ~
20746 \SpecialChar ~
20747 \SpecialChar ~
20748 \SpecialChar ~
20749 \SpecialChar ~
20750 \SpecialChar ~
20751 \SpecialChar ~
20752 \SpecialChar ~
20753 \SpecialChar ~
20754 \SpecialChar ~
20755 \SpecialChar ~
20756 \SpecialChar ~
20757 sdcdb-back-from-src\SpecialChar ~
20758 \SpecialChar ~
20759 \SpecialChar ~
20760 \SpecialChar ~
20761 \SpecialChar ~
20762 \SpecialChar ~
20763 \SpecialChar ~
20764 \SpecialChar ~
20765 \SpecialChar ~
20766 \SpecialChar ~
20767 SDCDB back command
20768 \newline
20769 ;;\SpecialChar ~
20770 c\SpecialChar ~
20771 \SpecialChar ~
20772 \SpecialChar ~
20773 \SpecialChar ~
20774 \SpecialChar ~
20775 \SpecialChar ~
20776 \SpecialChar ~
20777 \SpecialChar ~
20778 \SpecialChar ~
20779 \SpecialChar ~
20780 \SpecialChar ~
20781 \SpecialChar ~
20782 \SpecialChar ~
20783 \SpecialChar ~
20784 \SpecialChar ~
20785 sdcdb-cont-from-src\SpecialChar ~
20786 \SpecialChar ~
20787 \SpecialChar ~
20788 \SpecialChar ~
20789 \SpecialChar ~
20790 \SpecialChar ~
20791 \SpecialChar ~
20792 \SpecialChar ~
20793 \SpecialChar ~
20794 \SpecialChar ~
20795 SDCDB continue command
20796 \newline
20797 ;;\SpecialChar ~
20798 s\SpecialChar ~
20799 \SpecialChar ~
20800 \SpecialChar ~
20801 \SpecialChar ~
20802 \SpecialChar ~
20803 \SpecialChar ~
20804 \SpecialChar ~
20805 \SpecialChar ~
20806 \SpecialChar ~
20807 \SpecialChar ~
20808 \SpecialChar ~
20809 \SpecialChar ~
20810 \SpecialChar ~
20811 \SpecialChar ~
20812 \SpecialChar ~
20813 sdcdb-step-from-src\SpecialChar ~
20814 \SpecialChar ~
20815 \SpecialChar ~
20816 \SpecialChar ~
20817 \SpecialChar ~
20818 \SpecialChar ~
20819 \SpecialChar ~
20820 \SpecialChar ~
20821 \SpecialChar ~
20822 \SpecialChar ~
20823 SDCDB step command
20824 \newline
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 sdcdb-whatis-c-sexp\SpecialChar ~
20842 \SpecialChar ~
20843 \SpecialChar ~
20844 \SpecialChar ~
20845 \SpecialChar ~
20846 \SpecialChar ~
20847 \SpecialChar ~
20848 \SpecialChar ~
20849 \SpecialChar ~
20850 \SpecialChar ~
20851 SDCDB ptypecommand for data at
20852 \newline
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 \SpecialChar ~
20868 \SpecialChar ~
20869 \SpecialChar ~
20870 \SpecialChar ~
20871 \SpecialChar ~
20872 \SpecialChar ~
20873 \SpecialChar ~
20874 \SpecialChar ~
20875 \SpecialChar ~
20876 \SpecialChar ~
20877 \SpecialChar ~
20878 \SpecialChar ~
20879 \SpecialChar ~
20880 \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 \SpecialChar ~
20896 \SpecialChar ~
20897 \SpecialChar ~
20898 \SpecialChar ~
20899 \SpecialChar ~
20900 buffer point
20901 \newline
20902 ;;\SpecialChar ~
20903 x\SpecialChar ~
20904 \SpecialChar ~
20905 \SpecialChar ~
20906 \SpecialChar ~
20907 \SpecialChar ~
20908 \SpecialChar ~
20909 \SpecialChar ~
20910 \SpecialChar ~
20911 \SpecialChar ~
20912 \SpecialChar ~
20913 \SpecialChar ~
20914 \SpecialChar ~
20915 \SpecialChar ~
20916 \SpecialChar ~
20917 \SpecialChar ~
20918 sdcdbsrc-delete\SpecialChar ~
20919 \SpecialChar ~
20920 \SpecialChar ~
20921 \SpecialChar ~
20922 \SpecialChar ~
20923 \SpecialChar ~
20924 \SpecialChar ~
20925 \SpecialChar ~
20926 \SpecialChar ~
20927 \SpecialChar ~
20928 \SpecialChar ~
20929 \SpecialChar ~
20930 \SpecialChar ~
20931 \SpecialChar ~
20932 SDCDB Delete all breakpoints if no arg
20933 \newline
20934 ;;\SpecialChar ~
20935 \SpecialChar ~
20936 \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 \SpecialChar ~
20952 \SpecialChar ~
20953 \SpecialChar ~
20954 \SpecialChar ~
20955 \SpecialChar ~
20956 \SpecialChar ~
20957 \SpecialChar ~
20958 \SpecialChar ~
20959 \SpecialChar ~
20960 \SpecialChar ~
20961 \SpecialChar ~
20962 \SpecialChar ~
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 \SpecialChar ~
20980 \SpecialChar ~
20981 given or delete arg (C-u arg x)
20982 \newline
20983 ;;\SpecialChar ~
20984 m\SpecialChar ~
20985 \SpecialChar ~
20986 \SpecialChar ~
20987 \SpecialChar ~
20988 \SpecialChar ~
20989 \SpecialChar ~
20990 \SpecialChar ~
20991 \SpecialChar ~
20992 \SpecialChar ~
20993 \SpecialChar ~
20994 \SpecialChar ~
20995 \SpecialChar ~
20996 \SpecialChar ~
20997 \SpecialChar ~
20998 \SpecialChar ~
20999 sdcdbsrc-frame\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 SDCDB Display current frame if no arg,
21015 \newline
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 \SpecialChar ~
21039 \SpecialChar ~
21040 \SpecialChar ~
21041 \SpecialChar ~
21042 \SpecialChar ~
21043 \SpecialChar ~
21044 \SpecialChar ~
21045 \SpecialChar ~
21046 \SpecialChar ~
21047 \SpecialChar ~
21048 \SpecialChar ~
21049 \SpecialChar ~
21050 \SpecialChar ~
21051 \SpecialChar ~
21052 \SpecialChar ~
21053 \SpecialChar ~
21054 \SpecialChar ~
21055 \SpecialChar ~
21056 \SpecialChar ~
21057 \SpecialChar ~
21058 \SpecialChar ~
21059 \SpecialChar ~
21060 \SpecialChar ~
21061 \SpecialChar ~
21062 \SpecialChar ~
21063 given or display frame arg
21064 \newline
21065 ;;\SpecialChar ~
21066 \SpecialChar ~
21067 \SpecialChar ~
21068 \SpecialChar ~
21069 \SpecialChar ~
21070 \SpecialChar ~
21071 \SpecialChar ~
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 buffer point
21113 \newline
21114 ;;\SpecialChar ~
21115 !\SpecialChar ~
21116 \SpecialChar ~
21117 \SpecialChar ~
21118 \SpecialChar ~
21119 \SpecialChar ~
21120 \SpecialChar ~
21121 \SpecialChar ~
21122 \SpecialChar ~
21123 \SpecialChar ~
21124 \SpecialChar ~
21125 \SpecialChar ~
21126 \SpecialChar ~
21127 \SpecialChar ~
21128 \SpecialChar ~
21129 \SpecialChar ~
21130 sdcdbsrc-goto-sdcdb\SpecialChar ~
21131 \SpecialChar ~
21132 \SpecialChar ~
21133 \SpecialChar ~
21134 \SpecialChar ~
21135 \SpecialChar ~
21136 \SpecialChar ~
21137 \SpecialChar ~
21138 \SpecialChar ~
21139 \SpecialChar ~
21140 Goto the SDCDB output buffer
21141 \newline
21142 ;;\SpecialChar ~
21143 p\SpecialChar ~
21144 \SpecialChar ~
21145 \SpecialChar ~
21146 \SpecialChar ~
21147 \SpecialChar ~
21148 \SpecialChar ~
21149 \SpecialChar ~
21150 \SpecialChar ~
21151 \SpecialChar ~
21152 \SpecialChar ~
21153 \SpecialChar ~
21154 \SpecialChar ~
21155 \SpecialChar ~
21156 \SpecialChar ~
21157 \SpecialChar ~
21158 sdcdb-print-c-sexp\SpecialChar ~
21159 \SpecialChar ~
21160 \SpecialChar ~
21161 \SpecialChar ~
21162 \SpecialChar ~
21163 \SpecialChar ~
21164 \SpecialChar ~
21165 \SpecialChar ~
21166 \SpecialChar ~
21167 \SpecialChar ~
21168 \SpecialChar ~
21169 SDCDB print command for data at
21170 \newline
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 \SpecialChar ~
21202 \SpecialChar ~
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 buffer point
21219 \newline
21220 ;;\SpecialChar ~
21221 g\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 sdcdbsrc-goto-sdcdb\SpecialChar ~
21237 \SpecialChar ~
21238 \SpecialChar ~
21239 \SpecialChar ~
21240 \SpecialChar ~
21241 \SpecialChar ~
21242 \SpecialChar ~
21243 \SpecialChar ~
21244 \SpecialChar ~
21245 \SpecialChar ~
21246 Goto the SDCDB output buffer
21247 \newline
21248 ;;\SpecialChar ~
21249 t\SpecialChar ~
21250 \SpecialChar ~
21251 \SpecialChar ~
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 sdcdbsrc-mode\SpecialChar ~
21265 \SpecialChar ~
21266 \SpecialChar ~
21267 \SpecialChar ~
21268 \SpecialChar ~
21269 \SpecialChar ~
21270 \SpecialChar ~
21271 \SpecialChar ~
21272 \SpecialChar ~
21273 \SpecialChar ~
21274 \SpecialChar ~
21275 \SpecialChar ~
21276 \SpecialChar ~
21277 \SpecialChar ~
21278 \SpecialChar ~
21279 \SpecialChar ~
21280 Toggles Sdcdbsrc mode (turns it off)
21281 \newline
21282 ;;
21283 \newline
21284 ;;\SpecialChar ~
21285 C-c\SpecialChar ~
21286 C-f\SpecialChar ~
21287 \SpecialChar ~
21288 \SpecialChar ~
21289 \SpecialChar ~
21290 \SpecialChar ~
21291 \SpecialChar ~
21292 \SpecialChar ~
21293 \SpecialChar ~
21294 \SpecialChar ~
21295 sdcdb-finish-from-src\SpecialChar ~
21296 \SpecialChar ~
21297 \SpecialChar ~
21298 \SpecialChar ~
21299 \SpecialChar ~
21300 \SpecialChar ~
21301 \SpecialChar ~
21302 \SpecialChar ~
21303 SDCDB finish command
21304 \newline
21305 ;;
21306 \newline
21307 ;;\SpecialChar ~
21308 C-x\SpecialChar ~
21309 SPC\SpecialChar ~
21310 \SpecialChar ~
21311 \SpecialChar ~
21312 \SpecialChar ~
21313 \SpecialChar ~
21314 \SpecialChar ~
21315 \SpecialChar ~
21316 \SpecialChar ~
21317 \SpecialChar ~
21318 sdcdb-break\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 Set break for line with point
21337 \newline
21338 ;;\SpecialChar ~
21339 ESC\SpecialChar ~
21340 t\SpecialChar ~
21341 \SpecialChar ~
21342 \SpecialChar ~
21343 \SpecialChar ~
21344 \SpecialChar ~
21345 \SpecialChar ~
21346 \SpecialChar ~
21347 \SpecialChar ~
21348 \SpecialChar ~
21349 \SpecialChar ~
21350 \SpecialChar ~
21351 sdcdbsrc-mode\SpecialChar ~
21352 \SpecialChar ~
21353 \SpecialChar ~
21354 \SpecialChar ~
21355 \SpecialChar ~
21356 \SpecialChar ~
21357 \SpecialChar ~
21358 \SpecialChar ~
21359 \SpecialChar ~
21360 \SpecialChar ~
21361 \SpecialChar ~
21362 \SpecialChar ~
21363 \SpecialChar ~
21364 \SpecialChar ~
21365 \SpecialChar ~
21366 \SpecialChar ~
21367 Toggle Sdcdbsrc mode
21368 \newline
21369 ;;\SpecialChar ~
21370 ESC\SpecialChar ~
21371 m\SpecialChar ~
21372 \SpecialChar ~
21373 \SpecialChar ~
21374 \SpecialChar ~
21375 \SpecialChar ~
21376 \SpecialChar ~
21377 \SpecialChar ~
21378 \SpecialChar ~
21379 \SpecialChar ~
21380 \SpecialChar ~
21381 \SpecialChar ~
21382 sdcdbsrc-srcmode\SpecialChar ~
21383 \SpecialChar ~
21384 \SpecialChar ~
21385 \SpecialChar ~
21386 \SpecialChar ~
21387 \SpecialChar ~
21388 \SpecialChar ~
21389 \SpecialChar ~
21390 \SpecialChar ~
21391 \SpecialChar ~
21392 \SpecialChar ~
21393 \SpecialChar ~
21394 \SpecialChar ~
21395 Toggle list mode
21396 \newline
21397 ;;
21398 \newline
21399
21400 \layout Chapter
21401 \pagebreak_top
21402 TIPS
21403 \layout Standard
21404
21405 Here are a few guidelines that will help the compiler generate more efficient
21406  code, some of the tips are specific to this compiler others are generally
21407  good programming practice.
21408 \layout Itemize
21409
21410 Use the smallest data type to represent your data-value.
21411  If it is known in advance that the value is going to be less than 256 then
21412  use an 'unsigned char' instead of a 'short' or 'int'.
21413  Please note, that ANSI C requires both signed and unsigned chars to be
21414  promoted to 'signed int' before doing any operation.
21415  This promotion
21416 \begin_inset LatexCommand \index{type promotion}
21417
21418 \end_inset
21419
21420  can be omitted, if the result is the same.
21421  The effect of the promotion rules together with the sign-extension is often
21422  surprising:
21423 \begin_deeper
21424 \layout Verse
21425
21426
21427 \family typewriter
21428 unsigned char uc = 0xfe;
21429 \newline
21430 if (uc * uc < 0) /* this is true! */
21431 \newline
21432 {
21433 \newline
21434 \SpecialChar ~
21435 \SpecialChar ~
21436 \SpecialChar ~
21437 \SpecialChar ~
21438 ....
21439 \newline
21440 }
21441 \layout Standard
21442
21443
21444 \family typewriter
21445 uc * uc
21446 \family default
21447  is evaluated as
21448 \family typewriter
21449 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
21450 \family default
21451 .
21452
21453 \newline
21454 Another one:
21455 \layout Verse
21456
21457
21458 \family typewriter
21459 (unsigned char) -12 / (signed char) -3 = ...
21460 \layout Standard
21461
21462 No, the result is not 4:
21463 \layout Verse
21464
21465
21466 \family typewriter
21467 (int) (unsigned char) -12 / (int) (signed char) -3 =
21468 \newline
21469 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
21470 \newline
21471 (int) 0x00f4 / (int) 0xfffd =
21472 \newline
21473 (int) 0x00f4 / (int) 0xfffd =
21474 \newline
21475 (int) 244 / (int) -3 =
21476 \newline
21477 (int) -81 = (int) 0xffaf;
21478 \layout Standard
21479
21480 Don't complain, that gcc gives you a different result.
21481  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
21482  Therefore the results are different.
21483 \newline
21484 From
21485 \begin_inset Quotes sld
21486 \end_inset
21487
21488 comp.lang.c FAQ
21489 \begin_inset Quotes srd
21490 \end_inset
21491
21492 :
21493 \layout Quote
21494
21495 If well-defined overflow characteristics are important and negative values
21496  are not, or if you want to steer clear of sign-extension problems when
21497  manipulating bits or bytes, use one of the corresponding unsigned types.
21498  (Beware when mixing signed and unsigned values in expressions, though.)
21499 \newline
21500 Although character types (especially unsigned char) can be used as "tiny"
21501  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
21502 ble sign extension and increased code size.
21503 \end_deeper
21504 \layout Itemize
21505
21506 Use unsigned when it is known in advance that the value is not going to
21507  be negative.
21508  This helps especially if you are doing division or multiplication, bit-shifting
21509  or are using an array index.
21510 \layout Itemize
21511
21512 NEVER jump into a LOOP.
21513 \layout Itemize
21514
21515 Declare the variables to be local
21516 \begin_inset LatexCommand \index{local variables}
21517
21518 \end_inset
21519
21520  whenever possible, especially loop control variables (induction).
21521 \layout Itemize
21522
21523 Since the compiler does not always do implicit integral promotion, the programme
21524 r should do an explicit cast when integral promotion is required.
21525 \layout Itemize
21526
21527 Reducing the size of division, multiplication & modulus operations can reduce
21528  code size substantially.
21529  Take the following code for example.
21530 \begin_deeper
21531 \layout Verse
21532
21533
21534 \family typewriter
21535 foobar(unsigned int p1, unsigned char ch)
21536 \newline
21537 {
21538 \newline
21539 \SpecialChar ~
21540 \SpecialChar ~
21541 \SpecialChar ~
21542 \SpecialChar ~
21543 unsigned char ch1 = p1 % ch ;
21544 \newline
21545 \SpecialChar ~
21546 \SpecialChar ~
21547 \SpecialChar ~
21548 \SpecialChar ~
21549 ....
21550 \newline
21551 }
21552 \layout Standard
21553
21554 For the modulus operation the variable ch will be promoted to unsigned int
21555  first then the modulus operation will be performed (this will lead to a
21556  call to support routine _moduint()), and the result will be casted to a
21557  char.
21558  If the code is changed to
21559 \layout Verse
21560
21561
21562 \family typewriter
21563 foobar(unsigned int p1, unsigned char ch)
21564 \newline
21565 {
21566 \newline
21567 \SpecialChar ~
21568 \SpecialChar ~
21569 \SpecialChar ~
21570 \SpecialChar ~
21571 unsigned char ch1 = (unsigned char)p1 % ch ;
21572 \newline
21573 \SpecialChar ~
21574 \SpecialChar ~
21575 \SpecialChar ~
21576 \SpecialChar ~
21577 ....
21578 \newline
21579 }
21580 \layout Standard
21581
21582 It would substantially reduce the code generated (future versions of the
21583  compiler will be smart enough to detect such optimization opportunities).
21584 \end_deeper
21585 \layout Itemize
21586
21587 Have a look at the assembly listing to get a
21588 \begin_inset Quotes sld
21589 \end_inset
21590
21591 feeling
21592 \begin_inset Quotes srd
21593 \end_inset
21594
21595  for the code generation.
21596 \layout Section
21597
21598 Tools
21599 \begin_inset LatexCommand \index{Tools}
21600
21601 \end_inset
21602
21603  included in the distribution
21604 \layout Standard
21605 \align center
21606
21607 \begin_inset  Tabular
21608 <lyxtabular version="3" rows="12" columns="3">
21609 <features>
21610 <column alignment="center" valignment="top" leftline="true" width="0pt">
21611 <column alignment="center" valignment="top" leftline="true" width="0pt">
21612 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21613 <row topline="true" bottomline="true">
21614 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21615 \begin_inset Text
21616
21617 \layout Standard
21618
21619 Name
21620 \end_inset
21621 </cell>
21622 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21623 \begin_inset Text
21624
21625 \layout Standard
21626
21627 Purpose
21628 \end_inset
21629 </cell>
21630 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21631 \begin_inset Text
21632
21633 \layout Standard
21634
21635 Directory
21636 \end_inset
21637 </cell>
21638 </row>
21639 <row topline="true">
21640 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21641 \begin_inset Text
21642
21643 \layout Standard
21644
21645 uCsim
21646 \end_inset
21647 </cell>
21648 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21649 \begin_inset Text
21650
21651 \layout Standard
21652
21653 Simulator for various architectures
21654 \end_inset
21655 </cell>
21656 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21657 \begin_inset Text
21658
21659 \layout Standard
21660
21661 sdcc/sim/ucsim
21662 \end_inset
21663 </cell>
21664 </row>
21665 <row topline="true">
21666 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21667 \begin_inset Text
21668
21669 \layout Standard
21670
21671 keil2sdcc.pl
21672 \end_inset
21673 </cell>
21674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21675 \begin_inset Text
21676
21677 \layout Standard
21678
21679 header file conversion
21680 \end_inset
21681 </cell>
21682 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21683 \begin_inset Text
21684
21685 \layout Standard
21686
21687 sdcc/support/scripts
21688 \end_inset
21689 </cell>
21690 </row>
21691 <row topline="true">
21692 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21693 \begin_inset Text
21694
21695 \layout Standard
21696
21697 mh2h.c
21698 \end_inset
21699 </cell>
21700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21701 \begin_inset Text
21702
21703 \layout Standard
21704
21705 header file conversion
21706 \end_inset
21707 </cell>
21708 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21709 \begin_inset Text
21710
21711 \layout Standard
21712
21713 sdcc/support/scripts
21714 \end_inset
21715 </cell>
21716 </row>
21717 <row topline="true">
21718 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21719 \begin_inset Text
21720
21721 \layout Standard
21722
21723 as-gbz80
21724 \end_inset
21725 </cell>
21726 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21727 \begin_inset Text
21728
21729 \layout Standard
21730
21731 Assembler
21732 \end_inset
21733 </cell>
21734 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21735 \begin_inset Text
21736
21737 \layout Standard
21738
21739
21740 \family roman
21741 \series medium
21742 \shape up
21743 \size normal
21744 \emph off
21745 \bar no
21746 \noun off
21747 \color none
21748 sdcc/bin
21749 \end_inset
21750 </cell>
21751 </row>
21752 <row topline="true">
21753 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21754 \begin_inset Text
21755
21756 \layout Standard
21757
21758 as-z80
21759 \end_inset
21760 </cell>
21761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21762 \begin_inset Text
21763
21764 \layout Standard
21765
21766 Assembler
21767 \end_inset
21768 </cell>
21769 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21770 \begin_inset Text
21771
21772 \layout Standard
21773
21774
21775 \family roman
21776 \series medium
21777 \shape up
21778 \size normal
21779 \emph off
21780 \bar no
21781 \noun off
21782 \color none
21783 sdcc/bin
21784 \end_inset
21785 </cell>
21786 </row>
21787 <row topline="true">
21788 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21789 \begin_inset Text
21790
21791 \layout Standard
21792
21793 asx8051
21794 \end_inset
21795 </cell>
21796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21797 \begin_inset Text
21798
21799 \layout Standard
21800
21801 Assembler
21802 \end_inset
21803 </cell>
21804 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21805 \begin_inset Text
21806
21807 \layout Standard
21808
21809
21810 \family roman
21811 \series medium
21812 \shape up
21813 \size normal
21814 \emph off
21815 \bar no
21816 \noun off
21817 \color none
21818 sdcc/bin
21819 \end_inset
21820 </cell>
21821 </row>
21822 <row topline="true">
21823 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21824 \begin_inset Text
21825
21826 \layout Standard
21827
21828 sdcdb
21829 \end_inset
21830 </cell>
21831 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21832 \begin_inset Text
21833
21834 \layout Standard
21835
21836 Simulator
21837 \end_inset
21838 </cell>
21839 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21840 \begin_inset Text
21841
21842 \layout Standard
21843
21844
21845 \family roman
21846 \series medium
21847 \shape up
21848 \size normal
21849 \emph off
21850 \bar no
21851 \noun off
21852 \color none
21853 sdcc/bin
21854 \end_inset
21855 </cell>
21856 </row>
21857 <row topline="true">
21858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21859 \begin_inset Text
21860
21861 \layout Standard
21862
21863 aslink
21864 \end_inset
21865 </cell>
21866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21867 \begin_inset Text
21868
21869 \layout Standard
21870
21871 Linker
21872 \end_inset
21873 </cell>
21874 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21875 \begin_inset Text
21876
21877 \layout Standard
21878
21879
21880 \family roman
21881 \series medium
21882 \shape up
21883 \size normal
21884 \emph off
21885 \bar no
21886 \noun off
21887 \color none
21888 sdcc/bin
21889 \end_inset
21890 </cell>
21891 </row>
21892 <row topline="true">
21893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21894 \begin_inset Text
21895
21896 \layout Standard
21897
21898 link-z80
21899 \end_inset
21900 </cell>
21901 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21902 \begin_inset Text
21903
21904 \layout Standard
21905
21906 Linker
21907 \end_inset
21908 </cell>
21909 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21910 \begin_inset Text
21911
21912 \layout Standard
21913
21914
21915 \family roman
21916 \series medium
21917 \shape up
21918 \size normal
21919 \emph off
21920 \bar no
21921 \noun off
21922 \color none
21923 sdcc/bin
21924 \end_inset
21925 </cell>
21926 </row>
21927 <row topline="true">
21928 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21929 \begin_inset Text
21930
21931 \layout Standard
21932
21933 link-gbz80
21934 \end_inset
21935 </cell>
21936 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21937 \begin_inset Text
21938
21939 \layout Standard
21940
21941 Linker
21942 \end_inset
21943 </cell>
21944 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21945 \begin_inset Text
21946
21947 \layout Standard
21948
21949
21950 \family roman
21951 \series medium
21952 \shape up
21953 \size normal
21954 \emph off
21955 \bar no
21956 \noun off
21957 \color none
21958 sdcc/bin
21959 \end_inset
21960 </cell>
21961 </row>
21962 <row topline="true" bottomline="true">
21963 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21964 \begin_inset Text
21965
21966 \layout Standard
21967
21968 packihx
21969 \end_inset
21970 </cell>
21971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21972 \begin_inset Text
21973
21974 \layout Standard
21975
21976 ihx packer
21977 \end_inset
21978 </cell>
21979 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21980 \begin_inset Text
21981
21982 \layout Standard
21983
21984
21985 \family roman
21986 \series medium
21987 \shape up
21988 \size normal
21989 \emph off
21990 \bar no
21991 \noun off
21992 \color none
21993 sdcc/bin
21994 \end_inset
21995 </cell>
21996 </row>
21997 </lyxtabular>
21998
21999 \end_inset
22000
22001
22002 \newline
22003
22004 \layout Section
22005
22006 Documentation
22007 \begin_inset LatexCommand \index{Documentation}
22008
22009 \end_inset
22010
22011  included in the distribution
22012 \layout Standard
22013 \align center
22014
22015 \begin_inset  Tabular
22016 <lyxtabular version="3" rows="10" columns="2">
22017 <features>
22018 <column alignment="left" valignment="top" leftline="true" width="0">
22019 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22020 <row topline="true" bottomline="true">
22021 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22022 \begin_inset Text
22023
22024 \layout Standard
22025
22026 Subject / Title
22027 \end_inset
22028 </cell>
22029 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22030 \begin_inset Text
22031
22032 \layout Standard
22033
22034 Where to get / filename
22035 \end_inset
22036 </cell>
22037 </row>
22038 <row topline="true">
22039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22040 \begin_inset Text
22041
22042 \layout Standard
22043
22044 SDCC Compiler User Guide
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 You're reading it right now
22053 \end_inset
22054 </cell>
22055 </row>
22056 <row topline="true">
22057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22058 \begin_inset Text
22059
22060 \layout Standard
22061
22062 Changelog of SDCC
22063 \end_inset
22064 </cell>
22065 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22066 \begin_inset Text
22067
22068 \layout Standard
22069
22070 sdcc/Changelog
22071 \end_inset
22072 </cell>
22073 </row>
22074 <row topline="true">
22075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22076 \begin_inset Text
22077
22078 \layout Standard
22079
22080 ASXXXX
22081 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
22082
22083 \end_inset
22084
22085
22086 \begin_inset LatexCommand \index{Assembler documentation}
22087
22088 \end_inset
22089
22090  Assemblers and ASLINK
22091 \begin_inset LatexCommand \index{aslink}
22092
22093 \end_inset
22094
22095
22096 \begin_inset LatexCommand \index{Linker documentation}
22097
22098 \end_inset
22099
22100  Relocating Linker
22101 \end_inset
22102 </cell>
22103 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22104 \begin_inset Text
22105
22106 \layout Standard
22107
22108 sdcc/as/doc/asxhtm.html
22109 \end_inset
22110 </cell>
22111 </row>
22112 <row topline="true">
22113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22114 \begin_inset Text
22115
22116 \layout Standard
22117
22118 SDCC regression test
22119 \begin_inset LatexCommand \index{Regression test}
22120
22121 \end_inset
22122
22123
22124 \end_inset
22125 </cell>
22126 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22127 \begin_inset Text
22128
22129 \layout Standard
22130
22131 sdcc/doc/test_suite_spec.pdf
22132 \end_inset
22133 </cell>
22134 </row>
22135 <row topline="true">
22136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22137 \begin_inset Text
22138
22139 \layout Standard
22140
22141 Various notes
22142 \end_inset
22143 </cell>
22144 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22145 \begin_inset Text
22146
22147 \layout Standard
22148
22149 sdcc/doc/*
22150 \end_inset
22151 </cell>
22152 </row>
22153 <row topline="true">
22154 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22155 \begin_inset Text
22156
22157 \layout Standard
22158
22159 Notes on debugging with sdcdb
22160 \begin_inset LatexCommand \index{sdcdb (debugger)}
22161
22162 \end_inset
22163
22164
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 sdcc/debugger/README
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 Software simulator for microcontrollers
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
22191 \family roman
22192 \series medium
22193 \shape up
22194 \size normal
22195 \emph off
22196 \bar no
22197 \noun off
22198 \color none
22199 sdcc/sim/ucsim/doc
22200 \family default
22201 \series default
22202 \shape default
22203 \size default
22204 \emph default
22205 \bar default
22206 \noun default
22207 \color default
22208 /index.html
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 Temporary notes on the pic16
22219 \begin_inset LatexCommand \index{PIC16}
22220
22221 \end_inset
22222
22223  port
22224 \end_inset
22225 </cell>
22226 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22227 \begin_inset Text
22228
22229 \layout Standard
22230
22231 sdcc/src/pic16/NOTES
22232 \end_inset
22233 </cell>
22234 </row>
22235 <row topline="true" bottomline="true">
22236 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22237 \begin_inset Text
22238
22239 \layout Standard
22240
22241 SDCC internal documentation (debugging file format)
22242 \end_inset
22243 </cell>
22244 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22245 \begin_inset Text
22246
22247 \layout Standard
22248
22249 sdcc/doc/
22250 \family roman
22251 \series medium
22252 \shape up
22253 \size normal
22254 \emph off
22255 \bar no
22256 \noun off
22257 \color none
22258 cdbfileformat.pd
22259 \family default
22260 \series default
22261 \shape default
22262 \size default
22263 \emph default
22264 \bar default
22265 \noun default
22266 \color default
22267 f
22268 \end_inset
22269 </cell>
22270 </row>
22271 </lyxtabular>
22272
22273 \end_inset
22274
22275
22276 \newline
22277
22278 \layout Section
22279
22280 Related open source tools
22281 \begin_inset LatexCommand \index{Related tools}
22282
22283 \end_inset
22284
22285
22286 \layout Standard
22287 \align center
22288
22289 \begin_inset  Tabular
22290 <lyxtabular version="3" rows="11" columns="3">
22291 <features>
22292 <column alignment="center" valignment="top" leftline="true" width="0pt">
22293 <column alignment="block" valignment="top" leftline="true" width="30line%">
22294 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22295 <row topline="true" bottomline="true">
22296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22297 \begin_inset Text
22298
22299 \layout Standard
22300
22301 Name
22302 \end_inset
22303 </cell>
22304 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22305 \begin_inset Text
22306
22307 \layout Standard
22308
22309 Purpose
22310 \end_inset
22311 </cell>
22312 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22313 \begin_inset Text
22314
22315 \layout Standard
22316
22317 Where to get
22318 \end_inset
22319 </cell>
22320 </row>
22321 <row topline="true">
22322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22323 \begin_inset Text
22324
22325 \layout Standard
22326
22327 gpsim
22328 \begin_inset LatexCommand \index{gpsim (pic simulator)}
22329
22330 \end_inset
22331
22332
22333 \end_inset
22334 </cell>
22335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22336 \begin_inset Text
22337
22338 \layout Standard
22339
22340 PIC simulator
22341 \end_inset
22342 </cell>
22343 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22344 \begin_inset Text
22345
22346 \layout Standard
22347
22348
22349 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
22350
22351 \end_inset
22352
22353
22354 \end_inset
22355 </cell>
22356 </row>
22357 <row topline="true">
22358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22359 \begin_inset Text
22360
22361 \layout Standard
22362
22363 gputils
22364 \begin_inset LatexCommand \index{gputils (pic tools)}
22365
22366 \end_inset
22367
22368
22369 \end_inset
22370 </cell>
22371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22372 \begin_inset Text
22373
22374 \layout Standard
22375
22376 GNU PIC utilities
22377 \end_inset
22378 </cell>
22379 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22380 \begin_inset Text
22381
22382 \layout Standard
22383
22384
22385 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
22386
22387 \end_inset
22388
22389
22390 \end_inset
22391 </cell>
22392 </row>
22393 <row topline="true">
22394 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22395 \begin_inset Text
22396
22397 \layout Standard
22398
22399 flP5
22400 \end_inset
22401 </cell>
22402 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22403 \begin_inset Text
22404
22405 \layout Standard
22406
22407 PIC programmer
22408 \end_inset
22409 </cell>
22410 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22411 \begin_inset Text
22412
22413 \layout Standard
22414
22415
22416 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
22417
22418 \end_inset
22419
22420
22421 \end_inset
22422 </cell>
22423 </row>
22424 <row topline="true">
22425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22426 \begin_inset Text
22427
22428 \layout Standard
22429
22430 indent
22431 \begin_inset LatexCommand \index{indent (source formatting tool)}
22432
22433 \end_inset
22434
22435
22436 \end_inset
22437 </cell>
22438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22439 \begin_inset Text
22440
22441 \layout Standard
22442
22443 Formats C source - Master of the white spaces
22444 \end_inset
22445 </cell>
22446 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22447 \begin_inset Text
22448
22449 \layout Standard
22450
22451
22452 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
22453
22454 \end_inset
22455
22456
22457 \end_inset
22458 </cell>
22459 </row>
22460 <row topline="true">
22461 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22462 \begin_inset Text
22463
22464 \layout Standard
22465
22466 srecord
22467 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
22468
22469 \end_inset
22470
22471
22472 \end_inset
22473 </cell>
22474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22475 \begin_inset Text
22476
22477 \layout Standard
22478
22479 Object file conversion, checksumming, ...
22480 \end_inset
22481 </cell>
22482 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22483 \begin_inset Text
22484
22485 \layout Standard
22486
22487
22488 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
22489
22490 \end_inset
22491
22492
22493 \end_inset
22494 </cell>
22495 </row>
22496 <row topline="true">
22497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22498 \begin_inset Text
22499
22500 \layout Standard
22501
22502 objdump
22503 \begin_inset LatexCommand \index{objdump (tool)}
22504
22505 \end_inset
22506
22507
22508 \end_inset
22509 </cell>
22510 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22511 \begin_inset Text
22512
22513 \layout Standard
22514
22515 Object file conversion, ...
22516 \end_inset
22517 </cell>
22518 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22519 \begin_inset Text
22520
22521 \layout Standard
22522
22523 Part of binutils (should be there anyway)
22524 \end_inset
22525 </cell>
22526 </row>
22527 <row topline="true">
22528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22529 \begin_inset Text
22530
22531 \layout Standard
22532
22533 doxygen
22534 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
22535
22536 \end_inset
22537
22538
22539 \end_inset
22540 </cell>
22541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22542 \begin_inset Text
22543
22544 \layout Standard
22545
22546 Source code documentation system
22547 \end_inset
22548 </cell>
22549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22550 \begin_inset Text
22551
22552 \layout Standard
22553
22554
22555 \begin_inset LatexCommand \url{http://www.doxygen.org}
22556
22557 \end_inset
22558
22559
22560 \end_inset
22561 </cell>
22562 </row>
22563 <row topline="true">
22564 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22565 \begin_inset Text
22566
22567 \layout Standard
22568
22569 kdevelop
22570 \end_inset
22571 </cell>
22572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22573 \begin_inset Text
22574
22575 \layout Standard
22576
22577 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
22578 \end_inset
22579 </cell>
22580 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22581 \begin_inset Text
22582
22583 \layout Standard
22584
22585
22586 \begin_inset LatexCommand \url{http://www.kdevelop.org}
22587
22588 \end_inset
22589
22590
22591 \end_inset
22592 </cell>
22593 </row>
22594 <row topline="true">
22595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22596 \begin_inset Text
22597
22598 \layout Standard
22599
22600 splint
22601 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22602
22603 \end_inset
22604
22605
22606 \end_inset
22607 </cell>
22608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22609 \begin_inset Text
22610
22611 \layout Standard
22612
22613 Statically checks c sources (see
22614 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22615
22616 \end_inset
22617
22618 )
22619 \end_inset
22620 </cell>
22621 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22622 \begin_inset Text
22623
22624 \layout Standard
22625
22626
22627 \begin_inset LatexCommand \url{http://www.splint.org}
22628
22629 \end_inset
22630
22631
22632 \end_inset
22633 </cell>
22634 </row>
22635 <row topline="true" bottomline="true">
22636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22637 \begin_inset Text
22638
22639 \layout Standard
22640
22641 ddd
22642 \begin_inset LatexCommand \index{ddd (debugger)}
22643
22644 \end_inset
22645
22646
22647 \end_inset
22648 </cell>
22649 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22650 \begin_inset Text
22651
22652 \layout Standard
22653
22654 Debugger, serves nicely as GUI to sdcdb
22655 \begin_inset LatexCommand \index{sdcdb (debugger)}
22656
22657 \end_inset
22658
22659  (Unix only)
22660 \end_inset
22661 </cell>
22662 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22663 \begin_inset Text
22664
22665 \layout Standard
22666
22667
22668 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
22669
22670 \end_inset
22671
22672
22673 \end_inset
22674 </cell>
22675 </row>
22676 </lyxtabular>
22677
22678 \end_inset
22679
22680
22681 \newline
22682
22683 \layout Section
22684
22685 Related documentation / recommended reading
22686 \layout Standard
22687 \align center
22688
22689 \begin_inset  Tabular
22690 <lyxtabular version="3" rows="6" columns="3">
22691 <features>
22692 <column alignment="center" valignment="top" leftline="true" width="0pt">
22693 <column alignment="block" valignment="top" leftline="true" width="30line%">
22694 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
22695 <row topline="true" bottomline="true">
22696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22697 \begin_inset Text
22698
22699 \layout Standard
22700
22701 Name
22702 \end_inset
22703 </cell>
22704 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22705 \begin_inset Text
22706
22707 \layout Standard
22708
22709 Subject / Title
22710 \end_inset
22711 </cell>
22712 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22713 \begin_inset Text
22714
22715 \layout Standard
22716
22717 Where to get
22718 \end_inset
22719 </cell>
22720 </row>
22721 <row topline="true">
22722 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22723 \begin_inset Text
22724
22725 \layout Standard
22726
22727
22728 \family roman
22729 \series medium
22730 \shape up
22731 \size normal
22732 \emph off
22733 \bar no
22734 \noun off
22735 \color none
22736 c-refcard.pdf
22737 \end_inset
22738 </cell>
22739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22740 \begin_inset Text
22741
22742 \layout Standard
22743
22744 C Reference Card
22745 \begin_inset LatexCommand \index{C Reference card}
22746
22747 \end_inset
22748
22749 , 2 pages
22750 \end_inset
22751 </cell>
22752 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22753 \begin_inset Text
22754
22755 \layout Standard
22756
22757
22758 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
22759
22760 \end_inset
22761
22762
22763 \end_inset
22764 </cell>
22765 </row>
22766 <row topline="true">
22767 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22768 \begin_inset Text
22769
22770 \layout Standard
22771
22772 c-faq
22773 \end_inset
22774 </cell>
22775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22776 \begin_inset Text
22777
22778 \layout Standard
22779
22780 C-FAQ-list
22781 \end_inset
22782 </cell>
22783 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22784 \begin_inset Text
22785
22786 \layout Standard
22787
22788
22789 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
22790
22791 \end_inset
22792
22793
22794 \end_inset
22795 </cell>
22796 </row>
22797 <row topline="true">
22798 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22799 \begin_inset Text
22800
22801 \layout Standard
22802
22803 \end_inset
22804 </cell>
22805 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22806 \begin_inset Text
22807
22808 \layout Standard
22809
22810 Latest datasheet of the target CPU
22811 \end_inset
22812 </cell>
22813 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22814 \begin_inset Text
22815
22816 \layout Standard
22817
22818 vendor
22819 \end_inset
22820 </cell>
22821 </row>
22822 <row topline="true">
22823 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22824 \begin_inset Text
22825
22826 \layout Standard
22827
22828 \end_inset
22829 </cell>
22830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22831 \begin_inset Text
22832
22833 \layout Standard
22834
22835 Revision history of datasheet
22836 \end_inset
22837 </cell>
22838 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22839 \begin_inset Text
22840
22841 \layout Standard
22842
22843 vendor
22844 \end_inset
22845 </cell>
22846 </row>
22847 <row topline="true" bottomline="true">
22848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22849 \begin_inset Text
22850
22851 \layout Standard
22852
22853 S.
22854  S.
22855  Muchnick
22856 \end_inset
22857 </cell>
22858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22859 \begin_inset Text
22860
22861 \layout Standard
22862
22863 Advanced Compiler Design and Implementation
22864 \end_inset
22865 </cell>
22866 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22867 \begin_inset Text
22868
22869 \layout Standard
22870
22871 bookstore (very dedicated, probably read other books first)
22872 \end_inset
22873 </cell>
22874 </row>
22875 </lyxtabular>
22876
22877 \end_inset
22878
22879
22880 \newline
22881
22882 \layout Section
22883
22884 Some Questions
22885 \layout Standard
22886
22887 Some questions answered, some pointers given - it might be time to in turn
22888  ask
22889 \emph on
22890 you
22891 \emph default
22892  some questions:
22893 \layout Itemize
22894
22895 can you solve your project with the selected microcontroller? Would you
22896  find out early or rather late that your target is too small/slow/whatever?
22897  Can you switch to a slightly better device if it doesn't fit?
22898 \layout Itemize
22899
22900 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
22901  and/or another programming language be more adequate? Would an operating
22902  system on the target device help?
22903 \layout Itemize
22904
22905 if you solved the problem, will the marketing department be happy?
22906 \layout Itemize
22907
22908 if the marketing department is happy, will customers be happy?
22909 \layout Itemize
22910
22911 if you're the project manager, marketing department and maybe even the customer
22912  in one person, have you tried to see the project from the outside?
22913 \layout Itemize
22914
22915 is the project done if you think it is done? Or is just that other interface/pro
22916 tocol/feature/configuration/option missing? How about website, manual(s),
22917  internationali(z|s)ation, packaging, labels, 2nd source for components,
22918  electromagnetic compatability/interference, documentation for production,
22919  production test software, update mechanism, patent issues?
22920 \layout Itemize
22921
22922 is your project adequately positioned in that magic triangle: fame, fortune,
22923  fun?
22924 \layout Standard
22925
22926 Maybe not all answers to these questions are known and some answers may
22927  even be
22928 \emph on
22929 no
22930 \emph default
22931 , nevertheless knowing these questions may help you to avoid burnout
22932 \begin_inset Foot
22933 collapsed false
22934
22935 \layout Standard
22936
22937 burnout is bad for electronic devices, programmers and motorcycle tyres
22938 \end_inset
22939
22940 .
22941  Chances are you didn't want to hear some of them...
22942 \layout Chapter
22943
22944 Support
22945 \begin_inset LatexCommand \index{Support}
22946
22947 \end_inset
22948
22949
22950 \layout Standard
22951
22952 SDCC has grown to be a large project.
22953  The compiler alone (without the preprocessor, assembler and linker) is
22954  well over 100,000 lines of code (blank stripped).
22955  The open source nature of this project is a key to its continued growth
22956  and support.
22957  You gain the benefit and support of many active software developers and
22958  end users.
22959  Is SDCC perfect? No, that's why we need your help.
22960  The developers take pride in fixing reported bugs.
22961  You can help by reporting the bugs and helping other SDCC users.
22962  There are lots of ways to contribute, and we encourage you to take part
22963  in making SDCC a great software package.
22964
22965 \layout Standard
22966
22967 The SDCC project is hosted on the SDCC sourceforge site at
22968 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
22969
22970 \end_inset
22971
22972 .
22973  You'll find the complete set of mailing lists
22974 \begin_inset LatexCommand \index{Mailing list(s)}
22975
22976 \end_inset
22977
22978 , forums, bug reporting system, patch submission
22979 \begin_inset LatexCommand \index{Patch submission}
22980
22981 \end_inset
22982
22983  system, download
22984 \begin_inset LatexCommand \index{download}
22985
22986 \end_inset
22987
22988  area and Subversion code repository
22989 \begin_inset LatexCommand \index{Subversion code repository}
22990
22991 \end_inset
22992
22993  there.
22994 \layout Section
22995
22996 Reporting Bugs
22997 \begin_inset LatexCommand \index{Bug reporting}
22998
22999 \end_inset
23000
23001
23002 \begin_inset LatexCommand \index{Reporting bugs}
23003
23004 \end_inset
23005
23006
23007 \layout Standard
23008
23009 The recommended way of reporting bugs is using the infrastructure of the
23010  sourceforge site.
23011  You can follow the status of bug reports there and have an overview about
23012  the known bugs.
23013 \layout Standard
23014
23015 Bug reports are automatically forwarded to the developer mailing list and
23016  will be fixed ASAP.
23017  When reporting a bug, it is very useful to include a small test program
23018  (the smaller the better) which reproduces the problem.
23019  If you can isolate the problem by looking at the generated assembly code,
23020  this can be very helpful.
23021  Compiling your program with the -
23022 \begin_inset ERT
23023 status Collapsed
23024
23025 \layout Standard
23026
23027 \backslash
23028 /
23029 \end_inset
23030
23031 -dumpall
23032 \begin_inset LatexCommand \index{-\/-dumpall}
23033
23034 \end_inset
23035
23036  option can sometimes be useful in locating optimization problems.
23037  When reporting a bug please maker sure you:
23038 \layout Enumerate
23039
23040 Attach the code you are compiling with SDCC.
23041
23042 \layout Enumerate
23043
23044 Specify the exact command you use to run SDCC, or attach your Makefile.
23045
23046 \layout Enumerate
23047
23048 Specify the SDCC version (type "
23049 \family sans
23050 \series bold
23051 sdcc -v
23052 \family default
23053 \series default
23054 "), your platform, and operating system.
23055
23056 \layout Enumerate
23057
23058 Provide an exact copy of any error message or incorrect output.
23059
23060 \layout Enumerate
23061
23062 Put something meaningful in the subject of your message.
23063 \layout Standard
23064
23065 Please attempt to include these 5 important parts, as applicable, in all
23066  requests for support or when reporting any problems or bugs with SDCC.
23067  Though this will make your message lengthy, it will greatly improve your
23068  chance that SDCC users and developers will be able to help you.
23069  Some SDCC developers are frustrated by bug reports without code provided
23070  that they can use to reproduce and ultimately fix the problem, so please
23071  be sure to provide sample code if you are reporting a bug!
23072 \layout Standard
23073
23074 Please have a short check that you are using a recent version of SDCC and
23075  the bug is not yet known.
23076  This is the link for reporting bugs:
23077 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
23078
23079 \end_inset
23080
23081 .
23082 \layout Section
23083
23084 Requesting Features
23085 \begin_inset LatexCommand \label{sub:Requesting-Features}
23086
23087 \end_inset
23088
23089
23090 \begin_inset LatexCommand \index{Feature request}
23091
23092 \end_inset
23093
23094
23095 \begin_inset LatexCommand \index{Requesting features}
23096
23097 \end_inset
23098
23099
23100 \layout Standard
23101
23102 Like bug reports feature requests are forwarded to the developer mailing
23103  list.
23104  This is the link for requesting features:
23105 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
23106
23107 \end_inset
23108
23109 .
23110 \layout Section
23111
23112 Submitting patches
23113 \layout Standard
23114
23115 Like bug reports contributed patches are forwarded to the developer mailing
23116  list.
23117  This is the link for submitting patches
23118 \begin_inset LatexCommand \index{Patch submission}
23119
23120 \end_inset
23121
23122 :
23123 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
23124
23125 \end_inset
23126
23127 .
23128 \layout Standard
23129
23130 You need to specify some parameters to the
23131 \family typewriter
23132 diff
23133 \family default
23134  command for the patches to be useful.
23135  If you modified more than one file a patch created f.e.
23136  with
23137 \family sans
23138 \series bold
23139
23140 \begin_inset Quotes sld
23141 \end_inset
23142
23143 diff -Naur unmodified_directory modified_directory >my_changes.patch
23144 \begin_inset Quotes srd
23145 \end_inset
23146
23147
23148 \family default
23149 \series default
23150  will be fine, otherwise
23151 \family sans
23152 \series bold
23153
23154 \begin_inset Quotes sld
23155 \end_inset
23156
23157 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
23158 \begin_inset Quotes srd
23159 \end_inset
23160
23161
23162 \series default
23163
23164 \family default
23165 will do.
23166 \layout Section
23167
23168 Getting Help
23169 \layout Standard
23170
23171 These links should take you directly to the
23172 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
23173
23174 \end_inset
23175
23176
23177 \begin_inset Foot
23178 collapsed false
23179
23180 \layout Standard
23181
23182 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
23183  automated messages (mid 2003)
23184 \end_inset
23185
23186  and the
23187 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
23188
23189 \end_inset
23190
23191 , lists
23192 \begin_inset LatexCommand \index{Mailing list(s)}
23193
23194 \end_inset
23195
23196  and forums are archived and searchable so if you are lucky someone already
23197  had a similar problem.
23198  While mails to the lists themselves are delivered promptly their web front
23199  end on sourceforge sometimes shows a severe time lag (up to several weeks),
23200  if you're seriously using SDCC please consider subscribing to the lists.
23201 \layout Section
23202
23203 ChangeLog
23204 \layout Standard
23205
23206 You can follow the status of the Subversion version
23207 \begin_inset LatexCommand \index{version}
23208
23209 \end_inset
23210
23211  of SDCC by watching the Changelog
23212 \begin_inset LatexCommand \index{Changelog}
23213
23214 \end_inset
23215
23216  in the Subversion repository
23217 \newline
23218
23219 \size footnotesize
23220
23221 \begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
23222
23223 \end_inset
23224
23225 .
23226 \layout Section
23227
23228 Release policy
23229 \begin_inset LatexCommand \index{Release policy}
23230
23231 \end_inset
23232
23233
23234 \layout Standard
23235
23236 Historically there often were long delays between official releases and
23237  the sourceforge download area tends to get not updated at all.
23238  Excuses in the past might have referred to problems with live range analysis,
23239  but as this was fixed a while ago, the current problem is that another
23240  excuse has to be found.
23241  Kidding aside, we have to get better there! On the other hand there are
23242  daily snapshots available at
23243 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
23244
23245 \end_inset
23246
23247 , and you can always build the very last version (hopefully with many bugs
23248  fixed, and features added) from the source code available at
23249 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
23250
23251 \end_inset
23252
23253 .
23254 \layout Section
23255
23256 Examples
23257 \begin_inset LatexCommand \index{Examples}
23258
23259 \end_inset
23260
23261
23262 \layout Standard
23263
23264 You'll find some small examples in the directory
23265 \emph on
23266 sdcc/device/examples/.
23267
23268 \emph default
23269 More examples and libraries are available at
23270 \emph on
23271  The SDCC Open Knowledge Resource
23272 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
23273
23274 \end_inset
23275
23276
23277 \emph default
23278 web site or at
23279 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
23280
23281 \end_inset
23282
23283 .
23284 \layout Comment
23285
23286 I did insert a reference to Paul's web site here although it seems rather
23287  dedicated to a specific 8032 board (I think it's okay because it f.e.
23288  shows LCD/Harddisc interface and has a free 8051 monitor.
23289  Independent 8032 board vendors face hard competition of heavily subsidized
23290  development boards anyway).
23291 \layout Comment
23292
23293 Maybe we should include some links to real world applications.
23294  Preferably pointer to pointers (one for each architecture) so this stays
23295  manageable here?
23296 \layout Section
23297
23298 Quality control
23299 \begin_inset LatexCommand \index{Quality control}
23300
23301 \end_inset
23302
23303
23304 \layout Standard
23305
23306 The compiler is passed through nightly compile and build checks.
23307  The so called
23308 \shape italic
23309 regression tests
23310 \shape default
23311
23312 \begin_inset LatexCommand \index{Regression test}
23313
23314 \end_inset
23315
23316  check that SDCC itself compiles flawlessly on several platforms and checks
23317  the quality of the code generated by SDCC by running the code through simulator
23318 s.
23319  There is a separate document
23320 \shape italic
23321 test_suite.pdf
23322 \begin_inset LatexCommand \index{Test suite}
23323
23324 \end_inset
23325
23326
23327 \shape default
23328  about this.
23329 \layout Standard
23330
23331 You'll find the test code in the directory
23332 \shape italic
23333 sdcc/support/regression
23334 \shape default
23335 .
23336  You can run these tests manually by running
23337 \family sans
23338 make
23339 \family default
23340  in this directory (or f.e.
23341
23342 \family sans
23343 \series bold
23344
23345 \begin_inset Quotes sld
23346 \end_inset
23347
23348 make test-mcs51
23349 \begin_inset Quotes srd
23350 \end_inset
23351
23352
23353 \family default
23354 \series default
23355  if you don't want to run the complete tests).
23356  The test code might also be interesting if you want to look for examples
23357 \begin_inset LatexCommand \index{Examples}
23358
23359 \end_inset
23360
23361  checking corner cases of SDCC or if you plan to submit patches
23362 \begin_inset LatexCommand \index{Patch submission}
23363
23364 \end_inset
23365
23366 .
23367 \layout Standard
23368
23369 The pic port uses a different set of regression tests, you'll find them
23370  in the directory
23371 \shape italic
23372 sdcc/src/regression
23373 \shape default
23374 .
23375 \layout Section
23376
23377 Use of SDCC in Education
23378 \layout Standard
23379
23380 In short:
23381 \emph on
23382 highly
23383 \emph default
23384  encouraged
23385 \begin_inset Foot
23386 collapsed false
23387
23388 \layout Standard
23389
23390 the phrase "use in education" might evoke the association "
23391 \emph on
23392 only
23393 \emph default
23394  fit for use in education".
23395  This connotation is not intended but nevertheless risked as the licensing
23396  of SDCC makes it difficult to offer educational discounts
23397 \end_inset
23398
23399 .
23400  If your rationales are to:
23401 \layout Enumerate
23402
23403 give students a chance to understand the
23404 \emph on
23405 complete
23406 \emph default
23407  steps of code generation
23408 \layout Enumerate
23409
23410 have a curriculum that can be extended for years.
23411  Then you could use an fpga board as target and your curriculum will seamlessly
23412  extend from logic synthesis (
23413 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
23414
23415 \end_inset
23416
23417 ,
23418 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
23419
23420 \end_inset
23421
23422 ), over assembly programming, to C to FPGA compilers (
23423 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
23424
23425 \end_inset
23426
23427 ) and to C.
23428 \layout Enumerate
23429
23430 be able to insert excursions about skills like using a revision control
23431  system, submitting/applying patches, using a type-setting (as opposed to
23432  word-processing) engine LyX/LaTeX, using
23433 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
23434
23435 \end_inset
23436
23437 , following some
23438 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
23439
23440 \end_inset
23441
23442 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
23443  Source Software, CPU simulation, compiler regression tests
23444 \begin_inset LatexCommand \index{Regression test}
23445
23446 \end_inset
23447
23448 .
23449
23450 \newline
23451 And if there should be a shortage of ideas then you can always point students
23452  to the ever-growing feature request list
23453 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
23454
23455 \end_inset
23456
23457 .
23458 \layout Enumerate
23459
23460 not tie students to a specific host platform and instead allow them to use
23461  a host platform of
23462 \emph on
23463 their
23464 \emph default
23465  choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
23466  eventually
23467 \begin_inset LatexCommand \url[OLPC]{http://wiki.laptop.org/wiki/One_Laptop_per_Child}
23468
23469 \end_inset
23470
23471 )
23472 \layout Enumerate
23473
23474 not encourage students to use illegal copies of educational software
23475 \layout Enumerate
23476
23477 be immune to licensing/availability/price changes of the chosen tool chain
23478 \layout Enumerate
23479
23480 be able to change to a new target platform without having to adopt a new
23481  tool chain
23482 \layout Enumerate
23483
23484 have complete control over and insight into the tool chain
23485 \layout Enumerate
23486
23487 make your students aware about the pros and cons of open source software
23488  development
23489 \layout Enumerate
23490
23491 give back to the public as you are probably at least partially publically
23492  funded
23493 \layout Enumerate
23494
23495 give students a chance to publically prove their skills and to possibly
23496  see a world wide impact
23497 \layout Standard
23498
23499 then SDCC is probably among the first choices.
23500  Well, probably SDCC might be the only choice.
23501 \layout Chapter
23502 \pagebreak_top
23503 SDCC Technical Data
23504 \layout Section
23505
23506 Optimizations
23507 \begin_inset LatexCommand \index{Optimizations}
23508
23509 \end_inset
23510
23511
23512 \layout Standard
23513
23514 SDCC performs a host of standard optimizations in addition to some MCU specific
23515  optimizations.
23516
23517 \layout Subsection
23518
23519 Sub-expression Elimination
23520 \begin_inset LatexCommand \index{Subexpression elimination}
23521
23522 \end_inset
23523
23524
23525 \layout Standard
23526
23527 The compiler does local and
23528 \emph on
23529 g
23530 \emph default
23531 lobal
23532 \emph on
23533 c
23534 \emph default
23535 ommon
23536 \emph on
23537 s
23538 \emph default
23539 ubexpression
23540 \emph on
23541 e
23542 \emph default
23543 limination, e.g.:
23544 \layout Verse
23545
23546
23547 \family typewriter
23548 i = x + y + 1;
23549 \newline
23550 j = x + y;
23551 \layout Standard
23552
23553 will be translated to
23554 \layout Verse
23555
23556
23557 \family typewriter
23558 iTemp = x + y;
23559 \newline
23560 i = iTemp + 1;
23561 \newline
23562 j = iTemp;
23563 \layout Standard
23564
23565 Some subexpressions are not as obvious as the above example, e.g.:
23566 \layout Verse
23567
23568
23569 \family typewriter
23570 a->b[i].c = 10;
23571 \newline
23572 a->b[i].d = 11;
23573 \layout Standard
23574
23575 In this case the address arithmetic a->b[i] will be computed only once;
23576  the equivalent code in C would be.
23577 \layout Verse
23578
23579
23580 \family typewriter
23581 iTemp = a->b[i];
23582 \newline
23583 iTemp.c = 10;
23584 \newline
23585 iTemp.d = 11;
23586 \layout Standard
23587
23588 The compiler will try to keep these temporary variables in registers.
23589 \layout Subsection
23590
23591 Dead-Code Elimination
23592 \begin_inset LatexCommand \index{Dead-code elimination}
23593
23594 \end_inset
23595
23596
23597 \layout Verse
23598
23599
23600 \family typewriter
23601 int global;
23602 \newline
23603
23604 \newline
23605 void f () {
23606 \newline
23607 \SpecialChar ~
23608 \SpecialChar ~
23609 int i;
23610 \newline
23611 \SpecialChar ~
23612 \SpecialChar ~
23613 i = 1; \SpecialChar ~
23614 \SpecialChar ~
23615 \SpecialChar ~
23616 \SpecialChar ~
23617 \SpecialChar ~
23618 /* dead store */
23619 \newline
23620 \SpecialChar ~
23621 \SpecialChar ~
23622 global = 1;\SpecialChar ~
23623 /* dead store */
23624 \newline
23625 \SpecialChar ~
23626 \SpecialChar ~
23627 global = 2;
23628 \newline
23629 \SpecialChar ~
23630 \SpecialChar ~
23631 return;
23632 \newline
23633 \SpecialChar ~
23634 \SpecialChar ~
23635 global = 3;\SpecialChar ~
23636 /* unreachable */
23637 \newline
23638 }
23639 \layout Standard
23640
23641 will be changed to
23642 \layout Verse
23643
23644
23645 \family typewriter
23646 int global;
23647 \newline
23648
23649 \newline
23650 void f () {
23651 \newline
23652 \SpecialChar ~
23653 \SpecialChar ~
23654 global = 2;
23655 \newline
23656 }
23657 \layout Subsection
23658
23659 Copy-Propagation
23660 \begin_inset LatexCommand \index{Copy propagation}
23661
23662 \end_inset
23663
23664
23665 \layout Verse
23666
23667
23668 \family typewriter
23669 int f() {
23670 \newline
23671 \SpecialChar ~
23672 \SpecialChar ~
23673 int i, j;
23674 \newline
23675 \SpecialChar ~
23676 \SpecialChar ~
23677 i = 10;
23678 \newline
23679 \SpecialChar ~
23680 \SpecialChar ~
23681 j = i;
23682 \newline
23683 \SpecialChar ~
23684 \SpecialChar ~
23685 return j;
23686 \newline
23687 }
23688 \layout Standard
23689
23690 will be changed to
23691 \layout Verse
23692
23693
23694 \family typewriter
23695 int f() {
23696 \newline
23697 \SpecialChar ~
23698 \SpecialChar ~
23699 int i, j;
23700 \newline
23701 \SpecialChar ~
23702 \SpecialChar ~
23703 i = 10;
23704 \newline
23705 \SpecialChar ~
23706 \SpecialChar ~
23707 j = 10;
23708 \newline
23709 \SpecialChar ~
23710 \SpecialChar ~
23711 return 10;
23712 \newline
23713 }
23714 \layout Standard
23715
23716 Note: the dead stores created by this copy propagation will be eliminated
23717  by dead-code elimination.
23718 \layout Subsection
23719
23720 Loop Optimizations
23721 \begin_inset LatexCommand \index{Loop optimization}
23722
23723 \end_inset
23724
23725
23726 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
23727
23728 \end_inset
23729
23730
23731 \layout Standard
23732
23733 Two types of loop optimizations are done by SDCC
23734 \emph on
23735 loop invariant
23736 \emph default
23737  lifting and
23738 \emph on
23739  strength reduction
23740 \emph default
23741  of loop induction variables.
23742  In addition to the strength reduction the optimizer marks the induction
23743  variables and the register allocator tries to keep the induction variables
23744  in registers for the duration of the loop.
23745  Because of this preference of the register allocator
23746 \begin_inset LatexCommand \index{Register allocation}
23747
23748 \end_inset
23749
23750 , loop induction optimization causes an increase in register pressure, which
23751  may cause unwanted spilling of other temporary variables into the stack
23752 \begin_inset LatexCommand \index{stack}
23753
23754 \end_inset
23755
23756  / data space.
23757  The compiler will generate a warning message when it is forced to allocate
23758  extra space either on the stack or data space.
23759  If this extra space allocation is undesirable then induction optimization
23760  can be eliminated either for the entire source file (with -
23761 \begin_inset ERT
23762 status Collapsed
23763
23764 \layout Standard
23765
23766 \backslash
23767 /
23768 \end_inset
23769
23770 -noinduction option) or for a given function only using #pragma\SpecialChar ~
23771 noinduction
23772 \begin_inset LatexCommand \index{\#pragma noinduction}
23773
23774 \end_inset
23775
23776 .
23777 \newline
23778
23779 \newline
23780 Loop Invariant:
23781 \layout Verse
23782
23783
23784 \family typewriter
23785 for (i = 0 ; i < 100 ; i ++)
23786 \newline
23787 \SpecialChar ~
23788 \SpecialChar ~
23789 \SpecialChar ~
23790 \SpecialChar ~
23791 f += k + l;
23792 \layout Standard
23793
23794 changed to
23795 \layout Verse
23796
23797
23798 \family typewriter
23799 itemp = k + l;
23800 \newline
23801 for (i = 0; i < 100; i++)
23802 \newline
23803 \SpecialChar ~
23804 \SpecialChar ~
23805 \SpecialChar ~
23806 \SpecialChar ~
23807 f += itemp;
23808 \layout Standard
23809
23810 As mentioned previously some loop invariants are not as apparent, all static
23811  address computations are also moved out of the loop.
23812 \newline
23813
23814 \newline
23815 Strength Reduction
23816 \begin_inset LatexCommand \index{Strength reduction}
23817
23818 \end_inset
23819
23820 , this optimization substitutes an expression by a cheaper expression:
23821 \layout Verse
23822
23823
23824 \family typewriter
23825 for (i=0;i < 100; i++)
23826 \newline
23827 \SpecialChar ~
23828 \SpecialChar ~
23829 \SpecialChar ~
23830 \SpecialChar ~
23831 ar[i*5] = i*3;
23832 \layout Standard
23833
23834 changed to
23835 \layout Verse
23836
23837
23838 \family typewriter
23839 itemp1 = 0;
23840 \newline
23841 itemp2 = 0;
23842 \newline
23843 for (i=0;i< 100;i++) {
23844 \newline
23845 \SpecialChar ~
23846 \SpecialChar ~
23847 \SpecialChar ~
23848 \SpecialChar ~
23849 ar[itemp1] = itemp2;
23850 \newline
23851 \SpecialChar ~
23852 \SpecialChar ~
23853 \SpecialChar ~
23854 \SpecialChar ~
23855 itemp1 += 5;
23856 \newline
23857 \SpecialChar ~
23858 \SpecialChar ~
23859 \SpecialChar ~
23860 \SpecialChar ~
23861 itemp2 += 3;
23862 \newline
23863 }
23864 \layout Standard
23865
23866 The more expensive multiplication
23867 \begin_inset LatexCommand \index{Multiplication}
23868
23869 \end_inset
23870
23871  is changed to a less expensive addition.
23872 \layout Subsection
23873
23874 Loop Reversing
23875 \begin_inset LatexCommand \index{Loop reversing}
23876
23877 \end_inset
23878
23879
23880 \layout Standard
23881
23882 This optimization is done to reduce the overhead of checking loop boundaries
23883  for every iteration.
23884  Some simple loops can be reversed and implemented using a
23885 \begin_inset Quotes eld
23886 \end_inset
23887
23888 decrement and jump if not zero
23889 \begin_inset Quotes erd
23890 \end_inset
23891
23892  instruction.
23893  SDCC checks for the following criterion to determine if a loop is reversible
23894  (note: more sophisticated compilers use data-dependency analysis to make
23895  this determination, SDCC uses a more simple minded analysis).
23896 \layout Itemize
23897
23898 The 'for' loop is of the form
23899 \newline
23900
23901 \newline
23902
23903 \family typewriter
23904 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
23905  += 1])
23906 \newline
23907 \SpecialChar ~
23908 \SpecialChar ~
23909 \SpecialChar ~
23910 \SpecialChar ~
23911 <for body>
23912 \layout Itemize
23913
23914 The <for body> does not contain
23915 \begin_inset Quotes eld
23916 \end_inset
23917
23918 continue
23919 \begin_inset Quotes erd
23920 \end_inset
23921
23922  or 'break
23923 \begin_inset Quotes erd
23924 \end_inset
23925
23926 .
23927 \layout Itemize
23928
23929 All goto's are contained within the loop.
23930 \layout Itemize
23931
23932 No function calls within the loop.
23933 \layout Itemize
23934
23935 The loop control variable <sym> is not assigned any value within the loop
23936 \layout Itemize
23937
23938 The loop control variable does NOT participate in any arithmetic operation
23939  within the loop.
23940 \layout Itemize
23941
23942 There are NO switch statements in the loop.
23943 \layout Subsection
23944
23945 Algebraic Simplifications
23946 \layout Standard
23947
23948 SDCC does numerous algebraic simplifications, the following is a small sub-set
23949  of these optimizations.
23950 \layout Verse
23951
23952
23953 \family typewriter
23954 i = j + 0;\SpecialChar ~
23955 \SpecialChar ~
23956 \SpecialChar ~
23957 \SpecialChar ~
23958  /* changed to: */\SpecialChar ~
23959 \SpecialChar ~
23960 \SpecialChar ~
23961 \SpecialChar ~
23962  i = j;
23963 \newline
23964 i /= 2;\SpecialChar ~
23965 \SpecialChar ~
23966 \SpecialChar ~
23967 \SpecialChar ~
23968 \SpecialChar ~
23969 \SpecialChar ~
23970 \SpecialChar ~
23971  /* changed to: */\SpecialChar ~
23972 \SpecialChar ~
23973 \SpecialChar ~
23974 \SpecialChar ~
23975  i >>= 1;
23976 \newline
23977 i = j - j;\SpecialChar ~
23978 \SpecialChar ~
23979 \SpecialChar ~
23980 \SpecialChar ~
23981  /* changed to: */\SpecialChar ~
23982 \SpecialChar ~
23983 \SpecialChar ~
23984 \SpecialChar ~
23985  i = 0;
23986 \newline
23987 i = j / 1;\SpecialChar ~
23988 \SpecialChar ~
23989 \SpecialChar ~
23990 \SpecialChar ~
23991  /* changed to: */\SpecialChar ~
23992 \SpecialChar ~
23993 \SpecialChar ~
23994 \SpecialChar ~
23995  i = j;
23996 \layout Standard
23997
23998 Note the subexpressions
23999 \begin_inset LatexCommand \index{Subexpression}
24000
24001 \end_inset
24002
24003  given above are generally introduced by macro expansions or as a result
24004  of copy/constant propagation.
24005 \layout Subsection
24006
24007 'switch' Statements
24008 \begin_inset LatexCommand \label{sub:'switch'-Statements}
24009
24010 \end_inset
24011
24012
24013 \begin_inset LatexCommand \index{switch statement}
24014
24015 \end_inset
24016
24017
24018 \layout Standard
24019
24020 SDCC can optimize switch statements to jump tables
24021 \begin_inset LatexCommand \index{jump tables}
24022
24023 \end_inset
24024
24025 .
24026  It makes the decision based on an estimate of the generated code size.
24027  SDCC is quite liberal in the requirements for jump table generation:
24028 \layout Itemize
24029
24030 The labels need not be in order, and the starting number need not be one
24031  or zero, the case labels are in numerical sequence or not too many case
24032  labels are missing.
24033 \begin_deeper
24034 \layout Verse
24035
24036
24037 \family typewriter
24038 switch(i) {\SpecialChar ~
24039 \SpecialChar ~
24040 \SpecialChar ~
24041 \SpecialChar ~
24042 \SpecialChar ~
24043 \SpecialChar ~
24044 \SpecialChar ~
24045 \SpecialChar ~
24046 \SpecialChar ~
24047 \SpecialChar ~
24048 \SpecialChar ~
24049 \SpecialChar ~
24050 \SpecialChar ~
24051 \SpecialChar ~
24052 \SpecialChar ~
24053 \SpecialChar ~
24054 \SpecialChar ~
24055 \SpecialChar ~
24056 \SpecialChar ~
24057 \SpecialChar ~
24058 \SpecialChar ~
24059 \SpecialChar ~
24060 \SpecialChar ~
24061 \SpecialChar ~
24062 \SpecialChar ~
24063 \SpecialChar ~
24064 switch (i) {
24065 \newline
24066 \SpecialChar ~
24067 \SpecialChar ~
24068 \SpecialChar ~
24069 case 4: ...\SpecialChar ~
24070 \SpecialChar ~
24071 \SpecialChar ~
24072 \SpecialChar ~
24073 \SpecialChar ~
24074 \SpecialChar ~
24075 \SpecialChar ~
24076 \SpecialChar ~
24077 \SpecialChar ~
24078 \SpecialChar ~
24079 \SpecialChar ~
24080 \SpecialChar ~
24081 \SpecialChar ~
24082 \SpecialChar ~
24083 \SpecialChar ~
24084 \SpecialChar ~
24085 \SpecialChar ~
24086 \SpecialChar ~
24087 \SpecialChar ~
24088 \SpecialChar ~
24089 \SpecialChar ~
24090 \SpecialChar ~
24091 \SpecialChar ~
24092 \SpecialChar ~
24093 \SpecialChar ~
24094 \SpecialChar ~
24095 case 0: ...
24096
24097 \newline
24098 \SpecialChar ~
24099 \SpecialChar ~
24100 \SpecialChar ~
24101 case 5: ...\SpecialChar ~
24102 \SpecialChar ~
24103 \SpecialChar ~
24104 \SpecialChar ~
24105 \SpecialChar ~
24106 \SpecialChar ~
24107 \SpecialChar ~
24108 \SpecialChar ~
24109 \SpecialChar ~
24110 \SpecialChar ~
24111 \SpecialChar ~
24112 \SpecialChar ~
24113 \SpecialChar ~
24114 \SpecialChar ~
24115 \SpecialChar ~
24116 \SpecialChar ~
24117 \SpecialChar ~
24118 \SpecialChar ~
24119 \SpecialChar ~
24120 \SpecialChar ~
24121 \SpecialChar ~
24122 \SpecialChar ~
24123 \SpecialChar ~
24124 \SpecialChar ~
24125 \SpecialChar ~
24126 \SpecialChar ~
24127 case 1: ...
24128
24129 \newline
24130 \SpecialChar ~
24131 \SpecialChar ~
24132 \SpecialChar ~
24133 case 3: ...\SpecialChar ~
24134 \SpecialChar ~
24135 \SpecialChar ~
24136 \SpecialChar ~
24137 \SpecialChar ~
24138 \SpecialChar ~
24139 \SpecialChar ~
24140 \SpecialChar ~
24141 \SpecialChar ~
24142 \SpecialChar ~
24143 \SpecialChar ~
24144 \SpecialChar ~
24145 \SpecialChar ~
24146 \SpecialChar ~
24147 \SpecialChar ~
24148 \SpecialChar ~
24149 \SpecialChar ~
24150 \SpecialChar ~
24151 \SpecialChar ~
24152 \SpecialChar ~
24153 \SpecialChar ~
24154 \SpecialChar ~
24155 \SpecialChar ~
24156 \SpecialChar ~
24157 \SpecialChar ~
24158 \SpecialChar ~
24159
24160 \newline
24161 \SpecialChar ~
24162 \SpecialChar ~
24163 \SpecialChar ~
24164 case 6: ...\SpecialChar ~
24165 \SpecialChar ~
24166 \SpecialChar ~
24167 \SpecialChar ~
24168 \SpecialChar ~
24169 \SpecialChar ~
24170 \SpecialChar ~
24171 \SpecialChar ~
24172 \SpecialChar ~
24173 \SpecialChar ~
24174 \SpecialChar ~
24175 \SpecialChar ~
24176 \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 case 3: ...
24191
24192 \newline
24193 \SpecialChar ~
24194 \SpecialChar ~
24195 \SpecialChar ~
24196 case 7: ...\SpecialChar ~
24197 \SpecialChar ~
24198 \SpecialChar ~
24199 \SpecialChar ~
24200 \SpecialChar ~
24201 \SpecialChar ~
24202 \SpecialChar ~
24203 \SpecialChar ~
24204 \SpecialChar ~
24205 \SpecialChar ~
24206 \SpecialChar ~
24207 \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 case 4: ...
24223
24224 \newline
24225 \SpecialChar ~
24226 \SpecialChar ~
24227 \SpecialChar ~
24228 case 8: ...\SpecialChar ~
24229 \SpecialChar ~
24230 \SpecialChar ~
24231 \SpecialChar ~
24232 \SpecialChar ~
24233 \SpecialChar ~
24234 \SpecialChar ~
24235 \SpecialChar ~
24236 \SpecialChar ~
24237 \SpecialChar ~
24238 \SpecialChar ~
24239 \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 case 5: ...
24255
24256 \newline
24257 \SpecialChar ~
24258 \SpecialChar ~
24259 \SpecialChar ~
24260 case 9: ...\SpecialChar ~
24261 \SpecialChar ~
24262 \SpecialChar ~
24263 \SpecialChar ~
24264 \SpecialChar ~
24265 \SpecialChar ~
24266 \SpecialChar ~
24267 \SpecialChar ~
24268 \SpecialChar ~
24269 \SpecialChar ~
24270 \SpecialChar ~
24271 \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 case 6: ...
24287
24288 \newline
24289 \SpecialChar ~
24290 \SpecialChar ~
24291 \SpecialChar ~
24292 case 10: ...\SpecialChar ~
24293 \SpecialChar ~
24294 \SpecialChar ~
24295 \SpecialChar ~
24296 \SpecialChar ~
24297 \SpecialChar ~
24298 \SpecialChar ~
24299 \SpecialChar ~
24300 \SpecialChar ~
24301 \SpecialChar ~
24302 \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 case 7: ...
24318
24319 \newline
24320 \SpecialChar ~
24321 \SpecialChar ~
24322 \SpecialChar ~
24323 case 11: ...\SpecialChar ~
24324 \SpecialChar ~
24325 \SpecialChar ~
24326 \SpecialChar ~
24327 \SpecialChar ~
24328 \SpecialChar ~
24329 \SpecialChar ~
24330 \SpecialChar ~
24331 \SpecialChar ~
24332 \SpecialChar ~
24333 \SpecialChar ~
24334 \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 case 8: ...
24349
24350 \newline
24351 }\SpecialChar ~
24352 \SpecialChar ~
24353 \SpecialChar ~
24354 \SpecialChar ~
24355 \SpecialChar ~
24356 \SpecialChar ~
24357 \SpecialChar ~
24358 \SpecialChar ~
24359 \SpecialChar ~
24360 \SpecialChar ~
24361 \SpecialChar ~
24362 \SpecialChar ~
24363 \SpecialChar ~
24364 \SpecialChar ~
24365 \SpecialChar ~
24366 \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 }
24388 \layout Standard
24389
24390 Both the above switch statements will be implemented using a jump-table.
24391  The example to the right side is slightly more efficient as the check for
24392  the lower boundary of the jump-table is not needed.
24393 \end_deeper
24394 \layout Itemize
24395
24396 The number of case labels is not larger than supported by the target architectur
24397 e.
24398 \layout Itemize
24399
24400 If the case labels are not in numerical sequence ('gaps' between cases)
24401  SDCC checks whether a jump table with additionally inserted dummy cases
24402  is still attractive.
24403
24404 \layout Itemize
24405
24406 If the starting number is not zero and a check for the lower boundary of
24407  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
24408  ...
24409  .
24410 \layout Standard
24411
24412 Switch statements which have large gaps in the numeric sequence or those
24413  that have too many case labels can be split into more than one switch statement
24414  for efficient code generation, e.g.:
24415 \layout Verse
24416
24417
24418 \family typewriter
24419 switch (i) {
24420 \newline
24421 \SpecialChar ~
24422 \SpecialChar ~
24423 case 1: ...
24424
24425 \newline
24426 \SpecialChar ~
24427 \SpecialChar ~
24428 case 2: ...
24429
24430 \newline
24431 \SpecialChar ~
24432 \SpecialChar ~
24433 case 3: ...
24434
24435 \newline
24436 \SpecialChar ~
24437 \SpecialChar ~
24438 case 4: ...
24439
24440 \newline
24441 \SpecialChar ~
24442 \SpecialChar ~
24443 case 5: ...
24444
24445 \newline
24446 \SpecialChar ~
24447 \SpecialChar ~
24448 case 6: ...
24449
24450 \newline
24451 \SpecialChar ~
24452 \SpecialChar ~
24453 case 7: ...
24454
24455 \newline
24456 \SpecialChar ~
24457 \SpecialChar ~
24458 case 101: ...
24459
24460 \newline
24461 \SpecialChar ~
24462 \SpecialChar ~
24463 case 102: ...
24464
24465 \newline
24466 \SpecialChar ~
24467 \SpecialChar ~
24468 case 103: ...
24469
24470 \newline
24471 \SpecialChar ~
24472 \SpecialChar ~
24473 case 104: ...
24474
24475 \newline
24476 \SpecialChar ~
24477 \SpecialChar ~
24478 case 105: ...
24479
24480 \newline
24481 \SpecialChar ~
24482 \SpecialChar ~
24483 case 106: ...
24484
24485 \newline
24486 \SpecialChar ~
24487 \SpecialChar ~
24488 case 107: ...
24489
24490 \newline
24491 }
24492 \layout Standard
24493
24494 If the above switch statement is broken down into two switch statements
24495 \layout Verse
24496
24497
24498 \family typewriter
24499 switch (i) {
24500 \newline
24501 \SpecialChar ~
24502 \SpecialChar ~
24503 case 1: ...
24504
24505 \newline
24506 \SpecialChar ~
24507 \SpecialChar ~
24508 case 2: ...
24509
24510 \newline
24511 \SpecialChar ~
24512 \SpecialChar ~
24513 case 3: ...
24514
24515 \newline
24516 \SpecialChar ~
24517 \SpecialChar ~
24518 case 4: ...
24519
24520 \newline
24521 \SpecialChar ~
24522 \SpecialChar ~
24523 case 5: ...
24524
24525 \newline
24526 \SpecialChar ~
24527 \SpecialChar ~
24528 case 6: ...
24529
24530 \newline
24531 \SpecialChar ~
24532 \SpecialChar ~
24533 case 7: ...
24534
24535 \newline
24536 }
24537 \layout Standard
24538
24539 and
24540 \layout Verse
24541
24542
24543 \family typewriter
24544 switch (i) {
24545 \newline
24546 \SpecialChar ~
24547 \SpecialChar ~
24548 case 101: ...
24549
24550 \newline
24551 \SpecialChar ~
24552 \SpecialChar ~
24553 case 102: ...
24554
24555 \newline
24556 \SpecialChar ~
24557 \SpecialChar ~
24558 case 103: ...
24559
24560 \newline
24561 \SpecialChar ~
24562 \SpecialChar ~
24563 case 104: ...
24564
24565 \newline
24566 \SpecialChar ~
24567 \SpecialChar ~
24568 case 105: ...
24569
24570 \newline
24571 \SpecialChar ~
24572 \SpecialChar ~
24573 case 106: ...
24574
24575 \newline
24576 \SpecialChar ~
24577 \SpecialChar ~
24578 case 107: ...
24579
24580 \newline
24581 }
24582 \layout Standard
24583
24584 then both the switch statements will be implemented using jump-tables whereas
24585  the unmodified switch statement will not be.
24586 \layout Comment
24587
24588 There might be reasons which SDCC cannot know about to either favour or
24589  not favour jump tables.
24590  If the target system has to be as quick for the last switch case as for
24591  the first (pro jump table), or if the switch argument is known to be zero
24592  in the majority of the cases (contra jump table).
24593 \layout Standard
24594
24595 The pragma nojtbound
24596 \begin_inset LatexCommand \index{\#pragma nojtbound}
24597
24598 \end_inset
24599
24600  can be used to turn off checking the
24601 \emph on
24602 j
24603 \emph default
24604 ump
24605 \emph on
24606 t
24607 \emph default
24608 able
24609 \emph on
24610 bound
24611 \emph default
24612 aries.
24613  It has no effect if a default label is supplied.
24614  Use of this pragma is dangerous: if the switch
24615 \begin_inset LatexCommand \index{switch statement}
24616
24617 \end_inset
24618
24619  argument is not matched by a case statement the processor will happily
24620  jump into Nirvana.
24621 \layout Subsection
24622
24623 Bit-shifting Operations
24624 \begin_inset LatexCommand \index{Bit shifting}
24625
24626 \end_inset
24627
24628 .
24629 \layout Standard
24630
24631 Bit shifting is one of the most frequently used operation in embedded programmin
24632 g.
24633  SDCC tries to implement bit-shift operations in the most efficient way
24634  possible, e.g.:
24635 \layout Verse
24636
24637
24638 \family typewriter
24639 unsigned char i;
24640 \newline
24641 ...
24642
24643 \newline
24644 i >>= 4;
24645 \newline
24646 ...
24647 \layout Standard
24648
24649 generates the following code:
24650 \layout Verse
24651
24652
24653 \family typewriter
24654 mov\SpecialChar ~
24655  a,_i
24656 \newline
24657 swap a
24658 \newline
24659 anl\SpecialChar ~
24660  a,#0x0f
24661 \newline
24662 mov\SpecialChar ~
24663  _i,a
24664 \layout Standard
24665
24666 In general SDCC will never setup a loop if the shift count is known.
24667  Another example:
24668 \layout Verse
24669
24670
24671 \family typewriter
24672 unsigned int i;
24673 \newline
24674 ...
24675
24676 \newline
24677 i >>= 9;
24678 \newline
24679 ...
24680 \layout Standard
24681
24682 will generate:
24683 \layout Verse
24684
24685
24686 \family typewriter
24687 mov\SpecialChar ~
24688 \SpecialChar ~
24689 a,(_i + 1)
24690 \newline
24691 mov\SpecialChar ~
24692 \SpecialChar ~
24693 (_i + 1),#0x00
24694 \newline
24695 clr\SpecialChar ~
24696 \SpecialChar ~
24697 c
24698 \newline
24699 rrc\SpecialChar ~
24700 \SpecialChar ~
24701 a
24702 \newline
24703 mov\SpecialChar ~
24704 \SpecialChar ~
24705 _i,a
24706 \layout Subsection
24707
24708 Bit-rotation
24709 \begin_inset LatexCommand \index{Bit rotation}
24710
24711 \end_inset
24712
24713
24714 \layout Standard
24715
24716 A special case of the bit-shift operation is bit rotation
24717 \begin_inset LatexCommand \index{rotating bits}
24718
24719 \end_inset
24720
24721 , SDCC recognizes the following expression to be a left bit-rotation:
24722 \layout Verse
24723
24724
24725 \family typewriter
24726 \series bold
24727 unsigned
24728 \series default
24729 \SpecialChar ~
24730 \SpecialChar ~
24731 char i;\SpecialChar ~
24732 \SpecialChar ~
24733 \SpecialChar ~
24734 \SpecialChar ~
24735 \SpecialChar ~
24736 \SpecialChar ~
24737 \SpecialChar ~
24738 \SpecialChar ~
24739 \SpecialChar ~
24740 \SpecialChar ~
24741 \SpecialChar ~
24742 /* unsigned is needed for rotation */
24743 \newline
24744 ...
24745
24746 \newline
24747 i = ((i << 1) | (i >> 7));
24748 \family default
24749
24750 \newline
24751
24752 \family typewriter
24753 ...
24754 \layout Standard
24755
24756 will generate the following code:
24757 \layout Verse
24758
24759
24760 \family typewriter
24761 mov\SpecialChar ~
24762 \SpecialChar ~
24763 a,_i
24764 \newline
24765 rl\SpecialChar ~
24766 \SpecialChar ~
24767 \SpecialChar ~
24768 a
24769 \newline
24770 mov\SpecialChar ~
24771 \SpecialChar ~
24772 _i,a
24773 \layout Standard
24774
24775 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
24776 ns of this case will also be recognized as bit-rotation, i.e.:
24777 \layout Verse
24778
24779
24780 \family typewriter
24781 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
24782 \layout Subsection
24783
24784 Nibble and Byte Swapping
24785 \layout Standard
24786
24787 Other special cases of the bit-shift operations are nibble or byte swapping
24788 \begin_inset LatexCommand \index{swapping nibbles/bytes}
24789
24790 \end_inset
24791
24792 , SDCC recognizes the following expressions:
24793 \layout Verse
24794
24795
24796 \family typewriter
24797 \series bold
24798 unsigned
24799 \series default
24800 \SpecialChar ~
24801 \SpecialChar ~
24802 char i;
24803 \newline
24804
24805 \series bold
24806 unsigned
24807 \series default
24808 \SpecialChar ~
24809 \SpecialChar ~
24810 int j;
24811 \newline
24812 ...
24813
24814 \newline
24815 i = ((i << 4) | (i >> 4));
24816 \family default
24817
24818 \newline
24819
24820 \family typewriter
24821 j = ((j << 8) | (j >> 8));
24822 \layout Standard
24823
24824 and generates a swap instruction for the nibble swapping
24825 \begin_inset LatexCommand \index{Nibble swapping}
24826
24827 \end_inset
24828
24829  or move instructions for the byte swapping
24830 \begin_inset LatexCommand \index{Byte swapping}
24831
24832 \end_inset
24833
24834 .
24835  The
24836 \begin_inset Quotes sld
24837 \end_inset
24838
24839 j
24840 \begin_inset Quotes srd
24841 \end_inset
24842
24843  example can be used to convert from little to big-endian or vice versa.
24844  If you want to change the endianness of a
24845 \emph on
24846 signed
24847 \emph default
24848  integer you have to cast to
24849 \family typewriter
24850 (unsigned int)
24851 \family default
24852  first.
24853 \layout Standard
24854
24855 Note that SDCC stores numbers in little-endian
24856 \begin_inset Foot
24857 collapsed false
24858
24859 \layout Standard
24860
24861 Usually 8-bit processors don't care much about endianness.
24862  This is not the case for the standard 8051 which only has an instruction
24863  to increment its
24864 \emph on
24865 dptr
24866 \emph default
24867
24868 \begin_inset LatexCommand \index{DPTR}
24869
24870 \end_inset
24871
24872 -datapointer
24873 \emph on
24874
24875 \emph default
24876 so little-endian is the more efficient byte order.
24877 \end_inset
24878
24879
24880 \begin_inset LatexCommand \index{little-endian}
24881
24882 \end_inset
24883
24884
24885 \begin_inset LatexCommand \index{Endianness}
24886
24887 \end_inset
24888
24889  format (i.e.
24890  lowest order first).
24891 \layout Subsection
24892
24893 Highest Order Bit
24894 \begin_inset LatexCommand \index{Highest Order Bit}
24895
24896 \end_inset
24897
24898  / Any Order Bit
24899 \begin_inset LatexCommand \index{Any Order Bit}
24900
24901 \end_inset
24902
24903
24904 \layout Standard
24905
24906 It is frequently required to obtain the highest order bit of an integral
24907  type (long, int, short or char types).
24908  Also obtaining any other order bit is not uncommon.
24909  SDCC recognizes the following expressions to yield the highest order bit
24910  and generates optimized code for it, e.g.:
24911 \layout Verse
24912
24913
24914 \family typewriter
24915 unsigned int gint;
24916 \newline
24917
24918 \newline
24919 foo () {
24920 \newline
24921 \SpecialChar ~
24922 \SpecialChar ~
24923 unsigned char hob1, aob1;
24924 \newline
24925 \SpecialChar ~
24926 \SpecialChar ~
24927 bit hob2, hob3, aob2, aob3;
24928 \newline
24929 \SpecialChar ~
24930 \SpecialChar ~
24931 ...
24932
24933 \newline
24934 \SpecialChar ~
24935 \SpecialChar ~
24936 hob1 = (gint >> 15) & 1;
24937 \newline
24938 \SpecialChar ~
24939 \SpecialChar ~
24940 hob2 = (gint >> 15) & 1;
24941 \newline
24942 \SpecialChar ~
24943 \SpecialChar ~
24944 hob3 = gint & 0x8000;
24945 \newline
24946 \SpecialChar ~
24947 \SpecialChar ~
24948 aob1 = (gint >> 9) & 1;
24949 \newline
24950 \SpecialChar ~
24951 \SpecialChar ~
24952 aob2 = (gint >> 8) & 1;
24953 \newline
24954 \SpecialChar ~
24955 \SpecialChar ~
24956 aob3 = gint & 0x0800;
24957 \newline
24958 \SpecialChar ~
24959 \SpecialChar ~
24960 ..
24961
24962 \newline
24963 }
24964 \layout Standard
24965
24966 will generate the following code:
24967 \layout Verse
24968
24969
24970 \family typewriter
24971 \SpecialChar ~
24972 \SpecialChar ~
24973 \SpecialChar ~
24974 \SpecialChar ~
24975 \SpecialChar ~
24976 \SpecialChar ~
24977 \SpecialChar ~
24978 \SpecialChar ~
24979 \SpecialChar ~
24980 \SpecialChar ~
24981 \SpecialChar ~
24982 \SpecialChar ~
24983 \SpecialChar ~
24984 \SpecialChar ~
24985 \SpecialChar ~
24986 \SpecialChar ~
24987 \SpecialChar ~
24988 \SpecialChar ~
24989 \SpecialChar ~
24990 \SpecialChar ~
24991 \SpecialChar ~
24992 \SpecialChar ~
24993 \SpecialChar ~
24994 \SpecialChar ~
24995 \SpecialChar ~
24996  61 ;\SpecialChar ~
24997  hob.c 7
24998 \newline
24999 000A E5*01\SpecialChar ~
25000 \SpecialChar ~
25001 \SpecialChar ~
25002 \SpecialChar ~
25003 \SpecialChar ~
25004 \SpecialChar ~
25005 \SpecialChar ~
25006 \SpecialChar ~
25007 \SpecialChar ~
25008 \SpecialChar ~
25009 \SpecialChar ~
25010 \SpecialChar ~
25011 \SpecialChar ~
25012 \SpecialChar ~
25013 \SpecialChar ~
25014  62\SpecialChar ~
25015 \SpecialChar ~
25016 \SpecialChar ~
25017 \SpecialChar ~
25018 \SpecialChar ~
25019 \SpecialChar ~
25020 \SpecialChar ~
25021 \SpecialChar ~
25022  mov\SpecialChar ~
25023 \SpecialChar ~
25024  a,(_gint + 1)
25025 \newline
25026 000C 23\SpecialChar ~
25027 \SpecialChar ~
25028 \SpecialChar ~
25029 \SpecialChar ~
25030 \SpecialChar ~
25031 \SpecialChar ~
25032 \SpecialChar ~
25033 \SpecialChar ~
25034 \SpecialChar ~
25035 \SpecialChar ~
25036 \SpecialChar ~
25037 \SpecialChar ~
25038 \SpecialChar ~
25039 \SpecialChar ~
25040 \SpecialChar ~
25041 \SpecialChar ~
25042 \SpecialChar ~
25043 \SpecialChar ~
25044  63\SpecialChar ~
25045 \SpecialChar ~
25046 \SpecialChar ~
25047 \SpecialChar ~
25048 \SpecialChar ~
25049 \SpecialChar ~
25050 \SpecialChar ~
25051 \SpecialChar ~
25052  rl\SpecialChar ~
25053 \SpecialChar ~
25054 \SpecialChar ~
25055  a
25056 \newline
25057 000D 54 01\SpecialChar ~
25058 \SpecialChar ~
25059 \SpecialChar ~
25060 \SpecialChar ~
25061 \SpecialChar ~
25062 \SpecialChar ~
25063 \SpecialChar ~
25064 \SpecialChar ~
25065 \SpecialChar ~
25066 \SpecialChar ~
25067 \SpecialChar ~
25068 \SpecialChar ~
25069 \SpecialChar ~
25070 \SpecialChar ~
25071 \SpecialChar ~
25072  64\SpecialChar ~
25073 \SpecialChar ~
25074 \SpecialChar ~
25075 \SpecialChar ~
25076 \SpecialChar ~
25077 \SpecialChar ~
25078 \SpecialChar ~
25079 \SpecialChar ~
25080  anl\SpecialChar ~
25081 \SpecialChar ~
25082  a,#0x01
25083 \newline
25084 000F F5*02\SpecialChar ~
25085 \SpecialChar ~
25086 \SpecialChar ~
25087 \SpecialChar ~
25088 \SpecialChar ~
25089 \SpecialChar ~
25090 \SpecialChar ~
25091 \SpecialChar ~
25092 \SpecialChar ~
25093 \SpecialChar ~
25094 \SpecialChar ~
25095 \SpecialChar ~
25096 \SpecialChar ~
25097 \SpecialChar ~
25098 \SpecialChar ~
25099  65\SpecialChar ~
25100 \SpecialChar ~
25101 \SpecialChar ~
25102 \SpecialChar ~
25103 \SpecialChar ~
25104 \SpecialChar ~
25105 \SpecialChar ~
25106 \SpecialChar ~
25107  mov\SpecialChar ~
25108 \SpecialChar ~
25109  _foo_hob1_1_1,a
25110 \newline
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 \SpecialChar ~
25135 \SpecialChar ~
25136  66 ;\SpecialChar ~
25137  hob.c 8
25138 \newline
25139 0011 E5*01\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 \SpecialChar ~
25153 \SpecialChar ~
25154  67\SpecialChar ~
25155 \SpecialChar ~
25156 \SpecialChar ~
25157 \SpecialChar ~
25158 \SpecialChar ~
25159 \SpecialChar ~
25160 \SpecialChar ~
25161 \SpecialChar ~
25162  mov\SpecialChar ~
25163 \SpecialChar ~
25164  a,(_gint + 1)
25165 \newline
25166 0013 33\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 \SpecialChar ~
25183 \SpecialChar ~
25184  68\SpecialChar ~
25185 \SpecialChar ~
25186 \SpecialChar ~
25187 \SpecialChar ~
25188 \SpecialChar ~
25189 \SpecialChar ~
25190 \SpecialChar ~
25191 \SpecialChar ~
25192  rlc\SpecialChar ~
25193 \SpecialChar ~
25194  a
25195 \newline
25196 0014 92*00\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 \SpecialChar ~
25211  69\SpecialChar ~
25212 \SpecialChar ~
25213 \SpecialChar ~
25214 \SpecialChar ~
25215 \SpecialChar ~
25216 \SpecialChar ~
25217 \SpecialChar ~
25218 \SpecialChar ~
25219  mov\SpecialChar ~
25220 \SpecialChar ~
25221  _foo_hob2_1_1,c
25222 \newline
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 \SpecialChar ~
25238 \SpecialChar ~
25239 \SpecialChar ~
25240 \SpecialChar ~
25241 \SpecialChar ~
25242 \SpecialChar ~
25243 \SpecialChar ~
25244 \SpecialChar ~
25245 \SpecialChar ~
25246 \SpecialChar ~
25247 \SpecialChar ~
25248  66 ;\SpecialChar ~
25249  hob.c 9
25250 \newline
25251 0016 E5*01\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  67\SpecialChar ~
25267 \SpecialChar ~
25268 \SpecialChar ~
25269 \SpecialChar ~
25270 \SpecialChar ~
25271 \SpecialChar ~
25272 \SpecialChar ~
25273 \SpecialChar ~
25274  mov\SpecialChar ~
25275 \SpecialChar ~
25276  a,(_gint + 1)
25277 \newline
25278 0018 33\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 \SpecialChar ~
25293 \SpecialChar ~
25294 \SpecialChar ~
25295 \SpecialChar ~
25296  68\SpecialChar ~
25297 \SpecialChar ~
25298 \SpecialChar ~
25299 \SpecialChar ~
25300 \SpecialChar ~
25301 \SpecialChar ~
25302 \SpecialChar ~
25303 \SpecialChar ~
25304  rlc\SpecialChar ~
25305 \SpecialChar ~
25306  a
25307 \newline
25308 0019 92*01\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 \SpecialChar ~
25323  69\SpecialChar ~
25324 \SpecialChar ~
25325 \SpecialChar ~
25326 \SpecialChar ~
25327 \SpecialChar ~
25328 \SpecialChar ~
25329 \SpecialChar ~
25330 \SpecialChar ~
25331  mov\SpecialChar ~
25332 \SpecialChar ~
25333  _foo_hob3_1_1,c
25334 \newline
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 \SpecialChar ~
25350 \SpecialChar ~
25351 \SpecialChar ~
25352 \SpecialChar ~
25353 \SpecialChar ~
25354 \SpecialChar ~
25355 \SpecialChar ~
25356 \SpecialChar ~
25357 \SpecialChar ~
25358 \SpecialChar ~
25359 \SpecialChar ~
25360  70 ;\SpecialChar ~
25361  hob.c 10
25362 \newline
25363 001B E5*01\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  71\SpecialChar ~
25379 \SpecialChar ~
25380 \SpecialChar ~
25381 \SpecialChar ~
25382 \SpecialChar ~
25383 \SpecialChar ~
25384 \SpecialChar ~
25385 \SpecialChar ~
25386  mov\SpecialChar ~
25387 \SpecialChar ~
25388  a,(_gint + 1)
25389 \newline
25390 001D 03\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 \SpecialChar ~
25405 \SpecialChar ~
25406 \SpecialChar ~
25407 \SpecialChar ~
25408  72\SpecialChar ~
25409 \SpecialChar ~
25410 \SpecialChar ~
25411 \SpecialChar ~
25412 \SpecialChar ~
25413 \SpecialChar ~
25414 \SpecialChar ~
25415 \SpecialChar ~
25416  rr\SpecialChar ~
25417 \SpecialChar ~
25418 \SpecialChar ~
25419  a
25420 \newline
25421 001E 54 01\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 \SpecialChar ~
25435 \SpecialChar ~
25436  73\SpecialChar ~
25437 \SpecialChar ~
25438 \SpecialChar ~
25439 \SpecialChar ~
25440 \SpecialChar ~
25441 \SpecialChar ~
25442 \SpecialChar ~
25443 \SpecialChar ~
25444  anl\SpecialChar ~
25445 \SpecialChar ~
25446  a,#0x01
25447 \newline
25448 0020 F5*03\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 \SpecialChar ~
25462 \SpecialChar ~
25463  74\SpecialChar ~
25464 \SpecialChar ~
25465 \SpecialChar ~
25466 \SpecialChar ~
25467 \SpecialChar ~
25468 \SpecialChar ~
25469 \SpecialChar ~
25470 \SpecialChar ~
25471  mov\SpecialChar ~
25472 \SpecialChar ~
25473  _foo_aob1_1_1,a
25474 \newline
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 \SpecialChar ~
25499 \SpecialChar ~
25500  75 ;\SpecialChar ~
25501  hob.c 11
25502 \newline
25503 0022 E5*01\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 \SpecialChar ~
25517 \SpecialChar ~
25518  76\SpecialChar ~
25519 \SpecialChar ~
25520 \SpecialChar ~
25521 \SpecialChar ~
25522 \SpecialChar ~
25523 \SpecialChar ~
25524 \SpecialChar ~
25525 \SpecialChar ~
25526  mov\SpecialChar ~
25527 \SpecialChar ~
25528  a,(_gint + 1)
25529 \newline
25530 0024 13\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 \SpecialChar ~
25547 \SpecialChar ~
25548  77\SpecialChar ~
25549 \SpecialChar ~
25550 \SpecialChar ~
25551 \SpecialChar ~
25552 \SpecialChar ~
25553 \SpecialChar ~
25554 \SpecialChar ~
25555 \SpecialChar ~
25556  rrc\SpecialChar ~
25557 \SpecialChar ~
25558  a
25559 \newline
25560 0025 92*02\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 \SpecialChar ~
25575  78\SpecialChar ~
25576 \SpecialChar ~
25577 \SpecialChar ~
25578 \SpecialChar ~
25579 \SpecialChar ~
25580 \SpecialChar ~
25581 \SpecialChar ~
25582 \SpecialChar ~
25583  mov\SpecialChar ~
25584 \SpecialChar ~
25585  _foo_aob2_1_1,c
25586 \newline
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 \SpecialChar ~
25602 \SpecialChar ~
25603 \SpecialChar ~
25604 \SpecialChar ~
25605 \SpecialChar ~
25606 \SpecialChar ~
25607 \SpecialChar ~
25608 \SpecialChar ~
25609 \SpecialChar ~
25610 \SpecialChar ~
25611 \SpecialChar ~
25612  79 ;\SpecialChar ~
25613  hob.c 12
25614 \newline
25615 0027 E5*01\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  80\SpecialChar ~
25631 \SpecialChar ~
25632 \SpecialChar ~
25633 \SpecialChar ~
25634 \SpecialChar ~
25635 \SpecialChar ~
25636 \SpecialChar ~
25637 \SpecialChar ~
25638  mov\SpecialChar ~
25639 \SpecialChar ~
25640  a,(_gint + 1)
25641 \newline
25642 0029 A2 E3\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 \SpecialChar ~
25657  81\SpecialChar ~
25658 \SpecialChar ~
25659 \SpecialChar ~
25660 \SpecialChar ~
25661 \SpecialChar ~
25662 \SpecialChar ~
25663 \SpecialChar ~
25664 \SpecialChar ~
25665  mov\SpecialChar ~
25666 \SpecialChar ~
25667  c,acc[3]
25668 \newline
25669 002B 92*03\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  82\SpecialChar ~
25685 \SpecialChar ~
25686 \SpecialChar ~
25687 \SpecialChar ~
25688 \SpecialChar ~
25689 \SpecialChar ~
25690 \SpecialChar ~
25691 \SpecialChar ~
25692  mov\SpecialChar ~
25693 \SpecialChar ~
25694  _foo_aob3_1_1,c
25695 \layout Standard
25696
25697 Other variations of these cases however will
25698 \emph on
25699 not
25700 \emph default
25701  be recognized.
25702  They are standard C expressions, so I heartily recommend these be the only
25703  way to get the highest order bit, (it is portable).
25704  Of course it will be recognized even if it is embedded in other expressions,
25705  e.g.:
25706 \layout Verse
25707
25708
25709 \family typewriter
25710 xyz = gint + ((gint >> 15) & 1);
25711 \layout Standard
25712
25713 will still be recognized.
25714 \layout Subsection
25715
25716 Higher Order Byte
25717 \begin_inset LatexCommand \index{Higher Order Byte}
25718
25719 \end_inset
25720
25721  / Higher Order Word
25722 \begin_inset LatexCommand \index{Higher Order Word}
25723
25724 \end_inset
25725
25726
25727 \layout Standard
25728
25729 It is also frequently required to obtain a higher order byte or word of
25730  a larger integral type (long, int or short types).
25731  SDCC recognizes the following expressions to yield the higher order byte
25732  or word and generates optimized code for it, e.g.:
25733 \layout Verse
25734
25735
25736 \family typewriter
25737 unsigned int gint;
25738 \newline
25739 unsigned long int glong;
25740 \newline
25741
25742 \newline
25743 foo () {
25744 \newline
25745 \SpecialChar ~
25746 \SpecialChar ~
25747 unsigned char hob1, hob2;
25748 \newline
25749 \SpecialChar ~
25750 \SpecialChar ~
25751 unsigned int how1, how2;
25752 \newline
25753 \SpecialChar ~
25754 \SpecialChar ~
25755 ...
25756
25757 \newline
25758 \SpecialChar ~
25759 \SpecialChar ~
25760 hob1 = (gint >> 8) & 0xFF;
25761 \newline
25762 \SpecialChar ~
25763 \SpecialChar ~
25764 hob2 = glong >> 24;
25765 \newline
25766 \SpecialChar ~
25767 \SpecialChar ~
25768 how1 = (glong >> 16) & 0xFFFF;
25769 \newline
25770 \SpecialChar ~
25771 \SpecialChar ~
25772 how2 = glong >> 8;
25773 \newline
25774 \SpecialChar ~
25775 \SpecialChar ~
25776 ..
25777
25778 \newline
25779 }
25780 \layout Standard
25781
25782 will generate the following code:
25783 \layout Verse
25784
25785
25786 \family typewriter
25787 \SpecialChar ~
25788 \SpecialChar ~
25789 \SpecialChar ~
25790 \SpecialChar ~
25791 \SpecialChar ~
25792 \SpecialChar ~
25793 \SpecialChar ~
25794 \SpecialChar ~
25795 \SpecialChar ~
25796 \SpecialChar ~
25797 \SpecialChar ~
25798 \SpecialChar ~
25799 \SpecialChar ~
25800 \SpecialChar ~
25801 \SpecialChar ~
25802 \SpecialChar ~
25803 \SpecialChar ~
25804 \SpecialChar ~
25805 \SpecialChar ~
25806 \SpecialChar ~
25807 \SpecialChar ~
25808 \SpecialChar ~
25809 \SpecialChar ~
25810 \SpecialChar ~
25811 \SpecialChar ~
25812  91 ;\SpecialChar ~
25813  hob.c 15
25814 \newline
25815 0037 85*01*06\SpecialChar ~
25816 \SpecialChar ~
25817 \SpecialChar ~
25818 \SpecialChar ~
25819 \SpecialChar ~
25820 \SpecialChar ~
25821 \SpecialChar ~
25822 \SpecialChar ~
25823 \SpecialChar ~
25824 \SpecialChar ~
25825 \SpecialChar ~
25826 \SpecialChar ~
25827  92\SpecialChar ~
25828 \SpecialChar ~
25829 \SpecialChar ~
25830 \SpecialChar ~
25831 \SpecialChar ~
25832 \SpecialChar ~
25833 \SpecialChar ~
25834 \SpecialChar ~
25835  mov\SpecialChar ~
25836 \SpecialChar ~
25837  _foo_hob1_1_1,(_gint + 1)
25838 \newline
25839 \SpecialChar ~
25840 \SpecialChar ~
25841 \SpecialChar ~
25842 \SpecialChar ~
25843 \SpecialChar ~
25844 \SpecialChar ~
25845 \SpecialChar ~
25846 \SpecialChar ~
25847 \SpecialChar ~
25848 \SpecialChar ~
25849 \SpecialChar ~
25850 \SpecialChar ~
25851 \SpecialChar ~
25852 \SpecialChar ~
25853 \SpecialChar ~
25854 \SpecialChar ~
25855 \SpecialChar ~
25856 \SpecialChar ~
25857 \SpecialChar ~
25858 \SpecialChar ~
25859 \SpecialChar ~
25860 \SpecialChar ~
25861 \SpecialChar ~
25862 \SpecialChar ~
25863 \SpecialChar ~
25864  93 ;\SpecialChar ~
25865  hob.c 16
25866 \newline
25867 003A 85*05*07\SpecialChar ~
25868 \SpecialChar ~
25869 \SpecialChar ~
25870 \SpecialChar ~
25871 \SpecialChar ~
25872 \SpecialChar ~
25873 \SpecialChar ~
25874 \SpecialChar ~
25875 \SpecialChar ~
25876 \SpecialChar ~
25877 \SpecialChar ~
25878 \SpecialChar ~
25879  94\SpecialChar ~
25880 \SpecialChar ~
25881 \SpecialChar ~
25882 \SpecialChar ~
25883 \SpecialChar ~
25884 \SpecialChar ~
25885 \SpecialChar ~
25886 \SpecialChar ~
25887  mov\SpecialChar ~
25888 \SpecialChar ~
25889  _foo_hob2_1_1,(_glong + 3)
25890 \newline
25891 \SpecialChar ~
25892 \SpecialChar ~
25893 \SpecialChar ~
25894 \SpecialChar ~
25895 \SpecialChar ~
25896 \SpecialChar ~
25897 \SpecialChar ~
25898 \SpecialChar ~
25899 \SpecialChar ~
25900 \SpecialChar ~
25901 \SpecialChar ~
25902 \SpecialChar ~
25903 \SpecialChar ~
25904 \SpecialChar ~
25905 \SpecialChar ~
25906 \SpecialChar ~
25907 \SpecialChar ~
25908 \SpecialChar ~
25909 \SpecialChar ~
25910 \SpecialChar ~
25911 \SpecialChar ~
25912 \SpecialChar ~
25913 \SpecialChar ~
25914 \SpecialChar ~
25915 \SpecialChar ~
25916  95 ;\SpecialChar ~
25917  hob.c 17
25918 \newline
25919 003D 85*04*08\SpecialChar ~
25920 \SpecialChar ~
25921 \SpecialChar ~
25922 \SpecialChar ~
25923 \SpecialChar ~
25924 \SpecialChar ~
25925 \SpecialChar ~
25926 \SpecialChar ~
25927 \SpecialChar ~
25928 \SpecialChar ~
25929 \SpecialChar ~
25930 \SpecialChar ~
25931  96\SpecialChar ~
25932 \SpecialChar ~
25933 \SpecialChar ~
25934 \SpecialChar ~
25935 \SpecialChar ~
25936 \SpecialChar ~
25937 \SpecialChar ~
25938 \SpecialChar ~
25939  mov\SpecialChar ~
25940 \SpecialChar ~
25941  _foo_how1_1_1,(_glong + 2)
25942 \newline
25943 0040 85*05*09\SpecialChar ~
25944 \SpecialChar ~
25945 \SpecialChar ~
25946 \SpecialChar ~
25947 \SpecialChar ~
25948 \SpecialChar ~
25949 \SpecialChar ~
25950 \SpecialChar ~
25951 \SpecialChar ~
25952 \SpecialChar ~
25953 \SpecialChar ~
25954 \SpecialChar ~
25955  97\SpecialChar ~
25956 \SpecialChar ~
25957 \SpecialChar ~
25958 \SpecialChar ~
25959 \SpecialChar ~
25960 \SpecialChar ~
25961 \SpecialChar ~
25962 \SpecialChar ~
25963  mov\SpecialChar ~
25964 \SpecialChar ~
25965  (_foo_how1_1_1 + 1),(_glong + 3)
25966 \newline
25967 0043 85*03*0A\SpecialChar ~
25968 \SpecialChar ~
25969 \SpecialChar ~
25970 \SpecialChar ~
25971 \SpecialChar ~
25972 \SpecialChar ~
25973 \SpecialChar ~
25974 \SpecialChar ~
25975 \SpecialChar ~
25976 \SpecialChar ~
25977 \SpecialChar ~
25978 \SpecialChar ~
25979  98\SpecialChar ~
25980 \SpecialChar ~
25981 \SpecialChar ~
25982 \SpecialChar ~
25983 \SpecialChar ~
25984 \SpecialChar ~
25985 \SpecialChar ~
25986 \SpecialChar ~
25987  mov\SpecialChar ~
25988 \SpecialChar ~
25989  _foo_how2_1_1,(_glong + 1)
25990 \newline
25991 0046 85*04*0B\SpecialChar ~
25992 \SpecialChar ~
25993 \SpecialChar ~
25994 \SpecialChar ~
25995 \SpecialChar ~
25996 \SpecialChar ~
25997 \SpecialChar ~
25998 \SpecialChar ~
25999 \SpecialChar ~
26000 \SpecialChar ~
26001 \SpecialChar ~
26002 \SpecialChar ~
26003  99\SpecialChar ~
26004 \SpecialChar ~
26005 \SpecialChar ~
26006 \SpecialChar ~
26007 \SpecialChar ~
26008 \SpecialChar ~
26009 \SpecialChar ~
26010 \SpecialChar ~
26011  mov\SpecialChar ~
26012 \SpecialChar ~
26013  (_foo_how2_1_1 + 1),(_glong + 2)
26014 \layout Standard
26015
26016 Again, variations of these cases may
26017 \emph on
26018 not
26019 \emph default
26020  be recognized.
26021  They are standard C expressions, so I heartily recommend these be the only
26022  way to get the higher order byte/word, (it is portable).
26023  Of course it will be recognized even if it is embedded in other expressions,
26024  e.g.:
26025 \layout Verse
26026
26027
26028 \family typewriter
26029 xyz = gint + ((gint >> 8) & 0xFF);
26030 \layout Standard
26031
26032 will still be recognized.
26033 \layout Subsection
26034
26035 Peephole Optimizer
26036 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
26037
26038 \end_inset
26039
26040
26041 \begin_inset LatexCommand \index{Peephole optimizer}
26042
26043 \end_inset
26044
26045
26046 \layout Standard
26047
26048 The compiler uses a rule based, pattern matching and re-writing mechanism
26049  for peep-hole optimization.
26050  It is inspired by
26051 \emph on
26052 copt
26053 \emph default
26054  a peep-hole optimizer by Christopher W.
26055  Fraser (cwfraser\SpecialChar ~
26056 @\SpecialChar ~
26057 microsoft.com).
26058  A default set of rules are compiled into the compiler, additional rules
26059  may be added with the
26060 \emph on
26061 -
26062 \begin_inset ERT
26063 status Collapsed
26064
26065 \layout Standard
26066
26067 \backslash
26068 /
26069 \end_inset
26070
26071 -peep-file
26072 \begin_inset LatexCommand \index{-\/-peep-file}
26073
26074 \end_inset
26075
26076  <filename>
26077 \emph default
26078  option.
26079  The rule language is best illustrated with examples.
26080 \layout Verse
26081
26082
26083 \family typewriter
26084 replace {
26085 \newline
26086 \SpecialChar ~
26087 \SpecialChar ~
26088 mov %1,a
26089 \newline
26090 \SpecialChar ~
26091 \SpecialChar ~
26092 mov a,%1
26093 \newline
26094 } by {
26095 \newline
26096 \SpecialChar ~
26097 \SpecialChar ~
26098 mov %1,a
26099 \newline
26100 }
26101 \layout Standard
26102
26103 The above rule will change the following assembly
26104 \begin_inset LatexCommand \index{Assembler routines}
26105
26106 \end_inset
26107
26108  sequence:
26109 \layout Verse
26110
26111
26112 \family typewriter
26113 mov r1,a
26114 \newline
26115 mov a,r1
26116 \layout Standard
26117
26118 to
26119 \layout Verse
26120
26121
26122 \family typewriter
26123 mov r1,a
26124 \layout Standard
26125
26126 Note: All occurrences of a
26127 \emph on
26128 %n
26129 \emph default
26130  (pattern variable) must denote the same string.
26131  With the above rule, the assembly sequence:
26132 \layout Verse
26133
26134
26135 \family typewriter
26136 mov r1,a
26137 \newline
26138 mov a,r2
26139 \layout Standard
26140
26141 will remain unmodified.
26142 \newline
26143
26144 \newline
26145 Other special case optimizations may be added by the user (via
26146 \emph on
26147 -
26148 \begin_inset ERT
26149 status Collapsed
26150
26151 \layout Standard
26152
26153 \backslash
26154 /
26155 \end_inset
26156
26157 -peep-file option
26158 \emph default
26159 ).
26160  E.g.
26161  some variants of the 8051 MCU
26162 \begin_inset LatexCommand \index{MCS51 variants}
26163
26164 \end_inset
26165
26166  allow only
26167 \family typewriter
26168 ajmp
26169 \family default
26170  and
26171 \family typewriter
26172 acall
26173 \family default
26174 .
26175  The following two rules will change all
26176 \family typewriter
26177 ljmp
26178 \family default
26179  and
26180 \family typewriter
26181 lcall
26182 \family default
26183  to
26184 \family typewriter
26185 ajmp
26186 \family default
26187  and
26188 \family typewriter
26189 acall
26190 \layout Verse
26191
26192
26193 \family typewriter
26194 replace { lcall %1 } by { acall %1 }
26195 \newline
26196 replace { ljmp %1 } by { ajmp %1 }
26197 \layout Standard
26198
26199 The
26200 \emph on
26201 inline-assembler code
26202 \emph default
26203  is also passed through the peep hole optimizer, thus the peephole optimizer
26204  can also be used as an assembly level macro expander.
26205  The rules themselves are MCU dependent whereas the rule language infra-structur
26206 e is MCU independent.
26207  Peephole optimization rules for other MCU can be easily programmed using
26208  the rule language.
26209 \newline
26210
26211 \newline
26212 The syntax for a rule is as follows:
26213 \layout Verse
26214
26215
26216 \family typewriter
26217 rule := replace [ restart ] '{' <assembly sequence> '
26218 \backslash
26219 n'
26220 \newline
26221 \SpecialChar ~
26222  \SpecialChar ~
26223  \SpecialChar ~
26224  \SpecialChar ~
26225  \SpecialChar ~
26226  \SpecialChar ~
26227  \SpecialChar ~
26228  \SpecialChar ~
26229  \SpecialChar ~
26230  \SpecialChar ~
26231  \SpecialChar ~
26232  \SpecialChar ~
26233  \SpecialChar ~
26234  \SpecialChar ~
26235  '}' by '{' '
26236 \backslash
26237 n'
26238 \newline
26239 \SpecialChar ~
26240  \SpecialChar ~
26241  \SpecialChar ~
26242  \SpecialChar ~
26243  \SpecialChar ~
26244  \SpecialChar ~
26245  \SpecialChar ~
26246  \SpecialChar ~
26247  \SpecialChar ~
26248  \SpecialChar ~
26249  \SpecialChar ~
26250  \SpecialChar ~
26251  \SpecialChar ~
26252  \SpecialChar ~
26253  \SpecialChar ~
26254  \SpecialChar ~
26255  <assembly sequence> '
26256 \backslash
26257 n'
26258 \newline
26259 \SpecialChar ~
26260  \SpecialChar ~
26261  \SpecialChar ~
26262  \SpecialChar ~
26263  \SpecialChar ~
26264  \SpecialChar ~
26265  \SpecialChar ~
26266  \SpecialChar ~
26267  \SpecialChar ~
26268  \SpecialChar ~
26269  \SpecialChar ~
26270  \SpecialChar ~
26271  \SpecialChar ~
26272  \SpecialChar ~
26273  '}' [if <functionName> ] '
26274 \backslash
26275 n'
26276 \layout Standard
26277
26278 <assembly sequence> := assembly instruction (each instruction including
26279  labels must be on a separate line).
26280 \newline
26281
26282 \newline
26283 The optimizer will apply to the rules one by one from the top in the sequence
26284  of their appearance, it will terminate when all rules are exhausted.
26285  If the 'restart' option is specified, then the optimizer will start matching
26286  the rules again from the top, this option for a rule is expensive (performance)
26287 , it is intended to be used in situations where a transformation will trigger
26288  the same rule again.
26289  An example of this (not a good one, it has side effects) is the following
26290  rule:
26291 \layout Verse
26292
26293
26294 \family typewriter
26295 replace restart {
26296 \newline
26297 \SpecialChar ~
26298 \SpecialChar ~
26299 pop %1
26300 \newline
26301 \SpecialChar ~
26302 \SpecialChar ~
26303 push %1 } by {
26304 \newline
26305 \SpecialChar ~
26306 \SpecialChar ~
26307 ; nop
26308 \newline
26309 }
26310 \layout Standard
26311
26312 Note that the replace pattern cannot be a blank, but can be a comment line.
26313  Without the 'restart' option only the innermost 'pop' 'push' pair would
26314  be eliminated, i.e.:
26315 \layout Verse
26316
26317
26318 \family typewriter
26319 pop ar1
26320 \newline
26321 pop ar2
26322 \newline
26323 push ar2
26324 \newline
26325 push ar1
26326 \layout Standard
26327
26328 would result in:
26329 \layout Verse
26330
26331
26332 \family typewriter
26333 pop ar1
26334 \newline
26335 ; nop
26336 \newline
26337 push ar1
26338 \layout Standard
26339
26340
26341 \emph on
26342 with
26343 \emph default
26344  the restart option the rule will be applied again to the resulting code
26345  and then all the pop-push pairs will be eliminated to yield:
26346 \layout Verse
26347
26348
26349 \family typewriter
26350 ; nop
26351 \newline
26352 ; nop
26353 \layout Standard
26354
26355 A conditional function can be attached to a rule.
26356  Attaching rules are somewhat more involved, let me illustrate this with
26357  an example.
26358 \layout Verse
26359
26360
26361 \family typewriter
26362 replace {
26363 \newline
26364 \SpecialChar ~
26365  \SpecialChar ~
26366  \SpecialChar ~
26367 ljmp %5
26368 \newline
26369 %2:
26370 \newline
26371 } by {
26372 \newline
26373 \SpecialChar ~
26374  \SpecialChar ~
26375  \SpecialChar ~
26376 sjmp %5
26377 \newline
26378 %2:
26379 \newline
26380 } if labelInRange
26381 \layout Standard
26382
26383 The optimizer does a look-up of a function name table defined in function
26384
26385 \emph on
26386 callFuncByName
26387 \emph default
26388  in the source file SDCCpeeph.c, with the name
26389 \emph on
26390 labelInRange
26391 \emph default
26392 .
26393  If it finds a corresponding entry the function is called.
26394  Note there can be no parameters specified for these functions, in this
26395  case the use of
26396 \emph on
26397 %5
26398 \emph default
26399  is crucial, since the function
26400 \emph on
26401 labelInRange
26402 \emph default
26403  expects to find the label in that particular variable (the hash table containin
26404 g the variable bindings is passed as a parameter).
26405  If you want to code more such functions, take a close look at the function
26406  labelInRange and the calling mechanism in source file SDCCpeeph.c.
26407  Currently implemented are
26408 \emph on
26409 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
26410  24bitMode, portIsDS390, 24bitModeAndPortDS390
26411 \emph default
26412 and
26413 \emph on
26414  notVolatile
26415 \emph default
26416 .
26417 \layout Standard
26418
26419 I know this whole thing is a little kludgey, but maybe some day we will
26420  have some better means.
26421  If you are looking at this file, you will see the default rules that are
26422  compiled into the compiler, you can add your own rules in the default set
26423  there if you get tired of specifying the -
26424 \begin_inset ERT
26425 status Collapsed
26426
26427 \layout Standard
26428
26429 \backslash
26430 /
26431 \end_inset
26432
26433 -peep-file option.
26434 \layout Section
26435
26436 ANSI-Compliance
26437 \begin_inset LatexCommand \index{ANSI-compliance}
26438
26439 \end_inset
26440
26441
26442 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
26443
26444 \end_inset
26445
26446
26447 \layout Standard
26448
26449 Deviations from the compliance:
26450 \layout Itemize
26451
26452 functions are not reentrant
26453 \begin_inset LatexCommand \index{reentrant}
26454
26455 \end_inset
26456
26457  unless explicitly declared as such or the
26458 \series bold
26459 -
26460 \begin_inset ERT
26461 status Collapsed
26462
26463 \layout Standard
26464
26465 \backslash
26466 /
26467 \end_inset
26468
26469 -stack-auto
26470 \begin_inset LatexCommand \index{-\/-stack-auto}
26471
26472 \end_inset
26473
26474
26475 \series default
26476  command line option is specified.
26477 \layout Itemize
26478
26479 structures and unions cannot be assigned values directly, cannot be passed
26480  as function parameters or assigned to each other and cannot be a return
26481  value from a function, e.g.:
26482 \begin_deeper
26483 \layout Verse
26484
26485
26486 \family typewriter
26487 struct s { ...
26488  };
26489 \newline
26490 struct s s1, s2;
26491 \newline
26492 foo()
26493 \newline
26494 {
26495 \newline
26496 \SpecialChar ~
26497 \SpecialChar ~
26498 \SpecialChar ~
26499 \SpecialChar ~
26500 ...
26501
26502 \newline
26503 \SpecialChar ~
26504 \SpecialChar ~
26505 \SpecialChar ~
26506 \SpecialChar ~
26507 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
26508 \newline
26509 \SpecialChar ~
26510 \SpecialChar ~
26511 \SpecialChar ~
26512 \SpecialChar ~
26513 ...
26514
26515 \newline
26516 }
26517 \newline
26518 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
26519  */
26520 \newline
26521 {
26522 \newline
26523 \SpecialChar ~
26524 \SpecialChar ~
26525 \SpecialChar ~
26526 \SpecialChar ~
26527 struct s rets;
26528 \newline
26529 \SpecialChar ~
26530 \SpecialChar ~
26531 \SpecialChar ~
26532 \SpecialChar ~
26533 ...
26534
26535 \newline
26536 \SpecialChar ~
26537 \SpecialChar ~
26538 \SpecialChar ~
26539 \SpecialChar ~
26540 return rets;/* is invalid in SDCC although allowed in ANSI */
26541 \newline
26542 }
26543 \end_deeper
26544 \layout Itemize
26545
26546 initialization of structure arrays must be fully braced.
26547 \begin_deeper
26548 \layout Verse
26549
26550
26551 \family typewriter
26552 struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
26553 \newline
26554 struct s { char x } a[] = {{1}, {2}}; /* OK */
26555 \end_deeper
26556 \layout Itemize
26557
26558 'long long
26559 \begin_inset LatexCommand \index{long long (not supported)}
26560
26561 \end_inset
26562
26563 ' (64 bit integers
26564 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
26565
26566 \end_inset
26567
26568 ) not supported.
26569 \layout Itemize
26570
26571 'double
26572 \begin_inset LatexCommand \index{double (not supported)}
26573
26574 \end_inset
26575
26576 ' precision floating point
26577 \begin_inset LatexCommand \index{Floating point support}
26578
26579 \end_inset
26580
26581 not supported.
26582 \layout Itemize
26583
26584 Old K&R style
26585 \begin_inset LatexCommand \index{K\&R style}
26586
26587 \end_inset
26588
26589  function declarations are NOT allowed.
26590 \begin_deeper
26591 \layout Verse
26592
26593
26594 \family typewriter
26595 foo(i,j) /* this old style of function declarations */
26596 \newline
26597 int i,j; /* are valid in ANSI but not valid in SDCC */
26598 \newline
26599 {
26600 \newline
26601 \SpecialChar ~
26602 \SpecialChar ~
26603 \SpecialChar ~
26604 \SpecialChar ~
26605 ...
26606
26607 \newline
26608 }
26609 \end_deeper
26610 \layout Itemize
26611
26612 Most enhancements in C99 are not supported, f.e.:
26613 \begin_deeper
26614 \layout Verse
26615
26616
26617 \family typewriter
26618 \series bold
26619 inline
26620 \series default
26621  int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
26622  in C99 */
26623 \newline
26624 for (
26625 \series bold
26626 int
26627 \series default
26628  i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
26629 \end_deeper
26630 \layout Itemize
26631
26632 Certain words that are valid identifiers in the standard may be reserved
26633  words in SDCC unless the
26634 \series bold
26635 -
26636 \begin_inset ERT
26637 status Collapsed
26638
26639 \layout Standard
26640
26641 \backslash
26642 /
26643 \end_inset
26644
26645 -std-c89
26646 \begin_inset LatexCommand \index{-\/-std-c89}
26647
26648 \end_inset
26649
26650  or -
26651 \begin_inset ERT
26652 status Collapsed
26653
26654 \layout Standard
26655
26656 \backslash
26657 /
26658 \end_inset
26659
26660 -std-c99
26661 \begin_inset LatexCommand \index{-\/-std-c99}
26662
26663 \end_inset
26664
26665
26666 \series default
26667  command line options are used.
26668  These may include (depending on the selected processor): 'at', 'banked',
26669  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
26670 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
26671  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
26672  '_naked'.
26673  Compliant equivalents of these keywords are always available in a form
26674  that begin with two underscores
26675 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
26676
26677 \end_inset
26678
26679 , f.e.
26680  '__data' instead of 'data'.
26681 \layout Section
26682
26683 Cyclomatic Complexity
26684 \begin_inset LatexCommand \index{Cyclomatic complexity}
26685
26686 \end_inset
26687
26688
26689 \layout Standard
26690
26691 Cyclomatic complexity of a function is defined as the number of independent
26692  paths the program can take during execution of the function.
26693  This is an important number since it defines the number test cases you
26694  have to generate to validate the function.
26695  The accepted industry standard for complexity number is 10, if the cyclomatic
26696  complexity reported by SDCC exceeds 10 you should think about simplification
26697  of the function logic.
26698  Note that the complexity level is not related to the number of lines of
26699  code in a function.
26700  Large functions can have low complexity, and small functions can have large
26701  complexity levels.
26702
26703 \newline
26704
26705 \newline
26706 SDCC uses the following formula to compute the complexity:
26707 \newline
26708
26709 \layout Standard
26710
26711 complexity = (number of edges in control flow graph) - (number of nodes
26712  in control flow graph) + 2;
26713 \newline
26714
26715 \newline
26716 Having said that the industry standard is 10, you should be aware that in
26717  some cases it be may unavoidable to have a complexity level of less than
26718  10.
26719  For example if you have switch statement with more than 10 case labels,
26720  each case label adds one to the complexity level.
26721  The complexity level is by no means an absolute measure of the algorithmic
26722  complexity of the function, it does however provide a good starting point
26723  for which functions you might look at for further optimization.
26724 \layout Section
26725
26726 Retargetting for other Processors
26727 \layout Standard
26728
26729 The issues for retargetting the compiler are far too numerous to be covered
26730  by this document.
26731  What follows is a brief description of each of the seven phases of the
26732  compiler and its MCU dependency.
26733 \layout Itemize
26734
26735 Parsing the source and building the annotated parse tree.
26736  This phase is largely MCU independent (except for the language extensions).
26737  Syntax & semantic checks are also done in this phase, along with some initial
26738  optimizations like back patching labels and the pattern matching optimizations
26739  like bit-rotation etc.
26740 \layout Itemize
26741
26742 The second phase involves generating an intermediate code which can be easy
26743  manipulated during the later phases.
26744  This phase is entirely MCU independent.
26745  The intermediate code generation assumes the target machine has unlimited
26746  number of registers, and designates them with the name iTemp.
26747  The compiler can be made to dump a human readable form of the code generated
26748  by using the -
26749 \begin_inset ERT
26750 status Collapsed
26751
26752 \layout Standard
26753
26754 \backslash
26755 /
26756 \end_inset
26757
26758 -dumpraw option.
26759 \layout Itemize
26760
26761 This phase does the bulk of the standard optimizations and is also MCU independe
26762 nt.
26763  This phase can be broken down into several sub-phases:
26764 \newline
26765
26766 \newline
26767 Break down intermediate code (iCode) into basic blocks.
26768 \newline
26769 Do control flow & data flow analysis on the basic blocks.
26770 \newline
26771 Do local common subexpression elimination, then global subexpression elimination
26772 \newline
26773 Dead code elimination
26774 \newline
26775 Loop optimizations
26776 \newline
26777 If loop optimizations caused any changes then do 'global subexpression eliminati
26778 on' and 'dead code elimination' again.
26779 \layout Itemize
26780
26781 This phase determines the live-ranges; by live range I mean those iTemp
26782  variables defined by the compiler that still survive after all the optimization
26783 s.
26784  Live range analysis
26785 \begin_inset LatexCommand \index{Live range analysis}
26786
26787 \end_inset
26788
26789  is essential for register allocation, since these computation determines
26790  which of these iTemps will be assigned to registers, and for how long.
26791 \layout Itemize
26792
26793 Phase five is register allocation.
26794  There are two parts to this process.
26795 \newline
26796
26797 \newline
26798 The first part I call 'register packing' (for lack of a better term).
26799  In this case several MCU specific expression folding is done to reduce
26800  register pressure.
26801 \newline
26802
26803 \newline
26804 The second part is more MCU independent and deals with allocating registers
26805  to the remaining live ranges.
26806  A lot of MCU specific code does creep into this phase because of the limited
26807  number of index registers available in the 8051.
26808 \layout Itemize
26809
26810 The Code generation phase is (unhappily), entirely MCU dependent and very
26811  little (if any at all) of this code can be reused for other MCU.
26812  However the scheme for allocating a homogenized assembler operand for each
26813  iCode operand may be reused.
26814 \layout Itemize
26815
26816 As mentioned in the optimization section the peep-hole optimizer is rule
26817  based system, which can reprogrammed for other MCUs.
26818 \layout Chapter
26819
26820 Compiler internals
26821 \begin_inset LatexCommand \index{Compiler internals}
26822
26823 \end_inset
26824
26825
26826 \layout Section
26827
26828 The anatomy of the compiler
26829 \begin_inset LatexCommand \label{sub:The-anatomy-of}
26830
26831 \end_inset
26832
26833
26834 \layout Standard
26835
26836
26837 \shape italic
26838 This is an excerpt from an article published in Circuit Cellar Magazine
26839  in
26840 \series bold
26841 August 2000
26842 \series default
26843 .
26844  It's a little outdated (the compiler is much more efficient now and user/develo
26845 per friendly), but pretty well exposes the guts of it all.
26846 \shape default
26847
26848 \newline
26849
26850 \newline
26851 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
26852  It is fairly easy to retarget for other 8-bit MCU.
26853  Here we take a look at some of the internals of the compiler.
26854
26855 \layout Paragraph*
26856
26857 Parsing
26858 \begin_inset LatexCommand \index{Parsing}
26859
26860 \end_inset
26861
26862
26863 \layout Standard
26864
26865 Parsing the input source file and creating an AST (Annotated Syntax Tree
26866 \begin_inset LatexCommand \index{Annotated syntax tree}
26867
26868 \end_inset
26869
26870 ).
26871  This phase also involves propagating types (annotating each node of the
26872  parse tree with type information) and semantic analysis.
26873  There are some MCU specific parsing rules.
26874  For example the storage classes, the extended storage classes are MCU specific
26875  while there may be a xdata storage class for 8051 there is no such storage
26876  class for z80 or Atmel AVR.
26877  SDCC allows MCU specific storage class extensions, i.e.
26878  xdata will be treated as a storage class specifier when parsing 8051 C
26879  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
26880  C code.
26881 \layout Paragraph*
26882
26883 Generating iCode
26884 \begin_inset LatexCommand \index{iCode}
26885
26886 \end_inset
26887
26888
26889 \layout Standard
26890
26891 Intermediate code generation.
26892  In this phase the AST is broken down into three-operand form (iCode).
26893  These three operand forms are represented as doubly linked lists.
26894  ICode is the term given to the intermediate form generated by the compiler.
26895  ICode example section shows some examples of iCode generated for some simple
26896  C source functions.
26897 \layout Paragraph*
26898
26899 Optimizations
26900 \begin_inset LatexCommand \index{Optimizations}
26901
26902 \end_inset
26903
26904 .
26905 \layout Standard
26906
26907 Bulk of the target independent optimizations is performed in this phase.
26908  The optimizations include constant propagation, common sub-expression eliminati
26909 on, loop invariant code movement, strength reduction of loop induction variables
26910  and dead-code elimination.
26911 \layout Paragraph*
26912
26913 Live range analysis
26914 \begin_inset LatexCommand \index{Live range analysis}
26915
26916 \end_inset
26917
26918
26919 \layout Standard
26920
26921 During intermediate code generation phase, the compiler assumes the target
26922  machine has infinite number of registers and generates a lot of temporary
26923  variables.
26924  The live range computation determines the lifetime of each of these compiler-ge
26925 nerated temporaries.
26926  A picture speaks a thousand words.
26927  ICode example sections show the live range annotations for each of the
26928  operand.
26929  It is important to note here, each iCode is assigned a number in the order
26930  of its execution in the function.
26931  The live ranges are computed in terms of these numbers.
26932  The from number is the number of the iCode which first defines the operand
26933  and the to number signifies the iCode which uses this operand last.
26934 \layout Paragraph*
26935
26936 Register Allocation
26937 \begin_inset LatexCommand \index{Register allocation}
26938
26939 \end_inset
26940
26941
26942 \layout Standard
26943
26944 The register allocation determines the type and number of registers needed
26945  by each operand.
26946  In most MCUs only a few registers can be used for indirect addressing.
26947  In case of 8051 for example the registers R0 & R1 can be used to indirectly
26948  address the internal ram and DPTR to indirectly address the external ram.
26949  The compiler will try to allocate the appropriate register to pointer variables
26950  if it can.
26951  ICode example section shows the operands annotated with the registers assigned
26952  to them.
26953  The compiler will try to keep operands in registers as much as possible;
26954  there are several schemes the compiler uses to do achieve this.
26955  When the compiler runs out of registers the compiler will check to see
26956  if there are any live operands which is not used or defined in the current
26957  basic block being processed, if there are any found then it will push that
26958  operand and use the registers in this block, the operand will then be popped
26959  at the end of the basic block.
26960
26961 \layout Standard
26962
26963 There are other MCU specific considerations in this phase.
26964  Some MCUs have an accumulator; very short-lived operands could be assigned
26965  to the accumulator instead of a general-purpose register.
26966 \layout Paragraph*
26967
26968 Code generation
26969 \layout Standard
26970
26971 Figure II gives a table of iCode operations supported by the compiler.
26972  The code generation involves translating these operations into corresponding
26973  assembly code for the processor.
26974  This sounds overly simple but that is the essence of code generation.
26975  Some of the iCode operations are generated on a MCU specific manner for
26976  example, the z80 port does not use registers to pass parameters so the
26977  SEND and RECV iCode operations will not be generated, and it also does
26978  not support JUMPTABLES.
26979
26980 \newline
26981
26982 \series bold
26983 \shape italic
26984 \color red
26985 <Where is Figure II?>
26986 \layout Comment
26987
26988 In the original article Figure II was announced to be downloadable on
26989 \shape italic
26990 Circuit Cellar
26991 \shape default
26992 's web site.
26993  Unfortunately it never seemed to have shown up there, so: where is Figure
26994  II?
26995 \layout Paragraph*
26996
26997 ICode Example
26998 \begin_inset LatexCommand \index{iCode}
26999
27000 \end_inset
27001
27002
27003 \layout Standard
27004
27005 This section shows some details of iCode.
27006  The example C code does not do anything useful; it is used as an example
27007  to illustrate the intermediate code generated by the compiler.
27008 \layout Verse
27009
27010
27011 \family typewriter
27012 1.\SpecialChar ~
27013 xdata int * p;
27014 \newline
27015 2.\SpecialChar ~
27016 int gint;
27017 \newline
27018 3.\SpecialChar ~
27019 /* This function does nothing useful.
27020  It is used
27021 \newline
27022 4.\SpecialChar ~
27023 \SpecialChar ~
27024 \SpecialChar ~
27025 \SpecialChar ~
27026 for the purpose of explaining iCode */
27027 \newline
27028 5.\SpecialChar ~
27029 short function (data int *x)
27030 \newline
27031 6.\SpecialChar ~
27032 {
27033 \newline
27034 7.\SpecialChar ~
27035 \SpecialChar ~
27036 \SpecialChar ~
27037 short i=10; \SpecialChar ~
27038 \SpecialChar ~
27039 /* dead initialization eliminated */
27040 \newline
27041 8.\SpecialChar ~
27042 \SpecialChar ~
27043 \SpecialChar ~
27044 short sum=10; /* dead initialization eliminated */
27045 \newline
27046 9.\SpecialChar ~
27047 \SpecialChar ~
27048 \SpecialChar ~
27049 short mul;
27050 \newline
27051 10.\SpecialChar ~
27052 \SpecialChar ~
27053 int j ;
27054 \newline
27055 11.\SpecialChar ~
27056 \SpecialChar ~
27057 while (*x) *x++ = *p++;
27058 \newline
27059 12.\SpecialChar ~
27060 \SpecialChar ~
27061 \SpecialChar ~
27062 \SpecialChar ~
27063 sum = 0 ;
27064 \newline
27065 13.\SpecialChar ~
27066 \SpecialChar ~
27067 mul = 0;
27068 \newline
27069 14.\SpecialChar ~
27070 \SpecialChar ~
27071 /* compiler detects i,j to be induction variables */
27072 \newline
27073 15.\SpecialChar ~
27074 \SpecialChar ~
27075 for (i = 0, j = 10 ; i < 10 ; i++, j
27076 \family default
27077 -
27078 \begin_inset ERT
27079 status Collapsed
27080
27081 \layout Standard
27082
27083 \backslash
27084 /
27085 \end_inset
27086
27087 -
27088 \family typewriter
27089 ) {
27090 \newline
27091 16.\SpecialChar ~
27092 \SpecialChar ~
27093 \SpecialChar ~
27094 \SpecialChar ~
27095 sum += i;
27096 \newline
27097 17.\SpecialChar ~
27098 \SpecialChar ~
27099 \SpecialChar ~
27100 \SpecialChar ~
27101 mul += i * 3; \SpecialChar ~
27102 \SpecialChar ~
27103 /* this multiplication remains */
27104 \newline
27105 18.\SpecialChar ~
27106 \SpecialChar ~
27107 \SpecialChar ~
27108 \SpecialChar ~
27109 gint += j * 3;\SpecialChar ~
27110 \SpecialChar ~
27111 /* this multiplication changed to addition */
27112 \newline
27113 19.\SpecialChar ~
27114 \SpecialChar ~
27115 }
27116 \newline
27117 20.\SpecialChar ~
27118 \SpecialChar ~
27119 return sum+mul;
27120 \newline
27121 21.\SpecialChar ~
27122 }
27123 \layout Standard
27124
27125 In addition to the operands each iCode contains information about the filename
27126  and line it corresponds to in the source file.
27127  The first field in the listing should be interpreted as follows:
27128 \newline
27129
27130 \shape italic
27131 \size footnotesize
27132 Filename(linenumber: iCode Execution sequence number : ICode hash table
27133  key : loop depth of the iCode).
27134 \shape default
27135 \size default
27136
27137 \newline
27138 Then follows the human readable form of the ICode operation.
27139  Each operand of this triplet form can be of three basic types a) compiler
27140  generated temporary b) user defined variable c) a constant value.
27141  Note that local variables and parameters are replaced by compiler generated
27142  temporaries.
27143  Live ranges
27144 \begin_inset LatexCommand \index{Live range analysis}
27145
27146 \end_inset
27147
27148  are computed only for temporaries (i.e.
27149  live ranges are not computed for global variables).
27150  Registers
27151 \begin_inset LatexCommand \index{Register allocation}
27152
27153 \end_inset
27154
27155  are allocated for temporaries only.
27156  Operands are formatted in the following manner:
27157 \newline
27158
27159 \shape italic
27160 \size footnotesize
27161 Operand Name [lr live-from : live-to ] { type information } [ registers
27162  allocated ].
27163 \shape default
27164 \size default
27165
27166 \newline
27167 As mentioned earlier the live ranges are computed in terms of the execution
27168  sequence number of the iCodes, for example
27169 \newline
27170 the iTemp0 is live from (i.e.
27171  first defined in iCode with execution sequence number 3, and is last used
27172  in the iCode with sequence number 5).
27173  For induction variables such as iTemp21 the live range computation extends
27174  the lifetime from the start to the end of the loop.
27175 \newline
27176 The register allocator used the live range information to allocate registers,
27177  the same registers may be used for different temporaries if their live
27178  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
27179  iTemp17 since their live ranges do not overlap.
27180  In addition the allocator also takes into consideration the type and usage
27181  of a temporary, for example itemp6 is a pointer to near space and is used
27182  as to fetch data from (i.e.
27183  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
27184  Some short lived temporaries are allocated to special registers which have
27185  meaning to the code generator e.g.
27186  iTemp13 is allocated to a pseudo register CC which tells the back end that
27187  the temporary is used only for a conditional jump the code generation makes
27188  use of this information to optimize a compare and jump ICode.
27189 \newline
27190 There are several loop optimizations
27191 \begin_inset LatexCommand \index{Loop optimization}
27192
27193 \end_inset
27194
27195  performed by the compiler.
27196  It can detect induction variables iTemp21(i) and iTemp23(j).
27197  Also note the compiler does selective strength reduction
27198 \begin_inset LatexCommand \index{Strength reduction}
27199
27200 \end_inset
27201
27202 , i.e.
27203  the multiplication of an induction variable in line 18 (gint = j * 3) is
27204  changed to addition, a new temporary iTemp17 is allocated and assigned
27205  a initial value, a constant 3 is then added for each iteration of the loop.
27206  The compiler does not change the multiplication
27207 \begin_inset LatexCommand \index{Multiplication}
27208
27209 \end_inset
27210
27211  in line 17 however since the processor does support an 8 * 8 bit multiplication.
27212 \newline
27213 Note the dead code elimination
27214 \begin_inset LatexCommand \index{Dead-code elimination}
27215
27216 \end_inset
27217
27218  optimization eliminated the dead assignments in line 7 & 8 to I and sum
27219  respectively.
27220 \newline
27221
27222 \layout Standard
27223
27224
27225 \size footnotesize
27226 Sample.c (5:1:0:0) _entry($9) :
27227 \layout Standard
27228
27229
27230 \size footnotesize
27231 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
27232 \layout Standard
27233
27234
27235 \size footnotesize
27236 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
27237 \layout Standard
27238
27239
27240 \size footnotesize
27241 Sample.c(11:4:53:0) preHeaderLbl0($11) :
27242 \layout Standard
27243
27244
27245 \size footnotesize
27246 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
27247  * int}[r2]
27248 \layout Standard
27249
27250
27251 \size footnotesize
27252 Sample.c(11:6:5:1) _whilecontinue_0($1) :
27253 \layout Standard
27254
27255
27256 \size footnotesize
27257 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
27258  int}[r0]]
27259 \layout Standard
27260
27261
27262 \size footnotesize
27263 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27264 \layout Standard
27265
27266
27267 \size footnotesize
27268 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
27269  * int}
27270 \layout Standard
27271
27272
27273 \size footnotesize
27274 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
27275  {short}
27276 \layout Standard
27277
27278
27279 \size footnotesize
27280 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
27281  * int}[DPTR]]
27282 \layout Standard
27283
27284
27285 \size footnotesize
27286 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
27287 }[r2 r3]
27288 \layout Standard
27289
27290
27291 \size footnotesize
27292 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
27293  * int}[r0] + 0x2 {short}
27294 \layout Standard
27295
27296
27297 \size footnotesize
27298 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
27299 \layout Standard
27300
27301
27302 \size footnotesize
27303 Sample.c(11:17:21:0)_whilebreak_0($3) :
27304 \layout Standard
27305
27306
27307 \size footnotesize
27308 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27309 \layout Standard
27310
27311
27312 \size footnotesize
27313 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27314 \layout Standard
27315
27316
27317 \size footnotesize
27318 Sample.c(15:20:54:0)preHeaderLbl1($13) :
27319 \layout Standard
27320
27321
27322 \size footnotesize
27323 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27324 \layout Standard
27325
27326
27327 \size footnotesize
27328 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27329 \layout Standard
27330
27331
27332 \size footnotesize
27333 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27334 \layout Standard
27335
27336
27337 \size footnotesize
27338 Sample.c(15:24:26:1)_forcond_0($4) :
27339 \layout Standard
27340
27341
27342 \size footnotesize
27343 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
27344  < 0xa {short}
27345 \layout Standard
27346
27347
27348 \size footnotesize
27349 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27350 \layout Standard
27351
27352
27353 \size footnotesize
27354 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
27355  + ITemp21 [lr21:38]{short}[r4]
27356 \layout Standard
27357
27358
27359 \size footnotesize
27360 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
27361  * 0x3 {short}
27362 \layout Standard
27363
27364
27365 \size footnotesize
27366 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
27367  + iTemp15 [lr29:30]{short}[r1]
27368 \layout Standard
27369
27370
27371 \size footnotesize
27372 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
27373  r0]- 0x3 {short}
27374 \layout Standard
27375
27376
27377 \size footnotesize
27378 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
27379 int}[r7 r0]
27380 \layout Standard
27381
27382
27383 \size footnotesize
27384 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
27385  + 0x1 {short}
27386 \layout Standard
27387
27388
27389 \size footnotesize
27390 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
27391  r6]- 0x1 {short}
27392 \layout Standard
27393
27394
27395 \size footnotesize
27396 Sample.c(19:38:47:1) goto _forcond_0($4)
27397 \layout Standard
27398
27399
27400 \size footnotesize
27401 Sample.c(19:39:48:0)_forbreak_0($7) :
27402 \layout Standard
27403
27404
27405 \size footnotesize
27406 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
27407  + ITemp11 [lr19:40]{short}[r3]
27408 \layout Standard
27409
27410
27411 \size footnotesize
27412 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
27413 \layout Standard
27414
27415
27416 \size footnotesize
27417 Sample.c(20:42:51:0)_return($8) :
27418 \layout Standard
27419
27420
27421 \size footnotesize
27422 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
27423 \size default
27424
27425 \newline
27426
27427 \newline
27428 Finally the code generated for this function:
27429 \newline
27430
27431 \layout Standard
27432
27433
27434 \size footnotesize
27435 .area DSEG (DATA)
27436 \layout Standard
27437
27438
27439 \size footnotesize
27440 _p::
27441 \layout Standard
27442
27443
27444 \size footnotesize
27445 \SpecialChar ~
27446 \SpecialChar ~
27447 .ds 2
27448 \layout Standard
27449
27450
27451 \size footnotesize
27452 _gint::
27453 \layout Standard
27454
27455
27456 \size footnotesize
27457 \SpecialChar ~
27458 \SpecialChar ~
27459 .ds 2
27460 \layout Standard
27461
27462
27463 \size footnotesize
27464 ; sample.c 5
27465 \layout Standard
27466
27467
27468 \size footnotesize
27469 ; ----------------------------------------------
27470 \layout Standard
27471
27472
27473 \size footnotesize
27474 ; function function
27475 \layout Standard
27476
27477
27478 \size footnotesize
27479 ; ----------------------------------------------
27480 \layout Standard
27481
27482
27483 \size footnotesize
27484 _function:
27485 \layout Standard
27486
27487
27488 \size footnotesize
27489 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
27490 \layout Standard
27491
27492
27493 \size footnotesize
27494 \SpecialChar ~
27495 \SpecialChar ~
27496 mov r2,dpl
27497 \layout Standard
27498
27499
27500 \size footnotesize
27501 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
27502 \layout Standard
27503
27504
27505 \size footnotesize
27506 \SpecialChar ~
27507 \SpecialChar ~
27508 mov ar0,r2
27509 \layout Standard
27510
27511
27512 \size footnotesize
27513 ;_whilecontinue_0($1) :
27514 \layout Standard
27515
27516
27517 \size footnotesize
27518 00101$:
27519 \layout Standard
27520
27521
27522 \size footnotesize
27523 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
27524 \layout Standard
27525
27526
27527 \size footnotesize
27528 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27529 \layout Standard
27530
27531
27532 \size footnotesize
27533 \SpecialChar ~
27534 \SpecialChar ~
27535 mov ar2,@r0
27536 \layout Standard
27537
27538
27539 \size footnotesize
27540 \SpecialChar ~
27541 \SpecialChar ~
27542 inc r0
27543 \layout Standard
27544
27545
27546 \size footnotesize
27547 \SpecialChar ~
27548 \SpecialChar ~
27549 mov ar3,@r0
27550 \layout Standard
27551
27552
27553 \size footnotesize
27554 \SpecialChar ~
27555 \SpecialChar ~
27556 dec r0
27557 \layout Standard
27558
27559
27560 \size footnotesize
27561 \SpecialChar ~
27562 \SpecialChar ~
27563 mov a,r2
27564 \layout Standard
27565
27566
27567 \size footnotesize
27568 \SpecialChar ~
27569 \SpecialChar ~
27570 orl a,r3
27571 \layout Standard
27572
27573
27574 \size footnotesize
27575 \SpecialChar ~
27576 \SpecialChar ~
27577 jz 00103$
27578 \layout Standard
27579
27580
27581 \size footnotesize
27582 00114$:
27583 \layout Standard
27584
27585
27586 \size footnotesize
27587 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
27588 \layout Standard
27589
27590
27591 \size footnotesize
27592 \SpecialChar ~
27593 \SpecialChar ~
27594 mov dpl,_p
27595 \layout Standard
27596
27597
27598 \size footnotesize
27599 \SpecialChar ~
27600 \SpecialChar ~
27601 mov dph,(_p + 1)
27602 \layout Standard
27603
27604
27605 \size footnotesize
27606 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
27607 \layout Standard
27608
27609
27610 \size footnotesize
27611 \SpecialChar ~
27612 \SpecialChar ~
27613 mov a,#0x02
27614 \layout Standard
27615
27616
27617 \size footnotesize
27618 \SpecialChar ~
27619 \SpecialChar ~
27620 add a,_p
27621 \layout Standard
27622
27623
27624 \size footnotesize
27625 \SpecialChar ~
27626 \SpecialChar ~
27627 mov _p,a
27628 \layout Standard
27629
27630
27631 \size footnotesize
27632 \SpecialChar ~
27633 \SpecialChar ~
27634 clr a
27635 \layout Standard
27636
27637
27638 \size footnotesize
27639 \SpecialChar ~
27640 \SpecialChar ~
27641 addc a,(_p + 1)
27642 \layout Standard
27643
27644
27645 \size footnotesize
27646 \SpecialChar ~
27647 \SpecialChar ~
27648 mov (_p + 1),a
27649 \layout Standard
27650
27651
27652 \size footnotesize
27653 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
27654 \layout Standard
27655
27656
27657 \size footnotesize
27658 \SpecialChar ~
27659 \SpecialChar ~
27660 movx a,@dptr
27661 \layout Standard
27662
27663
27664 \size footnotesize
27665 \SpecialChar ~
27666 \SpecialChar ~
27667 mov r2,a
27668 \layout Standard
27669
27670
27671 \size footnotesize
27672 \SpecialChar ~
27673 \SpecialChar ~
27674 inc dptr
27675 \layout Standard
27676
27677
27678 \size footnotesize
27679 \SpecialChar ~
27680 \SpecialChar ~
27681 movx a,@dptr
27682 \layout Standard
27683
27684
27685 \size footnotesize
27686 \SpecialChar ~
27687 \SpecialChar ~
27688 mov r3,a
27689 \layout Standard
27690
27691
27692 \size footnotesize
27693 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
27694 \layout Standard
27695
27696
27697 \size footnotesize
27698 \SpecialChar ~
27699 \SpecialChar ~
27700 mov @r0,ar2
27701 \layout Standard
27702
27703
27704 \size footnotesize
27705 \SpecialChar ~
27706 \SpecialChar ~
27707 inc r0
27708 \layout Standard
27709
27710
27711 \size footnotesize
27712 \SpecialChar ~
27713 \SpecialChar ~
27714 mov @r0,ar3
27715 \layout Standard
27716
27717
27718 \size footnotesize
27719 ; iTemp6 [lr5:16]{_near * int}[r0] =
27720 \layout Standard
27721
27722
27723 \size footnotesize
27724 ; iTemp6 [lr5:16]{_near * int}[r0] +
27725 \layout Standard
27726
27727
27728 \size footnotesize
27729 ; 0x2 {short}
27730 \layout Standard
27731
27732
27733 \size footnotesize
27734 \SpecialChar ~
27735 \SpecialChar ~
27736 inc r0
27737 \layout Standard
27738
27739
27740 \size footnotesize
27741 ; goto _whilecontinue_0($1)
27742 \layout Standard
27743
27744
27745 \size footnotesize
27746 \SpecialChar ~
27747 \SpecialChar ~
27748 sjmp 00101$
27749 \layout Standard
27750
27751
27752 \size footnotesize
27753 ; _whilebreak_0($3) :
27754 \layout Standard
27755
27756
27757 \size footnotesize
27758 00103$:
27759 \layout Standard
27760
27761
27762 \size footnotesize
27763 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27764 \layout Standard
27765
27766
27767 \size footnotesize
27768 \SpecialChar ~
27769 \SpecialChar ~
27770 mov r2,#0x00
27771 \layout Standard
27772
27773
27774 \size footnotesize
27775 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27776 \layout Standard
27777
27778
27779 \size footnotesize
27780 \SpecialChar ~
27781 \SpecialChar ~
27782 mov r3,#0x00
27783 \layout Standard
27784
27785
27786 \size footnotesize
27787 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27788 \layout Standard
27789
27790
27791 \size footnotesize
27792 \SpecialChar ~
27793 \SpecialChar ~
27794 mov r4,#0x00
27795 \layout Standard
27796
27797
27798 \size footnotesize
27799 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27800 \layout Standard
27801
27802
27803 \size footnotesize
27804 \SpecialChar ~
27805 \SpecialChar ~
27806 mov r5,#0x0A
27807 \layout Standard
27808
27809
27810 \size footnotesize
27811 \SpecialChar ~
27812 \SpecialChar ~
27813 mov r6,#0x00
27814 \layout Standard
27815
27816
27817 \size footnotesize
27818 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27819 \layout Standard
27820
27821
27822 \size footnotesize
27823 \SpecialChar ~
27824 \SpecialChar ~
27825 mov r7,#0x1E
27826 \layout Standard
27827
27828
27829 \size footnotesize
27830 \SpecialChar ~
27831 \SpecialChar ~
27832 mov r0,#0x00
27833 \layout Standard
27834
27835
27836 \size footnotesize
27837 ; _forcond_0($4) :
27838 \layout Standard
27839
27840
27841 \size footnotesize
27842 00104$:
27843 \layout Standard
27844
27845
27846 \size footnotesize
27847 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
27848 \layout Standard
27849
27850
27851 \size footnotesize
27852 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27853 \layout Standard
27854
27855
27856 \size footnotesize
27857 \SpecialChar ~
27858 \SpecialChar ~
27859 clr c
27860 \layout Standard
27861
27862
27863 \size footnotesize
27864 \SpecialChar ~
27865 \SpecialChar ~
27866 mov a,r4
27867 \layout Standard
27868
27869
27870 \size footnotesize
27871 \SpecialChar ~
27872 \SpecialChar ~
27873 xrl a,#0x80
27874 \layout Standard
27875
27876
27877 \size footnotesize
27878 \SpecialChar ~
27879 \SpecialChar ~
27880 subb a,#0x8a
27881 \layout Standard
27882
27883
27884 \size footnotesize
27885 \SpecialChar ~
27886 \SpecialChar ~
27887 jnc 00107$
27888 \layout Standard
27889
27890
27891 \size footnotesize
27892 00115$:
27893 \layout Standard
27894
27895
27896 \size footnotesize
27897 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
27898 \layout Standard
27899
27900
27901 \size footnotesize
27902 ; iTemp21 [lr21:38]{short}[r4]
27903 \layout Standard
27904
27905
27906 \size footnotesize
27907 \SpecialChar ~
27908 \SpecialChar ~
27909 mov a,r4
27910 \layout Standard
27911
27912
27913 \size footnotesize
27914 \SpecialChar ~
27915 \SpecialChar ~
27916 add a,r2
27917 \layout Standard
27918
27919
27920 \size footnotesize
27921 \SpecialChar ~
27922 \SpecialChar ~
27923 mov r2,a
27924 \layout Standard
27925
27926
27927 \size footnotesize
27928 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
27929 \layout Standard
27930
27931
27932 \size footnotesize
27933 \SpecialChar ~
27934 \SpecialChar ~
27935 mov b,#0x03
27936 \layout Standard
27937
27938
27939 \size footnotesize
27940 \SpecialChar ~
27941 \SpecialChar ~
27942 mov a,r4
27943 \layout Standard
27944
27945
27946 \size footnotesize
27947 \SpecialChar ~
27948 \SpecialChar ~
27949 mul ab
27950 \layout Standard
27951
27952
27953 \size footnotesize
27954 \SpecialChar ~
27955 \SpecialChar ~
27956 mov r1,a
27957 \layout Standard
27958
27959
27960 \size footnotesize
27961 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
27962 \layout Standard
27963
27964
27965 \size footnotesize
27966 ; iTemp15 [lr29:30]{short}[r1]
27967 \layout Standard
27968
27969
27970 \size footnotesize
27971 \SpecialChar ~
27972 \SpecialChar ~
27973 add a,r3
27974 \layout Standard
27975
27976
27977 \size footnotesize
27978 \SpecialChar ~
27979 \SpecialChar ~
27980 mov r3,a
27981 \layout Standard
27982
27983
27984 \size footnotesize
27985 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
27986 \layout Standard
27987
27988
27989 \size footnotesize
27990 \SpecialChar ~
27991 \SpecialChar ~
27992 mov a,r7
27993 \layout Standard
27994
27995
27996 \size footnotesize
27997 \SpecialChar ~
27998 \SpecialChar ~
27999 add a,#0xfd
28000 \layout Standard
28001
28002
28003 \size footnotesize
28004 \SpecialChar ~
28005 \SpecialChar ~
28006 mov r7,a
28007 \layout Standard
28008
28009
28010 \size footnotesize
28011 \SpecialChar ~
28012 \SpecialChar ~
28013 mov a,r0
28014 \layout Standard
28015
28016
28017 \size footnotesize
28018 \SpecialChar ~
28019 \SpecialChar ~
28020 addc a,#0xff
28021 \layout Standard
28022
28023
28024 \size footnotesize
28025 \SpecialChar ~
28026 \SpecialChar ~
28027 mov r0,a
28028 \layout Standard
28029
28030
28031 \size footnotesize
28032 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
28033 \layout Standard
28034
28035
28036 \size footnotesize
28037 \SpecialChar ~
28038 \SpecialChar ~
28039 mov a,r7
28040 \layout Standard
28041
28042
28043 \size footnotesize
28044 \SpecialChar ~
28045 \SpecialChar ~
28046 add a,_gint
28047 \layout Standard
28048
28049
28050 \size footnotesize
28051 \SpecialChar ~
28052 \SpecialChar ~
28053 mov _gint,a
28054 \layout Standard
28055
28056
28057 \size footnotesize
28058 \SpecialChar ~
28059 \SpecialChar ~
28060 mov a,r0
28061 \layout Standard
28062
28063
28064 \size footnotesize
28065 \SpecialChar ~
28066 \SpecialChar ~
28067 addc a,(_gint + 1)
28068 \layout Standard
28069
28070
28071 \size footnotesize
28072 \SpecialChar ~
28073 \SpecialChar ~
28074 mov (_gint + 1),a
28075 \layout Standard
28076
28077
28078 \size footnotesize
28079 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
28080 \layout Standard
28081
28082
28083 \size footnotesize
28084 \SpecialChar ~
28085 \SpecialChar ~
28086 inc r4
28087 \layout Standard
28088
28089
28090 \size footnotesize
28091 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
28092 \layout Standard
28093
28094
28095 \size footnotesize
28096 \SpecialChar ~
28097 \SpecialChar ~
28098 dec r5
28099 \layout Standard
28100
28101
28102 \size footnotesize
28103 \SpecialChar ~
28104 \SpecialChar ~
28105 cjne r5,#0xff,00104$
28106 \layout Standard
28107
28108
28109 \size footnotesize
28110 \SpecialChar ~
28111 \SpecialChar ~
28112 dec r6
28113 \layout Standard
28114
28115
28116 \size footnotesize
28117 ; goto _forcond_0($4)
28118 \layout Standard
28119
28120
28121 \size footnotesize
28122 \SpecialChar ~
28123 \SpecialChar ~
28124 sjmp 00104$
28125 \layout Standard
28126
28127
28128 \size footnotesize
28129 ; _forbreak_0($7) :
28130 \layout Standard
28131
28132
28133 \size footnotesize
28134 00107$:
28135 \layout Standard
28136
28137
28138 \size footnotesize
28139 ; ret iTemp24 [lr40:41]{short}
28140 \layout Standard
28141
28142
28143 \size footnotesize
28144 \SpecialChar ~
28145 \SpecialChar ~
28146 mov a,r3
28147 \layout Standard
28148
28149
28150 \size footnotesize
28151 \SpecialChar ~
28152 \SpecialChar ~
28153 add a,r2
28154 \layout Standard
28155
28156
28157 \size footnotesize
28158 \SpecialChar ~
28159 \SpecialChar ~
28160 mov dpl,a
28161 \layout Standard
28162
28163
28164 \size footnotesize
28165 ; _return($8) :
28166 \layout Standard
28167
28168
28169 \size footnotesize
28170 00108$:
28171 \layout Standard
28172
28173
28174 \size footnotesize
28175 \SpecialChar ~
28176 \SpecialChar ~
28177 ret
28178 \newline
28179
28180 \layout Section
28181
28182 A few words about basic block successors, predecessors and dominators
28183 \layout Standard
28184
28185 Successors are basic blocks
28186 \begin_inset LatexCommand \index{Basic blocks}
28187
28188 \end_inset
28189
28190  that might execute after this basic block.
28191 \newline
28192 Predecessors are basic blocks that might execute before reaching this basic
28193  block.
28194 \newline
28195 Dominators are basic blocks that WILL execute before reaching this basic
28196  block.
28197 \newline
28198
28199 \layout Standard
28200
28201 [basic block 1]
28202 \layout Standard
28203
28204 if (something)
28205 \layout Standard
28206
28207 \SpecialChar ~
28208 \SpecialChar ~
28209 \SpecialChar ~
28210 \SpecialChar ~
28211 [basic block 2]
28212 \layout Standard
28213
28214 else
28215 \layout Standard
28216
28217 \SpecialChar ~
28218 \SpecialChar ~
28219 \SpecialChar ~
28220 \SpecialChar ~
28221 [basic block 3]
28222 \layout Standard
28223
28224 [basic block 4]
28225 \newline
28226
28227 \layout Standard
28228
28229 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
28230 \layout Standard
28231
28232 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
28233 \layout Standard
28234
28235 c) domVect of [BB4] = BB1 ...
28236  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
28237  was executed.
28238 \layout Chapter
28239
28240 Acknowledgments
28241 \layout Standard
28242
28243
28244 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
28245
28246 \end_inset
28247
28248
28249 \newline
28250
28251 \newline
28252
28253 \emph on
28254 Thanks to all the other volunteer developers who have helped with coding,
28255  testing, web-page creation, distribution sets, etc.
28256  You know who you are :-)
28257 \emph default
28258
28259 \newline
28260
28261 \layout Standard
28262
28263 This document was initially written by Sandeep Dutta
28264 \layout Standard
28265
28266 All product names mentioned herein may be trademarks
28267 \begin_inset LatexCommand \index{Trademarks}
28268
28269 \end_inset
28270
28271  of their respective companies.
28272
28273 \layout Section*
28274
28275 Alphabetical index
28276 \layout Standard
28277
28278 To avoid confusion, the installation and building options for SDCC itself
28279  (chapter 2) are not part of the index.
28280 \layout Standard
28281
28282
28283 \begin_inset LatexCommand \printindex{}
28284
28285 \end_inset
28286
28287
28288 \the_end