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.5
  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.
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 an
11263  RETI instruction to return from the interrupt.
11264  To write an interrupt handler for the non-maskable interrupt, which needs
11265  an 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 Section
11287
11288 Enabling and Disabling Interrupts
11289 \layout Subsection
11290
11291 Critical Functions and Critical Statements
11292 \layout Standard
11293
11294 A special keyword may be associated with a block or a function declaring
11295  it as
11296 \emph on
11297 critical
11298 \emph default
11299 .
11300  SDCC will generate code to disable all interrupts
11301 \begin_inset LatexCommand \index{interrupt}
11302
11303 \end_inset
11304
11305  upon entry to a critical function and restore the interrupt enable to the
11306  previous state before returning.
11307  Nesting critical functions will need one additional byte on the stack
11308 \begin_inset LatexCommand \index{stack}
11309
11310 \end_inset
11311
11312  for each call.
11313 \layout Verse
11314
11315
11316 \family typewriter
11317 int foo () critical
11318 \begin_inset LatexCommand \index{critical}
11319
11320 \end_inset
11321
11322
11323 \begin_inset LatexCommand \index{\_\_critical}
11324
11325 \end_inset
11326
11327
11328 \newline
11329 {
11330 \newline
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 \SpecialChar ~
11334 \SpecialChar ~
11335 ...
11336
11337 \newline
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 \SpecialChar ~
11341 \SpecialChar ~
11342 ...
11343
11344 \newline
11345 }
11346 \layout Standard
11347
11348 The critical attribute maybe used with other attributes like
11349 \emph on
11350 reentrant.
11351 \emph default
11352
11353 \newline
11354 The keyword
11355 \emph on
11356 critical
11357 \emph default
11358  may also be used to disable interrupts more locally:
11359 \layout Verse
11360
11361
11362 \family typewriter
11363 critical{ i++; }
11364 \layout Standard
11365
11366 More than one statement could have been included in the block.
11367 \layout Subsection
11368
11369 Enabling and Disabling Interrupts directly
11370 \layout Standard
11371
11372 Interrupts
11373 \begin_inset LatexCommand \index{interrupt}
11374
11375 \end_inset
11376
11377  can also be disabled and enabled directly (8051):
11378 \layout Verse
11379
11380
11381 \family typewriter
11382 EA = 0;\SpecialChar ~
11383 \SpecialChar ~
11384 \SpecialChar ~
11385 \SpecialChar ~
11386 \SpecialChar ~
11387 \SpecialChar ~
11388 \SpecialChar ~
11389 \SpecialChar ~
11390 \SpecialChar ~
11391 \SpecialChar ~
11392 \SpecialChar ~
11393 \SpecialChar ~
11394 or:\SpecialChar ~
11395 \SpecialChar ~
11396 \SpecialChar ~
11397 \SpecialChar ~
11398 \SpecialChar ~
11399 \SpecialChar ~
11400 \SpecialChar ~
11401 \SpecialChar ~
11402 \SpecialChar ~
11403 \SpecialChar ~
11404 \SpecialChar ~
11405 EA_SAVE = EA;
11406 \layout Verse
11407
11408
11409 \family typewriter
11410 ...\SpecialChar ~
11411 \SpecialChar ~
11412 \SpecialChar ~
11413 \SpecialChar ~
11414 \SpecialChar ~
11415 \SpecialChar ~
11416 \SpecialChar ~
11417 \SpecialChar ~
11418 \SpecialChar ~
11419 \SpecialChar ~
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 EA = 0;
11441 \layout Verse
11442
11443
11444 \family typewriter
11445 EA = 1;\SpecialChar ~
11446 \SpecialChar ~
11447 \SpecialChar ~
11448 \SpecialChar ~
11449 \SpecialChar ~
11450 \SpecialChar ~
11451 \SpecialChar ~
11452 \SpecialChar ~
11453 \SpecialChar ~
11454 \SpecialChar ~
11455 \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 ...
11472 \layout Verse
11473
11474
11475 \family typewriter
11476 \SpecialChar ~
11477 \SpecialChar ~
11478 \SpecialChar ~
11479 \SpecialChar ~
11480 \SpecialChar ~
11481 \SpecialChar ~
11482 \SpecialChar ~
11483 \SpecialChar ~
11484 \SpecialChar ~
11485 \SpecialChar ~
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 EA = EA_SAVE;
11510 \layout Standard
11511
11512 On other architectures which have seperate opcodes for enabling and disabling
11513  interrupts you might want to make use of defines with inline assembly
11514 \begin_inset LatexCommand \index{Assembler routines}
11515
11516 \end_inset
11517
11518  (HC08):
11519 \layout Verse
11520
11521
11522 \family typewriter
11523 #define CLI _asm
11524 \begin_inset LatexCommand \index{\_asm}
11525
11526 \end_inset
11527
11528 \SpecialChar ~
11529 \SpecialChar ~
11530 cli\SpecialChar ~
11531 \SpecialChar ~
11532 _endasm
11533 \begin_inset LatexCommand \index{\_endasm}
11534
11535 \end_inset
11536
11537 ;
11538 \layout Verse
11539
11540
11541 \family typewriter
11542 #define SEI _asm\SpecialChar ~
11543 \SpecialChar ~
11544 sei\SpecialChar ~
11545 \SpecialChar ~
11546 _endasm;
11547 \layout Verse
11548
11549
11550 \family typewriter
11551 ...
11552 \layout Standard
11553
11554 Note: it is sometimes sufficient to disable only a specific interrupt source
11555  like f.e.
11556  a timer or serial interrupt by manipulating an
11557 \emph on
11558 interrupt mask
11559 \begin_inset LatexCommand \index{interrupt mask}
11560
11561 \end_inset
11562
11563
11564 \emph default
11565  register.
11566
11567 \layout Standard
11568
11569 Usually the time during which interrupts are disabled should be kept as
11570  short as possible.
11571  This minimizes both
11572 \emph on
11573 interrupt latency
11574 \emph default
11575
11576 \begin_inset LatexCommand \index{interrupt latency}
11577
11578 \end_inset
11579
11580  (the time between the occurrence of the interrupt and the execution of
11581  the first code in the interrupt routine) and
11582 \emph on
11583 interrupt jitter
11584 \emph default
11585
11586 \begin_inset LatexCommand \index{interrupt jitter}
11587
11588 \end_inset
11589
11590  (the difference between the shortest and the longest interrupt latency).
11591  These really are something different, f.e.
11592  a serial interrupt has to be served before its buffer overruns so it cares
11593  for the maximum interrupt latency, whereas it does not care about jitter.
11594  On a loudspeaker driven via a digital to analog converter which is fed
11595  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11596  a much smaller jitter will be very audible.
11597 \layout Standard
11598
11599 You can reenable interrupts within an interrupt routine and on some architecture
11600 s you can make use of two (or more) levels of
11601 \emph on
11602 interrupt priorities
11603 \emph default
11604
11605 \begin_inset LatexCommand \index{interrupt priority}
11606
11607 \end_inset
11608
11609 .
11610  On some architectures which don't support interrupt priorities these can
11611  be implemented by manipulating the interrupt mask and reenabling interrupts
11612  within the interrupt routine.
11613  Check there is sufficient space on the stack
11614 \begin_inset LatexCommand \index{stack}
11615
11616 \end_inset
11617
11618  and don't add complexity unless you have to.
11619
11620 \layout Subsection
11621
11622 Semaphore
11623 \begin_inset LatexCommand \index{semaphore}
11624
11625 \end_inset
11626
11627  locking (mcs51/ds390)
11628 \layout Standard
11629
11630 Some architectures (mcs51/ds390) have an atomic
11631 \begin_inset LatexCommand \index{atomic}
11632
11633 \end_inset
11634
11635  bit test and
11636 \emph on
11637
11638 \emph default
11639 clear
11640 \emph on
11641
11642 \emph default
11643 instruction.
11644  These type of instructions are typically used in preemptive multitasking
11645  systems, where a routine f.e.
11646  claims the use of a data structure ('acquires a lock
11647 \begin_inset LatexCommand \index{lock}
11648
11649 \end_inset
11650
11651  on it'), makes some modifications and then releases the lock when the data
11652  structure is consistent again.
11653  The instruction may also be used if interrupt and non-interrupt code have
11654  to compete for a resource.
11655  With the atomic bit test and clear instruction interrupts
11656 \begin_inset LatexCommand \index{interrupt}
11657
11658 \end_inset
11659
11660  don't have to be disabled for the locking operation.
11661
11662 \layout Standard
11663
11664 SDCC generates this instruction if the source follows this pattern:
11665 \layout Verse
11666
11667
11668 \family typewriter
11669 volatile
11670 \begin_inset LatexCommand \index{volatile}
11671
11672 \end_inset
11673
11674  bit resource_is_free;
11675 \newline
11676
11677 \newline
11678 if (resource_is_free)
11679 \newline
11680 \SpecialChar ~
11681 \SpecialChar ~
11682 {
11683 \newline
11684 \SpecialChar ~
11685 \SpecialChar ~
11686 \SpecialChar ~
11687 \SpecialChar ~
11688 resource_is_free=0;
11689 \newline
11690 \SpecialChar ~
11691 \SpecialChar ~
11692 \SpecialChar ~
11693 \SpecialChar ~
11694 ...
11695
11696 \newline
11697 \SpecialChar ~
11698 \SpecialChar ~
11699 \SpecialChar ~
11700 \SpecialChar ~
11701 resource_is_free=1;
11702 \newline
11703 \SpecialChar ~
11704 \SpecialChar ~
11705 }
11706 \layout Standard
11707
11708 Note, mcs51 and ds390 support only an atomic
11709 \begin_inset LatexCommand \index{atomic}
11710
11711 \end_inset
11712
11713  bit test and
11714 \emph on
11715 clear
11716 \emph default
11717  instruction (as opposed to atomic bit test and
11718 \emph on
11719 set).
11720 \layout Section
11721
11722 Functions using private register banks
11723 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11724
11725 \end_inset
11726
11727  (mcs51/ds390)
11728 \layout Standard
11729
11730 Some architectures have support for quickly changing register sets.
11731  SDCC supports this feature with the
11732 \emph on
11733 using
11734 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11735
11736 \end_inset
11737
11738
11739 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11740
11741 \end_inset
11742
11743
11744 \emph default
11745  attribute (which tells the compiler to use a register bank
11746 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11747
11748 \end_inset
11749
11750  other than the default bank zero).
11751  It should only be applied to
11752 \emph on
11753 interrupt
11754 \begin_inset LatexCommand \index{interrupt}
11755
11756 \end_inset
11757
11758
11759 \emph default
11760  functions (see footnote below).
11761  This will in most circumstances make the generated ISR code more efficient
11762  since it will not have to save registers on the stack.
11763 \layout Standard
11764
11765 The
11766 \emph on
11767 using
11768 \emph default
11769  attribute will have no effect on the generated code for a
11770 \emph on
11771 non-interrupt
11772 \emph default
11773  function (but may occasionally be useful anyway
11774 \begin_inset Foot
11775 collapsed false
11776
11777 \layout Standard
11778
11779 possible exception: if a function is called ONLY from 'interrupt' functions
11780  using a particular bank, it can be declared with the same 'using' attribute
11781  as the calling 'interrupt' functions.
11782  For instance, if you have several ISRs using bank one, and all of them
11783  call memcpy(), it might make sense to create a specialized version of memcpy()
11784  'using 1', since this would prevent the ISR from having to save bank zero
11785  to the stack on entry and switch to bank zero before calling the function
11786 \end_inset
11787
11788 ).
11789 \newline
11790
11791 \emph on
11792 (pending: I don't think this has been done yet)
11793 \layout Standard
11794
11795 An
11796 \emph on
11797 interrupt
11798 \emph default
11799  function using a non-zero bank will assume that it can trash that register
11800  bank, and will not save it.
11801  Since high-priority interrupts
11802 \begin_inset LatexCommand \index{interrupts}
11803
11804 \end_inset
11805
11806
11807 \begin_inset LatexCommand \index{interrupt priority}
11808
11809 \end_inset
11810
11811  can interrupt low-priority ones on the 8051 and friends, this means that
11812  if a high-priority ISR
11813 \emph on
11814 using
11815 \emph default
11816  a particular bank occurs while processing a low-priority ISR
11817 \emph on
11818 using
11819 \emph default
11820  the same bank, terrible and bad things can happen.
11821  To prevent this, no single register bank should be
11822 \emph on
11823 used
11824 \emph default
11825  by both a high priority and a low priority ISR.
11826  This is probably most easily done by having all high priority ISRs use
11827  one bank and all low priority ISRs use another.
11828  If you have an ISR which can change priority at runtime, you're on your
11829  own: I suggest using the default bank zero and taking the small performance
11830  hit.
11831 \layout Standard
11832
11833 It is most efficient if your ISR calls no other functions.
11834  If your ISR must call other functions, it is most efficient if those functions
11835  use the same bank as the ISR (see note 1 below); the next best is if the
11836  called functions use bank zero.
11837  It is very inefficient to call a function using a different, non-zero bank
11838  from an ISR.
11839
11840 \layout Section
11841
11842 Startup Code
11843 \begin_inset LatexCommand \label{sub:Startup-Code}
11844
11845 \end_inset
11846
11847
11848 \begin_inset LatexCommand \index{Startup code}
11849
11850 \end_inset
11851
11852
11853 \layout Subsection
11854
11855 MCS51/DS390 Startup Code
11856 \layout Standard
11857
11858 The compiler inserts a call to the C routine
11859 \emph on
11860 _sdcc_external_startup()
11861 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11862
11863 \end_inset
11864
11865
11866 \series bold
11867 \emph default
11868
11869 \series default
11870 at the start of the CODE area.
11871  This routine is in the runtime library
11872 \begin_inset LatexCommand \index{Runtime library}
11873
11874 \end_inset
11875
11876 .
11877  By default this routine returns 0, if this routine returns a non-zero value,
11878  the static & global variable initialization will be skipped and the function
11879  main will be invoked.
11880  Otherwise static & global variables will be initialized before the function
11881  main is invoked.
11882  You could add a
11883 \emph on
11884 _sdcc_external_startup()
11885 \emph default
11886  routine to your program to override the default if you need to setup hardware
11887  or perform some other critical operation prior to static & global variable
11888  initialization
11889 \begin_inset LatexCommand \index{Variable initialization}
11890
11891 \end_inset
11892
11893 .
11894  On some mcs51 variants xdata
11895 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11896
11897 \end_inset
11898
11899  memory has to be explicitly enabled before it can be accessed or if the
11900  watchdog needs to be disabled, this is the place to do it.
11901  The startup code clears all internal data memory, 256 bytes by default,
11902  but from 0 to n-1 if
11903 \emph on
11904 -
11905 \begin_inset ERT
11906 status Collapsed
11907
11908 \layout Standard
11909
11910 \backslash
11911 /
11912 \end_inset
11913
11914 -iram-size
11915 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
11916
11917 \end_inset
11918
11919 n
11920 \emph default
11921  is used.
11922  (recommended for Chipcon CC1010).
11923 \layout Standard
11924
11925 See also the compiler option
11926 \emph on
11927 -
11928 \begin_inset ERT
11929 status Collapsed
11930
11931 \layout Standard
11932
11933 \backslash
11934 /
11935 \end_inset
11936
11937 -no-xinit
11938 \emph default
11939 -
11940 \emph on
11941 opt
11942 \emph default
11943
11944 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11945
11946 \end_inset
11947
11948  and section
11949 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11950
11951 \end_inset
11952
11953 \SpecialChar ~
11954 about MCS51-variants.
11955 \layout Subsection
11956
11957 HC08 Startup Code
11958 \layout Standard
11959
11960 The HC08 startup code follows the same scheme as the MCS51 startup code.
11961 \layout Subsection
11962
11963 Z80 Startup Code
11964 \layout Standard
11965
11966 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11967  from sdcc/device/lib/z80/crt0.s.
11968  If you need a different startup code you can use the compiler option
11969 \emph on
11970 -
11971 \series bold
11972 \emph default
11973
11974 \begin_inset ERT
11975 status Collapsed
11976
11977 \layout Standard
11978
11979 \backslash
11980 /
11981 \end_inset
11982
11983
11984 \series default
11985 \emph on
11986 -no-std-crt0
11987 \emph default
11988
11989 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11990
11991 \end_inset
11992
11993  and provide your own crt0.o.
11994
11995 \layout Section
11996
11997 Inline Assembler Code
11998 \begin_inset LatexCommand \index{Assembler routines}
11999
12000 \end_inset
12001
12002
12003 \layout Subsection
12004
12005 A Step by Step Introduction
12006 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
12007
12008 \end_inset
12009
12010
12011 \layout Standard
12012
12013 Starting from a small snippet of c-code this example shows for the MCS51
12014  how to use inline assembly, access variables, a function parameter and
12015  an array in xdata memory.
12016  The example uses an MCS51 here but is easily adapted for other architectures.
12017  This is a buffer routine which should be optimized:
12018 \layout Verse
12019
12020
12021 \family typewriter
12022 \size footnotesize
12023 unsigned char far
12024 \begin_inset LatexCommand \index{far (storage class)}
12025
12026 \end_inset
12027
12028
12029 \begin_inset LatexCommand \index{\_\_far (storage class)}
12030
12031 \end_inset
12032
12033  at
12034 \begin_inset LatexCommand \index{at}
12035
12036 \end_inset
12037
12038
12039 \begin_inset LatexCommand \index{\_\_at}
12040
12041 \end_inset
12042
12043  0x7f00 buf[0x100];
12044 \begin_inset LatexCommand \index{Aligned array}
12045
12046 \end_inset
12047
12048
12049 \newline
12050 unsigned char head,tail;
12051 \newline
12052
12053 \newline
12054 void to_buffer( unsigned char c )
12055 \newline
12056 {
12057 \newline
12058 \SpecialChar ~
12059 \SpecialChar ~
12060 \SpecialChar ~
12061 \SpecialChar ~
12062 if( head != tail-1 )
12063 \newline
12064 \SpecialChar ~
12065 \SpecialChar ~
12066 \SpecialChar ~
12067 \SpecialChar ~
12068 \SpecialChar ~
12069 \SpecialChar ~
12070 \SpecialChar ~
12071 \SpecialChar ~
12072 buf[ head++ ] = c;\SpecialChar ~
12073 \SpecialChar ~
12074 \SpecialChar ~
12075 \SpecialChar ~
12076 /* access to a 256 byte aligned array */
12077 \newline
12078 }
12079 \layout Standard
12080
12081 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
12082  then a corresponding buffer.asm file is generated.
12083  We define a new function
12084 \family typewriter
12085 to_buffer_asm()
12086 \family default
12087  in file buffer.c in which we cut and paste the generated code, removing
12088  unwanted comments and some ':'.
12089  Then add
12090 \begin_inset Quotes sld
12091 \end_inset
12092
12093 _asm
12094 \begin_inset Quotes srd
12095 \end_inset
12096
12097  and
12098 \begin_inset Quotes sld
12099 \end_inset
12100
12101 _endasm;
12102 \begin_inset Quotes srd
12103 \end_inset
12104
12105  to the beginning and the end of the function body:
12106 \layout Verse
12107
12108
12109 \family typewriter
12110 \size footnotesize
12111 /* With a cut and paste from the .asm file, we have something to start with.
12112 \newline
12113 \SpecialChar ~
12114 \SpecialChar ~
12115 \SpecialChar ~
12116 The function is not yet OK! (registers aren't saved) */
12117 \newline
12118 void to_buffer_asm( unsigned char c )
12119 \newline
12120 {
12121 \newline
12122 \SpecialChar ~
12123 \SpecialChar ~
12124 \SpecialChar ~
12125 \SpecialChar ~
12126 _asm
12127 \begin_inset LatexCommand \index{\_asm}
12128
12129 \end_inset
12130
12131
12132 \begin_inset LatexCommand \index{\_\_asm}
12133
12134 \end_inset
12135
12136
12137 \newline
12138 \SpecialChar ~
12139 \SpecialChar ~
12140 \SpecialChar ~
12141 \SpecialChar ~
12142 mov\SpecialChar ~
12143 \SpecialChar ~
12144 r2,dpl
12145 \newline
12146 ;buffer.c if( head != tail-1 )
12147 \newline
12148 \SpecialChar ~
12149 \SpecialChar ~
12150 \SpecialChar ~
12151 \SpecialChar ~
12152 mov\SpecialChar ~
12153 \SpecialChar ~
12154 a,_tail
12155 \newline
12156 \SpecialChar ~
12157 \SpecialChar ~
12158 \SpecialChar ~
12159 \SpecialChar ~
12160 dec\SpecialChar ~
12161 \SpecialChar ~
12162 a
12163 \newline
12164 \SpecialChar ~
12165 \SpecialChar ~
12166 \SpecialChar ~
12167 \SpecialChar ~
12168 mov\SpecialChar ~
12169 \SpecialChar ~
12170 r3,a
12171 \newline
12172 \SpecialChar ~
12173 \SpecialChar ~
12174 \SpecialChar ~
12175 \SpecialChar ~
12176 mov\SpecialChar ~
12177 \SpecialChar ~
12178 a,_head
12179 \newline
12180 \SpecialChar ~
12181 \SpecialChar ~
12182 \SpecialChar ~
12183 \SpecialChar ~
12184 cjne a,ar3,00106$
12185 \newline
12186 \SpecialChar ~
12187 \SpecialChar ~
12188 \SpecialChar ~
12189 \SpecialChar ~
12190 ret
12191 \newline
12192 00106$:
12193 \newline
12194 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12195 \begin_inset LatexCommand \index{Aligned array}
12196
12197 \end_inset
12198
12199
12200 \newline
12201 \SpecialChar ~
12202 \SpecialChar ~
12203 \SpecialChar ~
12204 \SpecialChar ~
12205 mov\SpecialChar ~
12206 \SpecialChar ~
12207 r3,_head
12208 \newline
12209 \SpecialChar ~
12210 \SpecialChar ~
12211 \SpecialChar ~
12212 \SpecialChar ~
12213 inc\SpecialChar ~
12214 \SpecialChar ~
12215 _head
12216 \newline
12217 \SpecialChar ~
12218 \SpecialChar ~
12219 \SpecialChar ~
12220 \SpecialChar ~
12221 mov\SpecialChar ~
12222 \SpecialChar ~
12223 dpl,r3
12224 \newline
12225 \SpecialChar ~
12226 \SpecialChar ~
12227 \SpecialChar ~
12228 \SpecialChar ~
12229 mov\SpecialChar ~
12230 \SpecialChar ~
12231 dph,#(_buf >> 8)
12232 \newline
12233 \SpecialChar ~
12234 \SpecialChar ~
12235 \SpecialChar ~
12236 \SpecialChar ~
12237 mov\SpecialChar ~
12238 \SpecialChar ~
12239 a,r2
12240 \newline
12241 \SpecialChar ~
12242 \SpecialChar ~
12243 \SpecialChar ~
12244 \SpecialChar ~
12245 movx @dptr,a
12246 \newline
12247 00103$:
12248 \newline
12249 \SpecialChar ~
12250 \SpecialChar ~
12251 \SpecialChar ~
12252 \SpecialChar ~
12253 ret
12254 \newline
12255 \SpecialChar ~
12256 \SpecialChar ~
12257 \SpecialChar ~
12258 \SpecialChar ~
12259 _endasm
12260 \begin_inset LatexCommand \index{\_endasm}
12261
12262 \end_inset
12263
12264
12265 \begin_inset LatexCommand \index{\_\_endasm}
12266
12267 \end_inset
12268
12269 ;
12270 \newline
12271 }
12272 \layout Standard
12273
12274 The new file buffer.c should compile with only one warning about the unreferenced
12275  function argument 'c'.
12276  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12277  (1) and finally have:
12278 \layout Verse
12279
12280
12281 \family typewriter
12282 \size footnotesize
12283 unsigned char far at 0x7f00 buf[0x100];
12284 \newline
12285 unsigned char head,tail;
12286 \newline
12287 #define USE_ASSEMBLY (1)
12288 \newline
12289
12290 \newline
12291 #if !USE_ASSEMBLY
12292 \newline
12293
12294 \newline
12295 void to_buffer( unsigned char c )
12296 \newline
12297 {
12298 \newline
12299 \SpecialChar ~
12300 \SpecialChar ~
12301 \SpecialChar ~
12302 \SpecialChar ~
12303 if( head != tail-1 )
12304 \newline
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 \SpecialChar ~
12308 \SpecialChar ~
12309 \SpecialChar ~
12310 \SpecialChar ~
12311 \SpecialChar ~
12312 \SpecialChar ~
12313 buf[ head++ ] = c;
12314 \newline
12315 }
12316 \newline
12317
12318 \newline
12319 #else
12320 \newline
12321
12322 \newline
12323 void to_buffer( unsigned char c )
12324 \newline
12325 {
12326 \newline
12327 \SpecialChar ~
12328 \SpecialChar ~
12329 \SpecialChar ~
12330 \SpecialChar ~
12331 c; // to avoid warning: unreferenced function argument
12332 \newline
12333 \SpecialChar ~
12334 \SpecialChar ~
12335 \SpecialChar ~
12336 \SpecialChar ~
12337 _asm
12338 \begin_inset LatexCommand \index{\_asm}
12339
12340 \end_inset
12341
12342
12343 \begin_inset LatexCommand \index{\_\_asm}
12344
12345 \end_inset
12346
12347
12348 \newline
12349 \SpecialChar ~
12350 \SpecialChar ~
12351 \SpecialChar ~
12352 \SpecialChar ~
12353 \SpecialChar ~
12354 \SpecialChar ~
12355 \SpecialChar ~
12356 \SpecialChar ~
12357 ; save used registers here.
12358
12359 \newline
12360 \SpecialChar ~
12361 \SpecialChar ~
12362 \SpecialChar ~
12363 \SpecialChar ~
12364 \SpecialChar ~
12365 \SpecialChar ~
12366 \SpecialChar ~
12367 \SpecialChar ~
12368 ; If we were still using r2,r3 we would have to push them here.
12369
12370 \newline
12371 ; if( head != tail-1 )
12372 \newline
12373 \SpecialChar ~
12374 \SpecialChar ~
12375 \SpecialChar ~
12376 \SpecialChar ~
12377 \SpecialChar ~
12378 \SpecialChar ~
12379 \SpecialChar ~
12380 \SpecialChar ~
12381 mov\SpecialChar ~
12382  a,_tail
12383 \newline
12384 \SpecialChar ~
12385 \SpecialChar ~
12386 \SpecialChar ~
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 \SpecialChar ~
12392 dec\SpecialChar ~
12393  a
12394 \newline
12395 \SpecialChar ~
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 \SpecialChar ~
12399 \SpecialChar ~
12400 \SpecialChar ~
12401 \SpecialChar ~
12402 \SpecialChar ~
12403 xrl\SpecialChar ~
12404  a,_head
12405 \newline
12406 \SpecialChar ~
12407 \SpecialChar ~
12408 \SpecialChar ~
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 \SpecialChar ~
12414 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
12415 \newline
12416 \SpecialChar ~
12417 \SpecialChar ~
12418 \SpecialChar ~
12419 \SpecialChar ~
12420 \SpecialChar ~
12421 \SpecialChar ~
12422 \SpecialChar ~
12423 \SpecialChar ~
12424 jz\SpecialChar ~
12425 \SpecialChar ~
12426  t_b_end$
12427 \newline
12428 \SpecialChar ~
12429 \SpecialChar ~
12430 \SpecialChar ~
12431 \SpecialChar ~
12432 \SpecialChar ~
12433 \SpecialChar ~
12434 \SpecialChar ~
12435 \SpecialChar ~
12436 ;
12437 \newline
12438 ; buf[ head++ ] = c;
12439 \newline
12440 \SpecialChar ~
12441 \SpecialChar ~
12442 \SpecialChar ~
12443 \SpecialChar ~
12444 \SpecialChar ~
12445 \SpecialChar ~
12446 \SpecialChar ~
12447 \SpecialChar ~
12448 mov\SpecialChar ~
12449  a,dpl \SpecialChar ~
12450 \SpecialChar ~
12451 \SpecialChar ~
12452 \SpecialChar ~
12453 \SpecialChar ~
12454 \SpecialChar ~
12455 \SpecialChar ~
12456 ; dpl holds lower byte of function argument
12457 \newline
12458 \SpecialChar ~
12459 \SpecialChar ~
12460 \SpecialChar ~
12461 \SpecialChar ~
12462 \SpecialChar ~
12463 \SpecialChar ~
12464 \SpecialChar ~
12465 \SpecialChar ~
12466 mov\SpecialChar ~
12467  dpl,_head \SpecialChar ~
12468 \SpecialChar ~
12469 \SpecialChar ~
12470 ; buf is 0x100 byte aligned so head can be used directly
12471 \newline
12472 \SpecialChar ~
12473 \SpecialChar ~
12474 \SpecialChar ~
12475 \SpecialChar ~
12476 \SpecialChar ~
12477 \SpecialChar ~
12478 \SpecialChar ~
12479 \SpecialChar ~
12480 mov\SpecialChar ~
12481  dph,#(_buf>>8)
12482 \newline
12483 \SpecialChar ~
12484 \SpecialChar ~
12485 \SpecialChar ~
12486 \SpecialChar ~
12487 \SpecialChar ~
12488 \SpecialChar ~
12489 \SpecialChar ~
12490 \SpecialChar ~
12491 movx @dptr,a
12492 \newline
12493 \SpecialChar ~
12494 \SpecialChar ~
12495 \SpecialChar ~
12496 \SpecialChar ~
12497 \SpecialChar ~
12498 \SpecialChar ~
12499 \SpecialChar ~
12500 \SpecialChar ~
12501 inc \SpecialChar ~
12502 _head
12503 \newline
12504 \SpecialChar ~
12505 \SpecialChar ~
12506 \SpecialChar ~
12507 \SpecialChar ~
12508 \SpecialChar ~
12509 \SpecialChar ~
12510 \SpecialChar ~
12511 \SpecialChar ~
12512 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
12513 \newline
12514 t_b_end$:
12515 \newline
12516 \SpecialChar ~
12517 \SpecialChar ~
12518 \SpecialChar ~
12519 \SpecialChar ~
12520 \SpecialChar ~
12521 \SpecialChar ~
12522 \SpecialChar ~
12523 \SpecialChar ~
12524 ; restore used registers here
12525 \newline
12526 \SpecialChar ~
12527 \SpecialChar ~
12528 \SpecialChar ~
12529 \SpecialChar ~
12530 _endasm
12531 \begin_inset LatexCommand \index{\_endasm}
12532
12533 \end_inset
12534
12535
12536 \begin_inset LatexCommand \index{\_\_endasm}
12537
12538 \end_inset
12539
12540 ;
12541 \newline
12542 }
12543 \newline
12544 #endif
12545 \layout Standard
12546
12547 The inline assembler code can contain any valid code understood by the assembler
12548 , this includes any assembler directives and comment lines
12549 \begin_inset Foot
12550 collapsed false
12551
12552 \layout Standard
12553
12554 The assembler does not like some characters like ':' or ''' in comments.
12555  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
12556 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
12557
12558 \end_inset
12559
12560
12561 \begin_inset LatexCommand \index{Assembler documentation}
12562
12563 \end_inset
12564
12565
12566 \end_inset
12567
12568 .
12569  The compiler does not do any validation of the code within the
12570 \family typewriter
12571 _asm
12572 \begin_inset LatexCommand \index{\_asm}
12573
12574 \end_inset
12575
12576
12577 \begin_inset LatexCommand \index{\_\_asm}
12578
12579 \end_inset
12580
12581  ...
12582  _endasm
12583 \size footnotesize
12584
12585 \begin_inset LatexCommand \index{\_endasm}
12586
12587 \end_inset
12588
12589
12590 \begin_inset LatexCommand \index{\_\_endasm}
12591
12592 \end_inset
12593
12594
12595 \size default
12596 ;
12597 \family default
12598  keyword pair.
12599  Specifically it will not know which registers are used and thus register
12600  pushing/popping
12601 \begin_inset LatexCommand \index{push/pop}
12602
12603 \end_inset
12604
12605  has to be done manually.
12606
12607 \layout Standard
12608
12609 It is recommended that each assembly instruction (including labels) be placed
12610  in a separate line (as the example shows).
12611  When the -
12612 \begin_inset ERT
12613 status Collapsed
12614
12615 \layout Standard
12616
12617 \backslash
12618 /
12619 \end_inset
12620
12621 -
12622 \emph on
12623 peep-asm
12624 \begin_inset LatexCommand \index{-\/-peep-asm}
12625
12626 \end_inset
12627
12628
12629 \emph default
12630  command line option is used, the inline assembler code will be passed through
12631  the peephole optimizer
12632 \begin_inset LatexCommand \index{Peephole optimizer}
12633
12634 \end_inset
12635
12636 .
12637  There are only a few (if any) cases where this option makes sense, it might
12638  cause some unexpected changes in the inline assembler code.
12639  Please go through the peephole optimizer rules defined in file
12640 \emph on
12641 SDCCpeeph.def
12642 \emph default
12643  before using this option.
12644 \layout Subsection
12645
12646 Naked Functions
12647 \begin_inset LatexCommand \label{sub:Naked-Functions}
12648
12649 \end_inset
12650
12651
12652 \begin_inset LatexCommand \index{Naked functions}
12653
12654 \end_inset
12655
12656
12657 \layout Standard
12658
12659 A special keyword may be associated with a function declaring it as
12660 \emph on
12661 _naked
12662 \begin_inset LatexCommand \index{\_naked}
12663
12664 \end_inset
12665
12666
12667 \begin_inset LatexCommand \index{\_\_naked}
12668
12669 \end_inset
12670
12671 .
12672
12673 \emph default
12674 The
12675 \emph on
12676 _naked
12677 \emph default
12678  function modifier attribute prevents the compiler from generating prologue
12679 \begin_inset LatexCommand \index{function prologue}
12680
12681 \end_inset
12682
12683  and epilogue
12684 \begin_inset LatexCommand \index{function epilogue}
12685
12686 \end_inset
12687
12688  code for that function.
12689  This means that the user is entirely responsible for such things as saving
12690  any registers that may need to be preserved, selecting the proper register
12691  bank, generating the
12692 \emph on
12693 return
12694 \emph default
12695  instruction at the end, etc.
12696  Practically, this means that the contents of the function must be written
12697  in inline assembler.
12698  This is particularly useful for interrupt functions, which can have a large
12699  (and often unnecessary) prologue/epilogue.
12700  For example, compare the code generated by these two functions:
12701 \layout Verse
12702
12703
12704 \family typewriter
12705 volatile
12706 \begin_inset LatexCommand \index{volatile}
12707
12708 \end_inset
12709
12710  data unsigned char counter;
12711 \newline
12712
12713 \newline
12714 void simpleInterrupt(void) interrupt
12715 \begin_inset LatexCommand \index{interrupt}
12716
12717 \end_inset
12718
12719
12720 \begin_inset LatexCommand \index{\_\_interrupt}
12721
12722 \end_inset
12723
12724  1
12725 \newline
12726 {
12727 \newline
12728 \SpecialChar ~
12729 \SpecialChar ~
12730 \SpecialChar ~
12731 \SpecialChar ~
12732 counter++;
12733 \newline
12734 }
12735 \newline
12736
12737 \newline
12738 void nakedInterrupt(void) interrupt 2 _naked
12739 \newline
12740 {
12741 \newline
12742 \SpecialChar ~
12743 \SpecialChar ~
12744 \SpecialChar ~
12745 \SpecialChar ~
12746 _asm
12747 \begin_inset LatexCommand \index{\_asm}
12748
12749 \end_inset
12750
12751
12752 \begin_inset LatexCommand \index{\_\_asm}
12753
12754 \end_inset
12755
12756
12757 \newline
12758 \SpecialChar ~
12759 \SpecialChar ~
12760 \SpecialChar ~
12761 \SpecialChar ~
12762 \SpecialChar ~
12763 \SpecialChar ~
12764 inc\SpecialChar ~
12765 \SpecialChar ~
12766 \SpecialChar ~
12767 \SpecialChar ~
12768 \SpecialChar ~
12769 _counter ; does not change flags, no need to save psw
12770 \newline
12771 \SpecialChar ~
12772 \SpecialChar ~
12773 \SpecialChar ~
12774 \SpecialChar ~
12775 \SpecialChar ~
12776 \SpecialChar ~
12777 reti\SpecialChar ~
12778 \SpecialChar ~
12779 \SpecialChar ~
12780 \SpecialChar ~
12781 ; MUST explicitly include ret or reti in _naked function.
12782 \newline
12783 \SpecialChar ~
12784 \SpecialChar ~
12785 \SpecialChar ~
12786 \SpecialChar ~
12787 _endasm
12788 \begin_inset LatexCommand \index{\_endasm}
12789
12790 \end_inset
12791
12792
12793 \begin_inset LatexCommand \index{\_\_endasm}
12794
12795 \end_inset
12796
12797 ;
12798 \newline
12799 }
12800 \layout Standard
12801
12802 For an 8051 target, the generated simpleInterrupt looks like:
12803 \layout Verse
12804
12805
12806 \family typewriter
12807 _simpleInterrupt:
12808 \newline
12809 \SpecialChar ~
12810 \SpecialChar ~
12811 \SpecialChar ~
12812 \SpecialChar ~
12813 push\SpecialChar ~
12814 \SpecialChar ~
12815 \SpecialChar ~
12816 \SpecialChar ~
12817 acc
12818 \newline
12819 \SpecialChar ~
12820 \SpecialChar ~
12821 \SpecialChar ~
12822 \SpecialChar ~
12823 push\SpecialChar ~
12824 \SpecialChar ~
12825 \SpecialChar ~
12826 \SpecialChar ~
12827 b
12828 \newline
12829 \SpecialChar ~
12830 \SpecialChar ~
12831 \SpecialChar ~
12832 \SpecialChar ~
12833 push\SpecialChar ~
12834 \SpecialChar ~
12835 \SpecialChar ~
12836 \SpecialChar ~
12837 dpl
12838 \newline
12839 \SpecialChar ~
12840 \SpecialChar ~
12841 \SpecialChar ~
12842 \SpecialChar ~
12843 push\SpecialChar ~
12844 \SpecialChar ~
12845 \SpecialChar ~
12846 \SpecialChar ~
12847 dph
12848 \newline
12849 \SpecialChar ~
12850 \SpecialChar ~
12851 \SpecialChar ~
12852 \SpecialChar ~
12853 push\SpecialChar ~
12854 \SpecialChar ~
12855 \SpecialChar ~
12856 \SpecialChar ~
12857 psw
12858 \newline
12859 \SpecialChar ~
12860 \SpecialChar ~
12861 \SpecialChar ~
12862 \SpecialChar ~
12863 mov\SpecialChar ~
12864 \SpecialChar ~
12865 \SpecialChar ~
12866 \SpecialChar ~
12867 \SpecialChar ~
12868 psw,#0x00
12869 \newline
12870 \SpecialChar ~
12871 \SpecialChar ~
12872 \SpecialChar ~
12873 \SpecialChar ~
12874 inc\SpecialChar ~
12875 \SpecialChar ~
12876 \SpecialChar ~
12877 \SpecialChar ~
12878 \SpecialChar ~
12879 _counter
12880 \newline
12881 \SpecialChar ~
12882 \SpecialChar ~
12883 \SpecialChar ~
12884 \SpecialChar ~
12885 pop\SpecialChar ~
12886 \SpecialChar ~
12887 \SpecialChar ~
12888 \SpecialChar ~
12889 \SpecialChar ~
12890 psw
12891 \newline
12892 \SpecialChar ~
12893 \SpecialChar ~
12894 \SpecialChar ~
12895 \SpecialChar ~
12896 pop\SpecialChar ~
12897 \SpecialChar ~
12898 \SpecialChar ~
12899 \SpecialChar ~
12900 \SpecialChar ~
12901 dph
12902 \newline
12903 \SpecialChar ~
12904 \SpecialChar ~
12905 \SpecialChar ~
12906 \SpecialChar ~
12907 pop\SpecialChar ~
12908 \SpecialChar ~
12909 \SpecialChar ~
12910 \SpecialChar ~
12911 \SpecialChar ~
12912 dpl
12913 \newline
12914 \SpecialChar ~
12915 \SpecialChar ~
12916 \SpecialChar ~
12917 \SpecialChar ~
12918 pop\SpecialChar ~
12919 \SpecialChar ~
12920 \SpecialChar ~
12921 \SpecialChar ~
12922 \SpecialChar ~
12923 b
12924 \newline
12925 \SpecialChar ~
12926 \SpecialChar ~
12927 \SpecialChar ~
12928 \SpecialChar ~
12929 pop\SpecialChar ~
12930 \SpecialChar ~
12931 \SpecialChar ~
12932 \SpecialChar ~
12933 \SpecialChar ~
12934 acc
12935 \newline
12936 \SpecialChar ~
12937 \SpecialChar ~
12938 \SpecialChar ~
12939 \SpecialChar ~
12940 reti
12941 \layout Standard
12942
12943 whereas nakedInterrupt looks like:
12944 \layout Verse
12945
12946
12947 \family typewriter
12948 _nakedInterrupt:
12949 \newline
12950 \SpecialChar ~
12951 \SpecialChar ~
12952 \SpecialChar ~
12953 \SpecialChar ~
12954 inc\SpecialChar ~
12955 \SpecialChar ~
12956 \SpecialChar ~
12957 \SpecialChar ~
12958 _counter ; does not change flags, no need to save psw
12959 \newline
12960 \SpecialChar ~
12961 \SpecialChar ~
12962 \SpecialChar ~
12963 \SpecialChar ~
12964 reti\SpecialChar ~
12965 \SpecialChar ~
12966 \SpecialChar ~
12967 \SpecialChar ~
12968 \SpecialChar ~
12969 \SpecialChar ~
12970 \SpecialChar ~
12971 \SpecialChar ~
12972 \SpecialChar ~
12973 \SpecialChar ~
12974 \SpecialChar ~
12975 \SpecialChar ~
12976 ; MUST explicitly include ret or reti in _naked function
12977 \layout Standard
12978
12979 The related directive #pragma exclude
12980 \begin_inset LatexCommand \index{\#pragma exclude}
12981
12982 \end_inset
12983
12984  allows a more fine grained control over pushing & popping
12985 \begin_inset LatexCommand \index{push/pop}
12986
12987 \end_inset
12988
12989  the registers.
12990 \layout Standard
12991
12992 While there is nothing preventing you from writing C code inside a
12993 \family typewriter
12994 _naked
12995 \family default
12996  function, there are many ways to shoot yourself in the foot doing this,
12997  and it is recommended that you stick to inline assembler.
12998 \layout Subsection
12999
13000 Use of Labels within Inline Assembler
13001 \layout Standard
13002
13003 SDCC allows the use of in-line assembler with a few restrictions regarding
13004  labels.
13005  In older versions of the compiler all labels defined within inline assembler
13006  code
13007 \emph on
13008 had to be
13009 \emph default
13010  of the form
13011 \emph on
13012 nnnnn$
13013 \emph default
13014  where nnnn is a number less than 100 (which implies a limit of utmost 100
13015  inline assembler labels
13016 \emph on
13017 per function
13018 \emph default
13019 \noun on
13020 )
13021 \noun default
13022 .
13023
13024 \layout Verse
13025
13026
13027 \family typewriter
13028 _asm
13029 \begin_inset LatexCommand \index{\_asm}
13030
13031 \end_inset
13032
13033
13034 \begin_inset LatexCommand \index{\_\_asm}
13035
13036 \end_inset
13037
13038
13039 \newline
13040 \SpecialChar ~
13041 \SpecialChar ~
13042 \SpecialChar ~
13043 \SpecialChar ~
13044 mov\SpecialChar ~
13045 \SpecialChar ~
13046 \SpecialChar ~
13047 \SpecialChar ~
13048 \SpecialChar ~
13049 b,#10
13050 \newline
13051 00001$:
13052 \newline
13053 \SpecialChar ~
13054 \SpecialChar ~
13055 \SpecialChar ~
13056 \SpecialChar ~
13057 djnz\SpecialChar ~
13058 \SpecialChar ~
13059 \SpecialChar ~
13060 \SpecialChar ~
13061 b,00001$
13062 \newline
13063 _endasm
13064 \begin_inset LatexCommand \index{\_endasm}
13065
13066 \end_inset
13067
13068
13069 \begin_inset LatexCommand \index{\_\_endasm}
13070
13071 \end_inset
13072
13073  ;
13074 \layout Standard
13075
13076 Inline assembler code cannot reference any C-Labels, however it can reference
13077  labels
13078 \begin_inset LatexCommand \index{Labels}
13079
13080 \end_inset
13081
13082  defined by the inline assembler, e.g.:
13083 \layout Verse
13084
13085
13086 \family typewriter
13087 foo() {
13088 \newline
13089 \SpecialChar ~
13090 \SpecialChar ~
13091 \SpecialChar ~
13092 \SpecialChar ~
13093 /* some c code */
13094 \newline
13095 \SpecialChar ~
13096 \SpecialChar ~
13097 \SpecialChar ~
13098 \SpecialChar ~
13099 _asm
13100 \newline
13101 \SpecialChar ~
13102 \SpecialChar ~
13103 \SpecialChar ~
13104 \SpecialChar ~
13105 \SpecialChar ~
13106 \SpecialChar ~
13107 ; some assembler code
13108 \newline
13109 \SpecialChar ~
13110 \SpecialChar ~
13111 \SpecialChar ~
13112 \SpecialChar ~
13113 \SpecialChar ~
13114 \SpecialChar ~
13115 ljmp $0003
13116 \newline
13117 \SpecialChar ~
13118 \SpecialChar ~
13119 \SpecialChar ~
13120 \SpecialChar ~
13121 _endasm;
13122 \newline
13123 \SpecialChar ~
13124 \SpecialChar ~
13125 \SpecialChar ~
13126 \SpecialChar ~
13127 /* some more c code */
13128 \newline
13129 clabel:\SpecialChar ~
13130 \SpecialChar ~
13131 /* inline assembler cannot reference this label */
13132 \newline
13133 \SpecialChar ~
13134 \SpecialChar ~
13135 \SpecialChar ~
13136 \SpecialChar ~
13137 _asm
13138 \newline
13139 \SpecialChar ~
13140 \SpecialChar ~
13141 \SpecialChar ~
13142 \SpecialChar ~
13143 $0003: ;label (can be referenced by inline assembler only)
13144 \newline
13145 \SpecialChar ~
13146 \SpecialChar ~
13147 \SpecialChar ~
13148 \SpecialChar ~
13149 _endasm
13150 \begin_inset LatexCommand \index{\_endasm}
13151
13152 \end_inset
13153
13154
13155 \begin_inset LatexCommand \index{\_\_endasm}
13156
13157 \end_inset
13158
13159  ;
13160 \newline
13161 \SpecialChar ~
13162 \SpecialChar ~
13163 \SpecialChar ~
13164 \SpecialChar ~
13165 /* some more c code */
13166 \newline
13167 }
13168 \layout Standard
13169
13170 In other words inline assembly code can access labels defined in inline
13171  assembly within the scope of the function.
13172  The same goes the other way, i.e.
13173  labels defines in inline assembly can not be accessed by C statements.
13174 \layout Section
13175
13176 Interfacing with Assembler Code
13177 \begin_inset LatexCommand \index{Assembler routines}
13178
13179 \end_inset
13180
13181
13182 \layout Subsection
13183
13184 Global Registers used for Parameter Passing
13185 \begin_inset LatexCommand \index{Parameter passing}
13186
13187 \end_inset
13188
13189
13190 \layout Standard
13191
13192 The compiler always uses the global registers
13193 \emph on
13194 DPL, DPH
13195 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13196
13197 \end_inset
13198
13199
13200 \begin_inset LatexCommand \index{DPTR}
13201
13202 \end_inset
13203
13204 , B
13205 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13206
13207 \end_inset
13208
13209
13210 \emph default
13211 and
13212 \emph on
13213  ACC
13214 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13215
13216 \end_inset
13217
13218
13219 \emph default
13220  to pass the first parameter to a routine.
13221  The second parameter onwards is either allocated on the stack (for reentrant
13222  routines or if -
13223 \begin_inset ERT
13224 status Collapsed
13225
13226 \layout Standard
13227
13228 \backslash
13229 /
13230 \end_inset
13231
13232 -stack-auto is used) or in data / xdata memory (depending on the memory
13233  model).
13234
13235 \layout Subsection
13236
13237 Assembler Routine (non-reentrant)
13238 \layout Standard
13239
13240 In the following example
13241 \begin_inset LatexCommand \index{reentrant}
13242
13243 \end_inset
13244
13245
13246 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13247
13248 \end_inset
13249
13250  the function c_func calls an assembler routine asm_func, which takes two
13251  parameters
13252 \begin_inset LatexCommand \index{function parameter}
13253
13254 \end_inset
13255
13256 .
13257 \layout Verse
13258
13259
13260 \family typewriter
13261 extern int asm_func(unsigned char, unsigned char);
13262 \newline
13263
13264 \newline
13265 int c_func (unsigned char i, unsigned char j)
13266 \newline
13267 {
13268 \newline
13269 \SpecialChar ~
13270 \SpecialChar ~
13271 \SpecialChar ~
13272 \SpecialChar ~
13273 return asm_func(i,j);
13274 \newline
13275 }
13276 \newline
13277
13278 \newline
13279 int main()
13280 \newline
13281 {
13282 \newline
13283 \SpecialChar ~
13284 \SpecialChar ~
13285 \SpecialChar ~
13286 \SpecialChar ~
13287 return c_func(10,9);
13288 \newline
13289 }
13290 \layout Standard
13291
13292 The corresponding assembler function is:
13293 \layout Verse
13294
13295
13296 \family typewriter
13297 .globl _asm_func_PARM_2
13298 \newline
13299 \SpecialChar ~
13300 \SpecialChar ~
13301 \SpecialChar ~
13302 \SpecialChar ~
13303 \SpecialChar ~
13304 \SpecialChar ~
13305 \SpecialChar ~
13306 \SpecialChar ~
13307 .globl _asm_func
13308 \newline
13309 \SpecialChar ~
13310 \SpecialChar ~
13311 \SpecialChar ~
13312 \SpecialChar ~
13313 \SpecialChar ~
13314 \SpecialChar ~
13315 \SpecialChar ~
13316 \SpecialChar ~
13317 .area OSEG
13318 \newline
13319 _asm_func_PARM_2:
13320 \newline
13321 \SpecialChar ~
13322 \SpecialChar ~
13323 \SpecialChar ~
13324 \SpecialChar ~
13325 \SpecialChar ~
13326 \SpecialChar ~
13327 \SpecialChar ~
13328 \SpecialChar ~
13329 .ds    1
13330 \newline
13331 \SpecialChar ~
13332 \SpecialChar ~
13333 \SpecialChar ~
13334 \SpecialChar ~
13335 \SpecialChar ~
13336 \SpecialChar ~
13337 \SpecialChar ~
13338 \SpecialChar ~
13339 .area CSEG
13340 \newline
13341 _asm_func:
13342 \newline
13343 \SpecialChar ~
13344 \SpecialChar ~
13345 \SpecialChar ~
13346 \SpecialChar ~
13347 \SpecialChar ~
13348 \SpecialChar ~
13349 \SpecialChar ~
13350 \SpecialChar ~
13351 mov\SpecialChar ~
13352 \SpecialChar ~
13353 \SpecialChar ~
13354 \SpecialChar ~
13355 a,dpl
13356 \newline
13357 \SpecialChar ~
13358 \SpecialChar ~
13359 \SpecialChar ~
13360 \SpecialChar ~
13361 \SpecialChar ~
13362 \SpecialChar ~
13363 \SpecialChar ~
13364 \SpecialChar ~
13365 add\SpecialChar ~
13366 \SpecialChar ~
13367 \SpecialChar ~
13368 \SpecialChar ~
13369 a,_asm_func_PARM_2
13370 \newline
13371 \SpecialChar ~
13372 \SpecialChar ~
13373 \SpecialChar ~
13374 \SpecialChar ~
13375 \SpecialChar ~
13376 \SpecialChar ~
13377 \SpecialChar ~
13378 \SpecialChar ~
13379 mov\SpecialChar ~
13380 \SpecialChar ~
13381 \SpecialChar ~
13382 \SpecialChar ~
13383 dpl,a
13384 \newline
13385 \SpecialChar ~
13386 \SpecialChar ~
13387 \SpecialChar ~
13388 \SpecialChar ~
13389 \SpecialChar ~
13390 \SpecialChar ~
13391 \SpecialChar ~
13392 \SpecialChar ~
13393 mov\SpecialChar ~
13394 \SpecialChar ~
13395 \SpecialChar ~
13396 \SpecialChar ~
13397 dph
13398 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13399
13400 \end_inset
13401
13402 ,#0x00
13403 \newline
13404 \SpecialChar ~
13405 \SpecialChar ~
13406 \SpecialChar ~
13407 \SpecialChar ~
13408 \SpecialChar ~
13409 \SpecialChar ~
13410 \SpecialChar ~
13411 \SpecialChar ~
13412 ret
13413 \layout Standard
13414
13415 Note here that the return values
13416 \begin_inset LatexCommand \index{return value}
13417
13418 \end_inset
13419
13420  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
13421  two byte values.
13422  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
13423 b' & 'acc' for four byte values.
13424 \layout Standard
13425
13426 The parameter naming convention is _<function_name>_PARM_<n>, where n is
13427  the parameter number starting from 1, and counting from the left.
13428  The first parameter is passed in
13429 \begin_inset Quotes eld
13430 \end_inset
13431
13432 dpl
13433 \begin_inset Quotes erd
13434 \end_inset
13435
13436  for a one byte parameter,
13437 \begin_inset Quotes eld
13438 \end_inset
13439
13440 dptr
13441 \begin_inset Quotes erd
13442 \end_inset
13443
13444  for two bytes,
13445 \begin_inset Quotes eld
13446 \end_inset
13447
13448 b,dptr
13449 \begin_inset Quotes erd
13450 \end_inset
13451
13452  for three bytes and
13453 \begin_inset Quotes eld
13454 \end_inset
13455
13456 acc,b,dptr
13457 \begin_inset Quotes erd
13458 \end_inset
13459
13460  for a four bytes parameter.
13461  The variable name for the second parameter will be _<function_name>_PARM_2.
13462 \newline
13463
13464 \newline
13465 Assemble the assembler routine with the following command:
13466 \newline
13467
13468 \newline
13469
13470 \family sans
13471 \series bold
13472 asx8051 -losg asmfunc.asm
13473 \newline
13474
13475 \newline
13476
13477 \family default
13478 \series default
13479 Then compile and link the assembler routine to the C source file with the
13480  following command:
13481 \newline
13482
13483 \newline
13484
13485 \family sans
13486 \series bold
13487 sdcc cfunc.c asmfunc.rel
13488 \layout Subsection
13489
13490 Assembler Routine (reentrant)
13491 \layout Standard
13492
13493 In this case
13494 \begin_inset LatexCommand \index{reentrant}
13495
13496 \end_inset
13497
13498
13499 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
13500
13501 \end_inset
13502
13503  the second parameter
13504 \begin_inset LatexCommand \index{function parameter}
13505
13506 \end_inset
13507
13508  onwards will be passed on the stack, the parameters are pushed from right
13509  to left i.e.
13510  after the call the leftmost parameter will be on the top of the stack.
13511  Here is an example:
13512 \layout Verse
13513
13514
13515 \family typewriter
13516 extern int asm_func(unsigned char, unsigned char);
13517 \newline
13518
13519 \newline
13520 int c_func (unsigned char i, unsigned char j) reentrant
13521 \newline
13522 {
13523 \newline
13524 \SpecialChar ~
13525 \SpecialChar ~
13526 \SpecialChar ~
13527 \SpecialChar ~
13528 return asm_func(i,j);
13529 \newline
13530 }
13531 \newline
13532
13533 \newline
13534 int main()
13535 \newline
13536 {
13537 \newline
13538 \SpecialChar ~
13539 \SpecialChar ~
13540 \SpecialChar ~
13541 \SpecialChar ~
13542 return c_func(10,9);
13543 \newline
13544 }
13545 \layout Standard
13546
13547 The corresponding assembler routine is:
13548 \layout Verse
13549
13550
13551 \family typewriter
13552 .globl _asm_func
13553 \newline
13554 _asm_func:
13555 \newline
13556 \SpecialChar ~
13557 \SpecialChar ~
13558 \SpecialChar ~
13559 \SpecialChar ~
13560 push  _bp
13561 \newline
13562 \SpecialChar ~
13563 \SpecialChar ~
13564 \SpecialChar ~
13565 \SpecialChar ~
13566 mov _bp,sp
13567 \newline
13568 \SpecialChar ~
13569 \SpecialChar ~
13570 \SpecialChar ~
13571 \SpecialChar ~
13572 mov r2,dpl
13573 \newline
13574 \SpecialChar ~
13575 \SpecialChar ~
13576 \SpecialChar ~
13577 \SpecialChar ~
13578 mov a,_bp
13579 \newline
13580 \SpecialChar ~
13581 \SpecialChar ~
13582 \SpecialChar ~
13583 \SpecialChar ~
13584 add a,#0xfd
13585 \newline
13586 \SpecialChar ~
13587 \SpecialChar ~
13588 \SpecialChar ~
13589 \SpecialChar ~
13590 mov r0,a
13591 \newline
13592 \SpecialChar ~
13593 \SpecialChar ~
13594 \SpecialChar ~
13595 \SpecialChar ~
13596 add  a,#0xfc ;?
13597 \newline
13598 \SpecialChar ~
13599 \SpecialChar ~
13600 \SpecialChar ~
13601 \SpecialChar ~
13602 mov  r1,a
13603 \newline
13604 \SpecialChar ~
13605 \SpecialChar ~
13606 \SpecialChar ~
13607 \SpecialChar ~
13608 mov  a,@r0
13609 \newline
13610 \SpecialChar ~
13611 \SpecialChar ~
13612 \SpecialChar ~
13613 \SpecialChar ~
13614 add  a,r2 ;?
13615 \newline
13616 \SpecialChar ~
13617 \SpecialChar ~
13618 \SpecialChar ~
13619 \SpecialChar ~
13620 mov  dpl,a
13621 \newline
13622 \SpecialChar ~
13623 \SpecialChar ~
13624 \SpecialChar ~
13625 \SpecialChar ~
13626 mov  dph,#0x00
13627 \newline
13628 \SpecialChar ~
13629 \SpecialChar ~
13630 \SpecialChar ~
13631 \SpecialChar ~
13632 mov  sp,_bp
13633 \newline
13634 \SpecialChar ~
13635 \SpecialChar ~
13636 \SpecialChar ~
13637 \SpecialChar ~
13638 pop  _bp
13639 \newline
13640 \SpecialChar ~
13641 \SpecialChar ~
13642 \SpecialChar ~
13643 \SpecialChar ~
13644 ret
13645 \layout Standard
13646
13647 The compiling and linking procedure remains the same, however note the extra
13648  entry & exit linkage required for the assembler code, _bp is the stack
13649  frame pointer and is used to compute the offset into the stack for parameters
13650  and local variables.
13651 \layout Section
13652
13653 int (16 bit)
13654 \begin_inset LatexCommand \index{int (16 bit)}
13655
13656 \end_inset
13657
13658  and long (32 bit)
13659 \begin_inset LatexCommand \index{long (32 bit)}
13660
13661 \end_inset
13662
13663  Support
13664 \layout Standard
13665
13666 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
13667  multiplication and modulus operations are implemented by support routines.
13668  These support routines are all developed in ANSI-C to facilitate porting
13669  to other MCUs, although some model specific assembler optimizations are
13670  used.
13671  The following files contain the described routines, all of them can be
13672  found in <installdir>/share/sdcc/lib.
13673 \newline
13674
13675 \layout Standard
13676 \align center
13677
13678 \begin_inset  Tabular
13679 <lyxtabular version="3" rows="11" columns="2">
13680 <features>
13681 <column alignment="center" valignment="top" leftline="true" width="0">
13682 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13683 <row topline="true" bottomline="true">
13684 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13685 \begin_inset Text
13686
13687 \layout Standard
13688
13689
13690 \series bold
13691 Function
13692 \end_inset
13693 </cell>
13694 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13695 \begin_inset Text
13696
13697 \layout Standard
13698
13699
13700 \series bold
13701 Description
13702 \end_inset
13703 </cell>
13704 </row>
13705 <row topline="true">
13706 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13707 \begin_inset Text
13708
13709 \layout Standard
13710
13711 _mulint.c
13712 \end_inset
13713 </cell>
13714 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13715 \begin_inset Text
13716
13717 \layout Standard
13718
13719 16 bit multiplication
13720 \end_inset
13721 </cell>
13722 </row>
13723 <row topline="true">
13724 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13725 \begin_inset Text
13726
13727 \layout Standard
13728
13729 _divsint.c
13730 \end_inset
13731 </cell>
13732 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13733 \begin_inset Text
13734
13735 \layout Standard
13736
13737  signed 16 bit division (calls _divuint)
13738 \end_inset
13739 </cell>
13740 </row>
13741 <row topline="true">
13742 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13743 \begin_inset Text
13744
13745 \layout Standard
13746
13747 _divuint.c
13748 \end_inset
13749 </cell>
13750 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13751 \begin_inset Text
13752
13753 \layout Standard
13754
13755  unsigned 16 bit division
13756 \end_inset
13757 </cell>
13758 </row>
13759 <row topline="true">
13760 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13761 \begin_inset Text
13762
13763 \layout Standard
13764
13765 _modsint.c
13766 \end_inset
13767 </cell>
13768 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13769 \begin_inset Text
13770
13771 \layout Standard
13772
13773 signed 16 bit modulus (calls _moduint)
13774 \end_inset
13775 </cell>
13776 </row>
13777 <row topline="true">
13778 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13779 \begin_inset Text
13780
13781 \layout Standard
13782
13783 _moduint.c
13784 \end_inset
13785 </cell>
13786 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13787 \begin_inset Text
13788
13789 \layout Standard
13790
13791 unsigned 16 bit modulus
13792 \end_inset
13793 </cell>
13794 </row>
13795 <row topline="true">
13796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13797 \begin_inset Text
13798
13799 \layout Standard
13800
13801 _mullong.c
13802 \end_inset
13803 </cell>
13804 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13805 \begin_inset Text
13806
13807 \layout Standard
13808
13809 32 bit multiplication
13810 \end_inset
13811 </cell>
13812 </row>
13813 <row topline="true">
13814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13815 \begin_inset Text
13816
13817 \layout Standard
13818
13819 _divslong.c
13820 \end_inset
13821 </cell>
13822 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13823 \begin_inset Text
13824
13825 \layout Standard
13826
13827  signed 32 division (calls _divulong)
13828 \end_inset
13829 </cell>
13830 </row>
13831 <row topline="true">
13832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13833 \begin_inset Text
13834
13835 \layout Standard
13836
13837 _divulong.c
13838 \end_inset
13839 </cell>
13840 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13841 \begin_inset Text
13842
13843 \layout Standard
13844
13845 unsigned 32 division
13846 \end_inset
13847 </cell>
13848 </row>
13849 <row topline="true">
13850 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13851 \begin_inset Text
13852
13853 \layout Standard
13854
13855 _modslong.c
13856 \end_inset
13857 </cell>
13858 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13859 \begin_inset Text
13860
13861 \layout Standard
13862
13863  signed 32 bit modulus (calls _modulong)
13864 \end_inset
13865 </cell>
13866 </row>
13867 <row topline="true" bottomline="true">
13868 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13869 \begin_inset Text
13870
13871 \layout Standard
13872
13873 _modulong.c
13874 \end_inset
13875 </cell>
13876 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13877 \begin_inset Text
13878
13879 \layout Standard
13880
13881 unsigned 32 bit modulus
13882 \end_inset
13883 </cell>
13884 </row>
13885 </lyxtabular>
13886
13887 \end_inset
13888
13889
13890 \newline
13891
13892 \layout Standard
13893
13894 Since they are compiled as
13895 \emph on
13896 non-reentrant
13897 \emph default
13898
13899 \begin_inset LatexCommand \index{reentrant}
13900
13901 \end_inset
13902
13903 , interrupt
13904 \begin_inset LatexCommand \index{interrupt}
13905
13906 \end_inset
13907
13908  service routines should not do any of the above operations.
13909  If this is unavoidable then the above routines will need to be compiled
13910  with the
13911 \emph on
13912 -
13913 \begin_inset ERT
13914 status Collapsed
13915
13916 \layout Standard
13917
13918 \backslash
13919 /
13920 \end_inset
13921
13922 -stack-auto
13923 \begin_inset LatexCommand \index{-\/-stack-auto}
13924
13925 \end_inset
13926
13927
13928 \emph default
13929  option, after which the source program will have to be compiled with
13930 \emph on
13931 -
13932 \begin_inset ERT
13933 status Collapsed
13934
13935 \layout Standard
13936
13937 \backslash
13938 /
13939 \end_inset
13940
13941 -int-long-reent
13942 \begin_inset LatexCommand \index{-\/-int-long-reent}
13943
13944 \end_inset
13945
13946
13947 \emph default
13948  option.
13949  Notice that you don't have to call these routines directly.
13950  The compiler will use them automatically every time an integer operation
13951  is required.
13952 \layout Section
13953
13954 Floating Point Support
13955 \begin_inset LatexCommand \index{Floating point support}
13956
13957 \end_inset
13958
13959
13960 \layout Standard
13961
13962 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13963  floating point support routines are derived from gcc's floatlib.c and consist
13964  of the following routines:
13965 \newline
13966
13967 \layout Standard
13968 \align center
13969
13970 \size footnotesize
13971
13972 \begin_inset  Tabular
13973 <lyxtabular version="3" rows="17" columns="2">
13974 <features>
13975 <column alignment="center" valignment="top" leftline="true" width="0">
13976 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13977 <row topline="true" bottomline="true">
13978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13979 \begin_inset Text
13980
13981 \layout Standard
13982
13983
13984 \family roman
13985 \series medium
13986 \shape up
13987 \size normal
13988 \emph off
13989 \bar no
13990 \noun off
13991 \color none
13992 Function
13993 \end_inset
13994 </cell>
13995 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13996 \begin_inset Text
13997
13998 \layout Standard
13999
14000 Description
14001 \end_inset
14002 </cell>
14003 </row>
14004 <row topline="true">
14005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14006 \begin_inset Text
14007
14008 \layout Standard
14009
14010
14011 \family roman
14012 \series medium
14013 \shape up
14014 \size normal
14015 \emph off
14016 \bar no
14017 \noun off
14018 \color none
14019 _fsadd.c
14020 \end_inset
14021 </cell>
14022 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14023 \begin_inset Text
14024
14025 \layout Standard
14026
14027
14028 \family roman
14029 \series medium
14030 \shape up
14031 \size normal
14032 \emph off
14033 \bar no
14034 \noun off
14035 \color none
14036 add floating point numbers
14037 \end_inset
14038 </cell>
14039 </row>
14040 <row topline="true">
14041 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14042 \begin_inset Text
14043
14044 \layout Standard
14045
14046
14047 \family roman
14048 \series medium
14049 \shape up
14050 \size normal
14051 \emph off
14052 \bar no
14053 \noun off
14054 \color none
14055 _fssub.c
14056 \end_inset
14057 </cell>
14058 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14059 \begin_inset Text
14060
14061 \layout Standard
14062
14063
14064 \family roman
14065 \series medium
14066 \shape up
14067 \size normal
14068 \emph off
14069 \bar no
14070 \noun off
14071 \color none
14072 subtract floating point numbers
14073 \end_inset
14074 </cell>
14075 </row>
14076 <row topline="true">
14077 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14078 \begin_inset Text
14079
14080 \layout Standard
14081
14082
14083 \family roman
14084 \series medium
14085 \shape up
14086 \size normal
14087 \emph off
14088 \bar no
14089 \noun off
14090 \color none
14091 _fsdiv.c
14092 \end_inset
14093 </cell>
14094 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14095 \begin_inset Text
14096
14097 \layout Standard
14098
14099
14100 \family roman
14101 \series medium
14102 \shape up
14103 \size normal
14104 \emph off
14105 \bar no
14106 \noun off
14107 \color none
14108 divide floating point numbers
14109 \end_inset
14110 </cell>
14111 </row>
14112 <row topline="true">
14113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14114 \begin_inset Text
14115
14116 \layout Standard
14117
14118
14119 \family roman
14120 \series medium
14121 \shape up
14122 \size normal
14123 \emph off
14124 \bar no
14125 \noun off
14126 \color none
14127 _fsmul.c
14128 \end_inset
14129 </cell>
14130 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14131 \begin_inset Text
14132
14133 \layout Standard
14134
14135
14136 \family roman
14137 \series medium
14138 \shape up
14139 \size normal
14140 \emph off
14141 \bar no
14142 \noun off
14143 \color none
14144 multiply floating point numbers
14145 \end_inset
14146 </cell>
14147 </row>
14148 <row topline="true">
14149 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14150 \begin_inset Text
14151
14152 \layout Standard
14153
14154
14155 \family roman
14156 \series medium
14157 \shape up
14158 \size normal
14159 \emph off
14160 \bar no
14161 \noun off
14162 \color none
14163 _fs2uchar.c
14164 \end_inset
14165 </cell>
14166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14167 \begin_inset Text
14168
14169 \layout Standard
14170
14171
14172 \family roman
14173 \series medium
14174 \shape up
14175 \size normal
14176 \emph off
14177 \bar no
14178 \noun off
14179 \color none
14180 convert floating point to unsigned char
14181 \end_inset
14182 </cell>
14183 </row>
14184 <row topline="true">
14185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14186 \begin_inset Text
14187
14188 \layout Standard
14189
14190
14191 \family roman
14192 \series medium
14193 \shape up
14194 \size normal
14195 \emph off
14196 \bar no
14197 \noun off
14198 \color none
14199 _fs2char.c
14200 \end_inset
14201 </cell>
14202 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14203 \begin_inset Text
14204
14205 \layout Standard
14206
14207
14208 \family roman
14209 \series medium
14210 \shape up
14211 \size normal
14212 \emph off
14213 \bar no
14214 \noun off
14215 \color none
14216 convert floating point to signed char
14217 \end_inset
14218 </cell>
14219 </row>
14220 <row topline="true">
14221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14222 \begin_inset Text
14223
14224 \layout Standard
14225
14226
14227 \family roman
14228 \series medium
14229 \shape up
14230 \size normal
14231 \emph off
14232 \bar no
14233 \noun off
14234 \color none
14235 _fs2uint.c
14236 \end_inset
14237 </cell>
14238 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14239 \begin_inset Text
14240
14241 \layout Standard
14242
14243
14244 \family roman
14245 \series medium
14246 \shape up
14247 \size normal
14248 \emph off
14249 \bar no
14250 \noun off
14251 \color none
14252 convert floating point to unsigned int
14253 \end_inset
14254 </cell>
14255 </row>
14256 <row topline="true">
14257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14258 \begin_inset Text
14259
14260 \layout Standard
14261
14262
14263 \family roman
14264 \series medium
14265 \shape up
14266 \size normal
14267 \emph off
14268 \bar no
14269 \noun off
14270 \color none
14271 _fs2int.c
14272 \end_inset
14273 </cell>
14274 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14275 \begin_inset Text
14276
14277 \layout Standard
14278
14279
14280 \family roman
14281 \series medium
14282 \shape up
14283 \size normal
14284 \emph off
14285 \bar no
14286 \noun off
14287 \color none
14288 convert floating point to signed int
14289 \end_inset
14290 </cell>
14291 </row>
14292 <row topline="true">
14293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14294 \begin_inset Text
14295
14296 \layout Standard
14297
14298
14299 \family roman
14300 \series medium
14301 \shape up
14302 \size normal
14303 \emph off
14304 \bar no
14305 \noun off
14306 \color none
14307 _fs2ulong.
14308 \family default
14309 \series default
14310 \shape default
14311 \size default
14312 \emph default
14313 \bar default
14314 \noun default
14315 \color default
14316 c
14317 \end_inset
14318 </cell>
14319 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14320 \begin_inset Text
14321
14322 \layout Standard
14323
14324
14325 \family roman
14326 \series medium
14327 \shape up
14328 \size normal
14329 \emph off
14330 \bar no
14331 \noun off
14332 \color none
14333 convert floating point to unsigned long
14334 \end_inset
14335 </cell>
14336 </row>
14337 <row topline="true">
14338 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14339 \begin_inset Text
14340
14341 \layout Standard
14342
14343
14344 \family roman
14345 \series medium
14346 \shape up
14347 \size normal
14348 \emph off
14349 \bar no
14350 \noun off
14351 \color none
14352 _fs2long.c
14353 \end_inset
14354 </cell>
14355 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14356 \begin_inset Text
14357
14358 \layout Standard
14359
14360
14361 \family roman
14362 \series medium
14363 \shape up
14364 \size normal
14365 \emph off
14366 \bar no
14367 \noun off
14368 \color none
14369 convert floating point to signed long
14370 \end_inset
14371 </cell>
14372 </row>
14373 <row topline="true">
14374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14375 \begin_inset Text
14376
14377 \layout Standard
14378
14379
14380 \family roman
14381 \series medium
14382 \shape up
14383 \size normal
14384 \emph off
14385 \bar no
14386 \noun off
14387 \color none
14388 _uchar2fs.c
14389 \end_inset
14390 </cell>
14391 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14392 \begin_inset Text
14393
14394 \layout Standard
14395
14396
14397 \family roman
14398 \series medium
14399 \shape up
14400 \size normal
14401 \emph off
14402 \bar no
14403 \noun off
14404 \color none
14405 convert unsigned char to floating point
14406 \end_inset
14407 </cell>
14408 </row>
14409 <row topline="true">
14410 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14411 \begin_inset Text
14412
14413 \layout Standard
14414
14415
14416 \family roman
14417 \series medium
14418 \shape up
14419 \size normal
14420 \emph off
14421 \bar no
14422 \noun off
14423 \color none
14424 _char2fs.c
14425 \end_inset
14426 </cell>
14427 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14428 \begin_inset Text
14429
14430 \layout Standard
14431
14432
14433 \family roman
14434 \series medium
14435 \shape up
14436 \size normal
14437 \emph off
14438 \bar no
14439 \noun off
14440 \color none
14441 convert char to floating point number
14442 \end_inset
14443 </cell>
14444 </row>
14445 <row topline="true">
14446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14447 \begin_inset Text
14448
14449 \layout Standard
14450
14451
14452 \family roman
14453 \series medium
14454 \shape up
14455 \size normal
14456 \emph off
14457 \bar no
14458 \noun off
14459 \color none
14460 _uint2fs.c
14461 \end_inset
14462 </cell>
14463 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14464 \begin_inset Text
14465
14466 \layout Standard
14467
14468
14469 \family roman
14470 \series medium
14471 \shape up
14472 \size normal
14473 \emph off
14474 \bar no
14475 \noun off
14476 \color none
14477 convert unsigned int to floating point
14478 \end_inset
14479 </cell>
14480 </row>
14481 <row topline="true">
14482 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14483 \begin_inset Text
14484
14485 \layout Standard
14486
14487
14488 \family roman
14489 \series medium
14490 \shape up
14491 \size normal
14492 \emph off
14493 \bar no
14494 \noun off
14495 \color none
14496 _int2fs.c
14497 \end_inset
14498 </cell>
14499 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14500 \begin_inset Text
14501
14502 \layout Standard
14503
14504
14505 \family roman
14506 \series medium
14507 \shape up
14508 \size normal
14509 \emph off
14510 \bar no
14511 \noun off
14512 \color none
14513 convert int to floating point numbers
14514 \end_inset
14515 </cell>
14516 </row>
14517 <row topline="true">
14518 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14519 \begin_inset Text
14520
14521 \layout Standard
14522
14523
14524 \family roman
14525 \series medium
14526 \shape up
14527 \size normal
14528 \emph off
14529 \bar no
14530 \noun off
14531 \color none
14532 _ulong2fs.c
14533 \end_inset
14534 </cell>
14535 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14536 \begin_inset Text
14537
14538 \layout Standard
14539
14540
14541 \family roman
14542 \series medium
14543 \shape up
14544 \size normal
14545 \emph off
14546 \bar no
14547 \noun off
14548 \color none
14549 convert unsigned long to floating point number
14550 \end_inset
14551 </cell>
14552 </row>
14553 <row topline="true" bottomline="true">
14554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14555 \begin_inset Text
14556
14557 \layout Standard
14558
14559
14560 \family roman
14561 \series medium
14562 \shape up
14563 \size normal
14564 \emph off
14565 \bar no
14566 \noun off
14567 \color none
14568 _long2fs.c
14569 \end_inset
14570 </cell>
14571 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14572 \begin_inset Text
14573
14574 \layout Standard
14575
14576
14577 \family roman
14578 \series medium
14579 \shape up
14580 \size normal
14581 \emph off
14582 \bar no
14583 \noun off
14584 \color none
14585 convert long to floating point number
14586 \end_inset
14587 </cell>
14588 </row>
14589 </lyxtabular>
14590
14591 \end_inset
14592
14593
14594 \newline
14595
14596 \layout Standard
14597
14598 These support routines are developed in ANSI-C so there is room for space
14599  and speed improvement
14600 \begin_inset Foot
14601 collapsed false
14602
14603 \layout Standard
14604
14605 The floating point routines for the mcs51 are implemented in assembler
14606 \end_inset
14607
14608 .
14609  Note if all these routines are used simultaneously the data space might
14610  overflow.
14611  For serious floating point usage the large model might be needed.
14612  Also notice that you don't have to call this routines directly.
14613  The compiler will use them automatically every time a floating point operation
14614  is required.
14615 \layout Section
14616
14617 Library Routines
14618 \begin_inset LatexCommand \index{Libraries}
14619
14620 \end_inset
14621
14622
14623 \layout Standard
14624
14625
14626 \emph on
14627 <pending: this is messy and incomplete - a little more information is in
14628  sdcc/doc/libdoc.txt
14629 \emph default
14630  >
14631 \layout Subsection
14632
14633 Compiler support routines (_gptrget, _mulint etc.)
14634 \layout Subsection
14635
14636 Stdclib functions (puts, printf, strcat etc.)
14637 \layout Subsubsection
14638
14639 <stdio.h>
14640 \layout Standard
14641
14642
14643 \begin_inset LatexCommand \index{<stdio.h>}
14644
14645 \end_inset
14646
14647 As usual on embedded systems you have to provide your own
14648 \family typewriter
14649 getchar()
14650 \begin_inset LatexCommand \index{getchar()}
14651
14652 \end_inset
14653
14654
14655 \family default
14656 and
14657 \family typewriter
14658 putchar()
14659 \begin_inset LatexCommand \index{putchar()}
14660
14661 \end_inset
14662
14663
14664 \family default
14665  routines.
14666  SDCC does not know whether the system connects to a serial line with or
14667  without handshake, LCD, keyboard or other device.
14668  You'll find examples for serial routines f.e.
14669  in sdcc/device/lib.
14670 \layout Standard
14671
14672 The default
14673 \family typewriter
14674  printf()
14675 \begin_inset LatexCommand \index{printf()}
14676
14677 \end_inset
14678
14679
14680 \family default
14681 implementation in
14682 \family typewriter
14683  printf_large.c
14684 \family default
14685  does not support float (except on ds390).
14686  To enable this recompile it with the option
14687 \emph on
14688 -
14689 \begin_inset ERT
14690 status Collapsed
14691
14692 \layout Standard
14693
14694 \backslash
14695 /
14696 \end_inset
14697
14698 DUSE_FLOATS=1
14699 \begin_inset LatexCommand \index{USE\_FLOATS}
14700
14701 \end_inset
14702
14703
14704 \emph default
14705  on the command line.
14706  Use
14707 \emph on
14708 -
14709 \begin_inset ERT
14710 status Collapsed
14711
14712 \layout Standard
14713
14714 \backslash
14715 /
14716 \end_inset
14717
14718 -model-large
14719 \begin_inset LatexCommand \index{-\/-model-large}
14720
14721 \end_inset
14722
14723
14724 \emph default
14725  for the mcs51 port, since this uses a lot of memory.
14726 \layout Standard
14727
14728 If you're short on memory you might want to use
14729 \family typewriter
14730 printf_small()
14731 \begin_inset LatexCommand \index{printf\_small()}
14732
14733 \end_inset
14734
14735
14736 \family default
14737
14738 \emph on
14739 instead
14740 \emph default
14741  of
14742 \family typewriter
14743  printf().
14744
14745 \family default
14746  For the mcs51 there additionally are assembly versions
14747 \family typewriter
14748 printf_tiny()
14749 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
14750
14751 \end_inset
14752
14753
14754 \family default
14755  and
14756 \family typewriter
14757 printf_fast()
14758 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
14759
14760 \end_inset
14761
14762
14763 \family default
14764 and
14765 \family typewriter
14766  printf_fast_f()
14767 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
14768
14769 \end_inset
14770
14771
14772 \family default
14773  which should fit the requirements of many embedded systems (printf_fast()
14774  can be customized by unsetting #defines to
14775 \emph on
14776 not
14777 \emph default
14778  support long variables and field widths).
14779 \layout Subsection
14780
14781 Math functions (sin, pow, sqrt etc.)
14782 \layout Subsection
14783
14784 Other libraries
14785 \layout Standard
14786
14787 Libraries
14788 \begin_inset LatexCommand \index{Libraries}
14789
14790 \end_inset
14791
14792  included in SDCC should have a license at least as liberal as the GNU Lesser
14793  General Public License
14794 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14795
14796 \end_inset
14797
14798
14799 \emph on
14800 LGPL
14801 \emph default
14802 .
14803 \layout Comment
14804
14805 license statements for the libraries are missing.
14806  sdcc/device/lib/ser_ir.c
14807 \layout Comment
14808
14809 or _decdptr f.e.
14810  come with a GPL (as opposed to LGPL) License - this will not be liberal
14811  enough for many embedded programmers.
14812 \layout Standard
14813
14814 If you have ported some library or want to share experience about some code
14815  which f.e.
14816  falls into any of these categories Busses (I
14817 \begin_inset Formula $^{\textrm{2}}$
14818 \end_inset
14819
14820 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14821  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14822  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14823 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14824
14825 \end_inset
14826
14827 \SpecialChar ~
14828 would certainly like to hear about it.
14829  Programmers coding for embedded systems are not especially famous for being
14830  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14831 e these references are very valuable.
14832  Let's help to create a climate where information is shared.
14833 \layout Section
14834
14835 Memory Models
14836 \layout Subsection
14837
14838 MCS51 Memory Models
14839 \begin_inset LatexCommand \index{Memory model}
14840
14841 \end_inset
14842
14843
14844 \begin_inset LatexCommand \index{MCS51 memory model}
14845
14846 \end_inset
14847
14848
14849 \layout Subsubsection
14850
14851 Small, Medium and Large
14852 \layout Standard
14853
14854 SDCC allows three memory models for MCS51 code,
14855 \shape slanted
14856 small, medium
14857 \shape default
14858  and
14859 \shape slanted
14860 large
14861 \shape default
14862 .
14863  Modules compiled with different memory models should
14864 \emph on
14865 never
14866 \emph default
14867  be combined together or the results would be unpredictable.
14868  The library routines supplied with the compiler are compiled as small,
14869  medium and large.
14870  The compiled library modules are contained in separate directories as small,
14871  medium and large so that you can link to the appropriate set.
14872 \layout Standard
14873
14874 When the medium or large model is used all variables declared without a
14875  storage class will be allocated into the external ram, this includes all
14876  parameters and local variables (for non-reentrant
14877 \begin_inset LatexCommand \index{reentrant}
14878
14879 \end_inset
14880
14881  functions).
14882  When the small model is used variables without storage class are allocated
14883  in the internal ram.
14884 \layout Standard
14885
14886 Judicious usage of the processor specific storage classes
14887 \begin_inset LatexCommand \index{Storage class}
14888
14889 \end_inset
14890
14891  and the 'reentrant' function type will yield much more efficient code,
14892  than using the large model.
14893  Several optimizations are disabled when the program is compiled using the
14894  large model, it is therefore recommended that the small model be used unless
14895  absolutely required.
14896 \layout Subsubsection
14897
14898 External Stack
14899 \begin_inset LatexCommand \label{sub:External-Stack}
14900
14901 \end_inset
14902
14903
14904 \begin_inset LatexCommand \index{stack}
14905
14906 \end_inset
14907
14908
14909 \begin_inset LatexCommand \index{External stack (mcs51)}
14910
14911 \end_inset
14912
14913
14914 \layout Standard
14915
14916 The external stack (-
14917 \begin_inset ERT
14918 status Collapsed
14919
14920 \layout Standard
14921
14922 \backslash
14923 /
14924 \end_inset
14925
14926 -xstack option
14927 \begin_inset LatexCommand \index{-\/-xstack}
14928
14929 \end_inset
14930
14931 ) is located in pdata
14932 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14933
14934 \end_inset
14935
14936  memory (usually at the start of the external ram segment) and uses all
14937  unused space in pdata (max.
14938  256 bytes).
14939  When -
14940 \begin_inset ERT
14941 status Collapsed
14942
14943 \layout Standard
14944
14945 \backslash
14946 /
14947 \end_inset
14948
14949 -xstack option is used to compile the program, the parameters and local
14950  variables
14951 \begin_inset LatexCommand \index{local variables}
14952
14953 \end_inset
14954
14955  of all reentrant functions are allocated in this area.
14956  This option is provided for programs with large stack space requirements.
14957  When used with the -
14958 \begin_inset ERT
14959 status Collapsed
14960
14961 \layout Standard
14962
14963 \backslash
14964 /
14965 \end_inset
14966
14967 -stack-auto
14968 \begin_inset LatexCommand \index{-\/-stack-auto}
14969
14970 \end_inset
14971
14972  option, all parameters and local variables are allocated on the external
14973  stack (note: support libraries will need to be recompiled with the same
14974  options.
14975  There is a predefined target in the library makefile).
14976 \layout Standard
14977
14978 The compiler outputs the higher order address byte of the external ram segment
14979  into port P2
14980 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14981
14982 \end_inset
14983
14984  (see also section
14985 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14986
14987 \end_inset
14988
14989 ), therefore when using the External Stack option, this port
14990 \emph on
14991 may not
14992 \emph default
14993  be used by the application program.
14994 \layout Subsection
14995
14996 DS390 Memory Model
14997 \begin_inset LatexCommand \index{Memory model}
14998
14999 \end_inset
15000
15001
15002 \begin_inset LatexCommand \index{DS390 memory model}
15003
15004 \end_inset
15005
15006
15007 \layout Standard
15008
15009 The only model supported is Flat 24
15010 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
15011
15012 \end_inset
15013
15014 .
15015  This generates code for the 24 bit contiguous addressing mode of the Dallas
15016  DS80C390 part.
15017  In this mode, up to four meg of external RAM or code space can be directly
15018  addressed.
15019  See the data sheets at www.dalsemi.com for further information on this part.
15020 \newline
15021
15022 \newline
15023 Note that the compiler does not generate any code to place the processor
15024  into 24 bitmode (although
15025 \emph on
15026 tinibios
15027 \emph default
15028  in the ds390 libraries will do that for you).
15029  If you don't use
15030 \emph on
15031 tinibios
15032 \emph default
15033
15034 \begin_inset LatexCommand \index{Tinibios (DS390)}
15035
15036 \end_inset
15037
15038 , the boot loader or similar code must ensure that the processor is in 24
15039  bit contiguous addressing mode before calling the SDCC startup code.
15040 \newline
15041
15042 \newline
15043 Like the
15044 \emph on
15045 -
15046 \begin_inset ERT
15047 status Collapsed
15048
15049 \layout Standard
15050
15051 \backslash
15052 /
15053 \end_inset
15054
15055 -model-large
15056 \emph default
15057  option, variables will by default be placed into the XDATA segment.
15058
15059 \newline
15060
15061 \newline
15062 Segments may be placed anywhere in the 4 meg address space using the usual
15063  -
15064 \begin_inset ERT
15065 status Collapsed
15066
15067 \layout Standard
15068
15069 \backslash
15070 /
15071 \end_inset
15072
15073 -*-loc options.
15074  Note that if any segments are located above 64K, the -r flag must be passed
15075  to the linker to generate the proper segment relocations, and the Intel
15076  HEX output format must be used.
15077  The -r flag can be passed to the linker by using the option
15078 \emph on
15079 -Wl-r
15080 \emph default
15081  on the SDCC command line.
15082  However, currently the linker can not handle code segments > 64k.
15083 \layout Section
15084
15085 Pragmas
15086 \begin_inset LatexCommand \index{Pragmas}
15087
15088 \end_inset
15089
15090
15091 \layout Standard
15092
15093 SDCC supports the following #pragma directives:
15094 \layout Itemize
15095
15096 save
15097 \begin_inset LatexCommand \index{\#pragma save}
15098
15099 \end_inset
15100
15101  - this will save all current options to the save/restore stack.
15102  See #pragma\SpecialChar ~
15103 restore.
15104 \layout Itemize
15105
15106 restore
15107 \begin_inset LatexCommand \index{\#pragma restore}
15108
15109 \end_inset
15110
15111  - will restore saved options from the last save.
15112  saves & restores can be nested.
15113  SDCC uses a save/restore stack: save pushes current options to the stack,
15114  restore pulls current options from the stack.
15115  See #pragma\SpecialChar ~
15116 save.
15117 \newline
15118
15119 \layout Itemize
15120
15121 callee_saves
15122 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15123
15124 \end_inset
15125
15126
15127 \begin_inset LatexCommand \index{function prologue}
15128
15129 \end_inset
15130
15131  function1[,function2[,function3...]] - The compiler by default uses a caller
15132  saves convention for register saving across function calls, however this
15133  can cause unnecessary register pushing & popping
15134 \begin_inset LatexCommand \index{push/pop}
15135
15136 \end_inset
15137
15138  when calling small functions from larger functions.
15139  This option can be used to switch off the register saving convention for
15140  the function names specified.
15141  The compiler will not save registers when calling these functions, extra
15142  code need to be manually inserted at the entry & exit for these functions
15143  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15144  reduce code & improve run time performance of the generated code.
15145  In the future the compiler (with inter procedural analysis) may be able
15146  to determine the appropriate scheme to use for each function call.
15147  If -
15148 \begin_inset ERT
15149 status Collapsed
15150
15151 \layout Standard
15152
15153 \backslash
15154 /
15155 \end_inset
15156
15157 -callee-saves command line option is used, the function names specified
15158  in #pragma\SpecialChar ~
15159 callee_saves
15160 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15161
15162 \end_inset
15163
15164  is appended to the list of functions specified in the command line.
15165 \layout Itemize
15166
15167 exclude
15168 \begin_inset LatexCommand \index{\#pragma exclude}
15169
15170 \end_inset
15171
15172  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15173  of pairs of push/pop
15174 \begin_inset LatexCommand \index{push/pop}
15175
15176 \end_inset
15177
15178  instructions in
15179 \emph on
15180 I
15181 \emph default
15182 nterrupt
15183 \begin_inset LatexCommand \index{interrupt}
15184
15185 \end_inset
15186
15187
15188 \emph on
15189 S
15190 \emph default
15191 ervice
15192 \emph on
15193 R
15194 \emph default
15195 outines.
15196  The directive should be placed immediately before the ISR function definition
15197  and it affects ALL ISR functions following it.
15198  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15199 exclude\SpecialChar ~
15200 none
15201 \begin_inset LatexCommand \index{\#pragma exclude}
15202
15203 \end_inset
15204
15205 .
15206  See also the related keyword _naked
15207 \begin_inset LatexCommand \index{\_naked}
15208
15209 \end_inset
15210
15211
15212 \begin_inset LatexCommand \index{\_\_naked}
15213
15214 \end_inset
15215
15216 .
15217 \layout Itemize
15218
15219 less_pedantic
15220 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15221
15222 \end_inset
15223
15224  - the compiler will not warn you anymore for obvious mistakes, you'r on
15225  your own now ;-(
15226 \layout Itemize
15227
15228 disable_warning <nnnn>
15229 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15230
15231 \end_inset
15232
15233  - the compiler will not warn you anymore about warning number <nnnn>.
15234 \layout Itemize
15235
15236 nogcse
15237 \begin_inset LatexCommand \index{\#pragma nogcse}
15238
15239 \end_inset
15240
15241  - will stop global common subexpression elimination.
15242 \layout Itemize
15243
15244 noinduction
15245 \begin_inset LatexCommand \index{\#pragma noinduction}
15246
15247 \end_inset
15248
15249  - will stop loop induction optimizations.
15250 \layout Itemize
15251
15252 noinvariant
15253 \begin_inset LatexCommand \index{\#pragma noinvariant}
15254
15255 \end_inset
15256
15257  - will not do loop invariant optimizations.
15258  For more details see Loop Invariants in section
15259 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15260
15261 \end_inset
15262
15263 .
15264 \layout Itemize
15265
15266 noiv
15267 \begin_inset LatexCommand \index{\#pragma noiv}
15268
15269 \end_inset
15270
15271  - Do not generate interrupt
15272 \begin_inset LatexCommand \index{interrupt}
15273
15274 \end_inset
15275
15276  vector table entries for all ISR functions defined after the pragma.
15277  This is useful in cases where the interrupt vector table must be defined
15278  manually, or when there is a secondary, manually defined interrupt vector
15279  table (e.g.
15280  for the autovector feature of the Cypress EZ-USB FX2).
15281  More elegantly this can be achieved by obmitting the optional interrupt
15282  number after the interrupt keyword, see section
15283 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15284
15285 \end_inset
15286
15287 \SpecialChar ~
15288 about interrupts.
15289 \layout Itemize
15290
15291 nojtbound
15292 \begin_inset LatexCommand \index{\#pragma nojtbound}
15293
15294 \end_inset
15295
15296  - will not generate code for boundary value checking, when switch statements
15297  are turned into jump-tables (dangerous).
15298  For more details see section
15299 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15300
15301 \end_inset
15302
15303 .
15304 \layout Itemize
15305
15306 noloopreverse
15307 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15308
15309 \end_inset
15310
15311  - Will not do loop reversal optimization
15312 \layout Itemize
15313
15314 nooverlay
15315 \begin_inset LatexCommand \index{\#pragma nooverlay}
15316
15317 \end_inset
15318
15319  - the compiler will not overlay the parameters and local variables of a
15320  function.
15321 \layout Itemize
15322
15323 stackauto
15324 \begin_inset LatexCommand \index{\#pragma stackauto}
15325
15326 \end_inset
15327
15328 - See option -
15329 \begin_inset ERT
15330 status Collapsed
15331
15332 \layout Standard
15333
15334 \backslash
15335 /
15336 \end_inset
15337
15338 -stack-auto
15339 \begin_inset LatexCommand \index{-\/-stack-auto}
15340
15341 \end_inset
15342
15343  and section
15344 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
15345
15346 \end_inset
15347
15348  Parameters and Local Variables.
15349 \layout Itemize
15350
15351 opt_code_speed
15352 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
15353
15354 \end_inset
15355
15356 - The compiler will optimize code generation towards fast code, possibly
15357  at the expense of code size.
15358 \layout Itemize
15359
15360 opt_code_size
15361 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
15362
15363 \end_inset
15364
15365 - The compiler will optimize code generation towards compact code, possibly
15366  at the expense of code speed.
15367 \layout Itemize
15368
15369 opt_code_balanced
15370 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
15371
15372 \end_inset
15373
15374 - The compiler will attempt to generate code that is both compact and fast,
15375  as long as meeting one goal is not a detriment to the other (this is the
15376  default).
15377
15378 \layout Itemize
15379
15380 std_sdcc89
15381 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
15382
15383 \end_inset
15384
15385 - Generally follow the C89 standard, but allow SDCC features that conflict
15386  with the standard (default).
15387 \layout Itemize
15388
15389 std_c89
15390 \begin_inset LatexCommand \index{\#pragma std\_c89}
15391
15392 \end_inset
15393
15394 - Follow the C89 standard and disable SDCC features that conflict with the
15395  standard.
15396 \layout Itemize
15397
15398 std_sdcc99
15399 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
15400
15401 \end_inset
15402
15403 - Generally follow the C99 standard, but allow SDCC features that conflict
15404  with the standard (incomplete support).
15405 \layout Itemize
15406
15407 std_c99
15408 \begin_inset LatexCommand \index{\#pragma std\_c99}
15409
15410 \end_inset
15411
15412 - Follow the C99 standard and disable SDCC features that conflict with the
15413  standard (incomplete support).
15414 \layout Itemize
15415
15416 codeseg <name>
15417 \begin_inset LatexCommand \index{\#pragma codeseg}
15418
15419 \end_inset
15420
15421 - Use this name (max.
15422  8 characters) for the code segment.
15423 \layout Itemize
15424
15425 constseg <name>
15426 \begin_inset LatexCommand \index{\#pragma constseg}
15427
15428 \end_inset
15429
15430 - Use this name (max.
15431  8 characters) for the const segment.
15432 \layout Standard
15433
15434 SDCPP supports the following #pragma directives:
15435 \layout Itemize
15436
15437 preproc_asm
15438 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
15439
15440 \end_inset
15441
15442  (+ | -) - switch _asm _endasm block preprocessing on / off.
15443  Default is on.
15444 \layout Standard
15445
15446 The pragma's are intended to be used to turn-on or off certain optimizations
15447  which might cause the compiler to generate extra stack / data space to
15448  store compiler generated temporary variables.
15449  This usually happens in large functions.
15450  Pragma directives should be used as shown in the following example, they
15451  are used to control options & optimizations for a given function; pragmas
15452  should be placed before and/or after a function, placing pragma's inside
15453  a function body could have unpredictable results.
15454 \layout Verse
15455
15456
15457 \family typewriter
15458 #pragma save
15459 \begin_inset LatexCommand \index{\#pragma save}
15460
15461 \end_inset
15462
15463  \SpecialChar ~
15464 \SpecialChar ~
15465 \SpecialChar ~
15466 \SpecialChar ~
15467 \SpecialChar ~
15468 \SpecialChar ~
15469 \SpecialChar ~
15470 /* save the current settings */
15471 \newline
15472 #pragma nogcse
15473 \begin_inset LatexCommand \index{\#pragma nogcse}
15474
15475 \end_inset
15476
15477  \SpecialChar ~
15478 \SpecialChar ~
15479 \SpecialChar ~
15480 \SpecialChar ~
15481 \SpecialChar ~
15482 /* turnoff global subexpression elimination */
15483 \newline
15484 #pragma noinduction
15485 \begin_inset LatexCommand \index{\#pragma noinduction}
15486
15487 \end_inset
15488
15489  /* turn off induction optimizations */
15490 \newline
15491 int foo ()
15492 \newline
15493 {
15494 \newline
15495 \SpecialChar ~
15496  \SpecialChar ~
15497  ...
15498
15499 \newline
15500 \SpecialChar ~
15501  \SpecialChar ~
15502  /* large code */
15503 \newline
15504 \SpecialChar ~
15505  \SpecialChar ~
15506  ...
15507
15508 \newline
15509 }
15510 \newline
15511 #pragma restore
15512 \begin_inset LatexCommand \index{\#pragma restore}
15513
15514 \end_inset
15515
15516  /* turn the optimizations back on */
15517 \layout Standard
15518
15519 The compiler will generate a warning message when extra space is allocated.
15520  It is strongly recommended that the save and restore pragma's be used when
15521  changing options for a function.
15522 \layout Section
15523
15524 Defines Created by the Compiler
15525 \layout Standard
15526
15527 The compiler creates the following #defines
15528 \begin_inset LatexCommand \index{\#defines}
15529
15530 \end_inset
15531
15532
15533 \begin_inset LatexCommand \index{Defines created by the compiler}
15534
15535 \end_inset
15536
15537 :
15538 \newline
15539
15540 \layout Standard
15541
15542
15543 \begin_inset  Tabular
15544 <lyxtabular version="3" rows="11" columns="2">
15545 <features>
15546 <column alignment="center" valignment="top" leftline="true" width="0">
15547 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15548 <row topline="true" bottomline="true">
15549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15550 \begin_inset Text
15551
15552 \layout Standard
15553
15554
15555 \series bold
15556 #define
15557 \end_inset
15558 </cell>
15559 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15560 \begin_inset Text
15561
15562 \layout Standard
15563
15564
15565 \series bold
15566 Description
15567 \end_inset
15568 </cell>
15569 </row>
15570 <row topline="true">
15571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15572 \begin_inset Text
15573
15574 \layout Standard
15575
15576 SDCC
15577 \begin_inset LatexCommand \index{SDCC}
15578
15579 \end_inset
15580
15581
15582 \end_inset
15583 </cell>
15584 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15585 \begin_inset Text
15586
15587 \layout Standard
15588
15589 this Symbol is always defined
15590 \end_inset
15591 </cell>
15592 </row>
15593 <row topline="true">
15594 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15595 \begin_inset Text
15596
15597 \layout Standard
15598
15599 SDCC_mcs51
15600 \begin_inset LatexCommand \index{SDCC\_mcs51}
15601
15602 \end_inset
15603
15604  or SDCC_ds390
15605 \begin_inset LatexCommand \index{SDCC\_ds390}
15606
15607 \end_inset
15608
15609  or SDCC_z80
15610 \begin_inset LatexCommand \index{SDCC\_z80}
15611
15612 \end_inset
15613
15614 , etc
15615 \end_inset
15616 </cell>
15617 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15618 \begin_inset Text
15619
15620 \layout Standard
15621
15622 depending on the model used (e.g.: -mds390
15623 \end_inset
15624 </cell>
15625 </row>
15626 <row topline="true">
15627 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15628 \begin_inset Text
15629
15630 \layout Standard
15631
15632 __mcs51
15633 \begin_inset LatexCommand \index{\_\_mcs51}
15634
15635 \end_inset
15636
15637 , __ds390
15638 \begin_inset LatexCommand \index{\_\_ds390}
15639
15640 \end_inset
15641
15642 , __hc08
15643 \begin_inset LatexCommand \index{\_\_hc08}
15644
15645 \end_inset
15646
15647 , __z80
15648 \begin_inset LatexCommand \index{\_\_z80}
15649
15650 \end_inset
15651
15652 , etc
15653 \end_inset
15654 </cell>
15655 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15656 \begin_inset Text
15657
15658 \layout Standard
15659
15660 depending on the model used (e.g.
15661  -mz80)
15662 \end_inset
15663 </cell>
15664 </row>
15665 <row topline="true">
15666 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15667 \begin_inset Text
15668
15669 \layout Standard
15670
15671 SDCC_STACK_AUTO
15672 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
15673
15674 \end_inset
15675
15676
15677 \end_inset
15678 </cell>
15679 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15680 \begin_inset Text
15681
15682 \layout Standard
15683
15684 when
15685 \emph on
15686 -
15687 \begin_inset ERT
15688 status Collapsed
15689
15690 \layout Standard
15691
15692 \backslash
15693 /
15694 \end_inset
15695
15696 -stack-auto
15697 \emph default
15698  option is used
15699 \end_inset
15700 </cell>
15701 </row>
15702 <row topline="true">
15703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15704 \begin_inset Text
15705
15706 \layout Standard
15707
15708 SDCC_MODEL_SMALL
15709 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
15710
15711 \end_inset
15712
15713
15714 \end_inset
15715 </cell>
15716 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15717 \begin_inset Text
15718
15719 \layout Standard
15720
15721 when
15722 \emph on
15723 -
15724 \begin_inset ERT
15725 status Collapsed
15726
15727 \layout Standard
15728
15729 \backslash
15730 /
15731 \end_inset
15732
15733 -model-small
15734 \emph default
15735  is used
15736 \end_inset
15737 </cell>
15738 </row>
15739 <row topline="true">
15740 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15741 \begin_inset Text
15742
15743 \layout Standard
15744
15745 SDCC_MODEL_MEDIUM
15746 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
15747
15748 \end_inset
15749
15750
15751 \end_inset
15752 </cell>
15753 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15754 \begin_inset Text
15755
15756 \layout Standard
15757
15758 when
15759 \emph on
15760 -
15761 \begin_inset ERT
15762 status Collapsed
15763
15764 \layout Standard
15765
15766 \backslash
15767 /
15768 \end_inset
15769
15770 -model-medium
15771 \emph default
15772  is used
15773 \end_inset
15774 </cell>
15775 </row>
15776 <row topline="true">
15777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15778 \begin_inset Text
15779
15780 \layout Standard
15781
15782 SDCC_MODEL_LARGE
15783 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
15784
15785 \end_inset
15786
15787
15788 \end_inset
15789 </cell>
15790 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15791 \begin_inset Text
15792
15793 \layout Standard
15794
15795 when
15796 \emph on
15797 -
15798 \begin_inset ERT
15799 status Collapsed
15800
15801 \layout Standard
15802
15803 \backslash
15804 /
15805 \end_inset
15806
15807 -model-large
15808 \emph default
15809  is used
15810 \end_inset
15811 </cell>
15812 </row>
15813 <row topline="true">
15814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15815 \begin_inset Text
15816
15817 \layout Standard
15818
15819 SDCC_USE_XSTACK
15820 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15821
15822 \end_inset
15823
15824
15825 \end_inset
15826 </cell>
15827 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15828 \begin_inset Text
15829
15830 \layout Standard
15831
15832 when
15833 \emph on
15834 -
15835 \begin_inset ERT
15836 status Collapsed
15837
15838 \layout Standard
15839
15840 \backslash
15841 /
15842 \end_inset
15843
15844 -xstack
15845 \emph default
15846  option is used
15847 \end_inset
15848 </cell>
15849 </row>
15850 <row topline="true">
15851 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15852 \begin_inset Text
15853
15854 \layout Standard
15855
15856 SDCC_STACK_TENBIT
15857 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
15858
15859 \end_inset
15860
15861
15862 \end_inset
15863 </cell>
15864 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15865 \begin_inset Text
15866
15867 \layout Standard
15868
15869 when
15870 \emph on
15871 -mds390
15872 \emph default
15873  is used
15874 \end_inset
15875 </cell>
15876 </row>
15877 <row topline="true" bottomline="true">
15878 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15879 \begin_inset Text
15880
15881 \layout Standard
15882
15883 SDCC_MODEL_FLAT24
15884 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
15885
15886 \end_inset
15887
15888
15889 \end_inset
15890 </cell>
15891 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15892 \begin_inset Text
15893
15894 \layout Standard
15895
15896 when
15897 \emph on
15898 -mds390
15899 \emph default
15900  is used
15901 \end_inset
15902 </cell>
15903 </row>
15904 </lyxtabular>
15905
15906 \end_inset
15907
15908
15909 \layout Chapter
15910
15911 Notes on supported Processors
15912 \layout Section
15913
15914 MCS51 variants
15915 \begin_inset LatexCommand \label{sub:MCS51-variants}
15916
15917 \end_inset
15918
15919
15920 \begin_inset LatexCommand \index{MCS51 variants}
15921
15922 \end_inset
15923
15924
15925 \layout Standard
15926
15927 MCS51 processors are available from many vendors and come in many different
15928  flavours.
15929  While they might differ considerably in respect to Special Function Registers
15930  the core MCS51 is usually not modified or is kept compatible.
15931
15932 \layout Subsection
15933
15934 pdata access by SFR
15935 \layout Standard
15936
15937 With the upcome of devices with internal xdata and flash memory devices
15938  using port P2
15939 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15940
15941 \end_inset
15942
15943  as dedicated I/O port is becoming more popular.
15944  Switching the high byte for pdata
15945 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15946
15947 \end_inset
15948
15949  access which was formerly done by port P2 is then achieved by a Special
15950  Function Register
15951 \begin_inset LatexCommand \index{sfr}
15952
15953 \end_inset
15954
15955 .
15956  In well-established MCS51 tradition the address of this
15957 \emph on
15958 sfr
15959 \emph default
15960  is where the chip designers decided to put it.
15961  Needless to say that they didn't agree on a common name either.
15962  So that the startup code can correctly initialize xdata variables, you
15963  should define an sfr with the name _XPAGE
15964 \family typewriter
15965
15966 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
15967
15968 \end_inset
15969
15970
15971 \family default
15972  at the appropriate location if the default, port P2, is not used for this.
15973  Some examples are:
15974 \layout Verse
15975
15976
15977 \family typewriter
15978 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
15979 \layout Verse
15980
15981
15982 \family typewriter
15983 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
15984 \layout Verse
15985
15986
15987 \family typewriter
15988 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
15989 \layout Standard
15990
15991 For more exotic implementations further customizations may be needed.
15992  See section
15993 \begin_inset LatexCommand \ref{sub:Startup-Code}
15994
15995 \end_inset
15996
15997  for other possibilities.
15998 \layout Subsection
15999
16000 Other Features available by SFR
16001 \layout Standard
16002
16003 Some MCS51 variants offer features like Double DPTR
16004 \begin_inset LatexCommand \index{DPTR}
16005
16006 \end_inset
16007
16008 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
16009  These are currently not used for the MCS51 port.
16010  If you absolutely need them you can fall back to inline assembly or submit
16011  a patch to SDCC.
16012 \layout Section
16013
16014 DS400 port
16015 \layout Standard
16016
16017 The DS80C400 microcontroller has a rich set of peripherals.
16018  In its built-in ROM library it includes functions to access some of the
16019  features, among them is a TCP stack with IP4 and IP6 support.
16020  Library headers (currently in beta status) and other files are provided
16021  at
16022 \size footnotesize
16023
16024 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
16025
16026 \end_inset
16027
16028 .
16029
16030 \layout Section
16031
16032 The Z80 and gbz80 port
16033 \layout Standard
16034
16035 SDCC can target both the Zilog
16036 \begin_inset LatexCommand \index{Z80}
16037
16038 \end_inset
16039
16040  and the Nintendo Gameboy's Z80-like gbz80
16041 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
16042
16043 \end_inset
16044
16045 .
16046  The Z80 port is passed through the same
16047 \emph on
16048 regressions tests
16049 \begin_inset LatexCommand \index{Regression test}
16050
16051 \end_inset
16052
16053
16054 \emph default
16055  as the MCS51 and DS390 ports, so floating point support, support for long
16056  variables and bitfield support is fine.
16057  See mailing lists and forums about interrupt routines.
16058 \layout Standard
16059
16060 As always, the code is the authoritative reference - see z80/ralloc.c and
16061  z80/gen.c.
16062  The stack
16063 \begin_inset LatexCommand \index{stack}
16064
16065 \end_inset
16066
16067  frame is similar to that generated by the IAR Z80 compiler.
16068  IX is used as the base pointer, HL and IY are used as a temporary registers,
16069  and BC and DE are available for holding variables.
16070  Return values
16071 \begin_inset LatexCommand \index{return value}
16072
16073 \end_inset
16074
16075  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
16076  bytes).
16077  The gbz80 port use the same set of registers for the return values, but
16078  in a different order of significance: E (one byte), DE (two bytes), or
16079  HLDE (four bytes).
16080 \layout Section
16081
16082 The HC08 port
16083 \layout Standard
16084
16085 The port to the Motorola HC08
16086 \begin_inset LatexCommand \index{HC08}
16087
16088 \end_inset
16089
16090  family has been added in October 2003, and is still undergoing some basic
16091  development.
16092  The code generator is complete, but the register allocation is still quite
16093  unoptimized.
16094  Some of the SDCC's standard C library functions have embedded non-HC08
16095  inline assembly and so are not yet usable.
16096 \newline
16097
16098 \newline
16099
16100 \layout Section
16101
16102 The PIC14 port
16103 \layout Standard
16104
16105 The 14bit PIC
16106 \begin_inset LatexCommand \index{PIC14}
16107
16108 \end_inset
16109
16110  port still requires a major effort from the development community.
16111  However it can work for very simple code.
16112 \layout Subsection
16113
16114 C code and 14bit PIC code page
16115 \begin_inset LatexCommand \index{code page (pic14)}
16116
16117 \end_inset
16118
16119  and RAM banks
16120 \begin_inset LatexCommand \index{RAM bank (pic14)}
16121
16122 \end_inset
16123
16124
16125 \layout Standard
16126
16127 The linker organizes allocation for the code page and RAM banks.
16128  It does not have intimate knowledge of the code flow.
16129  It will put all the code section of a single asm file into a single code
16130  page.
16131  In order to make use of multiple code pages, separate asm files must be
16132  used.
16133  The compiler treats all functions of a single C file as being in the same
16134  code page unless it is non static.
16135  The compiler treats all local variables of a single C file as being in
16136  the same RAM bank unless it is an extern.
16137 \newline
16138
16139 \newline
16140 To get the best follow these guide lines:
16141 \layout Enumerate
16142
16143 make local functions static, as non static functions require code page selection
16144  overhead.
16145 \layout Enumerate
16146
16147 Make local variables static as extern variables require RAM bank selection
16148  overhead.
16149 \layout Enumerate
16150
16151 For devices that have multiple code pages it is more efficient to use the
16152  same number of files as pages, i.e.
16153  for the 16F877 use 4 separate files and i.e.
16154  for the 16F874 use 2 separate files.
16155  This way the linker can put the code for each file into different code
16156  pages and the compiler can allocate reusable variables more efficiently
16157  and there's less page selection overhead.
16158  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
16159  instruction set) use 'unsigned char' whereever possible instead of 'int'.
16160 \layout Subsection
16161
16162 Creating a device include file
16163 \layout Standard
16164
16165 For generating a device include file use the support perl script inc2h.pl
16166  kept in directory support/script.
16167 \layout Subsection
16168
16169 Interrupt code
16170 \layout Standard
16171
16172 For the interrupt function, use the keyword 'interrupt'
16173 \begin_inset LatexCommand \index{interrupt}
16174
16175 \end_inset
16176
16177  with level number of 0 (PIC14 only has 1 interrupt so this number is only
16178  there to avoid a syntax error - it ought to be fixed).
16179  E.g.:
16180 \layout Verse
16181
16182
16183 \family typewriter
16184 void Intr(void) interrupt 0
16185 \newline
16186 {
16187 \newline
16188 \SpecialChar ~
16189 \SpecialChar ~
16190 T0IF = 0; /* Clear timer interrupt */
16191 \newline
16192 }
16193 \layout Subsection
16194
16195 Linking and assembling
16196 \layout Standard
16197
16198 For assembling you can use either GPUTILS'
16199 \begin_inset LatexCommand \index{gputils (pic tools)}
16200
16201 \end_inset
16202
16203  gpasm.exe or MPLAB's mpasmwin.exe.
16204  GPUTILS is available from
16205 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
16206
16207 \end_inset
16208
16209 .
16210  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
16211  If you use MPLAB and an interrupt function then the linker script file
16212  vectors section will need to be enlarged to link with mplink.
16213 \newline
16214
16215 \newline
16216 Here is a
16217 \family typewriter
16218 Makefile
16219 \family default
16220  using GPUTILS:
16221 \layout Verse
16222
16223
16224 \family typewriter
16225 .c.o:
16226 \newline
16227 \SpecialChar ~
16228 \SpecialChar ~
16229 \SpecialChar ~
16230 \SpecialChar ~
16231 \SpecialChar ~
16232 \SpecialChar ~
16233 \SpecialChar ~
16234 \SpecialChar ~
16235 sdcc -S -V -mpic14 -p16F877 $<
16236 \newline
16237 \SpecialChar ~
16238 \SpecialChar ~
16239 \SpecialChar ~
16240 \SpecialChar ~
16241 \SpecialChar ~
16242 \SpecialChar ~
16243 \SpecialChar ~
16244 \SpecialChar ~
16245 gpasm -c $*.asm
16246 \newline
16247
16248 \newline
16249 $(PRJ).hex: $(OBJS)
16250 \newline
16251 \SpecialChar ~
16252 \SpecialChar ~
16253 \SpecialChar ~
16254 \SpecialChar ~
16255 \SpecialChar ~
16256 \SpecialChar ~
16257 \SpecialChar ~
16258 \SpecialChar ~
16259 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
16260 \layout Standard
16261
16262 Here is a
16263 \family typewriter
16264 Makefile
16265 \family default
16266  using MPLAB:
16267 \layout Verse
16268
16269
16270 \family typewriter
16271 .c.o:
16272 \newline
16273 \SpecialChar ~
16274 \SpecialChar ~
16275 \SpecialChar ~
16276 \SpecialChar ~
16277 \SpecialChar ~
16278 \SpecialChar ~
16279 \SpecialChar ~
16280 \SpecialChar ~
16281 sdcc -S -V -mpic14 -p16F877 $<
16282 \newline
16283 \SpecialChar ~
16284 \SpecialChar ~
16285 \SpecialChar ~
16286 \SpecialChar ~
16287 \SpecialChar ~
16288 \SpecialChar ~
16289 \SpecialChar ~
16290 \SpecialChar ~
16291 mpasmwin /q /o $*.asm
16292 \newline
16293
16294 \newline
16295 $(PRJ).hex: $(OBJS)
16296 \newline
16297 \SpecialChar ~
16298 \SpecialChar ~
16299 \SpecialChar ~
16300 \SpecialChar ~
16301 \SpecialChar ~
16302 \SpecialChar ~
16303 \SpecialChar ~
16304 \SpecialChar ~
16305 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
16306 \layout Standard
16307
16308 Please note that indentations within a
16309 \family typewriter
16310  Makefile
16311 \family default
16312  have to be done with a tabulator character.
16313 \layout Subsection
16314
16315 Command-line options
16316 \layout Standard
16317
16318 Besides the switches common to all SDCC backends, the PIC14 port accepts
16319  the following options (for an updated list see sdcc -
16320 \begin_inset ERT
16321 status Collapsed
16322
16323 \layout Standard
16324
16325 \backslash
16326 /
16327 \end_inset
16328
16329 -help):
16330 \layout List
16331 \labelwidthstring 00.00.0000
16332
16333 -
16334 \begin_inset ERT
16335 status Collapsed
16336
16337 \layout Standard
16338
16339 \backslash
16340 /
16341 \end_inset
16342
16343 -debug-extra emit debug info in assembly output
16344 \layout List
16345 \labelwidthstring 00.00.0000
16346
16347 -
16348 \begin_inset ERT
16349 status Collapsed
16350
16351 \layout Standard
16352
16353 \backslash
16354 /
16355 \end_inset
16356
16357 -no-pcode-opt disable (slightly faulty) optimization on pCode
16358 \layout Subsection
16359
16360 The library
16361 \layout Subsubsection
16362
16363 error: missing definition for symbol
16364 \begin_inset Quotes sld
16365 \end_inset
16366
16367 __gptrget1
16368 \begin_inset Quotes srd
16369 \end_inset
16370
16371
16372 \layout Standard
16373
16374 The PIC14 port uses library routines to provide more complex operations
16375  like multiplication, division/modulus and (generic) pointer dereferencing.
16376  In order to add these routines to your project, you must link with PIC14's
16377
16378 \family typewriter
16379 libsdcc.lib
16380 \family default
16381 .
16382  For single source file projects this is done automatically, more complex
16383  projects must add
16384 \family typewriter
16385 libsdcc.lib
16386 \family default
16387  to the linker's arguments.
16388  Make sure you also add an include path for the library (using the -I switch
16389  to the linker)!
16390 \layout Subsubsection
16391
16392 Processor mismatch in file
16393 \begin_inset Quotes sld
16394 \end_inset
16395
16396 XXX
16397 \begin_inset Quotes srd
16398 \end_inset
16399
16400 .
16401 \layout Standard
16402
16403 This warning can usually be ignored due to the very good compatibility amongst
16404  14 bit PIC devices.
16405 \layout Standard
16406
16407 You might also consider recompiling the library for your specific device
16408  by changing the ARCH=p16f877 (default target) entry in
16409 \family typewriter
16410 device/lib/pic/Makefile.in
16411 \family default
16412  and
16413 \family typewriter
16414 device/lib/pic/Makefile
16415 \family default
16416  to reflect your device.
16417  This might even improve performance for smaller devices as unneccesary
16418  BANKSELs migth be removed.
16419 \layout Subsection
16420
16421 Known bugs
16422 \layout Subsubsection
16423
16424 initialized data
16425 \layout Standard
16426
16427 Currently, data can only be initialized if it resides in the source file
16428  together with
16429 \emph on
16430 main()
16431 \emph default
16432 .
16433  Data in other source files will silently
16434 \series bold
16435 not
16436 \series default
16437  be initialized.
16438 \layout Section
16439
16440 The PIC16
16441 \begin_inset LatexCommand \index{PIC16}
16442
16443 \end_inset
16444
16445  port
16446 \layout Standard
16447
16448 The PIC16
16449 \begin_inset LatexCommand \index{PIC16}
16450
16451 \end_inset
16452
16453  port is the portion of SDCC that is responsible to produce code for the
16454  Microchip
16455 \begin_inset LatexCommand \index{Microchip}
16456
16457 \end_inset
16458
16459 (TM) microcontrollers with 16 bit core.
16460  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
16461  Currently supported devices are:
16462 \layout Standard
16463 \align center
16464
16465 \begin_inset  Tabular
16466 <lyxtabular version="3" rows="4" columns="6">
16467 <features>
16468 <column alignment="center" valignment="top" leftline="true" width="0">
16469 <column alignment="center" valignment="top" leftline="true" width="0">
16470 <column alignment="center" valignment="top" leftline="true" width="0">
16471 <column alignment="center" valignment="top" leftline="true" width="0">
16472 <column alignment="center" valignment="top" leftline="true" width="0">
16473 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16474 <row topline="true">
16475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16476 \begin_inset Text
16477
16478 \layout Standard
16479
16480 18F242
16481 \end_inset
16482 </cell>
16483 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16484 \begin_inset Text
16485
16486 \layout Standard
16487
16488 18F248
16489 \end_inset
16490 </cell>
16491 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16492 \begin_inset Text
16493
16494 \layout Standard
16495
16496 18F252
16497 \end_inset
16498 </cell>
16499 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16500 \begin_inset Text
16501
16502 \layout Standard
16503
16504 18F258
16505 \end_inset
16506 </cell>
16507 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16508 \begin_inset Text
16509
16510 \layout Standard
16511
16512 18F442
16513 \end_inset
16514 </cell>
16515 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16516 \begin_inset Text
16517
16518 \layout Standard
16519
16520 18F448
16521 \end_inset
16522 </cell>
16523 </row>
16524 <row topline="true">
16525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16526 \begin_inset Text
16527
16528 \layout Standard
16529
16530 18F452
16531 \end_inset
16532 </cell>
16533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16534 \begin_inset Text
16535
16536 \layout Standard
16537
16538 18F458
16539 \end_inset
16540 </cell>
16541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16542 \begin_inset Text
16543
16544 \layout Standard
16545
16546 18F1220
16547 \end_inset
16548 </cell>
16549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16550 \begin_inset Text
16551
16552 \layout Standard
16553
16554 18F2220
16555 \end_inset
16556 </cell>
16557 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16558 \begin_inset Text
16559
16560 \layout Standard
16561
16562 18F2550
16563 \end_inset
16564 </cell>
16565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16566 \begin_inset Text
16567
16568 \layout Standard
16569
16570 18F4331
16571 \end_inset
16572 </cell>
16573 </row>
16574 <row topline="true">
16575 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16576 \begin_inset Text
16577
16578 \layout Standard
16579
16580 18F4455
16581 \end_inset
16582 </cell>
16583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16584 \begin_inset Text
16585
16586 \layout Standard
16587
16588 18F6520
16589 \end_inset
16590 </cell>
16591 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16592 \begin_inset Text
16593
16594 \layout Standard
16595
16596 18F6620
16597 \end_inset
16598 </cell>
16599 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16600 \begin_inset Text
16601
16602 \layout Standard
16603
16604 18F6680
16605 \end_inset
16606 </cell>
16607 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16608 \begin_inset Text
16609
16610 \layout Standard
16611
16612 18F6720
16613 \end_inset
16614 </cell>
16615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16616 \begin_inset Text
16617
16618 \layout Standard
16619
16620 18F8520
16621 \end_inset
16622 </cell>
16623 </row>
16624 <row topline="true" bottomline="true">
16625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16626 \begin_inset Text
16627
16628 \layout Standard
16629
16630 18F8620
16631 \end_inset
16632 </cell>
16633 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16634 \begin_inset Text
16635
16636 \layout Standard
16637
16638 18F8680
16639 \end_inset
16640 </cell>
16641 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16642 \begin_inset Text
16643
16644 \layout Standard
16645
16646 18F8720
16647 \end_inset
16648 </cell>
16649 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16650 \begin_inset Text
16651
16652 \layout Standard
16653
16654 \end_inset
16655 </cell>
16656 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16657 \begin_inset Text
16658
16659 \layout Standard
16660
16661 \end_inset
16662 </cell>
16663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16664 \begin_inset Text
16665
16666 \layout Standard
16667
16668 \end_inset
16669 </cell>
16670 </row>
16671 </lyxtabular>
16672
16673 \end_inset
16674
16675
16676 \layout Subsection
16677
16678 Global Options
16679 \layout Standard
16680
16681 PIC16 port supports the standard command line arguments as supposed, with
16682  the exception of certain cases that will be mentioned in the following
16683  list:
16684 \layout List
16685 \labelwidthstring 00.00.0000
16686
16687 -
16688 \begin_inset ERT
16689 status Collapsed
16690
16691 \layout Standard
16692
16693 \backslash
16694 /
16695 \end_inset
16696
16697 -callee-saves See -
16698 \begin_inset ERT
16699 status Collapsed
16700
16701 \layout Standard
16702
16703 \backslash
16704 /
16705 \end_inset
16706
16707 -all-callee-saves
16708 \layout List
16709 \labelwidthstring 00.00.0000
16710
16711 -
16712 \begin_inset ERT
16713 status Collapsed
16714
16715 \layout Standard
16716
16717 \backslash
16718 /
16719 \end_inset
16720
16721 -all-callee-saves All function arguments are passed on stack by default.
16722
16723 \emph on
16724 There is no need to specify this in the command line.
16725 \layout List
16726 \labelwidthstring 00.00.0000
16727
16728 -
16729 \begin_inset ERT
16730 status Collapsed
16731
16732 \layout Standard
16733
16734 \backslash
16735 /
16736 \end_inset
16737
16738 -fommit-frame-pointer Frame pointer will be omitted when the function uses
16739  no local variables.
16740 \layout Subsection
16741
16742 Port Specific Options
16743 \begin_inset LatexCommand \index{Options PIC16}
16744
16745 \end_inset
16746
16747
16748 \layout Standard
16749
16750 The port specific options appear after the global options in the sdcc --help
16751  output.
16752 \layout Subsubsection
16753
16754 General Options
16755 \layout Standard
16756
16757 General options enable certain port features and optimizations.
16758 \layout List
16759 \labelwidthstring 00.00.0000
16760
16761 -
16762 \begin_inset ERT
16763 status Collapsed
16764
16765 \layout Standard
16766
16767 \backslash
16768 /
16769 \end_inset
16770
16771 -stack-model=[model] Used in conjuction with the command above.
16772  Defines the stack model to be used, valid stack models are :
16773 \begin_deeper
16774 \layout List
16775 \labelwidthstring 00.00.0000
16776
16777
16778 \emph on
16779 small
16780 \emph default
16781  Selects small stack model.
16782  8 bit stack and frame pointers.
16783  Supports 256 bytes stack size.
16784 \layout List
16785 \labelwidthstring 00.00.0000
16786
16787
16788 \emph on
16789 large
16790 \emph default
16791  Selects large stack model.
16792  16 bit stack and frame pointers.
16793  Supports 65536 bytes stack size.
16794 \end_deeper
16795 \layout List
16796 \labelwidthstring 00.00.0000
16797
16798 -
16799 \begin_inset ERT
16800 status Collapsed
16801
16802 \layout Standard
16803
16804 \backslash
16805 /
16806 \end_inset
16807
16808 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
16809  unitialized data variables with [kword].
16810  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
16811 \layout List
16812 \labelwidthstring 00.00.0000
16813
16814 -
16815 \begin_inset ERT
16816 status Collapsed
16817
16818 \layout Standard
16819
16820 \backslash
16821 /
16822 \end_inset
16823
16824 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
16825  Useful for bootloaders.
16826 \layout List
16827 \labelwidthstring 00.00.0000
16828
16829 -
16830 \begin_inset ERT
16831 status Collapsed
16832
16833 \layout Standard
16834
16835 \backslash
16836 /
16837 \end_inset
16838
16839 -asm= sets the full path and name of an external assembler to call.
16840 \layout List
16841 \labelwidthstring 00.00.0000
16842
16843 -
16844 \begin_inset ERT
16845 status Collapsed
16846
16847 \layout Standard
16848
16849 \backslash
16850 /
16851 \end_inset
16852
16853 -link= sets the full path and name of an external linker to call.
16854 \layout List
16855 \labelwidthstring 00.00.0000
16856
16857 -
16858 \begin_inset ERT
16859 status Collapsed
16860
16861 \layout Standard
16862
16863 \backslash
16864 /
16865 \end_inset
16866
16867 -mplab-comp MPLAB compatibility option.
16868  Currently only suppresses special gpasm directives.
16869 \layout Subsubsection
16870
16871 Optimization Options
16872 \layout List
16873 \labelwidthstring 00.00.0000
16874
16875 -
16876 \begin_inset ERT
16877 status Collapsed
16878
16879 \layout Standard
16880
16881 \backslash
16882 /
16883 \end_inset
16884
16885 -optimize-goto Try to use (conditional) BRA instead of GOTO
16886 \layout List
16887 \labelwidthstring 00.00.0000
16888
16889 -
16890 \begin_inset ERT
16891 status Collapsed
16892
16893 \layout Standard
16894
16895 \backslash
16896 /
16897 \end_inset
16898
16899 -optimize-cmp Try to optimize some compares.
16900 \layout List
16901 \labelwidthstring 00.00.0000
16902
16903 -
16904 \begin_inset ERT
16905 status Collapsed
16906
16907 \layout Standard
16908
16909 \backslash
16910 /
16911 \end_inset
16912
16913 -optimize-df Analyze the dataflow of the generated code and improve it.
16914 \layout List
16915 \labelwidthstring 00.00.0000
16916
16917 -
16918 \begin_inset ERT
16919 status Collapsed
16920
16921 \layout Standard
16922
16923 \backslash
16924 /
16925 \end_inset
16926
16927 -obanksel=nn Set optimization level for inserting BANKSELs.
16928 \newline
16929
16930 \begin_deeper
16931 \layout List
16932 \labelwidthstring 00.00.0000
16933
16934 0 no optimization
16935 \layout List
16936 \labelwidthstring 00.00.0000
16937
16938 1 checks previous used register and if it is the same then does not emit
16939  BANKSEL, accounts only for labels.
16940 \layout List
16941 \labelwidthstring 00.00.0000
16942
16943 2 tries to check the location of (even different) symbols and removes BANKSELs
16944  if they are in the same bank.
16945
16946 \newline
16947
16948 \emph on
16949 Important: There might be problems if the linker script has data sections
16950  across bank borders!
16951 \end_deeper
16952 \layout Subsubsection
16953
16954 Linking Options
16955 \layout List
16956 \labelwidthstring 00.00.0000
16957
16958 -
16959 \begin_inset ERT
16960 status Collapsed
16961
16962 \layout Standard
16963
16964 \backslash
16965 /
16966 \end_inset
16967
16968 -nodefaultlibs do not link default libraries when linking
16969 \layout List
16970 \labelwidthstring 00.00.0000
16971
16972 -
16973 \begin_inset ERT
16974 status Collapsed
16975
16976 \layout Standard
16977
16978 \backslash
16979 /
16980 \end_inset
16981
16982 -no-crt Don't link the default run-time modules
16983 \layout List
16984 \labelwidthstring 00.00.0000
16985
16986 -
16987 \begin_inset ERT
16988 status Collapsed
16989
16990 \layout Standard
16991
16992 \backslash
16993 /
16994 \end_inset
16995
16996 -use-crt= Use a custom run-time module instead of the defaults.
16997 \layout Subsubsection
16998
16999 Debugging Options
17000 \layout Standard
17001
17002 Debugging options enable extra debugging information in the output files.
17003 \layout List
17004 \labelwidthstring 00.00.0000
17005
17006 -
17007 \begin_inset ERT
17008 status Collapsed
17009
17010 \layout Standard
17011
17012 \backslash
17013 /
17014 \end_inset
17015
17016 -debug-xtra Similar to -
17017 \begin_inset ERT
17018 status Collapsed
17019
17020 \layout Standard
17021
17022 \backslash
17023 /
17024 \end_inset
17025
17026 -debug
17027 \begin_inset LatexCommand \index{-\/-debug}
17028
17029 \end_inset
17030
17031 , but dumps more information.
17032 \layout List
17033 \labelwidthstring 00.00.0000
17034
17035 -
17036 \begin_inset ERT
17037 status Collapsed
17038
17039 \layout Standard
17040
17041 \backslash
17042 /
17043 \end_inset
17044
17045 -debug-ralloc Force register allocator to dump <source>.d file with debugging
17046  information.
17047  <source> is the name of the file compiled.
17048 \layout List
17049 \labelwidthstring 00.00.0000
17050
17051 -
17052 \begin_inset ERT
17053 status Collapsed
17054
17055 \layout Standard
17056
17057 \backslash
17058 /
17059 \end_inset
17060
17061 -pcode-verbose Enable pcode debugging information in translation.
17062 \layout List
17063 \labelwidthstring 00.00.0000
17064
17065 -
17066 \begin_inset ERT
17067 status Collapsed
17068
17069 \layout Standard
17070
17071 \backslash
17072 /
17073 \end_inset
17074
17075 -denable-peeps Force the usage of peepholes.
17076  Use with care.
17077 \layout List
17078 \labelwidthstring 00.00.0000
17079
17080 -
17081 \begin_inset ERT
17082 status Collapsed
17083
17084 \layout Standard
17085
17086 \backslash
17087 /
17088 \end_inset
17089
17090 -gstack Trace push/pops for stack pointer overflow
17091 \layout List
17092 \labelwidthstring 00.00.0000
17093
17094 -
17095 \begin_inset ERT
17096 status Collapsed
17097
17098 \layout Standard
17099
17100 \backslash
17101 /
17102 \end_inset
17103
17104 -call-tree dump call tree in .calltree file
17105 \layout Subsection
17106
17107 Enviromental Variables
17108 \layout Standard
17109
17110 There is a number of enviromental variables that can be used when running
17111  SDCC to enable certain optimizations or force a specific program behaviour.
17112  these variables are primarily for debugging purposes so they can be enabled/dis
17113 abled at will.
17114 \layout Standard
17115
17116 Currently there is only two such variables available:
17117 \layout List
17118 \labelwidthstring 00.00.0000
17119
17120 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
17121  bitfields is optimized by directly loading FSR0 with the address of the
17122  bitfield structure.
17123  Normally SDCC will cast the bitfield structure to a bitfield pointer and
17124  then load FSR0.
17125  This step saves data ram and code space for functions that perform heavy
17126  use of bitfields.
17127  (ie.
17128  80 bytes of code space are saved when compiling malloc.c with this option).
17129
17130 \layout List
17131 \labelwidthstring 00.00.0000
17132
17133 NO_REG_OPT do not perform pCode registers optimization.
17134  This should be used for debugging purposes.
17135  In some where bugs in the pcode optimizer are found, users can benefit
17136  from temporarily disabling the optimizer until the bug is fixed.
17137 \layout Subsection
17138
17139 Preprocessor Macros
17140 \layout Standard
17141
17142 PIC16 port defines the following preprocessor macros while translating a
17143  source.
17144 \layout Standard
17145 \align center
17146
17147 \begin_inset  Tabular
17148 <lyxtabular version="3" rows="6" columns="2">
17149 <features>
17150 <column alignment="center" valignment="top" leftline="true" width="0">
17151 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17152 <row topline="true" bottomline="true">
17153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17154 \begin_inset Text
17155
17156 \layout Standard
17157
17158 Macro
17159 \end_inset
17160 </cell>
17161 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17162 \begin_inset Text
17163
17164 \layout Standard
17165
17166 Description
17167 \end_inset
17168 </cell>
17169 </row>
17170 <row topline="true">
17171 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17172 \begin_inset Text
17173
17174 \layout Standard
17175
17176 SDCC_pic16
17177 \end_inset
17178 </cell>
17179 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17180 \begin_inset Text
17181
17182 \layout Standard
17183
17184 Port identification
17185 \end_inset
17186 </cell>
17187 </row>
17188 <row topline="true">
17189 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17190 \begin_inset Text
17191
17192 \layout Standard
17193
17194 _
17195 \begin_inset ERT
17196 status Collapsed
17197
17198 \layout Standard
17199
17200 \backslash
17201 /
17202 \end_inset
17203
17204 _pic16
17205 \end_inset
17206 </cell>
17207 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17208 \begin_inset Text
17209
17210 \layout Standard
17211
17212 Port identification (same as above)
17213 \end_inset
17214 </cell>
17215 </row>
17216 <row topline="true">
17217 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17218 \begin_inset Text
17219
17220 \layout Standard
17221
17222 pic18fxxxx
17223 \end_inset
17224 </cell>
17225 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17226 \begin_inset Text
17227
17228 \layout Standard
17229
17230 MCU Identification.
17231
17232 \emph on
17233 xxxx
17234 \emph default
17235  is the microcontrol identification number, i.e.
17236  452, 6620, etc
17237 \end_inset
17238 </cell>
17239 </row>
17240 <row topline="true">
17241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17242 \begin_inset Text
17243
17244 \layout Standard
17245
17246 _
17247 \begin_inset ERT
17248 status Collapsed
17249
17250 \layout Standard
17251
17252 \backslash
17253 /
17254 \end_inset
17255
17256 _18Fxxxx
17257 \end_inset
17258 </cell>
17259 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17260 \begin_inset Text
17261
17262 \layout Standard
17263
17264 MCU Identification (same as above)
17265 \end_inset
17266 </cell>
17267 </row>
17268 <row topline="true" bottomline="true">
17269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17270 \begin_inset Text
17271
17272 \layout Standard
17273
17274 STACK_MODEL_nnn
17275 \end_inset
17276 </cell>
17277 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17278 \begin_inset Text
17279
17280 \layout Standard
17281
17282 nnn = SMALL or LARGE respectively according to the stack model used
17283 \end_inset
17284 </cell>
17285 </row>
17286 </lyxtabular>
17287
17288 \end_inset
17289
17290
17291 \layout Standard
17292
17293 In addition the following macros are defined when calling assembler:
17294 \layout Standard
17295 \align center
17296
17297 \begin_inset  Tabular
17298 <lyxtabular version="3" rows="4" columns="2">
17299 <features>
17300 <column alignment="center" valignment="top" leftline="true" width="0">
17301 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17302 <row topline="true" bottomline="true">
17303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17304 \begin_inset Text
17305
17306 \layout Standard
17307
17308 Macro
17309 \end_inset
17310 </cell>
17311 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17312 \begin_inset Text
17313
17314 \layout Standard
17315
17316 Description
17317 \end_inset
17318 </cell>
17319 </row>
17320 <row topline="true">
17321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17322 \begin_inset Text
17323
17324 \layout Standard
17325
17326 __18Fxxxx
17327 \end_inset
17328 </cell>
17329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17330 \begin_inset Text
17331
17332 \layout Standard
17333
17334 MCU Identification.
17335
17336 \emph on
17337 xxxx
17338 \emph default
17339  is the microcontrol identification number, i.e.
17340  452, 6620, etc
17341 \end_inset
17342 </cell>
17343 </row>
17344 <row topline="true">
17345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17346 \begin_inset Text
17347
17348 \layout Standard
17349
17350 SDCC_MODEL_nnn
17351 \end_inset
17352 </cell>
17353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17354 \begin_inset Text
17355
17356 \layout Standard
17357
17358 nnn = SMALL or LARGE respectively according to the memory model used for
17359  SDCC
17360 \end_inset
17361 </cell>
17362 </row>
17363 <row topline="true" bottomline="true">
17364 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17365 \begin_inset Text
17366
17367 \layout Standard
17368
17369 STACK_MODEL_nnn
17370 \end_inset
17371 </cell>
17372 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17373 \begin_inset Text
17374
17375 \layout Standard
17376
17377 nnn = SMALL or LARGE respectively according to the stack model used
17378 \end_inset
17379 </cell>
17380 </row>
17381 </lyxtabular>
17382
17383 \end_inset
17384
17385
17386 \layout Subsection
17387
17388 Directories
17389 \layout Standard
17390
17391 PIC16
17392 \begin_inset LatexCommand \index{PIC16}
17393
17394 \end_inset
17395
17396  port uses the following directories for searching header files and libraries.
17397 \layout Standard
17398 \align center
17399
17400 \begin_inset  Tabular
17401 <lyxtabular version="3" rows="3" columns="4">
17402 <features>
17403 <column alignment="center" valignment="top" leftline="true" width="0">
17404 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17405 <column alignment="center" valignment="top" width="0">
17406 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17407 <row topline="true" bottomline="true">
17408 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17409 \begin_inset Text
17410
17411 \layout Standard
17412
17413 Directory
17414 \end_inset
17415 </cell>
17416 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17417 \begin_inset Text
17418
17419 \layout Standard
17420
17421 Description
17422 \end_inset
17423 </cell>
17424 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17425 \begin_inset Text
17426
17427 \layout Standard
17428
17429 Target
17430 \end_inset
17431 </cell>
17432 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17433 \begin_inset Text
17434
17435 \layout Standard
17436
17437 Command prefix
17438 \end_inset
17439 </cell>
17440 </row>
17441 <row topline="true">
17442 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17443 \begin_inset Text
17444
17445 \layout Standard
17446
17447 PREFIX/sdcc/include/pic16
17448 \end_inset
17449 </cell>
17450 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17451 \begin_inset Text
17452
17453 \layout Standard
17454
17455 PIC16 specific headers
17456 \end_inset
17457 </cell>
17458 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17459 \begin_inset Text
17460
17461 \layout Standard
17462
17463 Compiler
17464 \end_inset
17465 </cell>
17466 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17467 \begin_inset Text
17468
17469 \layout Standard
17470
17471 -I
17472 \end_inset
17473 </cell>
17474 </row>
17475 <row topline="true" bottomline="true">
17476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17477 \begin_inset Text
17478
17479 \layout Standard
17480
17481 PREFIX/sdcc/lib/pic16
17482 \end_inset
17483 </cell>
17484 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17485 \begin_inset Text
17486
17487 \layout Standard
17488
17489 PIC16 specific libraries
17490 \end_inset
17491 </cell>
17492 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17493 \begin_inset Text
17494
17495 \layout Standard
17496
17497 Linker
17498 \end_inset
17499 </cell>
17500 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17501 \begin_inset Text
17502
17503 \layout Standard
17504
17505 -L
17506 \end_inset
17507 </cell>
17508 </row>
17509 </lyxtabular>
17510
17511 \end_inset
17512
17513
17514 \layout Subsection
17515
17516 Pragmas
17517 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
17518
17519 \end_inset
17520
17521
17522 \layout Standard
17523
17524 PIC16 port currently supports the following pragmas:
17525 \layout List
17526 \labelwidthstring 00.00.0000
17527
17528 stack pragma stack forces the code generator to initialize the stack & frame
17529  pointers at a specific address.
17530  This is an adhoc solution for cases where no STACK directive is available
17531  in the linker script or gplink is not instructed to create a stack section.
17532 \newline
17533 The stack pragma should be used only once in a project.
17534  Multiple pragmas may result in indeterminate behaviour of the program.
17535 \begin_inset Foot
17536 collapsed false
17537
17538 \layout Standard
17539
17540 The old format (ie.
17541  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
17542  cross page boundaries (or even exceed the available data RAM) and crash
17543  the program.
17544  Make sure that stack does not cross page boundaries when using the SMALL
17545  stack model.
17546 \end_inset
17547
17548
17549 \newline
17550 The format is as follows:
17551 \layout LyX-Code
17552
17553 #pragma stack bottom_address [stack_size]
17554 \layout Standard
17555
17556
17557 \emph on
17558 bottom_address
17559 \emph default
17560  is the lower bound of the stack section.
17561  The stack pointer initially will point at address (bottom_address+stack_size-1).
17562 \layout LyX-Code
17563
17564 Example:
17565 \layout LyX-Code
17566
17567 \layout LyX-Code
17568
17569 /* initializes stack of 100 bytes at RAM address 0x200 */
17570 \layout LyX-Code
17571
17572 #pragma stack 0x200 100
17573 \layout Standard
17574
17575 If the stack_size field is omitted then a stack is created with the default
17576  size of 64.
17577  This size might be enough for most programs, but its not enough for operations
17578  with deep function nesting or excessive stack usage.
17579 \layout List
17580 \labelwidthstring 00.00.0000
17581
17582 wparam
17583 \emph on
17584 This pragma is deprecated.
17585  Its use will cause a warning message to be issued.
17586 \emph default
17587
17588 \newline
17589
17590 \layout List
17591 \labelwidthstring 00.00.0000
17592
17593 code place a function symbol at static FLASH address
17594 \layout LyX-Code
17595
17596 Example:
17597 \layout LyX-Code
17598
17599 \layout LyX-Code
17600
17601 /* place function test_func at 0x4000 */
17602 \layout LyX-Code
17603
17604 #pragma code test_func 0x4000
17605 \layout LyX-Code
17606
17607 \layout List
17608 \labelwidthstring 00.00.0000
17609
17610 library instructs the linker to use a library module.
17611 \newline
17612 Usage:
17613 \layout LyX-Code
17614
17615 #pragma library module_name
17616 \layout Standard
17617
17618
17619 \emph on
17620 module_name
17621 \emph default
17622  can be any library or object file (including its path).
17623  Note that there are four reserved keywords which have special meaning.
17624  These are:
17625 \layout Standard
17626 \align center
17627
17628 \begin_inset  Tabular
17629 <lyxtabular version="3" rows="6" columns="3">
17630 <features>
17631 <column alignment="center" valignment="top" leftline="true" width="0">
17632 <column alignment="block" valignment="top" leftline="true" width="20page%">
17633 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
17634 <row topline="true" bottomline="true">
17635 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17636 \begin_inset Text
17637
17638 \layout Standard
17639
17640 Keyword
17641 \end_inset
17642 </cell>
17643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17644 \begin_inset Text
17645
17646 \layout Standard
17647
17648 Description
17649 \end_inset
17650 </cell>
17651 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17652 \begin_inset Text
17653
17654 \layout Standard
17655
17656 Module to link
17657 \end_inset
17658 </cell>
17659 </row>
17660 <row topline="true">
17661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17662 \begin_inset Text
17663
17664 \layout Standard
17665
17666
17667 \series bold
17668 ignore
17669 \end_inset
17670 </cell>
17671 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17672 \begin_inset Text
17673
17674 \layout Standard
17675
17676 ignore all library pragmas
17677 \end_inset
17678 </cell>
17679 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17680 \begin_inset Text
17681
17682 \layout Standard
17683
17684
17685 \emph on
17686 (none)
17687 \end_inset
17688 </cell>
17689 </row>
17690 <row topline="true">
17691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17692 \begin_inset Text
17693
17694 \layout Standard
17695
17696
17697 \series bold
17698 c
17699 \end_inset
17700 </cell>
17701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17702 \begin_inset Text
17703
17704 \layout Standard
17705
17706 link the C library
17707 \end_inset
17708 </cell>
17709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17710 \begin_inset Text
17711
17712 \layout Standard
17713
17714
17715 \emph on
17716 libc18f
17717 \emph default
17718 .lib
17719 \end_inset
17720 </cell>
17721 </row>
17722 <row topline="true">
17723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17724 \begin_inset Text
17725
17726 \layout Standard
17727
17728
17729 \series bold
17730 math
17731 \end_inset
17732 </cell>
17733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17734 \begin_inset Text
17735
17736 \layout Standard
17737
17738 link the Math libarary
17739 \end_inset
17740 </cell>
17741 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17742 \begin_inset Text
17743
17744 \layout Standard
17745
17746
17747 \emph on
17748 libm18f
17749 \emph default
17750 .lib
17751 \end_inset
17752 </cell>
17753 </row>
17754 <row topline="true">
17755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17756 \begin_inset Text
17757
17758 \layout Standard
17759
17760
17761 \series bold
17762 io
17763 \end_inset
17764 </cell>
17765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17766 \begin_inset Text
17767
17768 \layout Standard
17769
17770 link the I/O library
17771 \end_inset
17772 </cell>
17773 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17774 \begin_inset Text
17775
17776 \layout Standard
17777
17778
17779 \emph on
17780 libio18f*
17781 \emph default
17782 .lib
17783 \end_inset
17784 </cell>
17785 </row>
17786 <row topline="true" bottomline="true">
17787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17788 \begin_inset Text
17789
17790 \layout Standard
17791
17792
17793 \series bold
17794 debug
17795 \end_inset
17796 </cell>
17797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17798 \begin_inset Text
17799
17800 \layout Standard
17801
17802 link the debug library
17803 \end_inset
17804 </cell>
17805 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17806 \begin_inset Text
17807
17808 \layout Standard
17809
17810
17811 \emph on
17812 libdebug
17813 \emph default
17814 .lib
17815 \end_inset
17816 </cell>
17817 </row>
17818 </lyxtabular>
17819
17820 \end_inset
17821
17822
17823 \newline
17824 * is the device number, i.e.
17825  452 for PIC18F452 MCU.
17826 \layout Standard
17827
17828 This feature allows for linking with specific libraries withoug having to
17829  explicit name them in the command line.
17830  Note that the
17831 \noun on
17832 ignore
17833 \noun default
17834  keyword will reject all modules specified by the library pragma.
17835 \layout List
17836 \labelwidthstring 00.00.0000
17837
17838 udata pragma udata instructs the compiler to emit code so that linker will
17839  place a variable at a specific memory bank
17840 \layout LyX-Code
17841
17842 Example:
17843 \layout LyX-Code
17844
17845 \layout LyX-Code
17846
17847 /* places variable foo at bank2 */
17848 \layout LyX-Code
17849
17850 #pragma udata bank2 foo
17851 \layout LyX-Code
17852
17853 char foo;
17854 \layout Standard
17855
17856 In order for this pragma to work extra SECTION directives should be added
17857  in the .lkr script.
17858  In the following example a sample .lkr file is shown:
17859 \layout LyX-Code
17860
17861 \layout LyX-Code
17862
17863 // Sample linker script for the PIC18F452 processor
17864 \layout LyX-Code
17865
17866 LIBPATH .
17867 \layout LyX-Code
17868
17869 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
17870 \layout LyX-Code
17871
17872 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
17873 \layout LyX-Code
17874
17875 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
17876 \layout LyX-Code
17877
17878 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
17879 \layout LyX-Code
17880
17881 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
17882 \layout LyX-Code
17883
17884 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
17885 \layout LyX-Code
17886
17887 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
17888 \layout LyX-Code
17889
17890 \layout LyX-Code
17891
17892 DATABANK   NAME=gpr0       START=0x80           END=0xFF
17893 \layout LyX-Code
17894
17895 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
17896 \layout LyX-Code
17897
17898 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
17899 \layout LyX-Code
17900
17901 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
17902 \layout LyX-Code
17903
17904 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
17905 \layout LyX-Code
17906
17907 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
17908 \layout LyX-Code
17909
17910 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
17911 \layout LyX-Code
17912
17913 \layout LyX-Code
17914
17915 SECTION    NAME=CONFIG     ROM=config
17916 \layout LyX-Code
17917
17918 \layout LyX-Code
17919
17920 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
17921 \layout LyX-Code
17922
17923 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
17924 \layout LyX-Code
17925
17926 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
17927 \layout LyX-Code
17928
17929 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
17930 \layout LyX-Code
17931
17932 SECTION    NAME=bank4      RAM=gpr4
17933 \layout LyX-Code
17934
17935 SECTION    NAME=bank5      RAM=gpr5
17936 \layout Standard
17937
17938 The linker will recognise the section name set in the pragma statement and
17939  will position the variable at the memory bank set with the RAM field at
17940  the SECTION line in the linker script file.
17941 \layout Subsection
17942
17943 Header Files
17944 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
17945
17946 \end_inset
17947
17948
17949 \layout Standard
17950
17951 There is one main header file that can be included to the source files using
17952  the pic16 port.
17953  That file is the
17954 \series bold
17955 pic18fregs.h
17956 \series default
17957 .
17958  This header file contains the definitions for the processor special registers,
17959  so it is necessary if the source accesses them.
17960  It can be included by adding the following line in the beginning of the
17961  file:
17962 \layout LyX-Code
17963
17964 #include <pic18fregs.h>
17965 \layout Standard
17966
17967 The specific microcontroller is selected within the pic18fregs.h automatically,
17968  so the same source can be used with a variety of devices.
17969 \layout Subsection
17970
17971 Libraries
17972 \layout Standard
17973
17974 The libraries that PIC16
17975 \begin_inset LatexCommand \index{PIC16}
17976
17977 \end_inset
17978
17979  port depends on are the microcontroller device libraries which contain
17980  the symbol definitions for the microcontroller special function registers.
17981  These libraries have the format pic18fxxxx.lib, where
17982 \emph on
17983 xxxx
17984 \emph default
17985  is the microcontroller identification number.
17986  The specific library is selected automatically by the compiler at link
17987  stage according to the selected device.
17988 \layout Standard
17989
17990 Libraries are created with gplib which is part of the gputils package
17991 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17992
17993 \end_inset
17994
17995 .
17996 \layout Subsubsection*
17997
17998 Building the libraries
17999 \layout Standard
18000
18001 Before using SDCC/pic16 there are some libraries that need to be compiled.
18002  This process is not done automatically by SDCC since not all users use
18003  SDCC for pic16 projects.
18004  So each user should compile the libraries separately.
18005 \layout Standard
18006
18007 The steps to compile the pic16 libraries under Linux are:
18008 \layout LyX-Code
18009
18010 cd device/lib/pic16
18011 \layout LyX-Code
18012
18013 ./configure
18014 \layout LyX-Code
18015
18016 make
18017 \layout LyX-Code
18018
18019 cd ..
18020 \layout LyX-Code
18021
18022 make model-pic16
18023 \layout LyX-Code
18024
18025 su -c 'make install'     # install the libraries, you need the root password
18026 \layout Standard
18027
18028 If you need to install the headers too, do:
18029 \layout LyX-Code
18030
18031 cd device/include
18032 \layout LyX-Code
18033
18034 su -c 'make install'     # install the headers, you need the root password
18035 \layout Standard
18036
18037 There exist a special target to build the I/O libraries.
18038  This target is not automatically build because it will build the I/O library
18039  for
18040 \emph on
18041 every
18042 \emph default
18043  supported device.
18044  This way building will take quite a lot of time.
18045  Users are advised to edit the
18046 \series bold
18047 device/lib/pic16/pics.build
18048 \series default
18049  file and then execute:
18050 \layout LyX-Code
18051
18052 make lib-io
18053 \layout Subsection
18054
18055 Memory Models
18056 \layout Standard
18057
18058 The following memory models are supported by the PIC16 port:
18059 \layout Itemize
18060
18061 small model
18062 \layout Itemize
18063
18064 large model
18065 \layout Standard
18066
18067 Memory model affects the default size of pointers within the source.
18068  The sizes are shown in the next table:
18069 \layout Standard
18070 \align center
18071
18072 \begin_inset  Tabular
18073 <lyxtabular version="3" rows="3" columns="3">
18074 <features>
18075 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18076 <column alignment="center" valignment="top" leftline="true" width="0">
18077 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18078 <row topline="true" bottomline="true">
18079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18080 \begin_inset Text
18081
18082 \layout Standard
18083
18084 Pointer sizes according to memory model
18085 \end_inset
18086 </cell>
18087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18088 \begin_inset Text
18089
18090 \layout Standard
18091
18092 small model
18093 \end_inset
18094 </cell>
18095 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18096 \begin_inset Text
18097
18098 \layout Standard
18099
18100 large model
18101 \end_inset
18102 </cell>
18103 </row>
18104 <row topline="true" bottomline="true">
18105 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18106 \begin_inset Text
18107
18108 \layout Standard
18109
18110 code pointers
18111 \end_inset
18112 </cell>
18113 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18114 \begin_inset Text
18115
18116 \layout Standard
18117
18118 16-bits
18119 \end_inset
18120 </cell>
18121 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18122 \begin_inset Text
18123
18124 \layout Standard
18125
18126 24-bits
18127 \end_inset
18128 </cell>
18129 </row>
18130 <row topline="true" bottomline="true">
18131 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18132 \begin_inset Text
18133
18134 \layout Standard
18135
18136 data pointers
18137 \end_inset
18138 </cell>
18139 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
18140 \begin_inset Text
18141
18142 \layout Standard
18143
18144 16-bits
18145 \end_inset
18146 </cell>
18147 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18148 \begin_inset Text
18149
18150 \layout Standard
18151
18152 16-bits
18153 \end_inset
18154 </cell>
18155 </row>
18156 </lyxtabular>
18157
18158 \end_inset
18159
18160
18161 \layout Standard
18162
18163 It is advisable that all sources within a project are compiled with the
18164  same memory model.
18165  If one wants to override the default memory model, this can be done by
18166  declaring a pointer as
18167 \series bold
18168 far
18169 \series default
18170  or
18171 \series bold
18172 near
18173 \series default
18174 .
18175  Far selects large memory model's pointers, while near selects small memory
18176  model's pointers.
18177 \layout Standard
18178
18179 The standard device libraries (see
18180 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
18181
18182 \end_inset
18183
18184 ) contain no reference to pointers, so they can be used with both memory
18185  models.
18186 \layout Subsection
18187
18188 Stack
18189 \layout Standard
18190
18191 The stack implementation for the PIC16 port uses two indirect registers,
18192  FSR1 and FSR2.
18193 \layout List
18194 \labelwidthstring 00.00.0000
18195
18196 FSR1 is assigned as stack pointer
18197 \layout List
18198 \labelwidthstring 00.00.0000
18199
18200 FSR2 is assigned as frame pointer
18201 \layout Standard
18202
18203 The following stack models are supported by the PIC16 port
18204 \layout Itemize
18205
18206
18207 \noun on
18208 small
18209 \noun default
18210  model
18211 \layout Itemize
18212
18213
18214 \noun on
18215 large
18216 \noun default
18217  model
18218 \layout Standard
18219
18220
18221 \noun on
18222 Small
18223 \noun default
18224  model means that only the FSRxL byte is used to access stack and frame,
18225  while
18226 \emph on
18227 \noun on
18228 large
18229 \emph default
18230 \noun default
18231  uses both FSRxL and FSRxH registers.
18232  The following table shows the stack/frame pointers sizes according to stack
18233  model and the maximum space they can address:
18234 \layout Standard
18235 \align center
18236
18237 \begin_inset  Tabular
18238 <lyxtabular version="3" rows="3" columns="3">
18239 <features>
18240 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18241 <column alignment="center" valignment="top" leftline="true" width="0">
18242 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18243 <row topline="true" bottomline="true">
18244 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18245 \begin_inset Text
18246
18247 \layout Standard
18248
18249 Stack & Frame pointer sizes according to stack model
18250 \end_inset
18251 </cell>
18252 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18253 \begin_inset Text
18254
18255 \layout Standard
18256
18257 small
18258 \end_inset
18259 </cell>
18260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18261 \begin_inset Text
18262
18263 \layout Standard
18264
18265 large
18266 \end_inset
18267 </cell>
18268 </row>
18269 <row topline="true">
18270 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18271 \begin_inset Text
18272
18273 \layout Standard
18274
18275 Stack pointer FSR1
18276 \end_inset
18277 </cell>
18278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18279 \begin_inset Text
18280
18281 \layout Standard
18282
18283 8-bits
18284 \end_inset
18285 </cell>
18286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18287 \begin_inset Text
18288
18289 \layout Standard
18290
18291 16-bits
18292 \end_inset
18293 </cell>
18294 </row>
18295 <row topline="true" bottomline="true">
18296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18297 \begin_inset Text
18298
18299 \layout Standard
18300
18301 Frame pointer FSR2
18302 \end_inset
18303 </cell>
18304 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18305 \begin_inset Text
18306
18307 \layout Standard
18308
18309 8-bits
18310 \end_inset
18311 </cell>
18312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18313 \begin_inset Text
18314
18315 \layout Standard
18316
18317 16-bits
18318 \end_inset
18319 </cell>
18320 </row>
18321 </lyxtabular>
18322
18323 \end_inset
18324
18325
18326 \layout Standard
18327
18328
18329 \noun on
18330 Large
18331 \noun default
18332 stack model is currently not working properly throughout the code generator.
18333  So its use is not advised.
18334  Also there are some other points that need special care:
18335 \newline
18336
18337 \layout Enumerate
18338
18339 Do not create stack sections with size more than one physical bank (that
18340  is 256 bytes)
18341 \layout Enumerate
18342
18343 Stack sections should no cross physical bank limits (i.e.
18344  #pragma stack 0x50 0x100)
18345 \layout Standard
18346
18347 These limitations are caused by the fact that only FSRxL is modified when
18348  using SMALL stack model, so no more than 256 bytes of stack can be used.
18349  This problem will disappear after LARGE model is fully implemented.
18350 \layout Subsection
18351
18352 Functions
18353 \layout Standard
18354
18355 In addition to the standard SDCC function keywords, PIC16 port makes available
18356  two more:
18357 \layout List
18358 \labelwidthstring 00.00.0000
18359
18360 wparam Use the WREG to pass one byte of the first function argument.
18361  This improves speed but you may not use this for functions with arguments
18362  that are called via function pointers, otherwise the first byte of the
18363  first parameter will get lost.
18364  Usage:
18365 \layout LyX-Code
18366
18367 void func_wparam(int a) wparam
18368 \layout LyX-Code
18369
18370 {
18371 \layout LyX-Code
18372
18373     /* WREG hold the lower part of a */
18374 \layout LyX-Code
18375
18376     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
18377  */
18378 \layout LyX-Code
18379
18380 ...
18381 \layout LyX-Code
18382
18383 }
18384 \layout Standard
18385
18386 This keyword replaces the deprecated wparam pragma.
18387 \layout List
18388 \labelwidthstring 00.00.0000
18389
18390 shadowregs When entering/exiting an ISR, it is possible to take advantage
18391  of the PIC18F hardware shadow registers which hold the values of WREG,
18392  STATUS and BSR registers.
18393  This can be done by adding the keyword
18394 \emph on
18395 shadowregs
18396 \emph default
18397  before the
18398 \emph on
18399 interrupt
18400 \emph default
18401  keyword in the function's header.
18402 \layout LyX-Code
18403
18404 void isr_shadow(void) shadowregs interrupt 1
18405 \layout LyX-Code
18406
18407 {
18408 \layout LyX-Code
18409
18410 ...
18411 \layout LyX-Code
18412
18413 }
18414 \layout Standard
18415
18416
18417 \emph on
18418 shadowregs
18419 \emph default
18420  instructs the code generator not to store/restore WREG, STATUS, BSR when
18421  entering/exiting the ISR.
18422 \layout Subsection
18423
18424 Function return values
18425 \layout Standard
18426
18427 Return values from functions are placed to the appropriate registers following
18428  a modified Microchip policy optimized for SDCC.
18429  The following table shows these registers:
18430 \layout Standard
18431 \align center
18432
18433 \begin_inset  Tabular
18434 <lyxtabular version="3" rows="6" columns="2">
18435 <features>
18436 <column alignment="center" valignment="top" leftline="true" width="0">
18437 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18438 <row topline="true" bottomline="true">
18439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18440 \begin_inset Text
18441
18442 \layout Standard
18443
18444 size
18445 \end_inset
18446 </cell>
18447 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18448 \begin_inset Text
18449
18450 \layout Standard
18451
18452 destination register
18453 \end_inset
18454 </cell>
18455 </row>
18456 <row topline="true">
18457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18458 \begin_inset Text
18459
18460 \layout Standard
18461
18462 8 bits
18463 \end_inset
18464 </cell>
18465 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18466 \begin_inset Text
18467
18468 \layout Standard
18469
18470 WREG
18471 \end_inset
18472 </cell>
18473 </row>
18474 <row topline="true">
18475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18476 \begin_inset Text
18477
18478 \layout Standard
18479
18480 16 bits
18481 \end_inset
18482 </cell>
18483 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18484 \begin_inset Text
18485
18486 \layout Standard
18487
18488 PRODL:WREG
18489 \end_inset
18490 </cell>
18491 </row>
18492 <row topline="true">
18493 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18494 \begin_inset Text
18495
18496 \layout Standard
18497
18498 24 bits
18499 \end_inset
18500 </cell>
18501 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18502 \begin_inset Text
18503
18504 \layout Standard
18505
18506 PRODH:PRODL:WREG
18507 \end_inset
18508 </cell>
18509 </row>
18510 <row topline="true">
18511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18512 \begin_inset Text
18513
18514 \layout Standard
18515
18516 32 bits
18517 \end_inset
18518 </cell>
18519 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18520 \begin_inset Text
18521
18522 \layout Standard
18523
18524 FSR0L:PRODH:PRODL:WREG
18525 \end_inset
18526 </cell>
18527 </row>
18528 <row topline="true" bottomline="true">
18529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18530 \begin_inset Text
18531
18532 \layout Standard
18533
18534 >32 bits
18535 \end_inset
18536 </cell>
18537 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18538 \begin_inset Text
18539
18540 \layout Standard
18541
18542 on stack, FSR0 points to the beginning
18543 \end_inset
18544 </cell>
18545 </row>
18546 </lyxtabular>
18547
18548 \end_inset
18549
18550
18551 \layout Subsection
18552
18553 Interrupts
18554 \layout Standard
18555
18556 An interrupt servive routine (ISR) is declared using the
18557 \emph on
18558 interrupt
18559 \emph default
18560  keyword.
18561 \layout LyX-Code
18562
18563 void isr(void) interrupt
18564 \emph on
18565 n
18566 \layout LyX-Code
18567
18568 {
18569 \layout LyX-Code
18570
18571 ...
18572 \layout LyX-Code
18573
18574 }
18575 \layout Standard
18576
18577
18578 \emph on
18579 n
18580 \emph default
18581  is the interrupt number, which for PIC18F devices can be:
18582 \layout Standard
18583 \align center
18584
18585 \begin_inset  Tabular
18586 <lyxtabular version="3" rows="4" columns="3">
18587 <features>
18588 <column alignment="center" valignment="top" leftline="true" width="0">
18589 <column alignment="center" valignment="top" leftline="true" width="0">
18590 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18591 <row topline="true" bottomline="true">
18592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18593 \begin_inset Text
18594
18595 \layout Standard
18596
18597
18598 \emph on
18599 n
18600 \end_inset
18601 </cell>
18602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18603 \begin_inset Text
18604
18605 \layout Standard
18606
18607 Interrupt Vector
18608 \end_inset
18609 </cell>
18610 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18611 \begin_inset Text
18612
18613 \layout Standard
18614
18615 Interrupt Vector Address
18616 \end_inset
18617 </cell>
18618 </row>
18619 <row topline="true">
18620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18621 \begin_inset Text
18622
18623 \layout Standard
18624
18625 0
18626 \end_inset
18627 </cell>
18628 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18629 \begin_inset Text
18630
18631 \layout Standard
18632
18633 RESET vector
18634 \end_inset
18635 </cell>
18636 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18637 \begin_inset Text
18638
18639 \layout Standard
18640
18641 0x000000
18642 \end_inset
18643 </cell>
18644 </row>
18645 <row topline="true">
18646 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18647 \begin_inset Text
18648
18649 \layout Standard
18650
18651
18652 \family roman
18653 \series medium
18654 \shape up
18655 \size normal
18656 \emph off
18657 \bar no
18658 \noun off
18659 \color none
18660 1
18661 \end_inset
18662 </cell>
18663 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18664 \begin_inset Text
18665
18666 \layout Standard
18667
18668
18669 \family roman
18670 \series medium
18671 \shape up
18672 \size normal
18673 \emph off
18674 \bar no
18675 \noun off
18676 \color none
18677 HIGH priority interrupts
18678 \end_inset
18679 </cell>
18680 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18681 \begin_inset Text
18682
18683 \layout Standard
18684
18685 0x000008
18686 \end_inset
18687 </cell>
18688 </row>
18689 <row topline="true" bottomline="true">
18690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18691 \begin_inset Text
18692
18693 \layout Standard
18694
18695 2
18696 \end_inset
18697 </cell>
18698 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18699 \begin_inset Text
18700
18701 \layout Standard
18702
18703 LOW priority interrupts
18704 \end_inset
18705 </cell>
18706 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18707 \begin_inset Text
18708
18709 \layout Standard
18710
18711 0x000018
18712 \end_inset
18713 </cell>
18714 </row>
18715 </lyxtabular>
18716
18717 \end_inset
18718
18719
18720 \layout Standard
18721
18722 When generating assembly code for ISR the code generator places a
18723 \noun on
18724 goto
18725 \noun default
18726 instruction at the
18727 \emph on
18728 Interrupt Vector Address
18729 \emph default
18730  which points at the genetated ISR.
18731  This single GOTO instruction is part of an automatically generated
18732 \emph on
18733 interrupt entry point
18734 \emph default
18735  function.
18736  The actuall ISR code is placed as normally would in the code space.
18737  Upon interrupt request, the GOTO instruction is executed which jumps to
18738  the ISR code.
18739  When declaring interrupt functions as _naked this GOTO instruction is
18740 \series bold
18741 not
18742 \series default
18743  generated.
18744  The whole interrupt functions is therefore placed at the Interrupt Vector
18745  Address of the specific interrupt.
18746  This is not a problem for the LOW priority interrupts, but it is a problem
18747  for the RESET and the HIGH priority interrupts because code may be written
18748  at the next interrupt´s vector address and cause undeterminate program
18749  behaviour if that interrupt is raised.
18750 \begin_inset Foot
18751 collapsed false
18752
18753 \layout Standard
18754
18755 This is not a problem when
18756 \layout Enumerate
18757
18758 this is a HIGH interrupt ISR and LOW interrupts are
18759 \emph on
18760 disabled
18761 \emph default
18762  or not used.
18763 \layout Enumerate
18764
18765 when the ISR is small enough not to reach the next interrupt´s vector address.
18766 \end_inset
18767
18768
18769 \layout Standard
18770
18771
18772 \emph on
18773 n
18774 \emph default
18775  is possible to be omitted.
18776  This way a function is generated similar to an ISR, but it is not assigned
18777  to any interrupt.
18778 \layout Standard
18779
18780 When entering an interrupt, currently the PIC16
18781 \begin_inset LatexCommand \index{PIC16}
18782
18783 \end_inset
18784
18785  port automatically saves the following registers:
18786 \layout Itemize
18787
18788 WREG
18789 \layout Itemize
18790
18791 STATUS
18792 \layout Itemize
18793
18794 BSR
18795 \layout Itemize
18796
18797 PROD (PRODL and PRODH)
18798 \layout Itemize
18799
18800 FSR0 (FSR0L and FSR0H)
18801 \layout Standard
18802
18803 These registers are restored upon return from the interrupt routine.
18804 \begin_inset Foot
18805 collapsed false
18806
18807 \layout Standard
18808
18809 NOTE that when the _naked attribute is specified for an interrupt routine,
18810  then NO registers are stored or restored.
18811 \end_inset
18812
18813
18814 \layout Subsection
18815
18816 Generic Pointers
18817 \layout Standard
18818
18819 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
18820  There are 3 types of generic pointers currently implemented data, code
18821  and eeprom pointers.
18822  They are differentiated by the value of the 7th and 6th bits of the upper
18823  byte:
18824 \layout Standard
18825 \align center
18826
18827 \begin_inset  Tabular
18828 <lyxtabular version="3" rows="5" columns="5">
18829 <features>
18830 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18831 <column alignment="center" valignment="top" width="0">
18832 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18833 <column alignment="center" valignment="top" width="0">
18834 <column alignment="left" valignment="top" rightline="true" width="0">
18835 <row topline="true" bottomline="true">
18836 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18837 \begin_inset Text
18838
18839 \layout Standard
18840
18841 pointer type
18842 \end_inset
18843 </cell>
18844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18845 \begin_inset Text
18846
18847 \layout Standard
18848
18849 7th bit
18850 \end_inset
18851 </cell>
18852 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18853 \begin_inset Text
18854
18855 \layout Standard
18856
18857 6th bit
18858 \end_inset
18859 </cell>
18860 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18861 \begin_inset Text
18862
18863 \layout Standard
18864
18865 rest of the pointer
18866 \end_inset
18867 </cell>
18868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18869 \begin_inset Text
18870
18871 \layout Standard
18872
18873 descrption
18874 \end_inset
18875 </cell>
18876 </row>
18877 <row topline="true" bottomline="true">
18878 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18879 \begin_inset Text
18880
18881 \layout Standard
18882
18883 data
18884 \end_inset
18885 </cell>
18886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18887 \begin_inset Text
18888
18889 \layout Standard
18890
18891 1
18892 \end_inset
18893 </cell>
18894 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18895 \begin_inset Text
18896
18897 \layout Standard
18898
18899 0
18900 \end_inset
18901 </cell>
18902 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18903 \begin_inset Text
18904
18905 \layout Standard
18906
18907
18908 \family typewriter
18909 \shape slanted
18910 \emph on
18911 uuuuuu uuuuxxxx xxxxxxxx
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 a 12-bit data pointer in data RAM memory
18920 \end_inset
18921 </cell>
18922 </row>
18923 <row bottomline="true">
18924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18925 \begin_inset Text
18926
18927 \layout Standard
18928
18929 code
18930 \end_inset
18931 </cell>
18932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18933 \begin_inset Text
18934
18935 \layout Standard
18936
18937 0
18938 \end_inset
18939 </cell>
18940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18941 \begin_inset Text
18942
18943 \layout Standard
18944
18945 0
18946 \end_inset
18947 </cell>
18948 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18949 \begin_inset Text
18950
18951 \layout Standard
18952
18953
18954 \family typewriter
18955 \shape slanted
18956 \emph on
18957 uxxxxx xxxxxxxx xxxxxxxx
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 a 21-bit code pointer in FLASH memory
18966 \end_inset
18967 </cell>
18968 </row>
18969 <row bottomline="true">
18970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18971 \begin_inset Text
18972
18973 \layout Standard
18974
18975 eeprom
18976 \end_inset
18977 </cell>
18978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18979 \begin_inset Text
18980
18981 \layout Standard
18982
18983 0
18984 \end_inset
18985 </cell>
18986 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18987 \begin_inset Text
18988
18989 \layout Standard
18990
18991 1
18992 \end_inset
18993 </cell>
18994 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18995 \begin_inset Text
18996
18997 \layout Standard
18998
18999
19000 \family typewriter
19001 \shape slanted
19002 \emph on
19003 uuuuuu uuuuuuxx xxxxxxxx
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 a 10-bit eeprom pointer in EEPROM memory
19012 \end_inset
19013 </cell>
19014 </row>
19015 <row bottomline="true">
19016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19017 \begin_inset Text
19018
19019 \layout Standard
19020
19021 (unimplemented)
19022 \end_inset
19023 </cell>
19024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19025 \begin_inset Text
19026
19027 \layout Standard
19028
19029 1
19030 \end_inset
19031 </cell>
19032 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19033 \begin_inset Text
19034
19035 \layout Standard
19036
19037 1
19038 \end_inset
19039 </cell>
19040 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19041 \begin_inset Text
19042
19043 \layout Standard
19044
19045
19046 \family typewriter
19047 \shape slanted
19048 \emph on
19049 xxxxxx xxxxxxxx xxxxxxxx
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 unimplemented pointer type
19058 \end_inset
19059 </cell>
19060 </row>
19061 </lyxtabular>
19062
19063 \end_inset
19064
19065
19066 \layout Standard
19067
19068 Generic pointer are read and written with a set of library functions which
19069  read/write 1, 2, 3, 4 bytes.
19070 \layout Subsection
19071
19072 PIC16 C Libraries
19073 \layout Subsubsection
19074
19075 Standard I/O Streams
19076 \layout Standard
19077
19078 In the
19079 \emph on
19080 stdio.h
19081 \emph default
19082  the type FILE is defined as:
19083 \layout LyX-Code
19084
19085 typedef char * FILE;
19086 \layout Standard
19087
19088 This type is the stream type implemented I/O in the PIC18F devices.
19089  Also the standard input and output streams are declared in stdio.h:
19090 \layout LyX-Code
19091
19092 extern FILE * stdin;
19093 \layout LyX-Code
19094
19095 extern FILE * stdout;
19096 \layout Standard
19097
19098 The FILE type is actually a generic pointer which defines one more type
19099  of generic pointers, the
19100 \emph on
19101 stream
19102 \emph default
19103 pointer.
19104  This new type has the format:
19105 \layout Standard
19106 \align center
19107
19108 \begin_inset  Tabular
19109 <lyxtabular version="3" rows="2" columns="7">
19110 <features>
19111 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19112 <column alignment="center" valignment="top" width="0">
19113 <column alignment="center" valignment="top" leftline="true" width="0">
19114 <column alignment="center" valignment="top" leftline="true" width="0">
19115 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19116 <column alignment="center" valignment="top" width="0">
19117 <column alignment="left" valignment="top" rightline="true" width="0">
19118 <row topline="true" bottomline="true">
19119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19120 \begin_inset Text
19121
19122 \layout Standard
19123
19124 pointer type
19125 \end_inset
19126 </cell>
19127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19128 \begin_inset Text
19129
19130 \layout Standard
19131
19132 <7:6>
19133 \end_inset
19134 </cell>
19135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19136 \begin_inset Text
19137
19138 \layout Standard
19139
19140 <5>
19141 \end_inset
19142 </cell>
19143 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19144 \begin_inset Text
19145
19146 \layout Standard
19147
19148 <4>
19149 \end_inset
19150 </cell>
19151 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19152 \begin_inset Text
19153
19154 \layout Standard
19155
19156 <3:0>
19157 \end_inset
19158 </cell>
19159 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19160 \begin_inset Text
19161
19162 \layout Standard
19163
19164 rest of the pointer
19165 \end_inset
19166 </cell>
19167 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19168 \begin_inset Text
19169
19170 \layout Standard
19171
19172 descrption
19173 \end_inset
19174 </cell>
19175 </row>
19176 <row topline="true" bottomline="true">
19177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19178 \begin_inset Text
19179
19180 \layout Standard
19181
19182 stream
19183 \end_inset
19184 </cell>
19185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19186 \begin_inset Text
19187
19188 \layout Standard
19189
19190 00
19191 \end_inset
19192 </cell>
19193 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19194 \begin_inset Text
19195
19196 \layout Standard
19197
19198 1
19199 \end_inset
19200 </cell>
19201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19202 \begin_inset Text
19203
19204 \layout Standard
19205
19206 0
19207 \end_inset
19208 </cell>
19209 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19210 \begin_inset Text
19211
19212 \layout Standard
19213
19214 nnnn
19215 \end_inset
19216 </cell>
19217 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19218 \begin_inset Text
19219
19220 \layout Standard
19221
19222
19223 \family typewriter
19224 \shape slanted
19225 \emph on
19226 uuuuuuuu uuuuuuuu
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 upper byte high nubble is 0x2n, the rest are zeroes
19235 \end_inset
19236 </cell>
19237 </row>
19238 </lyxtabular>
19239
19240 \end_inset
19241
19242
19243 \layout Standard
19244
19245 Currently implemented there are 3 types of streams defined:
19246 \layout Standard
19247 \align center
19248
19249 \begin_inset  Tabular
19250 <lyxtabular version="3" rows="4" columns="4">
19251 <features>
19252 <column alignment="center" valignment="top" leftline="true" width="0">
19253 <column alignment="center" valignment="top" leftline="true" width="0">
19254 <column alignment="center" valignment="top" leftline="true" width="0">
19255 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19256 <row topline="true" bottomline="true">
19257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19258 \begin_inset Text
19259
19260 \layout Standard
19261
19262 stream type
19263 \end_inset
19264 </cell>
19265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19266 \begin_inset Text
19267
19268 \layout Standard
19269
19270 value
19271 \end_inset
19272 </cell>
19273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19274 \begin_inset Text
19275
19276 \layout Standard
19277
19278 module
19279 \end_inset
19280 </cell>
19281 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19282 \begin_inset Text
19283
19284 \layout Standard
19285
19286 description
19287 \end_inset
19288 </cell>
19289 </row>
19290 <row topline="true">
19291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19292 \begin_inset Text
19293
19294 \layout Standard
19295
19296 STREAM_USART
19297 \end_inset
19298 </cell>
19299 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19300 \begin_inset Text
19301
19302 \layout Standard
19303
19304
19305 \family typewriter
19306 0x200000UL
19307 \end_inset
19308 </cell>
19309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19310 \begin_inset Text
19311
19312 \layout Standard
19313
19314 USART
19315 \end_inset
19316 </cell>
19317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19318 \begin_inset Text
19319
19320 \layout Standard
19321
19322 Writes/Reads characters via the USART peripheral
19323 \end_inset
19324 </cell>
19325 </row>
19326 <row topline="true">
19327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19328 \begin_inset Text
19329
19330 \layout Standard
19331
19332 STREAM_MSSP
19333 \end_inset
19334 </cell>
19335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19336 \begin_inset Text
19337
19338 \layout Standard
19339
19340
19341 \family typewriter
19342 0x210000UL
19343 \end_inset
19344 </cell>
19345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19346 \begin_inset Text
19347
19348 \layout Standard
19349
19350 MSSP
19351 \end_inset
19352 </cell>
19353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19354 \begin_inset Text
19355
19356 \layout Standard
19357
19358 Writes/Reads characters via the MSSP peripheral
19359 \end_inset
19360 </cell>
19361 </row>
19362 <row topline="true" bottomline="true">
19363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19364 \begin_inset Text
19365
19366 \layout Standard
19367
19368 STREAM_USER
19369 \end_inset
19370 </cell>
19371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19372 \begin_inset Text
19373
19374 \layout Standard
19375
19376
19377 \family typewriter
19378 0x2f0000UL
19379 \end_inset
19380 </cell>
19381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19382 \begin_inset Text
19383
19384 \layout Standard
19385
19386 (none)
19387 \end_inset
19388 </cell>
19389 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19390 \begin_inset Text
19391
19392 \layout Standard
19393
19394 Writes/Reads characters via used defined functions
19395 \end_inset
19396 </cell>
19397 </row>
19398 </lyxtabular>
19399
19400 \end_inset
19401
19402
19403 \layout Standard
19404
19405 The stream identifiers are declared as macros in the stdio.h header.
19406 \layout Standard
19407
19408 In the libc library there exist the functions that are used to write to
19409  each of the above streams.
19410  These are
19411 \layout List
19412 \labelwidthstring 00.00.0000
19413
19414 _
19415 \begin_inset ERT
19416 status Collapsed
19417
19418 \layout Standard
19419
19420 \backslash
19421 /
19422 \end_inset
19423
19424 _stream_usart_putchar writes a character at the USART stream
19425 \layout List
19426 \labelwidthstring 00.00.0000
19427
19428 _
19429 \begin_inset ERT
19430 status Collapsed
19431
19432 \layout Standard
19433
19434 \backslash
19435 /
19436 \end_inset
19437
19438 _stream_mssp_putchar writes a character at the MSSP stream
19439 \layout List
19440 \labelwidthstring 00.00.0000
19441
19442 putchar dummy function.
19443  This writes a character to a user specified manner.
19444 \layout Standard
19445
19446 In order to increase performance
19447 \emph on
19448 putchar
19449 \emph default
19450 is declared in stdio.h as having its parameter in WREG (it has the wparam
19451  keyword).
19452  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
19453  in a user-friendly way.
19454
19455 \emph on
19456 arg
19457 \emph default
19458  is the name of the variable that holds the character to print.
19459  An example follows:
19460 \layout LyX-Code
19461
19462 #include <pic18fregs.h>
19463 \newline
19464 #include <stdio.h>
19465 \newline
19466
19467 \newline
19468 PUTCHAR( c )
19469 \layout LyX-Code
19470
19471 {
19472 \layout LyX-Code
19473
19474     PORTA = c;    /* dump character c to PORTA */
19475 \layout LyX-Code
19476
19477 }
19478 \newline
19479
19480 \newline
19481 void main(void)
19482 \layout LyX-Code
19483
19484 {
19485 \layout LyX-Code
19486
19487     stdout = STREAM_USER;    /* this is not necessery, since stdout points
19488 \layout LyX-Code
19489
19490                               * by default to STREAM_USER */
19491 \layout LyX-Code
19492
19493     printf (¨This is a printf test
19494 \backslash
19495 n¨);
19496 \layout LyX-Code
19497
19498 }
19499 \layout LyX-Code
19500
19501 \layout Subsubsection
19502
19503 Printing functions
19504 \layout Standard
19505
19506 PIC16 contains an implementation of the printf-family of functions.
19507  There exist the following functions:
19508 \layout LyX-Code
19509
19510 extern unsigned int sprintf(char *buf, char *fmt, ...);
19511 \layout LyX-Code
19512
19513 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
19514 \layout LyX-Code
19515
19516 \layout LyX-Code
19517
19518 extern unsigned int printf(char *fmt, ...);
19519 \layout LyX-Code
19520
19521 extern unsigned int vprintf(char *fmt, va_lista ap);
19522 \layout LyX-Code
19523
19524 \layout LyX-Code
19525
19526 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
19527 \layout LyX-Code
19528
19529 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
19530 \layout Standard
19531
19532 For sprintf and vsprintf
19533 \emph on
19534 buf
19535 \emph default
19536 should normally be a data pointer where the resulting string will be placed.
19537  No range checking is done so the user should allocate the necessery buffer.
19538  For fprintf and vfprintf
19539 \emph on
19540 fp
19541 \emph default
19542  should be a stream pointer (i.e.
19543  stdout, STREAM_MSSP, etc...).
19544 \layout Subsubsection
19545
19546 Signals
19547 \layout Standard
19548
19549 The PIC18F family of microcontrollers supports a number of interrupt sources.
19550  A list of these interrupts is shown in the following table:
19551 \layout Standard
19552 \align center
19553
19554 \begin_inset  Tabular
19555 <lyxtabular version="3" rows="11" columns="4">
19556 <features>
19557 <column alignment="left" valignment="top" leftline="true" width="0">
19558 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19559 <column alignment="left" valignment="top" leftline="true" width="0">
19560 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19561 <row topline="true" bottomline="true">
19562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19563 \begin_inset Text
19564
19565 \layout Standard
19566
19567 signal name
19568 \end_inset
19569 </cell>
19570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19571 \begin_inset Text
19572
19573 \layout Standard
19574
19575 description
19576 \end_inset
19577 </cell>
19578 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19579 \begin_inset Text
19580
19581 \layout Standard
19582
19583 signal name
19584 \end_inset
19585 </cell>
19586 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19587 \begin_inset Text
19588
19589 \layout Standard
19590
19591 descritpion
19592 \end_inset
19593 </cell>
19594 </row>
19595 <row topline="true">
19596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19597 \begin_inset Text
19598
19599 \layout Standard
19600
19601 SIG_RB
19602 \end_inset
19603 </cell>
19604 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19605 \begin_inset Text
19606
19607 \layout Standard
19608
19609 PORTB change interrupt
19610 \end_inset
19611 </cell>
19612 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19613 \begin_inset Text
19614
19615 \layout Standard
19616
19617 SIG_EE
19618 \end_inset
19619 </cell>
19620 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19621 \begin_inset Text
19622
19623 \layout Standard
19624
19625 EEPROM/FLASH write complete interrupt
19626 \end_inset
19627 </cell>
19628 </row>
19629 <row topline="true">
19630 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19631 \begin_inset Text
19632
19633 \layout Standard
19634
19635 SIG_INT0
19636 \end_inset
19637 </cell>
19638 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19639 \begin_inset Text
19640
19641 \layout Standard
19642
19643 INT0 external interrupt
19644 \end_inset
19645 </cell>
19646 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19647 \begin_inset Text
19648
19649 \layout Standard
19650
19651 SIG_BCOL
19652 \end_inset
19653 </cell>
19654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19655 \begin_inset Text
19656
19657 \layout Standard
19658
19659 Bus collision interrupt
19660 \end_inset
19661 </cell>
19662 </row>
19663 <row topline="true">
19664 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19665 \begin_inset Text
19666
19667 \layout Standard
19668
19669 SIG_INT1
19670 \end_inset
19671 </cell>
19672 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19673 \begin_inset Text
19674
19675 \layout Standard
19676
19677 INT1 external interrupt
19678 \end_inset
19679 </cell>
19680 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19681 \begin_inset Text
19682
19683 \layout Standard
19684
19685 SIG_LVD
19686 \end_inset
19687 </cell>
19688 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19689 \begin_inset Text
19690
19691 \layout Standard
19692
19693 Low voltage detect interrupt
19694 \end_inset
19695 </cell>
19696 </row>
19697 <row topline="true">
19698 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19699 \begin_inset Text
19700
19701 \layout Standard
19702
19703 SIG_INT2
19704 \end_inset
19705 </cell>
19706 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19707 \begin_inset Text
19708
19709 \layout Standard
19710
19711 INT2 external interrupt
19712 \end_inset
19713 </cell>
19714 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19715 \begin_inset Text
19716
19717 \layout Standard
19718
19719 SIG_PSP
19720 \end_inset
19721 </cell>
19722 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19723 \begin_inset Text
19724
19725 \layout Standard
19726
19727 Parallel slave port interrupt
19728 \end_inset
19729 </cell>
19730 </row>
19731 <row topline="true">
19732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19733 \begin_inset Text
19734
19735 \layout Standard
19736
19737 SIG_CCP1
19738 \end_inset
19739 </cell>
19740 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19741 \begin_inset Text
19742
19743 \layout Standard
19744
19745 CCP1 module interrupt
19746 \end_inset
19747 </cell>
19748 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19749 \begin_inset Text
19750
19751 \layout Standard
19752
19753 SIG_AD
19754 \end_inset
19755 </cell>
19756 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19757 \begin_inset Text
19758
19759 \layout Standard
19760
19761 AD convertion complete interrupt
19762 \end_inset
19763 </cell>
19764 </row>
19765 <row topline="true">
19766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19767 \begin_inset Text
19768
19769 \layout Standard
19770
19771 SIG_CCP2
19772 \end_inset
19773 </cell>
19774 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19775 \begin_inset Text
19776
19777 \layout Standard
19778
19779 CCP2 module interrupt
19780 \end_inset
19781 </cell>
19782 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19783 \begin_inset Text
19784
19785 \layout Standard
19786
19787 SIG_RC
19788 \end_inset
19789 </cell>
19790 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19791 \begin_inset Text
19792
19793 \layout Standard
19794
19795 USART receive interrupt
19796 \end_inset
19797 </cell>
19798 </row>
19799 <row topline="true">
19800 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19801 \begin_inset Text
19802
19803 \layout Standard
19804
19805 SIG_TMR0
19806 \end_inset
19807 </cell>
19808 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19809 \begin_inset Text
19810
19811 \layout Standard
19812
19813 TMR0 overflow interrupt
19814 \end_inset
19815 </cell>
19816 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19817 \begin_inset Text
19818
19819 \layout Standard
19820
19821 SIG_TX
19822 \end_inset
19823 </cell>
19824 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19825 \begin_inset Text
19826
19827 \layout Standard
19828
19829 USART transmit interrupt
19830 \end_inset
19831 </cell>
19832 </row>
19833 <row topline="true">
19834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19835 \begin_inset Text
19836
19837 \layout Standard
19838
19839 SIG_TMR1
19840 \end_inset
19841 </cell>
19842 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19843 \begin_inset Text
19844
19845 \layout Standard
19846
19847 TMR1 overflow interrupt
19848 \end_inset
19849 </cell>
19850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19851 \begin_inset Text
19852
19853 \layout Standard
19854
19855 SIG_MSSP
19856 \end_inset
19857 </cell>
19858 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19859 \begin_inset Text
19860
19861 \layout Standard
19862
19863 SSP receive/transmit interrupt
19864 \end_inset
19865 </cell>
19866 </row>
19867 <row topline="true">
19868 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19869 \begin_inset Text
19870
19871 \layout Standard
19872
19873 SIG_TMR2
19874 \end_inset
19875 </cell>
19876 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19877 \begin_inset Text
19878
19879 \layout Standard
19880
19881 TMR2 matches PR2 interrupt
19882 \end_inset
19883 </cell>
19884 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19885 \begin_inset Text
19886
19887 \layout Standard
19888
19889 \end_inset
19890 </cell>
19891 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19892 \begin_inset Text
19893
19894 \layout Standard
19895
19896 \end_inset
19897 </cell>
19898 </row>
19899 <row topline="true" bottomline="true">
19900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19901 \begin_inset Text
19902
19903 \layout Standard
19904
19905 SIG_TMR3
19906 \end_inset
19907 </cell>
19908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19909 \begin_inset Text
19910
19911 \layout Standard
19912
19913 TMR3 overflow interrupt
19914 \end_inset
19915 </cell>
19916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19917 \begin_inset Text
19918
19919 \layout Standard
19920
19921 \end_inset
19922 </cell>
19923 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19924 \begin_inset Text
19925
19926 \layout Standard
19927
19928 \end_inset
19929 </cell>
19930 </row>
19931 </lyxtabular>
19932
19933 \end_inset
19934
19935
19936 \layout Standard
19937
19938 The prototypes for these names are defined in the header file
19939 \emph on
19940 signal.h
19941 \emph default
19942  .
19943 \layout Standard
19944
19945 In order to simplify signal handling, a number of macros is provided:
19946 \layout List
19947 \labelwidthstring 00.00.0000
19948
19949 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
19950  high priority interrupts.
19951
19952 \emph on
19953 name
19954 \emph default
19955  is the function name to use.
19956 \layout List
19957 \labelwidthstring 00.00.0000
19958
19959 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
19960  low priority interrupt.
19961
19962 \emph on
19963 name
19964 \emph default
19965  is the function name to use.
19966 \layout List
19967 \labelwidthstring 00.00.0000
19968
19969 DEF_HANDLER(sig,handler) define a handler for signal
19970 \emph on
19971 sig.
19972 \layout List
19973 \labelwidthstring 00.00.0000
19974
19975 END_DEF end the declaration of the dispatch table.
19976 \layout Standard
19977
19978 Additionally there are two more macros to simplify the declaration of the
19979  signal handler:
19980 \layout List
19981 \labelwidthstring 00.00.0000
19982
19983
19984 \series medium
19985 SIGHANDLER(handler)
19986 \series default
19987 this declares the function prototype for the
19988 \emph on
19989 handler
19990 \emph default
19991  function.
19992 \layout List
19993 \labelwidthstring 00.00.0000
19994
19995 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
19996 \layout Standard
19997
19998 An example of using the macros above is shown below:
19999 \layout LyX-Code
20000
20001 #include <pic18fregs.h>
20002 \layout LyX-Code
20003
20004 #include <signal.h>
20005 \newline
20006
20007 \newline
20008 DEF_INTHIGH(high_int)
20009 \layout LyX-Code
20010
20011 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
20012 \layout LyX-Code
20013
20014 DEF_HANDLER(SIG_BCOL, _bcol_handler)
20015 \layout LyX-Code
20016
20017 END_DEF
20018 \newline
20019
20020 \newline
20021 SIGHANDLER(_tmr0_handler)
20022 \layout LyX-Code
20023
20024 {
20025 \layout LyX-Code
20026
20027   /* action to be taken when timer 0 overflows */
20028 \layout LyX-Code
20029
20030 }
20031 \newline
20032
20033 \newline
20034 SIGHANDLERNAKED(_bcol_handler)
20035 \layout LyX-Code
20036
20037 {
20038 \layout LyX-Code
20039
20040   _asm
20041 \layout LyX-Code
20042
20043     /* action to be taken when bus collision occurs */
20044 \layout LyX-Code
20045
20046     retfie
20047 \layout LyX-Code
20048
20049  _endasm;
20050 \layout LyX-Code
20051
20052 }
20053 \layout Standard
20054
20055
20056 \series bold
20057 NOTES:
20058 \series default
20059  Special care should be taken when using the above scheme:
20060 \layout Itemize
20061
20062 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
20063 \layout Itemize
20064
20065 when declaring SIGHANDLERNAKED handler never forget to use
20066 \emph on
20067 retfie
20068 \emph default
20069  for proper returning.
20070 \layout Subsection
20071
20072 PIC16 Port -- Tips
20073 \layout Standard
20074
20075 Here you can find some general tips for compiling programs with SDCC/pic16.
20076 \layout Subsubsection
20077
20078 Stack size
20079 \layout Standard
20080
20081 The default stack size (that is 64 bytes) probably is enough for many programs.
20082  One must take care that when there are many levels of function nesting,
20083  or there is excessive usage of stack, its size should be extended.
20084  An example of such a case is the printf/sprintf family of functions.
20085  If you encounter problems like not being able to print integers, then you
20086  need to set the stack size around the maximum (256 for small stack model).
20087  The following diagram shows what happens when calling printf to print an
20088  integer:
20089 \layout LyX-Code
20090
20091 printf () --> ltoa () --> ultoa () --> divschar ()
20092 \layout Standard
20093
20094 It is should be understood that stack is easily consumed when calling complicate
20095 d functions.
20096  Using command line arguments like -
20097 \begin_inset ERT
20098 status Collapsed
20099
20100 \layout Standard
20101
20102 \backslash
20103 /
20104 \end_inset
20105
20106 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
20107  stack frames.
20108  Other ways to reduce stack usage may exist.
20109 \layout Chapter
20110
20111 Debugging with SDCDB
20112 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
20113
20114 \end_inset
20115
20116
20117 \begin_inset LatexCommand \index{sdcdb (debugger)}
20118
20119 \end_inset
20120
20121
20122 \layout Standard
20123
20124 SDCC is distributed with a source level debugger
20125 \begin_inset LatexCommand \index{Debugger}
20126
20127 \end_inset
20128
20129 .
20130  The debugger uses a command line interface, the command repertoire of the
20131  debugger has been kept as close to gdb
20132 \begin_inset LatexCommand \index{gdb}
20133
20134 \end_inset
20135
20136  (the GNU debugger) as possible.
20137  The configuration and build process is part of the standard compiler installati
20138 on, which also builds and installs the debugger in the target directory
20139  specified during configuration.
20140  The debugger allows you debug BOTH at the C source and at the ASM source
20141  level.
20142  Sdcdb is currently not available on Win32 platforms.
20143 \layout Section
20144
20145 Compiling for Debugging
20146 \layout Standard
20147
20148 The -
20149 \begin_inset ERT
20150 status Collapsed
20151
20152 \layout Standard
20153
20154 \backslash
20155 /
20156 \end_inset
20157
20158 -debug
20159 \begin_inset LatexCommand \index{-\/-debug}
20160
20161 \end_inset
20162
20163  option must be specified for all files for which debug information is to
20164  be generated.
20165  The complier generates a .adb file for each of these files.
20166  The linker creates the .cdb
20167 \begin_inset LatexCommand \index{<file>.cdb}
20168
20169 \end_inset
20170
20171  file from the .adb
20172 \begin_inset LatexCommand \index{<file>.adb}
20173
20174 \end_inset
20175
20176  files and the address information.
20177  This .cdb is used by the debugger.
20178 \layout Section
20179
20180 How the Debugger Works
20181 \layout Standard
20182
20183 When the -
20184 \begin_inset ERT
20185 status Collapsed
20186
20187 \layout Standard
20188
20189 \backslash
20190 /
20191 \end_inset
20192
20193 -debug option is specified the compiler generates extra symbol information
20194  some of which are put into the assembler source and some are put into the
20195  .adb file.
20196   Then the linker creates the .cdb file from the individual .adb files with
20197  the address information for the symbols.
20198  The debugger reads the symbolic information generated by the compiler &
20199  the address information generated by the linker.
20200  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
20201  execution is controlled by the debugger.
20202  When a command is issued for the debugger, it translates it into appropriate
20203  commands for the simulator.
20204 \layout Section
20205
20206 Starting the Debugger
20207 \layout Standard
20208
20209 The debugger can be started using the following command line.
20210  (Assume the file you are debugging has the file name foo).
20211 \newline
20212
20213 \newline
20214
20215 \family sans
20216 \series bold
20217 sdcdb foo
20218 \newline
20219
20220 \family default
20221 \series default
20222
20223 \newline
20224 The debugger will look for the following files.
20225 \layout Itemize
20226
20227 foo.c - the source file.
20228 \layout Itemize
20229
20230 foo.cdb - the debugger symbol information file.
20231 \layout Itemize
20232
20233 foo.ihx - the Intel hex format
20234 \begin_inset LatexCommand \index{Intel hex format}
20235
20236 \end_inset
20237
20238  object file.
20239 \layout Section
20240
20241 Command Line Options
20242 \layout Itemize
20243
20244 -
20245 \begin_inset ERT
20246 status Collapsed
20247
20248 \layout Standard
20249
20250 \backslash
20251 /
20252 \end_inset
20253
20254 -directory=<source file directory> this option can used to specify the directory
20255  search list.
20256  The debugger will look into the directory list specified for source, cdb
20257  & ihx files.
20258  The items in the directory list must be separated by ':', e.g.
20259  if the source files can be in the directories /home/src1 and /home/src2,
20260  the -
20261 \begin_inset ERT
20262 status Collapsed
20263
20264 \layout Standard
20265
20266 \backslash
20267 /
20268 \end_inset
20269
20270 -directory option should be -
20271 \begin_inset ERT
20272 status Collapsed
20273
20274 \layout Standard
20275
20276 \backslash
20277 /
20278 \end_inset
20279
20280 -directory=/home/src1:/home/src2.
20281  Note there can be no spaces in the option.
20282
20283 \layout Itemize
20284
20285 -cd <directory> - change to the <directory>.
20286 \layout Itemize
20287
20288 -fullname - used by GUI front ends.
20289 \layout Itemize
20290
20291 -cpu <cpu-type> - this argument is passed to the simulator please see the
20292  simulator docs for details.
20293 \layout Itemize
20294
20295 -X <Clock frequency > this options is passed to the simulator please see
20296  the simulator docs for details.
20297 \layout Itemize
20298
20299 -s <serial port file> passed to simulator see the simulator docs for details.
20300 \layout Itemize
20301
20302 -S <serial in,out> passed to simulator see the simulator docs for details.
20303 \layout Itemize
20304
20305 -k <port number> passed to simulator see the simulator docs for details.
20306 \layout Section
20307
20308 Debugger Commands
20309 \layout Standard
20310
20311 As mentioned earlier the command interface for the debugger has been deliberatel
20312 y kept as close the GNU debugger gdb, as possible.
20313  This will help the integration with existing graphical user interfaces
20314  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
20315  If you use a graphical user interface for the debugger you can skip this
20316  section.
20317 \layout Subsubsection*
20318
20319 break [line | file:line | function | file:function]
20320 \layout Standard
20321
20322 Set breakpoint at specified line or function:
20323 \newline
20324
20325 \newline
20326
20327 \family sans
20328 \series bold
20329 sdcdb>break 100
20330 \newline
20331 sdcdb>break foo.c:100
20332 \newline
20333 sdcdb>break funcfoo
20334 \newline
20335 sdcdb>break foo.c:funcfoo
20336 \layout Subsubsection*
20337
20338 clear [line | file:line | function | file:function ]
20339 \layout Standard
20340
20341 Clear breakpoint at specified line or function:
20342 \newline
20343
20344 \newline
20345
20346 \family sans
20347 \series bold
20348 sdcdb>clear 100
20349 \newline
20350 sdcdb>clear foo.c:100
20351 \newline
20352 sdcdb>clear funcfoo
20353 \newline
20354 sdcdb>clear foo.c:funcfoo
20355 \layout Subsubsection*
20356
20357 continue
20358 \layout Standard
20359
20360 Continue program being debugged, after breakpoint.
20361 \layout Subsubsection*
20362
20363 finish
20364 \layout Standard
20365
20366 Execute till the end of the current function.
20367 \layout Subsubsection*
20368
20369 delete [n]
20370 \layout Standard
20371
20372 Delete breakpoint number 'n'.
20373  If used without any option clear ALL user defined break points.
20374 \layout Subsubsection*
20375
20376 info [break | stack | frame | registers ]
20377 \layout Itemize
20378
20379 info break - list all breakpoints
20380 \layout Itemize
20381
20382 info stack - show the function call stack.
20383 \layout Itemize
20384
20385 info frame - show information about the current execution frame.
20386 \layout Itemize
20387
20388 info registers - show content of all registers.
20389 \layout Subsubsection*
20390
20391 step
20392 \layout Standard
20393
20394 Step program until it reaches a different source line.
20395  Note: pressing <return> repeats the last command.
20396 \layout Subsubsection*
20397
20398 next
20399 \layout Standard
20400
20401 Step program, proceeding through subroutine calls.
20402 \layout Subsubsection*
20403
20404 run
20405 \layout Standard
20406
20407 Start debugged program.
20408 \layout Subsubsection*
20409
20410 ptype variable
20411 \layout Standard
20412
20413 Print type information of the variable.
20414 \layout Subsubsection*
20415
20416 print variable
20417 \layout Standard
20418
20419 print value of variable.
20420 \layout Subsubsection*
20421
20422 file filename
20423 \layout Standard
20424
20425 load the given file name.
20426  Note this is an alternate method of loading file for debugging.
20427 \layout Subsubsection*
20428
20429 frame
20430 \layout Standard
20431
20432 print information about current frame.
20433 \layout Subsubsection*
20434
20435 set srcmode
20436 \layout Standard
20437
20438 Toggle between C source & assembly source.
20439 \layout Subsubsection*
20440
20441 ! simulator command
20442 \layout Standard
20443
20444 Send the string following '!' to the simulator, the simulator response is
20445  displayed.
20446  Note the debugger does not interpret the command being sent to the simulator,
20447  so if a command like 'go' is sent the debugger can loose its execution
20448  context and may display incorrect values.
20449 \layout Subsubsection*
20450
20451 quit
20452 \layout Standard
20453
20454 "Watch me now.
20455  Iam going Down.
20456  My name is Bobby Brown"
20457 \layout Section
20458
20459 Interfacing with DDD
20460 \layout Comment
20461
20462 The screenshot was converted from png to eps with:
20463 \begin_inset Quotes sld
20464 \end_inset
20465
20466 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
20467 \begin_inset Quotes srd
20468 \end_inset
20469
20470  which produces a pretty compact eps file which is free from compression
20471  artifacts.
20472 \layout Comment
20473
20474 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
20475  as this broke the build system on Sourceforge (pdf-file was broken).
20476 \layout Standard
20477
20478 The .eps File
20479 \size footnotesize
20480
20481 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.eps}
20482
20483 \end_inset
20484
20485
20486 \size default
20487  shows a screenshot of a debugging session with DDD
20488 \begin_inset LatexCommand \index{DDD (debugger)}
20489
20490 \end_inset
20491
20492  (Unix only) on a simulated 8032.
20493  The debugging session might not run as smoothly as the screenshot suggests.
20494  The debugger allows setting of breakpoints, displaying and changing variables,
20495  single stepping through C and assembler code.
20496
20497 \newline
20498 The source was compiled with
20499 \family sans
20500 \series bold
20501
20502 \newline
20503
20504 \newline
20505 sdcc -
20506 \family default
20507 \series default
20508
20509 \begin_inset ERT
20510 status Collapsed
20511
20512 \layout Standard
20513
20514 \backslash
20515 /
20516 \end_inset
20517
20518
20519 \family sans
20520 \series bold
20521 -debug ddd_example.c
20522 \family default
20523 \series default
20524
20525 \family sans
20526 \series bold
20527
20528 \newline
20529
20530 \family default
20531 \series default
20532
20533 \newline
20534 and DDD was invoked with
20535 \family sans
20536 \series bold
20537
20538 \newline
20539
20540 \newline
20541 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
20542 \layout Section
20543
20544 Interfacing with XEmacs
20545 \begin_inset LatexCommand \index{XEmacs}
20546
20547 \end_inset
20548
20549
20550 \begin_inset LatexCommand \index{Emacs}
20551
20552 \end_inset
20553
20554
20555 \layout Standard
20556
20557 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
20558  sdcdb.el and sdcdbsrc.el.
20559  These two files can be found in the $(prefix)/bin directory after the installat
20560 ion is complete.
20561  These files need to be loaded into XEmacs for the interface to work.
20562  This can be done at XEmacs startup time by inserting the following into
20563  your '.xemacs' file (which can be found in your HOME directory):
20564 \newline
20565
20566 \newline
20567
20568 \family typewriter
20569 (load-file sdcdbsrc.el)
20570 \family default
20571
20572 \newline
20573
20574 \newline
20575 .xemacs is a lisp file so the () around the command is REQUIRED.
20576  The files can also be loaded dynamically while XEmacs is running, set the
20577  environment variable 'EMACSLOADPATH' to the installation bin directory
20578  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
20579  To start the interface enter the following command:
20580 \newline
20581
20582 \newline
20583
20584 \family sans
20585 \series bold
20586 ESC-x sdcdbsrc
20587 \family default
20588 \series default
20589
20590 \newline
20591
20592 \newline
20593 You will prompted to enter the file name to be debugged.
20594
20595 \newline
20596
20597 \newline
20598 The command line options that are passed to the simulator directly are bound
20599  to default values in the file sdcdbsrc.el.
20600  The variables are listed below, these values maybe changed as required.
20601 \layout Itemize
20602
20603 sdcdbsrc-cpu-type '51
20604 \layout Itemize
20605
20606 sdcdbsrc-frequency '11059200
20607 \layout Itemize
20608
20609 sdcdbsrc-serial nil
20610 \layout Standard
20611
20612 The following is a list of key mapping for the debugger interface.
20613 \layout Standard
20614
20615 \SpecialChar ~
20616
20617 \family typewriter
20618
20619 \newline
20620 ;;\SpecialChar ~
20621 Current Listing ::
20622 \newline
20623 ;;key\SpecialChar ~
20624 \SpecialChar ~
20625 \SpecialChar ~
20626 \SpecialChar ~
20627 \SpecialChar ~
20628 \SpecialChar ~
20629 \SpecialChar ~
20630 \SpecialChar ~
20631 \SpecialChar ~
20632 \SpecialChar ~
20633 \SpecialChar ~
20634 \SpecialChar ~
20635 \SpecialChar ~
20636 \SpecialChar ~
20637 binding\SpecialChar ~
20638 \SpecialChar ~
20639 \SpecialChar ~
20640 \SpecialChar ~
20641 \SpecialChar ~
20642 \SpecialChar ~
20643 \SpecialChar ~
20644 \SpecialChar ~
20645 \SpecialChar ~
20646 \SpecialChar ~
20647 \SpecialChar ~
20648 \SpecialChar ~
20649 \SpecialChar ~
20650 \SpecialChar ~
20651 \SpecialChar ~
20652 \SpecialChar ~
20653 \SpecialChar ~
20654 \SpecialChar ~
20655 \SpecialChar ~
20656 \SpecialChar ~
20657 \SpecialChar ~
20658 \SpecialChar ~
20659 Comment
20660 \newline
20661 ;;---\SpecialChar ~
20662 \SpecialChar ~
20663 \SpecialChar ~
20664 \SpecialChar ~
20665 \SpecialChar ~
20666 \SpecialChar ~
20667 \SpecialChar ~
20668 \SpecialChar ~
20669 \SpecialChar ~
20670 \SpecialChar ~
20671 \SpecialChar ~
20672 \SpecialChar ~
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 -------
20698 \newline
20699 ;;
20700 \newline
20701 ;;\SpecialChar ~
20702 n\SpecialChar ~
20703 \SpecialChar ~
20704 \SpecialChar ~
20705 \SpecialChar ~
20706 \SpecialChar ~
20707 \SpecialChar ~
20708 \SpecialChar ~
20709 \SpecialChar ~
20710 \SpecialChar ~
20711 \SpecialChar ~
20712 \SpecialChar ~
20713 \SpecialChar ~
20714 \SpecialChar ~
20715 \SpecialChar ~
20716 \SpecialChar ~
20717 sdcdb-next-from-src\SpecialChar ~
20718 \SpecialChar ~
20719 \SpecialChar ~
20720 \SpecialChar ~
20721 \SpecialChar ~
20722 \SpecialChar ~
20723 \SpecialChar ~
20724 \SpecialChar ~
20725 \SpecialChar ~
20726 \SpecialChar ~
20727 SDCDB next command
20728 \newline
20729 ;;\SpecialChar ~
20730 b\SpecialChar ~
20731 \SpecialChar ~
20732 \SpecialChar ~
20733 \SpecialChar ~
20734 \SpecialChar ~
20735 \SpecialChar ~
20736 \SpecialChar ~
20737 \SpecialChar ~
20738 \SpecialChar ~
20739 \SpecialChar ~
20740 \SpecialChar ~
20741 \SpecialChar ~
20742 \SpecialChar ~
20743 \SpecialChar ~
20744 \SpecialChar ~
20745 sdcdb-back-from-src\SpecialChar ~
20746 \SpecialChar ~
20747 \SpecialChar ~
20748 \SpecialChar ~
20749 \SpecialChar ~
20750 \SpecialChar ~
20751 \SpecialChar ~
20752 \SpecialChar ~
20753 \SpecialChar ~
20754 \SpecialChar ~
20755 SDCDB back command
20756 \newline
20757 ;;\SpecialChar ~
20758 c\SpecialChar ~
20759 \SpecialChar ~
20760 \SpecialChar ~
20761 \SpecialChar ~
20762 \SpecialChar ~
20763 \SpecialChar ~
20764 \SpecialChar ~
20765 \SpecialChar ~
20766 \SpecialChar ~
20767 \SpecialChar ~
20768 \SpecialChar ~
20769 \SpecialChar ~
20770 \SpecialChar ~
20771 \SpecialChar ~
20772 \SpecialChar ~
20773 sdcdb-cont-from-src\SpecialChar ~
20774 \SpecialChar ~
20775 \SpecialChar ~
20776 \SpecialChar ~
20777 \SpecialChar ~
20778 \SpecialChar ~
20779 \SpecialChar ~
20780 \SpecialChar ~
20781 \SpecialChar ~
20782 \SpecialChar ~
20783 SDCDB continue command
20784 \newline
20785 ;;\SpecialChar ~
20786 s\SpecialChar ~
20787 \SpecialChar ~
20788 \SpecialChar ~
20789 \SpecialChar ~
20790 \SpecialChar ~
20791 \SpecialChar ~
20792 \SpecialChar ~
20793 \SpecialChar ~
20794 \SpecialChar ~
20795 \SpecialChar ~
20796 \SpecialChar ~
20797 \SpecialChar ~
20798 \SpecialChar ~
20799 \SpecialChar ~
20800 \SpecialChar ~
20801 sdcdb-step-from-src\SpecialChar ~
20802 \SpecialChar ~
20803 \SpecialChar ~
20804 \SpecialChar ~
20805 \SpecialChar ~
20806 \SpecialChar ~
20807 \SpecialChar ~
20808 \SpecialChar ~
20809 \SpecialChar ~
20810 \SpecialChar ~
20811 SDCDB step command
20812 \newline
20813 ;;\SpecialChar ~
20814 ?\SpecialChar ~
20815 \SpecialChar ~
20816 \SpecialChar ~
20817 \SpecialChar ~
20818 \SpecialChar ~
20819 \SpecialChar ~
20820 \SpecialChar ~
20821 \SpecialChar ~
20822 \SpecialChar ~
20823 \SpecialChar ~
20824 \SpecialChar ~
20825 \SpecialChar ~
20826 \SpecialChar ~
20827 \SpecialChar ~
20828 \SpecialChar ~
20829 sdcdb-whatis-c-sexp\SpecialChar ~
20830 \SpecialChar ~
20831 \SpecialChar ~
20832 \SpecialChar ~
20833 \SpecialChar ~
20834 \SpecialChar ~
20835 \SpecialChar ~
20836 \SpecialChar ~
20837 \SpecialChar ~
20838 \SpecialChar ~
20839 SDCDB ptypecommand for data at
20840 \newline
20841 ;;\SpecialChar ~
20842 \SpecialChar ~
20843 \SpecialChar ~
20844 \SpecialChar ~
20845 \SpecialChar ~
20846 \SpecialChar ~
20847 \SpecialChar ~
20848 \SpecialChar ~
20849 \SpecialChar ~
20850 \SpecialChar ~
20851 \SpecialChar ~
20852 \SpecialChar ~
20853 \SpecialChar ~
20854 \SpecialChar ~
20855 \SpecialChar ~
20856 \SpecialChar ~
20857 \SpecialChar ~
20858 \SpecialChar ~
20859 \SpecialChar ~
20860 \SpecialChar ~
20861 \SpecialChar ~
20862 \SpecialChar ~
20863 \SpecialChar ~
20864 \SpecialChar ~
20865 \SpecialChar ~
20866 \SpecialChar ~
20867 \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 buffer point
20889 \newline
20890 ;;\SpecialChar ~
20891 x\SpecialChar ~
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895 \SpecialChar ~
20896 \SpecialChar ~
20897 \SpecialChar ~
20898 \SpecialChar ~
20899 \SpecialChar ~
20900 \SpecialChar ~
20901 \SpecialChar ~
20902 \SpecialChar ~
20903 \SpecialChar ~
20904 \SpecialChar ~
20905 \SpecialChar ~
20906 sdcdbsrc-delete\SpecialChar ~
20907 \SpecialChar ~
20908 \SpecialChar ~
20909 \SpecialChar ~
20910 \SpecialChar ~
20911 \SpecialChar ~
20912 \SpecialChar ~
20913 \SpecialChar ~
20914 \SpecialChar ~
20915 \SpecialChar ~
20916 \SpecialChar ~
20917 \SpecialChar ~
20918 \SpecialChar ~
20919 \SpecialChar ~
20920 SDCDB Delete all breakpoints if no arg
20921 \newline
20922 ;;\SpecialChar ~
20923 \SpecialChar ~
20924 \SpecialChar ~
20925 \SpecialChar ~
20926 \SpecialChar ~
20927 \SpecialChar ~
20928 \SpecialChar ~
20929 \SpecialChar ~
20930 \SpecialChar ~
20931 \SpecialChar ~
20932 \SpecialChar ~
20933 \SpecialChar ~
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 given or delete arg (C-u arg x)
20970 \newline
20971 ;;\SpecialChar ~
20972 m\SpecialChar ~
20973 \SpecialChar ~
20974 \SpecialChar ~
20975 \SpecialChar ~
20976 \SpecialChar ~
20977 \SpecialChar ~
20978 \SpecialChar ~
20979 \SpecialChar ~
20980 \SpecialChar ~
20981 \SpecialChar ~
20982 \SpecialChar ~
20983 \SpecialChar ~
20984 \SpecialChar ~
20985 \SpecialChar ~
20986 \SpecialChar ~
20987 sdcdbsrc-frame\SpecialChar ~
20988 \SpecialChar ~
20989 \SpecialChar ~
20990 \SpecialChar ~
20991 \SpecialChar ~
20992 \SpecialChar ~
20993 \SpecialChar ~
20994 \SpecialChar ~
20995 \SpecialChar ~
20996 \SpecialChar ~
20997 \SpecialChar ~
20998 \SpecialChar ~
20999 \SpecialChar ~
21000 \SpecialChar ~
21001 \SpecialChar ~
21002 SDCDB Display current frame if no arg,
21003 \newline
21004 ;;\SpecialChar ~
21005 \SpecialChar ~
21006 \SpecialChar ~
21007 \SpecialChar ~
21008 \SpecialChar ~
21009 \SpecialChar ~
21010 \SpecialChar ~
21011 \SpecialChar ~
21012 \SpecialChar ~
21013 \SpecialChar ~
21014 \SpecialChar ~
21015 \SpecialChar ~
21016 \SpecialChar ~
21017 \SpecialChar ~
21018 \SpecialChar ~
21019 \SpecialChar ~
21020 \SpecialChar ~
21021 \SpecialChar ~
21022 \SpecialChar ~
21023 \SpecialChar ~
21024 \SpecialChar ~
21025 \SpecialChar ~
21026 \SpecialChar ~
21027 \SpecialChar ~
21028 \SpecialChar ~
21029 \SpecialChar ~
21030 \SpecialChar ~
21031 \SpecialChar ~
21032 \SpecialChar ~
21033 \SpecialChar ~
21034 \SpecialChar ~
21035 \SpecialChar ~
21036 \SpecialChar ~
21037 \SpecialChar ~
21038 \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 given or display frame arg
21052 \newline
21053 ;;\SpecialChar ~
21054 \SpecialChar ~
21055 \SpecialChar ~
21056 \SpecialChar ~
21057 \SpecialChar ~
21058 \SpecialChar ~
21059 \SpecialChar ~
21060 \SpecialChar ~
21061 \SpecialChar ~
21062 \SpecialChar ~
21063 \SpecialChar ~
21064 \SpecialChar ~
21065 \SpecialChar ~
21066 \SpecialChar ~
21067 \SpecialChar ~
21068 \SpecialChar ~
21069 \SpecialChar ~
21070 \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 buffer point
21101 \newline
21102 ;;\SpecialChar ~
21103 !\SpecialChar ~
21104 \SpecialChar ~
21105 \SpecialChar ~
21106 \SpecialChar ~
21107 \SpecialChar ~
21108 \SpecialChar ~
21109 \SpecialChar ~
21110 \SpecialChar ~
21111 \SpecialChar ~
21112 \SpecialChar ~
21113 \SpecialChar ~
21114 \SpecialChar ~
21115 \SpecialChar ~
21116 \SpecialChar ~
21117 \SpecialChar ~
21118 sdcdbsrc-goto-sdcdb\SpecialChar ~
21119 \SpecialChar ~
21120 \SpecialChar ~
21121 \SpecialChar ~
21122 \SpecialChar ~
21123 \SpecialChar ~
21124 \SpecialChar ~
21125 \SpecialChar ~
21126 \SpecialChar ~
21127 \SpecialChar ~
21128 Goto the SDCDB output buffer
21129 \newline
21130 ;;\SpecialChar ~
21131 p\SpecialChar ~
21132 \SpecialChar ~
21133 \SpecialChar ~
21134 \SpecialChar ~
21135 \SpecialChar ~
21136 \SpecialChar ~
21137 \SpecialChar ~
21138 \SpecialChar ~
21139 \SpecialChar ~
21140 \SpecialChar ~
21141 \SpecialChar ~
21142 \SpecialChar ~
21143 \SpecialChar ~
21144 \SpecialChar ~
21145 \SpecialChar ~
21146 sdcdb-print-c-sexp\SpecialChar ~
21147 \SpecialChar ~
21148 \SpecialChar ~
21149 \SpecialChar ~
21150 \SpecialChar ~
21151 \SpecialChar ~
21152 \SpecialChar ~
21153 \SpecialChar ~
21154 \SpecialChar ~
21155 \SpecialChar ~
21156 \SpecialChar ~
21157 SDCDB print command for data at
21158 \newline
21159 ;;\SpecialChar ~
21160 \SpecialChar ~
21161 \SpecialChar ~
21162 \SpecialChar ~
21163 \SpecialChar ~
21164 \SpecialChar ~
21165 \SpecialChar ~
21166 \SpecialChar ~
21167 \SpecialChar ~
21168 \SpecialChar ~
21169 \SpecialChar ~
21170 \SpecialChar ~
21171 \SpecialChar ~
21172 \SpecialChar ~
21173 \SpecialChar ~
21174 \SpecialChar ~
21175 \SpecialChar ~
21176 \SpecialChar ~
21177 \SpecialChar ~
21178 \SpecialChar ~
21179 \SpecialChar ~
21180 \SpecialChar ~
21181 \SpecialChar ~
21182 \SpecialChar ~
21183 \SpecialChar ~
21184 \SpecialChar ~
21185 \SpecialChar ~
21186 \SpecialChar ~
21187 \SpecialChar ~
21188 \SpecialChar ~
21189 \SpecialChar ~
21190 \SpecialChar ~
21191 \SpecialChar ~
21192 \SpecialChar ~
21193 \SpecialChar ~
21194 \SpecialChar ~
21195 \SpecialChar ~
21196 \SpecialChar ~
21197 \SpecialChar ~
21198 \SpecialChar ~
21199 \SpecialChar ~
21200 \SpecialChar ~
21201 \SpecialChar ~
21202 \SpecialChar ~
21203 \SpecialChar ~
21204 \SpecialChar ~
21205 \SpecialChar ~
21206 buffer point
21207 \newline
21208 ;;\SpecialChar ~
21209 g\SpecialChar ~
21210 \SpecialChar ~
21211 \SpecialChar ~
21212 \SpecialChar ~
21213 \SpecialChar ~
21214 \SpecialChar ~
21215 \SpecialChar ~
21216 \SpecialChar ~
21217 \SpecialChar ~
21218 \SpecialChar ~
21219 \SpecialChar ~
21220 \SpecialChar ~
21221 \SpecialChar ~
21222 \SpecialChar ~
21223 \SpecialChar ~
21224 sdcdbsrc-goto-sdcdb\SpecialChar ~
21225 \SpecialChar ~
21226 \SpecialChar ~
21227 \SpecialChar ~
21228 \SpecialChar ~
21229 \SpecialChar ~
21230 \SpecialChar ~
21231 \SpecialChar ~
21232 \SpecialChar ~
21233 \SpecialChar ~
21234 Goto the SDCDB output buffer
21235 \newline
21236 ;;\SpecialChar ~
21237 t\SpecialChar ~
21238 \SpecialChar ~
21239 \SpecialChar ~
21240 \SpecialChar ~
21241 \SpecialChar ~
21242 \SpecialChar ~
21243 \SpecialChar ~
21244 \SpecialChar ~
21245 \SpecialChar ~
21246 \SpecialChar ~
21247 \SpecialChar ~
21248 \SpecialChar ~
21249 \SpecialChar ~
21250 \SpecialChar ~
21251 \SpecialChar ~
21252 sdcdbsrc-mode\SpecialChar ~
21253 \SpecialChar ~
21254 \SpecialChar ~
21255 \SpecialChar ~
21256 \SpecialChar ~
21257 \SpecialChar ~
21258 \SpecialChar ~
21259 \SpecialChar ~
21260 \SpecialChar ~
21261 \SpecialChar ~
21262 \SpecialChar ~
21263 \SpecialChar ~
21264 \SpecialChar ~
21265 \SpecialChar ~
21266 \SpecialChar ~
21267 \SpecialChar ~
21268 Toggles Sdcdbsrc mode (turns it off)
21269 \newline
21270 ;;
21271 \newline
21272 ;;\SpecialChar ~
21273 C-c\SpecialChar ~
21274 C-f\SpecialChar ~
21275 \SpecialChar ~
21276 \SpecialChar ~
21277 \SpecialChar ~
21278 \SpecialChar ~
21279 \SpecialChar ~
21280 \SpecialChar ~
21281 \SpecialChar ~
21282 \SpecialChar ~
21283 sdcdb-finish-from-src\SpecialChar ~
21284 \SpecialChar ~
21285 \SpecialChar ~
21286 \SpecialChar ~
21287 \SpecialChar ~
21288 \SpecialChar ~
21289 \SpecialChar ~
21290 \SpecialChar ~
21291 SDCDB finish command
21292 \newline
21293 ;;
21294 \newline
21295 ;;\SpecialChar ~
21296 C-x\SpecialChar ~
21297 SPC\SpecialChar ~
21298 \SpecialChar ~
21299 \SpecialChar ~
21300 \SpecialChar ~
21301 \SpecialChar ~
21302 \SpecialChar ~
21303 \SpecialChar ~
21304 \SpecialChar ~
21305 \SpecialChar ~
21306 sdcdb-break\SpecialChar ~
21307 \SpecialChar ~
21308 \SpecialChar ~
21309 \SpecialChar ~
21310 \SpecialChar ~
21311 \SpecialChar ~
21312 \SpecialChar ~
21313 \SpecialChar ~
21314 \SpecialChar ~
21315 \SpecialChar ~
21316 \SpecialChar ~
21317 \SpecialChar ~
21318 \SpecialChar ~
21319 \SpecialChar ~
21320 \SpecialChar ~
21321 \SpecialChar ~
21322 \SpecialChar ~
21323 \SpecialChar ~
21324 Set break for line with point
21325 \newline
21326 ;;\SpecialChar ~
21327 ESC\SpecialChar ~
21328 t\SpecialChar ~
21329 \SpecialChar ~
21330 \SpecialChar ~
21331 \SpecialChar ~
21332 \SpecialChar ~
21333 \SpecialChar ~
21334 \SpecialChar ~
21335 \SpecialChar ~
21336 \SpecialChar ~
21337 \SpecialChar ~
21338 \SpecialChar ~
21339 sdcdbsrc-mode\SpecialChar ~
21340 \SpecialChar ~
21341 \SpecialChar ~
21342 \SpecialChar ~
21343 \SpecialChar ~
21344 \SpecialChar ~
21345 \SpecialChar ~
21346 \SpecialChar ~
21347 \SpecialChar ~
21348 \SpecialChar ~
21349 \SpecialChar ~
21350 \SpecialChar ~
21351 \SpecialChar ~
21352 \SpecialChar ~
21353 \SpecialChar ~
21354 \SpecialChar ~
21355 Toggle Sdcdbsrc mode
21356 \newline
21357 ;;\SpecialChar ~
21358 ESC\SpecialChar ~
21359 m\SpecialChar ~
21360 \SpecialChar ~
21361 \SpecialChar ~
21362 \SpecialChar ~
21363 \SpecialChar ~
21364 \SpecialChar ~
21365 \SpecialChar ~
21366 \SpecialChar ~
21367 \SpecialChar ~
21368 \SpecialChar ~
21369 \SpecialChar ~
21370 sdcdbsrc-srcmode\SpecialChar ~
21371 \SpecialChar ~
21372 \SpecialChar ~
21373 \SpecialChar ~
21374 \SpecialChar ~
21375 \SpecialChar ~
21376 \SpecialChar ~
21377 \SpecialChar ~
21378 \SpecialChar ~
21379 \SpecialChar ~
21380 \SpecialChar ~
21381 \SpecialChar ~
21382 \SpecialChar ~
21383 Toggle list mode
21384 \newline
21385 ;;
21386 \newline
21387
21388 \layout Chapter
21389 \pagebreak_top
21390 TIPS
21391 \layout Standard
21392
21393 Here are a few guidelines that will help the compiler generate more efficient
21394  code, some of the tips are specific to this compiler others are generally
21395  good programming practice.
21396 \layout Itemize
21397
21398 Use the smallest data type to represent your data-value.
21399  If it is known in advance that the value is going to be less than 256 then
21400  use an 'unsigned char' instead of a 'short' or 'int'.
21401  Please note, that ANSI C requires both signed and unsigned chars to be
21402  promoted to 'signed int' before doing any operation.
21403  This promotion
21404 \begin_inset LatexCommand \index{type promotion}
21405
21406 \end_inset
21407
21408  can be omitted, if the result is the same.
21409  The effect of the promotion rules together with the sign-extension is often
21410  surprising:
21411 \begin_deeper
21412 \layout Verse
21413
21414
21415 \family typewriter
21416 unsigned char uc = 0xfe;
21417 \newline
21418 if (uc * uc < 0) /* this is true! */
21419 \newline
21420 {
21421 \newline
21422 \SpecialChar ~
21423 \SpecialChar ~
21424 \SpecialChar ~
21425 \SpecialChar ~
21426 ....
21427 \newline
21428 }
21429 \layout Standard
21430
21431
21432 \family typewriter
21433 uc * uc
21434 \family default
21435  is evaluated as
21436 \family typewriter
21437 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
21438 \family default
21439 .
21440
21441 \newline
21442 Another one:
21443 \layout Verse
21444
21445
21446 \family typewriter
21447 (unsigned char) -12 / (signed char) -3 = ...
21448 \layout Standard
21449
21450 No, the result is not 4:
21451 \layout Verse
21452
21453
21454 \family typewriter
21455 (int) (unsigned char) -12 / (int) (signed char) -3 =
21456 \newline
21457 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
21458 \newline
21459 (int) 0x00f4 / (int) 0xfffd =
21460 \newline
21461 (int) 0x00f4 / (int) 0xfffd =
21462 \newline
21463 (int) 244 / (int) -3 =
21464 \newline
21465 (int) -81 = (int) 0xffaf;
21466 \layout Standard
21467
21468 Don't complain, that gcc gives you a different result.
21469  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
21470  Therefore the results are different.
21471 \newline
21472 From
21473 \begin_inset Quotes sld
21474 \end_inset
21475
21476 comp.lang.c FAQ
21477 \begin_inset Quotes srd
21478 \end_inset
21479
21480 :
21481 \layout Quote
21482
21483 If well-defined overflow characteristics are important and negative values
21484  are not, or if you want to steer clear of sign-extension problems when
21485  manipulating bits or bytes, use one of the corresponding unsigned types.
21486  (Beware when mixing signed and unsigned values in expressions, though.)
21487 \newline
21488 Although character types (especially unsigned char) can be used as "tiny"
21489  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
21490 ble sign extension and increased code size.
21491 \end_deeper
21492 \layout Itemize
21493
21494 Use unsigned when it is known in advance that the value is not going to
21495  be negative.
21496  This helps especially if you are doing division or multiplication, bit-shifting
21497  or are using an array index.
21498 \layout Itemize
21499
21500 NEVER jump into a LOOP.
21501 \layout Itemize
21502
21503 Declare the variables to be local
21504 \begin_inset LatexCommand \index{local variables}
21505
21506 \end_inset
21507
21508  whenever possible, especially loop control variables (induction).
21509 \layout Itemize
21510
21511 Since the compiler does not always do implicit integral promotion, the programme
21512 r should do an explicit cast when integral promotion is required.
21513 \layout Itemize
21514
21515 Reducing the size of division, multiplication & modulus operations can reduce
21516  code size substantially.
21517  Take the following code for example.
21518 \begin_deeper
21519 \layout Verse
21520
21521
21522 \family typewriter
21523 foobar(unsigned int p1, unsigned char ch)
21524 \newline
21525 {
21526 \newline
21527 \SpecialChar ~
21528 \SpecialChar ~
21529 \SpecialChar ~
21530 \SpecialChar ~
21531 unsigned char ch1 = p1 % ch ;
21532 \newline
21533 \SpecialChar ~
21534 \SpecialChar ~
21535 \SpecialChar ~
21536 \SpecialChar ~
21537 ....
21538 \newline
21539 }
21540 \layout Standard
21541
21542 For the modulus operation the variable ch will be promoted to unsigned int
21543  first then the modulus operation will be performed (this will lead to a
21544  call to support routine _moduint()), and the result will be casted to a
21545  char.
21546  If the code is changed to
21547 \layout Verse
21548
21549
21550 \family typewriter
21551 foobar(unsigned int p1, unsigned char ch)
21552 \newline
21553 {
21554 \newline
21555 \SpecialChar ~
21556 \SpecialChar ~
21557 \SpecialChar ~
21558 \SpecialChar ~
21559 unsigned char ch1 = (unsigned char)p1 % ch ;
21560 \newline
21561 \SpecialChar ~
21562 \SpecialChar ~
21563 \SpecialChar ~
21564 \SpecialChar ~
21565 ....
21566 \newline
21567 }
21568 \layout Standard
21569
21570 It would substantially reduce the code generated (future versions of the
21571  compiler will be smart enough to detect such optimization opportunities).
21572 \end_deeper
21573 \layout Itemize
21574
21575 Have a look at the assembly listing to get a
21576 \begin_inset Quotes sld
21577 \end_inset
21578
21579 feeling
21580 \begin_inset Quotes srd
21581 \end_inset
21582
21583  for the code generation.
21584 \layout Section
21585
21586 Tools
21587 \begin_inset LatexCommand \index{Tools}
21588
21589 \end_inset
21590
21591  included in the distribution
21592 \layout Standard
21593 \align center
21594
21595 \begin_inset  Tabular
21596 <lyxtabular version="3" rows="12" columns="3">
21597 <features>
21598 <column alignment="center" valignment="top" leftline="true" width="0pt">
21599 <column alignment="center" valignment="top" leftline="true" width="0pt">
21600 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21601 <row topline="true" bottomline="true">
21602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21603 \begin_inset Text
21604
21605 \layout Standard
21606
21607 Name
21608 \end_inset
21609 </cell>
21610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21611 \begin_inset Text
21612
21613 \layout Standard
21614
21615 Purpose
21616 \end_inset
21617 </cell>
21618 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21619 \begin_inset Text
21620
21621 \layout Standard
21622
21623 Directory
21624 \end_inset
21625 </cell>
21626 </row>
21627 <row topline="true">
21628 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21629 \begin_inset Text
21630
21631 \layout Standard
21632
21633 uCsim
21634 \end_inset
21635 </cell>
21636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21637 \begin_inset Text
21638
21639 \layout Standard
21640
21641 Simulator for various architectures
21642 \end_inset
21643 </cell>
21644 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21645 \begin_inset Text
21646
21647 \layout Standard
21648
21649 sdcc/sim/ucsim
21650 \end_inset
21651 </cell>
21652 </row>
21653 <row topline="true">
21654 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21655 \begin_inset Text
21656
21657 \layout Standard
21658
21659 keil2sdcc.pl
21660 \end_inset
21661 </cell>
21662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21663 \begin_inset Text
21664
21665 \layout Standard
21666
21667 header file conversion
21668 \end_inset
21669 </cell>
21670 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21671 \begin_inset Text
21672
21673 \layout Standard
21674
21675 sdcc/support/scripts
21676 \end_inset
21677 </cell>
21678 </row>
21679 <row topline="true">
21680 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21681 \begin_inset Text
21682
21683 \layout Standard
21684
21685 mh2h.c
21686 \end_inset
21687 </cell>
21688 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21689 \begin_inset Text
21690
21691 \layout Standard
21692
21693 header file conversion
21694 \end_inset
21695 </cell>
21696 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21697 \begin_inset Text
21698
21699 \layout Standard
21700
21701 sdcc/support/scripts
21702 \end_inset
21703 </cell>
21704 </row>
21705 <row topline="true">
21706 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21707 \begin_inset Text
21708
21709 \layout Standard
21710
21711 as-gbz80
21712 \end_inset
21713 </cell>
21714 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21715 \begin_inset Text
21716
21717 \layout Standard
21718
21719 Assembler
21720 \end_inset
21721 </cell>
21722 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21723 \begin_inset Text
21724
21725 \layout Standard
21726
21727
21728 \family roman
21729 \series medium
21730 \shape up
21731 \size normal
21732 \emph off
21733 \bar no
21734 \noun off
21735 \color none
21736 sdcc/bin
21737 \end_inset
21738 </cell>
21739 </row>
21740 <row topline="true">
21741 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21742 \begin_inset Text
21743
21744 \layout Standard
21745
21746 as-z80
21747 \end_inset
21748 </cell>
21749 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21750 \begin_inset Text
21751
21752 \layout Standard
21753
21754 Assembler
21755 \end_inset
21756 </cell>
21757 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21758 \begin_inset Text
21759
21760 \layout Standard
21761
21762
21763 \family roman
21764 \series medium
21765 \shape up
21766 \size normal
21767 \emph off
21768 \bar no
21769 \noun off
21770 \color none
21771 sdcc/bin
21772 \end_inset
21773 </cell>
21774 </row>
21775 <row topline="true">
21776 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21777 \begin_inset Text
21778
21779 \layout Standard
21780
21781 asx8051
21782 \end_inset
21783 </cell>
21784 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21785 \begin_inset Text
21786
21787 \layout Standard
21788
21789 Assembler
21790 \end_inset
21791 </cell>
21792 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21793 \begin_inset Text
21794
21795 \layout Standard
21796
21797
21798 \family roman
21799 \series medium
21800 \shape up
21801 \size normal
21802 \emph off
21803 \bar no
21804 \noun off
21805 \color none
21806 sdcc/bin
21807 \end_inset
21808 </cell>
21809 </row>
21810 <row topline="true">
21811 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21812 \begin_inset Text
21813
21814 \layout Standard
21815
21816 sdcdb
21817 \end_inset
21818 </cell>
21819 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21820 \begin_inset Text
21821
21822 \layout Standard
21823
21824 Simulator
21825 \end_inset
21826 </cell>
21827 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21828 \begin_inset Text
21829
21830 \layout Standard
21831
21832
21833 \family roman
21834 \series medium
21835 \shape up
21836 \size normal
21837 \emph off
21838 \bar no
21839 \noun off
21840 \color none
21841 sdcc/bin
21842 \end_inset
21843 </cell>
21844 </row>
21845 <row topline="true">
21846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21847 \begin_inset Text
21848
21849 \layout Standard
21850
21851 aslink
21852 \end_inset
21853 </cell>
21854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21855 \begin_inset Text
21856
21857 \layout Standard
21858
21859 Linker
21860 \end_inset
21861 </cell>
21862 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21863 \begin_inset Text
21864
21865 \layout Standard
21866
21867
21868 \family roman
21869 \series medium
21870 \shape up
21871 \size normal
21872 \emph off
21873 \bar no
21874 \noun off
21875 \color none
21876 sdcc/bin
21877 \end_inset
21878 </cell>
21879 </row>
21880 <row topline="true">
21881 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21882 \begin_inset Text
21883
21884 \layout Standard
21885
21886 link-z80
21887 \end_inset
21888 </cell>
21889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21890 \begin_inset Text
21891
21892 \layout Standard
21893
21894 Linker
21895 \end_inset
21896 </cell>
21897 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21898 \begin_inset Text
21899
21900 \layout Standard
21901
21902
21903 \family roman
21904 \series medium
21905 \shape up
21906 \size normal
21907 \emph off
21908 \bar no
21909 \noun off
21910 \color none
21911 sdcc/bin
21912 \end_inset
21913 </cell>
21914 </row>
21915 <row topline="true">
21916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21917 \begin_inset Text
21918
21919 \layout Standard
21920
21921 link-gbz80
21922 \end_inset
21923 </cell>
21924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21925 \begin_inset Text
21926
21927 \layout Standard
21928
21929 Linker
21930 \end_inset
21931 </cell>
21932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21933 \begin_inset Text
21934
21935 \layout Standard
21936
21937
21938 \family roman
21939 \series medium
21940 \shape up
21941 \size normal
21942 \emph off
21943 \bar no
21944 \noun off
21945 \color none
21946 sdcc/bin
21947 \end_inset
21948 </cell>
21949 </row>
21950 <row topline="true" bottomline="true">
21951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21952 \begin_inset Text
21953
21954 \layout Standard
21955
21956 packihx
21957 \end_inset
21958 </cell>
21959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21960 \begin_inset Text
21961
21962 \layout Standard
21963
21964 ihx packer
21965 \end_inset
21966 </cell>
21967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21968 \begin_inset Text
21969
21970 \layout Standard
21971
21972
21973 \family roman
21974 \series medium
21975 \shape up
21976 \size normal
21977 \emph off
21978 \bar no
21979 \noun off
21980 \color none
21981 sdcc/bin
21982 \end_inset
21983 </cell>
21984 </row>
21985 </lyxtabular>
21986
21987 \end_inset
21988
21989
21990 \newline
21991
21992 \layout Section
21993
21994 Documentation
21995 \begin_inset LatexCommand \index{Documentation}
21996
21997 \end_inset
21998
21999  included in the distribution
22000 \layout Standard
22001 \align center
22002
22003 \begin_inset  Tabular
22004 <lyxtabular version="3" rows="10" columns="2">
22005 <features>
22006 <column alignment="left" valignment="top" leftline="true" width="0">
22007 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22008 <row topline="true" bottomline="true">
22009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22010 \begin_inset Text
22011
22012 \layout Standard
22013
22014 Subject / Title
22015 \end_inset
22016 </cell>
22017 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22018 \begin_inset Text
22019
22020 \layout Standard
22021
22022 Where to get / filename
22023 \end_inset
22024 </cell>
22025 </row>
22026 <row topline="true">
22027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22028 \begin_inset Text
22029
22030 \layout Standard
22031
22032 SDCC Compiler User Guide
22033 \end_inset
22034 </cell>
22035 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22036 \begin_inset Text
22037
22038 \layout Standard
22039
22040 You're reading it right now
22041 \end_inset
22042 </cell>
22043 </row>
22044 <row topline="true">
22045 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22046 \begin_inset Text
22047
22048 \layout Standard
22049
22050 Changelog of SDCC
22051 \end_inset
22052 </cell>
22053 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22054 \begin_inset Text
22055
22056 \layout Standard
22057
22058 sdcc/Changelog
22059 \end_inset
22060 </cell>
22061 </row>
22062 <row topline="true">
22063 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22064 \begin_inset Text
22065
22066 \layout Standard
22067
22068 ASXXXX
22069 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
22070
22071 \end_inset
22072
22073
22074 \begin_inset LatexCommand \index{Assembler documentation}
22075
22076 \end_inset
22077
22078  Assemblers and ASLINK
22079 \begin_inset LatexCommand \index{aslink}
22080
22081 \end_inset
22082
22083
22084 \begin_inset LatexCommand \index{Linker documentation}
22085
22086 \end_inset
22087
22088  Relocating Linker
22089 \end_inset
22090 </cell>
22091 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22092 \begin_inset Text
22093
22094 \layout Standard
22095
22096 sdcc/as/doc/asxhtm.html
22097 \end_inset
22098 </cell>
22099 </row>
22100 <row topline="true">
22101 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22102 \begin_inset Text
22103
22104 \layout Standard
22105
22106 SDCC regression test
22107 \begin_inset LatexCommand \index{Regression test}
22108
22109 \end_inset
22110
22111
22112 \end_inset
22113 </cell>
22114 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22115 \begin_inset Text
22116
22117 \layout Standard
22118
22119 sdcc/doc/test_suite_spec.pdf
22120 \end_inset
22121 </cell>
22122 </row>
22123 <row topline="true">
22124 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22125 \begin_inset Text
22126
22127 \layout Standard
22128
22129 Various notes
22130 \end_inset
22131 </cell>
22132 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22133 \begin_inset Text
22134
22135 \layout Standard
22136
22137 sdcc/doc/*
22138 \end_inset
22139 </cell>
22140 </row>
22141 <row topline="true">
22142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22143 \begin_inset Text
22144
22145 \layout Standard
22146
22147 Notes on debugging with sdcdb
22148 \begin_inset LatexCommand \index{sdcdb (debugger)}
22149
22150 \end_inset
22151
22152
22153 \end_inset
22154 </cell>
22155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22156 \begin_inset Text
22157
22158 \layout Standard
22159
22160 sdcc/debugger/README
22161 \end_inset
22162 </cell>
22163 </row>
22164 <row topline="true">
22165 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22166 \begin_inset Text
22167
22168 \layout Standard
22169
22170 Software simulator for microcontrollers
22171 \end_inset
22172 </cell>
22173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22174 \begin_inset Text
22175
22176 \layout Standard
22177
22178
22179 \family roman
22180 \series medium
22181 \shape up
22182 \size normal
22183 \emph off
22184 \bar no
22185 \noun off
22186 \color none
22187 sdcc/sim/ucsim/doc
22188 \family default
22189 \series default
22190 \shape default
22191 \size default
22192 \emph default
22193 \bar default
22194 \noun default
22195 \color default
22196 /index.html
22197 \end_inset
22198 </cell>
22199 </row>
22200 <row topline="true">
22201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22202 \begin_inset Text
22203
22204 \layout Standard
22205
22206 Temporary notes on the pic16
22207 \begin_inset LatexCommand \index{PIC16}
22208
22209 \end_inset
22210
22211  port
22212 \end_inset
22213 </cell>
22214 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22215 \begin_inset Text
22216
22217 \layout Standard
22218
22219 sdcc/src/pic16/NOTES
22220 \end_inset
22221 </cell>
22222 </row>
22223 <row topline="true" bottomline="true">
22224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22225 \begin_inset Text
22226
22227 \layout Standard
22228
22229 SDCC internal documentation (debugging file format)
22230 \end_inset
22231 </cell>
22232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22233 \begin_inset Text
22234
22235 \layout Standard
22236
22237 sdcc/doc/
22238 \family roman
22239 \series medium
22240 \shape up
22241 \size normal
22242 \emph off
22243 \bar no
22244 \noun off
22245 \color none
22246 cdbfileformat.pd
22247 \family default
22248 \series default
22249 \shape default
22250 \size default
22251 \emph default
22252 \bar default
22253 \noun default
22254 \color default
22255 f
22256 \end_inset
22257 </cell>
22258 </row>
22259 </lyxtabular>
22260
22261 \end_inset
22262
22263
22264 \newline
22265
22266 \layout Section
22267
22268 Related open source tools
22269 \begin_inset LatexCommand \index{Related tools}
22270
22271 \end_inset
22272
22273
22274 \layout Standard
22275 \align center
22276
22277 \begin_inset  Tabular
22278 <lyxtabular version="3" rows="11" columns="3">
22279 <features>
22280 <column alignment="center" valignment="top" leftline="true" width="0pt">
22281 <column alignment="block" valignment="top" leftline="true" width="30line%">
22282 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22283 <row topline="true" bottomline="true">
22284 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22285 \begin_inset Text
22286
22287 \layout Standard
22288
22289 Name
22290 \end_inset
22291 </cell>
22292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22293 \begin_inset Text
22294
22295 \layout Standard
22296
22297 Purpose
22298 \end_inset
22299 </cell>
22300 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22301 \begin_inset Text
22302
22303 \layout Standard
22304
22305 Where to get
22306 \end_inset
22307 </cell>
22308 </row>
22309 <row topline="true">
22310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22311 \begin_inset Text
22312
22313 \layout Standard
22314
22315 gpsim
22316 \begin_inset LatexCommand \index{gpsim (pic simulator)}
22317
22318 \end_inset
22319
22320
22321 \end_inset
22322 </cell>
22323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22324 \begin_inset Text
22325
22326 \layout Standard
22327
22328 PIC simulator
22329 \end_inset
22330 </cell>
22331 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22332 \begin_inset Text
22333
22334 \layout Standard
22335
22336
22337 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
22338
22339 \end_inset
22340
22341
22342 \end_inset
22343 </cell>
22344 </row>
22345 <row topline="true">
22346 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22347 \begin_inset Text
22348
22349 \layout Standard
22350
22351 gputils
22352 \begin_inset LatexCommand \index{gputils (pic tools)}
22353
22354 \end_inset
22355
22356
22357 \end_inset
22358 </cell>
22359 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22360 \begin_inset Text
22361
22362 \layout Standard
22363
22364 GNU PIC utilities
22365 \end_inset
22366 </cell>
22367 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22368 \begin_inset Text
22369
22370 \layout Standard
22371
22372
22373 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
22374
22375 \end_inset
22376
22377
22378 \end_inset
22379 </cell>
22380 </row>
22381 <row topline="true">
22382 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22383 \begin_inset Text
22384
22385 \layout Standard
22386
22387 flP5
22388 \end_inset
22389 </cell>
22390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22391 \begin_inset Text
22392
22393 \layout Standard
22394
22395 PIC programmer
22396 \end_inset
22397 </cell>
22398 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22399 \begin_inset Text
22400
22401 \layout Standard
22402
22403
22404 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
22405
22406 \end_inset
22407
22408
22409 \end_inset
22410 </cell>
22411 </row>
22412 <row topline="true">
22413 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22414 \begin_inset Text
22415
22416 \layout Standard
22417
22418 indent
22419 \begin_inset LatexCommand \index{indent (source formatting tool)}
22420
22421 \end_inset
22422
22423
22424 \end_inset
22425 </cell>
22426 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22427 \begin_inset Text
22428
22429 \layout Standard
22430
22431 Formats C source - Master of the white spaces
22432 \end_inset
22433 </cell>
22434 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22435 \begin_inset Text
22436
22437 \layout Standard
22438
22439
22440 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
22441
22442 \end_inset
22443
22444
22445 \end_inset
22446 </cell>
22447 </row>
22448 <row topline="true">
22449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22450 \begin_inset Text
22451
22452 \layout Standard
22453
22454 srecord
22455 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
22456
22457 \end_inset
22458
22459
22460 \end_inset
22461 </cell>
22462 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22463 \begin_inset Text
22464
22465 \layout Standard
22466
22467 Object file conversion, checksumming, ...
22468 \end_inset
22469 </cell>
22470 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22471 \begin_inset Text
22472
22473 \layout Standard
22474
22475
22476 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
22477
22478 \end_inset
22479
22480
22481 \end_inset
22482 </cell>
22483 </row>
22484 <row topline="true">
22485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22486 \begin_inset Text
22487
22488 \layout Standard
22489
22490 objdump
22491 \begin_inset LatexCommand \index{objdump (tool)}
22492
22493 \end_inset
22494
22495
22496 \end_inset
22497 </cell>
22498 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22499 \begin_inset Text
22500
22501 \layout Standard
22502
22503 Object file conversion, ...
22504 \end_inset
22505 </cell>
22506 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22507 \begin_inset Text
22508
22509 \layout Standard
22510
22511 Part of binutils (should be there anyway)
22512 \end_inset
22513 </cell>
22514 </row>
22515 <row topline="true">
22516 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22517 \begin_inset Text
22518
22519 \layout Standard
22520
22521 doxygen
22522 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
22523
22524 \end_inset
22525
22526
22527 \end_inset
22528 </cell>
22529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22530 \begin_inset Text
22531
22532 \layout Standard
22533
22534 Source code documentation system
22535 \end_inset
22536 </cell>
22537 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22538 \begin_inset Text
22539
22540 \layout Standard
22541
22542
22543 \begin_inset LatexCommand \url{http://www.doxygen.org}
22544
22545 \end_inset
22546
22547
22548 \end_inset
22549 </cell>
22550 </row>
22551 <row topline="true">
22552 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22553 \begin_inset Text
22554
22555 \layout Standard
22556
22557 kdevelop
22558 \end_inset
22559 </cell>
22560 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22561 \begin_inset Text
22562
22563 \layout Standard
22564
22565 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
22566 \end_inset
22567 </cell>
22568 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22569 \begin_inset Text
22570
22571 \layout Standard
22572
22573
22574 \begin_inset LatexCommand \url{http://www.kdevelop.org}
22575
22576 \end_inset
22577
22578
22579 \end_inset
22580 </cell>
22581 </row>
22582 <row topline="true">
22583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22584 \begin_inset Text
22585
22586 \layout Standard
22587
22588 splint
22589 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22590
22591 \end_inset
22592
22593
22594 \end_inset
22595 </cell>
22596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22597 \begin_inset Text
22598
22599 \layout Standard
22600
22601 Statically checks c sources (see
22602 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22603
22604 \end_inset
22605
22606 )
22607 \end_inset
22608 </cell>
22609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22610 \begin_inset Text
22611
22612 \layout Standard
22613
22614
22615 \begin_inset LatexCommand \url{http://www.splint.org}
22616
22617 \end_inset
22618
22619
22620 \end_inset
22621 </cell>
22622 </row>
22623 <row topline="true" bottomline="true">
22624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22625 \begin_inset Text
22626
22627 \layout Standard
22628
22629 ddd
22630 \begin_inset LatexCommand \index{ddd (debugger)}
22631
22632 \end_inset
22633
22634
22635 \end_inset
22636 </cell>
22637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22638 \begin_inset Text
22639
22640 \layout Standard
22641
22642 Debugger, serves nicely as GUI to sdcdb
22643 \begin_inset LatexCommand \index{sdcdb (debugger)}
22644
22645 \end_inset
22646
22647  (Unix only)
22648 \end_inset
22649 </cell>
22650 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22651 \begin_inset Text
22652
22653 \layout Standard
22654
22655
22656 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
22657
22658 \end_inset
22659
22660
22661 \end_inset
22662 </cell>
22663 </row>
22664 </lyxtabular>
22665
22666 \end_inset
22667
22668
22669 \newline
22670
22671 \layout Section
22672
22673 Related documentation / recommended reading
22674 \layout Standard
22675 \align center
22676
22677 \begin_inset  Tabular
22678 <lyxtabular version="3" rows="6" columns="3">
22679 <features>
22680 <column alignment="center" valignment="top" leftline="true" width="0pt">
22681 <column alignment="block" valignment="top" leftline="true" width="30line%">
22682 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
22683 <row topline="true" bottomline="true">
22684 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22685 \begin_inset Text
22686
22687 \layout Standard
22688
22689 Name
22690 \end_inset
22691 </cell>
22692 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22693 \begin_inset Text
22694
22695 \layout Standard
22696
22697 Subject / Title
22698 \end_inset
22699 </cell>
22700 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22701 \begin_inset Text
22702
22703 \layout Standard
22704
22705 Where to get
22706 \end_inset
22707 </cell>
22708 </row>
22709 <row topline="true">
22710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22711 \begin_inset Text
22712
22713 \layout Standard
22714
22715
22716 \family roman
22717 \series medium
22718 \shape up
22719 \size normal
22720 \emph off
22721 \bar no
22722 \noun off
22723 \color none
22724 c-refcard.pdf
22725 \end_inset
22726 </cell>
22727 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22728 \begin_inset Text
22729
22730 \layout Standard
22731
22732 C Reference Card
22733 \begin_inset LatexCommand \index{C Reference card}
22734
22735 \end_inset
22736
22737 , 2 pages
22738 \end_inset
22739 </cell>
22740 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22741 \begin_inset Text
22742
22743 \layout Standard
22744
22745
22746 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
22747
22748 \end_inset
22749
22750
22751 \end_inset
22752 </cell>
22753 </row>
22754 <row topline="true">
22755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22756 \begin_inset Text
22757
22758 \layout Standard
22759
22760 c-faq
22761 \end_inset
22762 </cell>
22763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22764 \begin_inset Text
22765
22766 \layout Standard
22767
22768 C-FAQ-list
22769 \end_inset
22770 </cell>
22771 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22772 \begin_inset Text
22773
22774 \layout Standard
22775
22776
22777 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
22778
22779 \end_inset
22780
22781
22782 \end_inset
22783 </cell>
22784 </row>
22785 <row topline="true">
22786 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22787 \begin_inset Text
22788
22789 \layout Standard
22790
22791 \end_inset
22792 </cell>
22793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22794 \begin_inset Text
22795
22796 \layout Standard
22797
22798 Latest datasheet of the target CPU
22799 \end_inset
22800 </cell>
22801 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22802 \begin_inset Text
22803
22804 \layout Standard
22805
22806 vendor
22807 \end_inset
22808 </cell>
22809 </row>
22810 <row topline="true">
22811 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22812 \begin_inset Text
22813
22814 \layout Standard
22815
22816 \end_inset
22817 </cell>
22818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22819 \begin_inset Text
22820
22821 \layout Standard
22822
22823 Revision history of datasheet
22824 \end_inset
22825 </cell>
22826 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22827 \begin_inset Text
22828
22829 \layout Standard
22830
22831 vendor
22832 \end_inset
22833 </cell>
22834 </row>
22835 <row topline="true" bottomline="true">
22836 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22837 \begin_inset Text
22838
22839 \layout Standard
22840
22841 S.
22842  S.
22843  Muchnick
22844 \end_inset
22845 </cell>
22846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22847 \begin_inset Text
22848
22849 \layout Standard
22850
22851 Advanced Compiler Design and Implementation
22852 \end_inset
22853 </cell>
22854 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22855 \begin_inset Text
22856
22857 \layout Standard
22858
22859 bookstore (very dedicated, probably read other books first)
22860 \end_inset
22861 </cell>
22862 </row>
22863 </lyxtabular>
22864
22865 \end_inset
22866
22867
22868 \newline
22869
22870 \layout Section
22871
22872 Some Questions
22873 \layout Standard
22874
22875 Some questions answered, some pointers given - it might be time to in turn
22876  ask
22877 \emph on
22878 you
22879 \emph default
22880  some questions:
22881 \layout Itemize
22882
22883 can you solve your project with the selected microcontroller? Would you
22884  find out early or rather late that your target is too small/slow/whatever?
22885  Can you switch to a slightly better device if it doesn't fit?
22886 \layout Itemize
22887
22888 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
22889  and/or another programming language be more adequate? Would an operating
22890  system on the target device help?
22891 \layout Itemize
22892
22893 if you solved the problem, will the marketing department be happy?
22894 \layout Itemize
22895
22896 if the marketing department is happy, will customers be happy?
22897 \layout Itemize
22898
22899 if you're the project manager, marketing department and maybe even the customer
22900  in one person, have you tried to see the project from the outside?
22901 \layout Itemize
22902
22903 is the project done if you think it is done? Or is just that other interface/pro
22904 tocol/feature/configuration/option missing? How about website, manual(s),
22905  internationali(z|s)ation, packaging, labels, 2nd source for components,
22906  electromagnetic compatability/interference, documentation for production,
22907  production test software, update mechanism, patent issues?
22908 \layout Itemize
22909
22910 is your project adequately positioned in that magic triangle: fame, fortune,
22911  fun?
22912 \layout Standard
22913
22914 Maybe not all answers to these questions are known and some answers may
22915  even be
22916 \emph on
22917 no
22918 \emph default
22919 , nevertheless knowing these questions may help you to avoid burnout
22920 \begin_inset Foot
22921 collapsed false
22922
22923 \layout Standard
22924
22925 burnout is bad for electronic devices, programmers and motorcycle tyres
22926 \end_inset
22927
22928 .
22929  Chances are you didn't want to hear some of them...
22930 \layout Chapter
22931
22932 Support
22933 \begin_inset LatexCommand \index{Support}
22934
22935 \end_inset
22936
22937
22938 \layout Standard
22939
22940 SDCC has grown to be a large project.
22941  The compiler alone (without the preprocessor, assembler and linker) is
22942  well over 100,000 lines of code (blank stripped).
22943  The open source nature of this project is a key to its continued growth
22944  and support.
22945  You gain the benefit and support of many active software developers and
22946  end users.
22947  Is SDCC perfect? No, that's why we need your help.
22948  The developers take pride in fixing reported bugs.
22949  You can help by reporting the bugs and helping other SDCC users.
22950  There are lots of ways to contribute, and we encourage you to take part
22951  in making SDCC a great software package.
22952
22953 \layout Standard
22954
22955 The SDCC project is hosted on the SDCC sourceforge site at
22956 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
22957
22958 \end_inset
22959
22960 .
22961  You'll find the complete set of mailing lists
22962 \begin_inset LatexCommand \index{Mailing list(s)}
22963
22964 \end_inset
22965
22966 , forums, bug reporting system, patch submission
22967 \begin_inset LatexCommand \index{Patch submission}
22968
22969 \end_inset
22970
22971  system, download
22972 \begin_inset LatexCommand \index{download}
22973
22974 \end_inset
22975
22976  area and Subversion code repository
22977 \begin_inset LatexCommand \index{Subversion code repository}
22978
22979 \end_inset
22980
22981  there.
22982 \layout Section
22983
22984 Reporting Bugs
22985 \begin_inset LatexCommand \index{Bug reporting}
22986
22987 \end_inset
22988
22989
22990 \begin_inset LatexCommand \index{Reporting bugs}
22991
22992 \end_inset
22993
22994
22995 \layout Standard
22996
22997 The recommended way of reporting bugs is using the infrastructure of the
22998  sourceforge site.
22999  You can follow the status of bug reports there and have an overview about
23000  the known bugs.
23001 \layout Standard
23002
23003 Bug reports are automatically forwarded to the developer mailing list and
23004  will be fixed ASAP.
23005  When reporting a bug, it is very useful to include a small test program
23006  (the smaller the better) which reproduces the problem.
23007  If you can isolate the problem by looking at the generated assembly code,
23008  this can be very helpful.
23009  Compiling your program with the -
23010 \begin_inset ERT
23011 status Collapsed
23012
23013 \layout Standard
23014
23015 \backslash
23016 /
23017 \end_inset
23018
23019 -dumpall
23020 \begin_inset LatexCommand \index{-\/-dumpall}
23021
23022 \end_inset
23023
23024  option can sometimes be useful in locating optimization problems.
23025  When reporting a bug please maker sure you:
23026 \layout Enumerate
23027
23028 Attach the code you are compiling with SDCC.
23029
23030 \layout Enumerate
23031
23032 Specify the exact command you use to run SDCC, or attach your Makefile.
23033
23034 \layout Enumerate
23035
23036 Specify the SDCC version (type "
23037 \family sans
23038 \series bold
23039 sdcc -v
23040 \family default
23041 \series default
23042 "), your platform, and operating system.
23043
23044 \layout Enumerate
23045
23046 Provide an exact copy of any error message or incorrect output.
23047
23048 \layout Enumerate
23049
23050 Put something meaningful in the subject of your message.
23051 \layout Standard
23052
23053 Please attempt to include these 5 important parts, as applicable, in all
23054  requests for support or when reporting any problems or bugs with SDCC.
23055  Though this will make your message lengthy, it will greatly improve your
23056  chance that SDCC users and developers will be able to help you.
23057  Some SDCC developers are frustrated by bug reports without code provided
23058  that they can use to reproduce and ultimately fix the problem, so please
23059  be sure to provide sample code if you are reporting a bug!
23060 \layout Standard
23061
23062 Please have a short check that you are using a recent version of SDCC and
23063  the bug is not yet known.
23064  This is the link for reporting bugs:
23065 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
23066
23067 \end_inset
23068
23069 .
23070 \layout Section
23071
23072 Requesting Features
23073 \begin_inset LatexCommand \label{sub:Requesting-Features}
23074
23075 \end_inset
23076
23077
23078 \begin_inset LatexCommand \index{Feature request}
23079
23080 \end_inset
23081
23082
23083 \begin_inset LatexCommand \index{Requesting features}
23084
23085 \end_inset
23086
23087
23088 \layout Standard
23089
23090 Like bug reports feature requests are forwarded to the developer mailing
23091  list.
23092  This is the link for requesting features:
23093 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
23094
23095 \end_inset
23096
23097 .
23098 \layout Section
23099
23100 Submitting patches
23101 \layout Standard
23102
23103 Like bug reports contributed patches are forwarded to the developer mailing
23104  list.
23105  This is the link for submitting patches
23106 \begin_inset LatexCommand \index{Patch submission}
23107
23108 \end_inset
23109
23110 :
23111 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
23112
23113 \end_inset
23114
23115 .
23116 \layout Standard
23117
23118 You need to specify some parameters to the
23119 \family typewriter
23120 diff
23121 \family default
23122  command for the patches to be useful.
23123  If you modified more than one file a patch created f.e.
23124  with
23125 \family sans
23126 \series bold
23127
23128 \begin_inset Quotes sld
23129 \end_inset
23130
23131 diff -Naur unmodified_directory modified_directory >my_changes.patch
23132 \begin_inset Quotes srd
23133 \end_inset
23134
23135
23136 \family default
23137 \series default
23138  will be fine, otherwise
23139 \family sans
23140 \series bold
23141
23142 \begin_inset Quotes sld
23143 \end_inset
23144
23145 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
23146 \begin_inset Quotes srd
23147 \end_inset
23148
23149
23150 \series default
23151
23152 \family default
23153 will do.
23154 \layout Section
23155
23156 Getting Help
23157 \layout Standard
23158
23159 These links should take you directly to the
23160 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
23161
23162 \end_inset
23163
23164
23165 \begin_inset Foot
23166 collapsed false
23167
23168 \layout Standard
23169
23170 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
23171  automated messages (mid 2003)
23172 \end_inset
23173
23174  and the
23175 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
23176
23177 \end_inset
23178
23179 , lists
23180 \begin_inset LatexCommand \index{Mailing list(s)}
23181
23182 \end_inset
23183
23184  and forums are archived and searchable so if you are lucky someone already
23185  had a similar problem.
23186  While mails to the lists themselves are delivered promptly their web front
23187  end on sourceforge sometimes shows a severe time lag (up to several weeks),
23188  if you're seriously using SDCC please consider subscribing to the lists.
23189 \layout Section
23190
23191 ChangeLog
23192 \layout Standard
23193
23194 You can follow the status of the Subversion version
23195 \begin_inset LatexCommand \index{version}
23196
23197 \end_inset
23198
23199  of SDCC by watching the Changelog
23200 \begin_inset LatexCommand \index{Changelog}
23201
23202 \end_inset
23203
23204  in the Subversion repository
23205 \newline
23206
23207 \size footnotesize
23208
23209 \begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
23210
23211 \end_inset
23212
23213 .
23214 \layout Section
23215
23216 Release policy
23217 \begin_inset LatexCommand \index{Release policy}
23218
23219 \end_inset
23220
23221
23222 \layout Standard
23223
23224 Historically there often were long delays between official releases and
23225  the sourceforge download area tends to get not updated at all.
23226  Excuses in the past might have referred to problems with live range analysis,
23227  but as this was fixed a while ago, the current problem is that another
23228  excuse has to be found.
23229  Kidding aside, we have to get better there! On the other hand there are
23230  daily snapshots available at
23231 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
23232
23233 \end_inset
23234
23235 , and you can always build the very last version (hopefully with many bugs
23236  fixed, and features added) from the source code available at
23237 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
23238
23239 \end_inset
23240
23241 .
23242 \layout Section
23243
23244 Examples
23245 \begin_inset LatexCommand \index{Examples}
23246
23247 \end_inset
23248
23249
23250 \layout Standard
23251
23252 You'll find some small examples in the directory
23253 \emph on
23254 sdcc/device/examples/.
23255
23256 \emph default
23257 More examples and libraries are available at
23258 \emph on
23259  The SDCC Open Knowledge Resource
23260 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
23261
23262 \end_inset
23263
23264
23265 \emph default
23266 web site or at
23267 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
23268
23269 \end_inset
23270
23271 .
23272 \layout Comment
23273
23274 I did insert a reference to Paul's web site here although it seems rather
23275  dedicated to a specific 8032 board (I think it's okay because it f.e.
23276  shows LCD/Harddisc interface and has a free 8051 monitor.
23277  Independent 8032 board vendors face hard competition of heavily subsidized
23278  development boards anyway).
23279 \layout Comment
23280
23281 Maybe we should include some links to real world applications.
23282  Preferably pointer to pointers (one for each architecture) so this stays
23283  manageable here?
23284 \layout Section
23285
23286 Quality control
23287 \begin_inset LatexCommand \index{Quality control}
23288
23289 \end_inset
23290
23291
23292 \layout Standard
23293
23294 The compiler is passed through nightly compile and build checks.
23295  The so called
23296 \shape italic
23297 regression tests
23298 \shape default
23299
23300 \begin_inset LatexCommand \index{Regression test}
23301
23302 \end_inset
23303
23304  check that SDCC itself compiles flawlessly on several platforms and checks
23305  the quality of the code generated by SDCC by running the code through simulator
23306 s.
23307  There is a separate document
23308 \shape italic
23309 test_suite.pdf
23310 \begin_inset LatexCommand \index{Test suite}
23311
23312 \end_inset
23313
23314
23315 \shape default
23316  about this.
23317 \layout Standard
23318
23319 You'll find the test code in the directory
23320 \shape italic
23321 sdcc/support/regression
23322 \shape default
23323 .
23324  You can run these tests manually by running
23325 \family sans
23326 make
23327 \family default
23328  in this directory (or f.e.
23329
23330 \family sans
23331 \series bold
23332
23333 \begin_inset Quotes sld
23334 \end_inset
23335
23336 make test-mcs51
23337 \begin_inset Quotes srd
23338 \end_inset
23339
23340
23341 \family default
23342 \series default
23343  if you don't want to run the complete tests).
23344  The test code might also be interesting if you want to look for examples
23345 \begin_inset LatexCommand \index{Examples}
23346
23347 \end_inset
23348
23349  checking corner cases of SDCC or if you plan to submit patches
23350 \begin_inset LatexCommand \index{Patch submission}
23351
23352 \end_inset
23353
23354 .
23355 \layout Standard
23356
23357 The pic port uses a different set of regression tests, you'll find them
23358  in the directory
23359 \shape italic
23360 sdcc/src/regression
23361 \shape default
23362 .
23363 \layout Section
23364
23365 Use of SDCC in Education
23366 \layout Standard
23367
23368 In short:
23369 \emph on
23370 highly
23371 \emph default
23372  encouraged
23373 \begin_inset Foot
23374 collapsed false
23375
23376 \layout Standard
23377
23378 the phrase "use in education" might evoke the association "
23379 \emph on
23380 only
23381 \emph default
23382  fit for use in education".
23383  This connotation is not intended but nevertheless risked as the licensing
23384  of SDCC makes it difficult to offer educational discounts
23385 \end_inset
23386
23387 .
23388  If your rationales are to:
23389 \layout Enumerate
23390
23391 give students a chance to understand the
23392 \emph on
23393 complete
23394 \emph default
23395  steps of code generation
23396 \layout Enumerate
23397
23398 have a curriculum that can be extended for years.
23399  Then you could use an fpga board as target and your curriculum will seamlessly
23400  extend from logic synthesis (
23401 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
23402
23403 \end_inset
23404
23405 ,
23406 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
23407
23408 \end_inset
23409
23410 ), over assembly programming, to C to FPGA compilers (
23411 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
23412
23413 \end_inset
23414
23415 ) and to C.
23416 \layout Enumerate
23417
23418 be able to insert excursions about skills like using a revision control
23419  system, submitting/applying patches, using a type-setting (as opposed to
23420  word-processing) engine LyX/LaTeX, using
23421 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
23422
23423 \end_inset
23424
23425 , following some
23426 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
23427
23428 \end_inset
23429
23430 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
23431  Source Software, CPU simulation, compiler regression tests
23432 \begin_inset LatexCommand \index{Regression test}
23433
23434 \end_inset
23435
23436 .
23437
23438 \newline
23439 And if there should be a shortage of ideas then you can always point students
23440  to the ever-growing feature request list
23441 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
23442
23443 \end_inset
23444
23445 .
23446 \layout Enumerate
23447
23448 not tie students to a specific host platform and instead allow them to use
23449  a host platform of
23450 \emph on
23451 their
23452 \emph default
23453  choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
23454  eventually
23455 \begin_inset LatexCommand \url[OLPC]{http://wiki.laptop.org/wiki/One_Laptop_per_Child}
23456
23457 \end_inset
23458
23459 )
23460 \layout Enumerate
23461
23462 not encourage students to use illegal copies of educational software
23463 \layout Enumerate
23464
23465 be immune to licensing/availability/price changes of the chosen tool chain
23466 \layout Enumerate
23467
23468 be able to change to a new target platform without having to adopt a new
23469  tool chain
23470 \layout Enumerate
23471
23472 have complete control over and insight into the tool chain
23473 \layout Enumerate
23474
23475 make your students aware about the pros and cons of open source software
23476  development
23477 \layout Enumerate
23478
23479 give back to the public as you are probably at least partially publically
23480  funded
23481 \layout Enumerate
23482
23483 give students a chance to publically prove their skills and to possibly
23484  see a world wide impact
23485 \layout Standard
23486
23487 then SDCC is probably among the first choices.
23488  Well, probably SDCC might be the only choice.
23489 \layout Chapter
23490 \pagebreak_top
23491 SDCC Technical Data
23492 \layout Section
23493
23494 Optimizations
23495 \begin_inset LatexCommand \index{Optimizations}
23496
23497 \end_inset
23498
23499
23500 \layout Standard
23501
23502 SDCC performs a host of standard optimizations in addition to some MCU specific
23503  optimizations.
23504
23505 \layout Subsection
23506
23507 Sub-expression Elimination
23508 \begin_inset LatexCommand \index{Subexpression elimination}
23509
23510 \end_inset
23511
23512
23513 \layout Standard
23514
23515 The compiler does local and
23516 \emph on
23517 g
23518 \emph default
23519 lobal
23520 \emph on
23521 c
23522 \emph default
23523 ommon
23524 \emph on
23525 s
23526 \emph default
23527 ubexpression
23528 \emph on
23529 e
23530 \emph default
23531 limination, e.g.:
23532 \layout Verse
23533
23534
23535 \family typewriter
23536 i = x + y + 1;
23537 \newline
23538 j = x + y;
23539 \layout Standard
23540
23541 will be translated to
23542 \layout Verse
23543
23544
23545 \family typewriter
23546 iTemp = x + y;
23547 \newline
23548 i = iTemp + 1;
23549 \newline
23550 j = iTemp;
23551 \layout Standard
23552
23553 Some subexpressions are not as obvious as the above example, e.g.:
23554 \layout Verse
23555
23556
23557 \family typewriter
23558 a->b[i].c = 10;
23559 \newline
23560 a->b[i].d = 11;
23561 \layout Standard
23562
23563 In this case the address arithmetic a->b[i] will be computed only once;
23564  the equivalent code in C would be.
23565 \layout Verse
23566
23567
23568 \family typewriter
23569 iTemp = a->b[i];
23570 \newline
23571 iTemp.c = 10;
23572 \newline
23573 iTemp.d = 11;
23574 \layout Standard
23575
23576 The compiler will try to keep these temporary variables in registers.
23577 \layout Subsection
23578
23579 Dead-Code Elimination
23580 \begin_inset LatexCommand \index{Dead-code elimination}
23581
23582 \end_inset
23583
23584
23585 \layout Verse
23586
23587
23588 \family typewriter
23589 int global;
23590 \newline
23591
23592 \newline
23593 void f () {
23594 \newline
23595 \SpecialChar ~
23596 \SpecialChar ~
23597 int i;
23598 \newline
23599 \SpecialChar ~
23600 \SpecialChar ~
23601 i = 1; \SpecialChar ~
23602 \SpecialChar ~
23603 \SpecialChar ~
23604 \SpecialChar ~
23605 \SpecialChar ~
23606 /* dead store */
23607 \newline
23608 \SpecialChar ~
23609 \SpecialChar ~
23610 global = 1;\SpecialChar ~
23611 /* dead store */
23612 \newline
23613 \SpecialChar ~
23614 \SpecialChar ~
23615 global = 2;
23616 \newline
23617 \SpecialChar ~
23618 \SpecialChar ~
23619 return;
23620 \newline
23621 \SpecialChar ~
23622 \SpecialChar ~
23623 global = 3;\SpecialChar ~
23624 /* unreachable */
23625 \newline
23626 }
23627 \layout Standard
23628
23629 will be changed to
23630 \layout Verse
23631
23632
23633 \family typewriter
23634 int global;
23635 \newline
23636
23637 \newline
23638 void f () {
23639 \newline
23640 \SpecialChar ~
23641 \SpecialChar ~
23642 global = 2;
23643 \newline
23644 }
23645 \layout Subsection
23646
23647 Copy-Propagation
23648 \begin_inset LatexCommand \index{Copy propagation}
23649
23650 \end_inset
23651
23652
23653 \layout Verse
23654
23655
23656 \family typewriter
23657 int f() {
23658 \newline
23659 \SpecialChar ~
23660 \SpecialChar ~
23661 int i, j;
23662 \newline
23663 \SpecialChar ~
23664 \SpecialChar ~
23665 i = 10;
23666 \newline
23667 \SpecialChar ~
23668 \SpecialChar ~
23669 j = i;
23670 \newline
23671 \SpecialChar ~
23672 \SpecialChar ~
23673 return j;
23674 \newline
23675 }
23676 \layout Standard
23677
23678 will be changed to
23679 \layout Verse
23680
23681
23682 \family typewriter
23683 int f() {
23684 \newline
23685 \SpecialChar ~
23686 \SpecialChar ~
23687 int i, j;
23688 \newline
23689 \SpecialChar ~
23690 \SpecialChar ~
23691 i = 10;
23692 \newline
23693 \SpecialChar ~
23694 \SpecialChar ~
23695 j = 10;
23696 \newline
23697 \SpecialChar ~
23698 \SpecialChar ~
23699 return 10;
23700 \newline
23701 }
23702 \layout Standard
23703
23704 Note: the dead stores created by this copy propagation will be eliminated
23705  by dead-code elimination.
23706 \layout Subsection
23707
23708 Loop Optimizations
23709 \begin_inset LatexCommand \index{Loop optimization}
23710
23711 \end_inset
23712
23713
23714 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
23715
23716 \end_inset
23717
23718
23719 \layout Standard
23720
23721 Two types of loop optimizations are done by SDCC
23722 \emph on
23723 loop invariant
23724 \emph default
23725  lifting and
23726 \emph on
23727  strength reduction
23728 \emph default
23729  of loop induction variables.
23730  In addition to the strength reduction the optimizer marks the induction
23731  variables and the register allocator tries to keep the induction variables
23732  in registers for the duration of the loop.
23733  Because of this preference of the register allocator
23734 \begin_inset LatexCommand \index{Register allocation}
23735
23736 \end_inset
23737
23738 , loop induction optimization causes an increase in register pressure, which
23739  may cause unwanted spilling of other temporary variables into the stack
23740 \begin_inset LatexCommand \index{stack}
23741
23742 \end_inset
23743
23744  / data space.
23745  The compiler will generate a warning message when it is forced to allocate
23746  extra space either on the stack or data space.
23747  If this extra space allocation is undesirable then induction optimization
23748  can be eliminated either for the entire source file (with -
23749 \begin_inset ERT
23750 status Collapsed
23751
23752 \layout Standard
23753
23754 \backslash
23755 /
23756 \end_inset
23757
23758 -noinduction option) or for a given function only using #pragma\SpecialChar ~
23759 noinduction
23760 \begin_inset LatexCommand \index{\#pragma noinduction}
23761
23762 \end_inset
23763
23764 .
23765 \newline
23766
23767 \newline
23768 Loop Invariant:
23769 \layout Verse
23770
23771
23772 \family typewriter
23773 for (i = 0 ; i < 100 ; i ++)
23774 \newline
23775 \SpecialChar ~
23776 \SpecialChar ~
23777 \SpecialChar ~
23778 \SpecialChar ~
23779 f += k + l;
23780 \layout Standard
23781
23782 changed to
23783 \layout Verse
23784
23785
23786 \family typewriter
23787 itemp = k + l;
23788 \newline
23789 for (i = 0; i < 100; i++)
23790 \newline
23791 \SpecialChar ~
23792 \SpecialChar ~
23793 \SpecialChar ~
23794 \SpecialChar ~
23795 f += itemp;
23796 \layout Standard
23797
23798 As mentioned previously some loop invariants are not as apparent, all static
23799  address computations are also moved out of the loop.
23800 \newline
23801
23802 \newline
23803 Strength Reduction
23804 \begin_inset LatexCommand \index{Strength reduction}
23805
23806 \end_inset
23807
23808 , this optimization substitutes an expression by a cheaper expression:
23809 \layout Verse
23810
23811
23812 \family typewriter
23813 for (i=0;i < 100; i++)
23814 \newline
23815 \SpecialChar ~
23816 \SpecialChar ~
23817 \SpecialChar ~
23818 \SpecialChar ~
23819 ar[i*5] = i*3;
23820 \layout Standard
23821
23822 changed to
23823 \layout Verse
23824
23825
23826 \family typewriter
23827 itemp1 = 0;
23828 \newline
23829 itemp2 = 0;
23830 \newline
23831 for (i=0;i< 100;i++) {
23832 \newline
23833 \SpecialChar ~
23834 \SpecialChar ~
23835 \SpecialChar ~
23836 \SpecialChar ~
23837 ar[itemp1] = itemp2;
23838 \newline
23839 \SpecialChar ~
23840 \SpecialChar ~
23841 \SpecialChar ~
23842 \SpecialChar ~
23843 itemp1 += 5;
23844 \newline
23845 \SpecialChar ~
23846 \SpecialChar ~
23847 \SpecialChar ~
23848 \SpecialChar ~
23849 itemp2 += 3;
23850 \newline
23851 }
23852 \layout Standard
23853
23854 The more expensive multiplication
23855 \begin_inset LatexCommand \index{Multiplication}
23856
23857 \end_inset
23858
23859  is changed to a less expensive addition.
23860 \layout Subsection
23861
23862 Loop Reversing
23863 \begin_inset LatexCommand \index{Loop reversing}
23864
23865 \end_inset
23866
23867
23868 \layout Standard
23869
23870 This optimization is done to reduce the overhead of checking loop boundaries
23871  for every iteration.
23872  Some simple loops can be reversed and implemented using a
23873 \begin_inset Quotes eld
23874 \end_inset
23875
23876 decrement and jump if not zero
23877 \begin_inset Quotes erd
23878 \end_inset
23879
23880  instruction.
23881  SDCC checks for the following criterion to determine if a loop is reversible
23882  (note: more sophisticated compilers use data-dependency analysis to make
23883  this determination, SDCC uses a more simple minded analysis).
23884 \layout Itemize
23885
23886 The 'for' loop is of the form
23887 \newline
23888
23889 \newline
23890
23891 \family typewriter
23892 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
23893  += 1])
23894 \newline
23895 \SpecialChar ~
23896 \SpecialChar ~
23897 \SpecialChar ~
23898 \SpecialChar ~
23899 <for body>
23900 \layout Itemize
23901
23902 The <for body> does not contain
23903 \begin_inset Quotes eld
23904 \end_inset
23905
23906 continue
23907 \begin_inset Quotes erd
23908 \end_inset
23909
23910  or 'break
23911 \begin_inset Quotes erd
23912 \end_inset
23913
23914 .
23915 \layout Itemize
23916
23917 All goto's are contained within the loop.
23918 \layout Itemize
23919
23920 No function calls within the loop.
23921 \layout Itemize
23922
23923 The loop control variable <sym> is not assigned any value within the loop
23924 \layout Itemize
23925
23926 The loop control variable does NOT participate in any arithmetic operation
23927  within the loop.
23928 \layout Itemize
23929
23930 There are NO switch statements in the loop.
23931 \layout Subsection
23932
23933 Algebraic Simplifications
23934 \layout Standard
23935
23936 SDCC does numerous algebraic simplifications, the following is a small sub-set
23937  of these optimizations.
23938 \layout Verse
23939
23940
23941 \family typewriter
23942 i = j + 0;\SpecialChar ~
23943 \SpecialChar ~
23944 \SpecialChar ~
23945 \SpecialChar ~
23946  /* changed to: */\SpecialChar ~
23947 \SpecialChar ~
23948 \SpecialChar ~
23949 \SpecialChar ~
23950  i = j;
23951 \newline
23952 i /= 2;\SpecialChar ~
23953 \SpecialChar ~
23954 \SpecialChar ~
23955 \SpecialChar ~
23956 \SpecialChar ~
23957 \SpecialChar ~
23958 \SpecialChar ~
23959  /* changed to: */\SpecialChar ~
23960 \SpecialChar ~
23961 \SpecialChar ~
23962 \SpecialChar ~
23963  i >>= 1;
23964 \newline
23965 i = j - j;\SpecialChar ~
23966 \SpecialChar ~
23967 \SpecialChar ~
23968 \SpecialChar ~
23969  /* changed to: */\SpecialChar ~
23970 \SpecialChar ~
23971 \SpecialChar ~
23972 \SpecialChar ~
23973  i = 0;
23974 \newline
23975 i = j / 1;\SpecialChar ~
23976 \SpecialChar ~
23977 \SpecialChar ~
23978 \SpecialChar ~
23979  /* changed to: */\SpecialChar ~
23980 \SpecialChar ~
23981 \SpecialChar ~
23982 \SpecialChar ~
23983  i = j;
23984 \layout Standard
23985
23986 Note the subexpressions
23987 \begin_inset LatexCommand \index{Subexpression}
23988
23989 \end_inset
23990
23991  given above are generally introduced by macro expansions or as a result
23992  of copy/constant propagation.
23993 \layout Subsection
23994
23995 'switch' Statements
23996 \begin_inset LatexCommand \label{sub:'switch'-Statements}
23997
23998 \end_inset
23999
24000
24001 \begin_inset LatexCommand \index{switch statement}
24002
24003 \end_inset
24004
24005
24006 \layout Standard
24007
24008 SDCC can optimize switch statements to jump tables
24009 \begin_inset LatexCommand \index{jump tables}
24010
24011 \end_inset
24012
24013 .
24014  It makes the decision based on an estimate of the generated code size.
24015  SDCC is quite liberal in the requirements for jump table generation:
24016 \layout Itemize
24017
24018 The labels need not be in order, and the starting number need not be one
24019  or zero, the case labels are in numerical sequence or not too many case
24020  labels are missing.
24021 \begin_deeper
24022 \layout Verse
24023
24024
24025 \family typewriter
24026 switch(i) {\SpecialChar ~
24027 \SpecialChar ~
24028 \SpecialChar ~
24029 \SpecialChar ~
24030 \SpecialChar ~
24031 \SpecialChar ~
24032 \SpecialChar ~
24033 \SpecialChar ~
24034 \SpecialChar ~
24035 \SpecialChar ~
24036 \SpecialChar ~
24037 \SpecialChar ~
24038 \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 switch (i) {
24053 \newline
24054 \SpecialChar ~
24055 \SpecialChar ~
24056 \SpecialChar ~
24057 case 4: ...\SpecialChar ~
24058 \SpecialChar ~
24059 \SpecialChar ~
24060 \SpecialChar ~
24061 \SpecialChar ~
24062 \SpecialChar ~
24063 \SpecialChar ~
24064 \SpecialChar ~
24065 \SpecialChar ~
24066 \SpecialChar ~
24067 \SpecialChar ~
24068 \SpecialChar ~
24069 \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 case 0: ...
24084
24085 \newline
24086 \SpecialChar ~
24087 \SpecialChar ~
24088 \SpecialChar ~
24089 case 5: ...\SpecialChar ~
24090 \SpecialChar ~
24091 \SpecialChar ~
24092 \SpecialChar ~
24093 \SpecialChar ~
24094 \SpecialChar ~
24095 \SpecialChar ~
24096 \SpecialChar ~
24097 \SpecialChar ~
24098 \SpecialChar ~
24099 \SpecialChar ~
24100 \SpecialChar ~
24101 \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 case 1: ...
24116
24117 \newline
24118 \SpecialChar ~
24119 \SpecialChar ~
24120 \SpecialChar ~
24121 case 3: ...\SpecialChar ~
24122 \SpecialChar ~
24123 \SpecialChar ~
24124 \SpecialChar ~
24125 \SpecialChar ~
24126 \SpecialChar ~
24127 \SpecialChar ~
24128 \SpecialChar ~
24129 \SpecialChar ~
24130 \SpecialChar ~
24131 \SpecialChar ~
24132 \SpecialChar ~
24133 \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
24148 \newline
24149 \SpecialChar ~
24150 \SpecialChar ~
24151 \SpecialChar ~
24152 case 6: ...\SpecialChar ~
24153 \SpecialChar ~
24154 \SpecialChar ~
24155 \SpecialChar ~
24156 \SpecialChar ~
24157 \SpecialChar ~
24158 \SpecialChar ~
24159 \SpecialChar ~
24160 \SpecialChar ~
24161 \SpecialChar ~
24162 \SpecialChar ~
24163 \SpecialChar ~
24164 \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 case 3: ...
24179
24180 \newline
24181 \SpecialChar ~
24182 \SpecialChar ~
24183 \SpecialChar ~
24184 case 7: ...\SpecialChar ~
24185 \SpecialChar ~
24186 \SpecialChar ~
24187 \SpecialChar ~
24188 \SpecialChar ~
24189 \SpecialChar ~
24190 \SpecialChar ~
24191 \SpecialChar ~
24192 \SpecialChar ~
24193 \SpecialChar ~
24194 \SpecialChar ~
24195 \SpecialChar ~
24196 \SpecialChar ~
24197 \SpecialChar ~
24198 \SpecialChar ~
24199 \SpecialChar ~
24200 \SpecialChar ~
24201 \SpecialChar ~
24202 \SpecialChar ~
24203 \SpecialChar ~
24204 \SpecialChar ~
24205 \SpecialChar ~
24206 \SpecialChar ~
24207 \SpecialChar ~
24208 \SpecialChar ~
24209 \SpecialChar ~
24210 case 4: ...
24211
24212 \newline
24213 \SpecialChar ~
24214 \SpecialChar ~
24215 \SpecialChar ~
24216 case 8: ...\SpecialChar ~
24217 \SpecialChar ~
24218 \SpecialChar ~
24219 \SpecialChar ~
24220 \SpecialChar ~
24221 \SpecialChar ~
24222 \SpecialChar ~
24223 \SpecialChar ~
24224 \SpecialChar ~
24225 \SpecialChar ~
24226 \SpecialChar ~
24227 \SpecialChar ~
24228 \SpecialChar ~
24229 \SpecialChar ~
24230 \SpecialChar ~
24231 \SpecialChar ~
24232 \SpecialChar ~
24233 \SpecialChar ~
24234 \SpecialChar ~
24235 \SpecialChar ~
24236 \SpecialChar ~
24237 \SpecialChar ~
24238 \SpecialChar ~
24239 \SpecialChar ~
24240 \SpecialChar ~
24241 \SpecialChar ~
24242 case 5: ...
24243
24244 \newline
24245 \SpecialChar ~
24246 \SpecialChar ~
24247 \SpecialChar ~
24248 case 9: ...\SpecialChar ~
24249 \SpecialChar ~
24250 \SpecialChar ~
24251 \SpecialChar ~
24252 \SpecialChar ~
24253 \SpecialChar ~
24254 \SpecialChar ~
24255 \SpecialChar ~
24256 \SpecialChar ~
24257 \SpecialChar ~
24258 \SpecialChar ~
24259 \SpecialChar ~
24260 \SpecialChar ~
24261 \SpecialChar ~
24262 \SpecialChar ~
24263 \SpecialChar ~
24264 \SpecialChar ~
24265 \SpecialChar ~
24266 \SpecialChar ~
24267 \SpecialChar ~
24268 \SpecialChar ~
24269 \SpecialChar ~
24270 \SpecialChar ~
24271 \SpecialChar ~
24272 \SpecialChar ~
24273 \SpecialChar ~
24274 case 6: ...
24275
24276 \newline
24277 \SpecialChar ~
24278 \SpecialChar ~
24279 \SpecialChar ~
24280 case 10: ...\SpecialChar ~
24281 \SpecialChar ~
24282 \SpecialChar ~
24283 \SpecialChar ~
24284 \SpecialChar ~
24285 \SpecialChar ~
24286 \SpecialChar ~
24287 \SpecialChar ~
24288 \SpecialChar ~
24289 \SpecialChar ~
24290 \SpecialChar ~
24291 \SpecialChar ~
24292 \SpecialChar ~
24293 \SpecialChar ~
24294 \SpecialChar ~
24295 \SpecialChar ~
24296 \SpecialChar ~
24297 \SpecialChar ~
24298 \SpecialChar ~
24299 \SpecialChar ~
24300 \SpecialChar ~
24301 \SpecialChar ~
24302 \SpecialChar ~
24303 \SpecialChar ~
24304 \SpecialChar ~
24305 case 7: ...
24306
24307 \newline
24308 \SpecialChar ~
24309 \SpecialChar ~
24310 \SpecialChar ~
24311 case 11: ...\SpecialChar ~
24312 \SpecialChar ~
24313 \SpecialChar ~
24314 \SpecialChar ~
24315 \SpecialChar ~
24316 \SpecialChar ~
24317 \SpecialChar ~
24318 \SpecialChar ~
24319 \SpecialChar ~
24320 \SpecialChar ~
24321 \SpecialChar ~
24322 \SpecialChar ~
24323 \SpecialChar ~
24324 \SpecialChar ~
24325 \SpecialChar ~
24326 \SpecialChar ~
24327 \SpecialChar ~
24328 \SpecialChar ~
24329 \SpecialChar ~
24330 \SpecialChar ~
24331 \SpecialChar ~
24332 \SpecialChar ~
24333 \SpecialChar ~
24334 \SpecialChar ~
24335 \SpecialChar ~
24336 case 8: ...
24337
24338 \newline
24339 }\SpecialChar ~
24340 \SpecialChar ~
24341 \SpecialChar ~
24342 \SpecialChar ~
24343 \SpecialChar ~
24344 \SpecialChar ~
24345 \SpecialChar ~
24346 \SpecialChar ~
24347 \SpecialChar ~
24348 \SpecialChar ~
24349 \SpecialChar ~
24350 \SpecialChar ~
24351 \SpecialChar ~
24352 \SpecialChar ~
24353 \SpecialChar ~
24354 \SpecialChar ~
24355 \SpecialChar ~
24356 \SpecialChar ~
24357 \SpecialChar ~
24358 \SpecialChar ~
24359 \SpecialChar ~
24360 \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 }
24376 \layout Standard
24377
24378 Both the above switch statements will be implemented using a jump-table.
24379  The example to the right side is slightly more efficient as the check for
24380  the lower boundary of the jump-table is not needed.
24381 \end_deeper
24382 \layout Itemize
24383
24384 The number of case labels is not larger than supported by the target architectur
24385 e.
24386 \layout Itemize
24387
24388 If the case labels are not in numerical sequence ('gaps' between cases)
24389  SDCC checks whether a jump table with additionally inserted dummy cases
24390  is still attractive.
24391
24392 \layout Itemize
24393
24394 If the starting number is not zero and a check for the lower boundary of
24395  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
24396  ...
24397  .
24398 \layout Standard
24399
24400 Switch statements which have large gaps in the numeric sequence or those
24401  that have too many case labels can be split into more than one switch statement
24402  for efficient code generation, e.g.:
24403 \layout Verse
24404
24405
24406 \family typewriter
24407 switch (i) {
24408 \newline
24409 \SpecialChar ~
24410 \SpecialChar ~
24411 case 1: ...
24412
24413 \newline
24414 \SpecialChar ~
24415 \SpecialChar ~
24416 case 2: ...
24417
24418 \newline
24419 \SpecialChar ~
24420 \SpecialChar ~
24421 case 3: ...
24422
24423 \newline
24424 \SpecialChar ~
24425 \SpecialChar ~
24426 case 4: ...
24427
24428 \newline
24429 \SpecialChar ~
24430 \SpecialChar ~
24431 case 5: ...
24432
24433 \newline
24434 \SpecialChar ~
24435 \SpecialChar ~
24436 case 6: ...
24437
24438 \newline
24439 \SpecialChar ~
24440 \SpecialChar ~
24441 case 7: ...
24442
24443 \newline
24444 \SpecialChar ~
24445 \SpecialChar ~
24446 case 101: ...
24447
24448 \newline
24449 \SpecialChar ~
24450 \SpecialChar ~
24451 case 102: ...
24452
24453 \newline
24454 \SpecialChar ~
24455 \SpecialChar ~
24456 case 103: ...
24457
24458 \newline
24459 \SpecialChar ~
24460 \SpecialChar ~
24461 case 104: ...
24462
24463 \newline
24464 \SpecialChar ~
24465 \SpecialChar ~
24466 case 105: ...
24467
24468 \newline
24469 \SpecialChar ~
24470 \SpecialChar ~
24471 case 106: ...
24472
24473 \newline
24474 \SpecialChar ~
24475 \SpecialChar ~
24476 case 107: ...
24477
24478 \newline
24479 }
24480 \layout Standard
24481
24482 If the above switch statement is broken down into two switch statements
24483 \layout Verse
24484
24485
24486 \family typewriter
24487 switch (i) {
24488 \newline
24489 \SpecialChar ~
24490 \SpecialChar ~
24491 case 1: ...
24492
24493 \newline
24494 \SpecialChar ~
24495 \SpecialChar ~
24496 case 2: ...
24497
24498 \newline
24499 \SpecialChar ~
24500 \SpecialChar ~
24501 case 3: ...
24502
24503 \newline
24504 \SpecialChar ~
24505 \SpecialChar ~
24506 case 4: ...
24507
24508 \newline
24509 \SpecialChar ~
24510 \SpecialChar ~
24511 case 5: ...
24512
24513 \newline
24514 \SpecialChar ~
24515 \SpecialChar ~
24516 case 6: ...
24517
24518 \newline
24519 \SpecialChar ~
24520 \SpecialChar ~
24521 case 7: ...
24522
24523 \newline
24524 }
24525 \layout Standard
24526
24527 and
24528 \layout Verse
24529
24530
24531 \family typewriter
24532 switch (i) {
24533 \newline
24534 \SpecialChar ~
24535 \SpecialChar ~
24536 case 101: ...
24537
24538 \newline
24539 \SpecialChar ~
24540 \SpecialChar ~
24541 case 102: ...
24542
24543 \newline
24544 \SpecialChar ~
24545 \SpecialChar ~
24546 case 103: ...
24547
24548 \newline
24549 \SpecialChar ~
24550 \SpecialChar ~
24551 case 104: ...
24552
24553 \newline
24554 \SpecialChar ~
24555 \SpecialChar ~
24556 case 105: ...
24557
24558 \newline
24559 \SpecialChar ~
24560 \SpecialChar ~
24561 case 106: ...
24562
24563 \newline
24564 \SpecialChar ~
24565 \SpecialChar ~
24566 case 107: ...
24567
24568 \newline
24569 }
24570 \layout Standard
24571
24572 then both the switch statements will be implemented using jump-tables whereas
24573  the unmodified switch statement will not be.
24574 \layout Comment
24575
24576 There might be reasons which SDCC cannot know about to either favour or
24577  not favour jump tables.
24578  If the target system has to be as quick for the last switch case as for
24579  the first (pro jump table), or if the switch argument is known to be zero
24580  in the majority of the cases (contra jump table).
24581 \layout Standard
24582
24583 The pragma nojtbound
24584 \begin_inset LatexCommand \index{\#pragma nojtbound}
24585
24586 \end_inset
24587
24588  can be used to turn off checking the
24589 \emph on
24590 j
24591 \emph default
24592 ump
24593 \emph on
24594 t
24595 \emph default
24596 able
24597 \emph on
24598 bound
24599 \emph default
24600 aries.
24601  It has no effect if a default label is supplied.
24602  Use of this pragma is dangerous: if the switch
24603 \begin_inset LatexCommand \index{switch statement}
24604
24605 \end_inset
24606
24607  argument is not matched by a case statement the processor will happily
24608  jump into Nirvana.
24609 \layout Subsection
24610
24611 Bit-shifting Operations
24612 \begin_inset LatexCommand \index{Bit shifting}
24613
24614 \end_inset
24615
24616 .
24617 \layout Standard
24618
24619 Bit shifting is one of the most frequently used operation in embedded programmin
24620 g.
24621  SDCC tries to implement bit-shift operations in the most efficient way
24622  possible, e.g.:
24623 \layout Verse
24624
24625
24626 \family typewriter
24627 unsigned char i;
24628 \newline
24629 ...
24630
24631 \newline
24632 i >>= 4;
24633 \newline
24634 ...
24635 \layout Standard
24636
24637 generates the following code:
24638 \layout Verse
24639
24640
24641 \family typewriter
24642 mov\SpecialChar ~
24643  a,_i
24644 \newline
24645 swap a
24646 \newline
24647 anl\SpecialChar ~
24648  a,#0x0f
24649 \newline
24650 mov\SpecialChar ~
24651  _i,a
24652 \layout Standard
24653
24654 In general SDCC will never setup a loop if the shift count is known.
24655  Another example:
24656 \layout Verse
24657
24658
24659 \family typewriter
24660 unsigned int i;
24661 \newline
24662 ...
24663
24664 \newline
24665 i >>= 9;
24666 \newline
24667 ...
24668 \layout Standard
24669
24670 will generate:
24671 \layout Verse
24672
24673
24674 \family typewriter
24675 mov\SpecialChar ~
24676 \SpecialChar ~
24677 a,(_i + 1)
24678 \newline
24679 mov\SpecialChar ~
24680 \SpecialChar ~
24681 (_i + 1),#0x00
24682 \newline
24683 clr\SpecialChar ~
24684 \SpecialChar ~
24685 c
24686 \newline
24687 rrc\SpecialChar ~
24688 \SpecialChar ~
24689 a
24690 \newline
24691 mov\SpecialChar ~
24692 \SpecialChar ~
24693 _i,a
24694 \layout Subsection
24695
24696 Bit-rotation
24697 \begin_inset LatexCommand \index{Bit rotation}
24698
24699 \end_inset
24700
24701
24702 \layout Standard
24703
24704 A special case of the bit-shift operation is bit rotation
24705 \begin_inset LatexCommand \index{rotating bits}
24706
24707 \end_inset
24708
24709 , SDCC recognizes the following expression to be a left bit-rotation:
24710 \layout Verse
24711
24712
24713 \family typewriter
24714 \series bold
24715 unsigned
24716 \series default
24717 \SpecialChar ~
24718 \SpecialChar ~
24719 char i;\SpecialChar ~
24720 \SpecialChar ~
24721 \SpecialChar ~
24722 \SpecialChar ~
24723 \SpecialChar ~
24724 \SpecialChar ~
24725 \SpecialChar ~
24726 \SpecialChar ~
24727 \SpecialChar ~
24728 \SpecialChar ~
24729 \SpecialChar ~
24730 /* unsigned is needed for rotation */
24731 \newline
24732 ...
24733
24734 \newline
24735 i = ((i << 1) | (i >> 7));
24736 \family default
24737
24738 \newline
24739
24740 \family typewriter
24741 ...
24742 \layout Standard
24743
24744 will generate the following code:
24745 \layout Verse
24746
24747
24748 \family typewriter
24749 mov\SpecialChar ~
24750 \SpecialChar ~
24751 a,_i
24752 \newline
24753 rl\SpecialChar ~
24754 \SpecialChar ~
24755 \SpecialChar ~
24756 a
24757 \newline
24758 mov\SpecialChar ~
24759 \SpecialChar ~
24760 _i,a
24761 \layout Standard
24762
24763 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
24764 ns of this case will also be recognized as bit-rotation, i.e.:
24765 \layout Verse
24766
24767
24768 \family typewriter
24769 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
24770 \layout Subsection
24771
24772 Nibble and Byte Swapping
24773 \layout Standard
24774
24775 Other special cases of the bit-shift operations are nibble or byte swapping
24776 \begin_inset LatexCommand \index{swapping nibbles/bytes}
24777
24778 \end_inset
24779
24780 , SDCC recognizes the following expressions:
24781 \layout Verse
24782
24783
24784 \family typewriter
24785 \series bold
24786 unsigned
24787 \series default
24788 \SpecialChar ~
24789 \SpecialChar ~
24790 char i;
24791 \newline
24792
24793 \series bold
24794 unsigned
24795 \series default
24796 \SpecialChar ~
24797 \SpecialChar ~
24798 int j;
24799 \newline
24800 ...
24801
24802 \newline
24803 i = ((i << 4) | (i >> 4));
24804 \family default
24805
24806 \newline
24807
24808 \family typewriter
24809 j = ((j << 8) | (j >> 8));
24810 \layout Standard
24811
24812 and generates a swap instruction for the nibble swapping
24813 \begin_inset LatexCommand \index{Nibble swapping}
24814
24815 \end_inset
24816
24817  or move instructions for the byte swapping
24818 \begin_inset LatexCommand \index{Byte swapping}
24819
24820 \end_inset
24821
24822 .
24823  The
24824 \begin_inset Quotes sld
24825 \end_inset
24826
24827 j
24828 \begin_inset Quotes srd
24829 \end_inset
24830
24831  example can be used to convert from little to big-endian or vice versa.
24832  If you want to change the endianness of a
24833 \emph on
24834 signed
24835 \emph default
24836  integer you have to cast to
24837 \family typewriter
24838 (unsigned int)
24839 \family default
24840  first.
24841 \layout Standard
24842
24843 Note that SDCC stores numbers in little-endian
24844 \begin_inset Foot
24845 collapsed false
24846
24847 \layout Standard
24848
24849 Usually 8-bit processors don't care much about endianness.
24850  This is not the case for the standard 8051 which only has an instruction
24851  to increment its
24852 \emph on
24853 dptr
24854 \emph default
24855
24856 \begin_inset LatexCommand \index{DPTR}
24857
24858 \end_inset
24859
24860 -datapointer
24861 \emph on
24862
24863 \emph default
24864 so little-endian is the more efficient byte order.
24865 \end_inset
24866
24867
24868 \begin_inset LatexCommand \index{little-endian}
24869
24870 \end_inset
24871
24872
24873 \begin_inset LatexCommand \index{Endianness}
24874
24875 \end_inset
24876
24877  format (i.e.
24878  lowest order first).
24879 \layout Subsection
24880
24881 Highest Order Bit
24882 \begin_inset LatexCommand \index{Highest Order Bit}
24883
24884 \end_inset
24885
24886  / Any Order Bit
24887 \begin_inset LatexCommand \index{Any Order Bit}
24888
24889 \end_inset
24890
24891
24892 \layout Standard
24893
24894 It is frequently required to obtain the highest order bit of an integral
24895  type (long, int, short or char types).
24896  Also obtaining any other order bit is not uncommon.
24897  SDCC recognizes the following expressions to yield the highest order bit
24898  and generates optimized code for it, e.g.:
24899 \layout Verse
24900
24901
24902 \family typewriter
24903 unsigned int gint;
24904 \newline
24905
24906 \newline
24907 foo () {
24908 \newline
24909 \SpecialChar ~
24910 \SpecialChar ~
24911 unsigned char hob1, aob1;
24912 \newline
24913 \SpecialChar ~
24914 \SpecialChar ~
24915 bit hob2, hob3, aob2, aob3;
24916 \newline
24917 \SpecialChar ~
24918 \SpecialChar ~
24919 ...
24920
24921 \newline
24922 \SpecialChar ~
24923 \SpecialChar ~
24924 hob1 = (gint >> 15) & 1;
24925 \newline
24926 \SpecialChar ~
24927 \SpecialChar ~
24928 hob2 = (gint >> 15) & 1;
24929 \newline
24930 \SpecialChar ~
24931 \SpecialChar ~
24932 hob3 = gint & 0x8000;
24933 \newline
24934 \SpecialChar ~
24935 \SpecialChar ~
24936 aob1 = (gint >> 9) & 1;
24937 \newline
24938 \SpecialChar ~
24939 \SpecialChar ~
24940 aob2 = (gint >> 8) & 1;
24941 \newline
24942 \SpecialChar ~
24943 \SpecialChar ~
24944 aob3 = gint & 0x0800;
24945 \newline
24946 \SpecialChar ~
24947 \SpecialChar ~
24948 ..
24949
24950 \newline
24951 }
24952 \layout Standard
24953
24954 will generate the following code:
24955 \layout Verse
24956
24957
24958 \family typewriter
24959 \SpecialChar ~
24960 \SpecialChar ~
24961 \SpecialChar ~
24962 \SpecialChar ~
24963 \SpecialChar ~
24964 \SpecialChar ~
24965 \SpecialChar ~
24966 \SpecialChar ~
24967 \SpecialChar ~
24968 \SpecialChar ~
24969 \SpecialChar ~
24970 \SpecialChar ~
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  61 ;\SpecialChar ~
24985  hob.c 7
24986 \newline
24987 000A E5*01\SpecialChar ~
24988 \SpecialChar ~
24989 \SpecialChar ~
24990 \SpecialChar ~
24991 \SpecialChar ~
24992 \SpecialChar ~
24993 \SpecialChar ~
24994 \SpecialChar ~
24995 \SpecialChar ~
24996 \SpecialChar ~
24997 \SpecialChar ~
24998 \SpecialChar ~
24999 \SpecialChar ~
25000 \SpecialChar ~
25001 \SpecialChar ~
25002  62\SpecialChar ~
25003 \SpecialChar ~
25004 \SpecialChar ~
25005 \SpecialChar ~
25006 \SpecialChar ~
25007 \SpecialChar ~
25008 \SpecialChar ~
25009 \SpecialChar ~
25010  mov\SpecialChar ~
25011 \SpecialChar ~
25012  a,(_gint + 1)
25013 \newline
25014 000C 23\SpecialChar ~
25015 \SpecialChar ~
25016 \SpecialChar ~
25017 \SpecialChar ~
25018 \SpecialChar ~
25019 \SpecialChar ~
25020 \SpecialChar ~
25021 \SpecialChar ~
25022 \SpecialChar ~
25023 \SpecialChar ~
25024 \SpecialChar ~
25025 \SpecialChar ~
25026 \SpecialChar ~
25027 \SpecialChar ~
25028 \SpecialChar ~
25029 \SpecialChar ~
25030 \SpecialChar ~
25031 \SpecialChar ~
25032  63\SpecialChar ~
25033 \SpecialChar ~
25034 \SpecialChar ~
25035 \SpecialChar ~
25036 \SpecialChar ~
25037 \SpecialChar ~
25038 \SpecialChar ~
25039 \SpecialChar ~
25040  rl\SpecialChar ~
25041 \SpecialChar ~
25042 \SpecialChar ~
25043  a
25044 \newline
25045 000D 54 01\SpecialChar ~
25046 \SpecialChar ~
25047 \SpecialChar ~
25048 \SpecialChar ~
25049 \SpecialChar ~
25050 \SpecialChar ~
25051 \SpecialChar ~
25052 \SpecialChar ~
25053 \SpecialChar ~
25054 \SpecialChar ~
25055 \SpecialChar ~
25056 \SpecialChar ~
25057 \SpecialChar ~
25058 \SpecialChar ~
25059 \SpecialChar ~
25060  64\SpecialChar ~
25061 \SpecialChar ~
25062 \SpecialChar ~
25063 \SpecialChar ~
25064 \SpecialChar ~
25065 \SpecialChar ~
25066 \SpecialChar ~
25067 \SpecialChar ~
25068  anl\SpecialChar ~
25069 \SpecialChar ~
25070  a,#0x01
25071 \newline
25072 000F F5*02\SpecialChar ~
25073 \SpecialChar ~
25074 \SpecialChar ~
25075 \SpecialChar ~
25076 \SpecialChar ~
25077 \SpecialChar ~
25078 \SpecialChar ~
25079 \SpecialChar ~
25080 \SpecialChar ~
25081 \SpecialChar ~
25082 \SpecialChar ~
25083 \SpecialChar ~
25084 \SpecialChar ~
25085 \SpecialChar ~
25086 \SpecialChar ~
25087  65\SpecialChar ~
25088 \SpecialChar ~
25089 \SpecialChar ~
25090 \SpecialChar ~
25091 \SpecialChar ~
25092 \SpecialChar ~
25093 \SpecialChar ~
25094 \SpecialChar ~
25095  mov\SpecialChar ~
25096 \SpecialChar ~
25097  _foo_hob1_1_1,a
25098 \newline
25099 \SpecialChar ~
25100 \SpecialChar ~
25101 \SpecialChar ~
25102 \SpecialChar ~
25103 \SpecialChar ~
25104 \SpecialChar ~
25105 \SpecialChar ~
25106 \SpecialChar ~
25107 \SpecialChar ~
25108 \SpecialChar ~
25109 \SpecialChar ~
25110 \SpecialChar ~
25111 \SpecialChar ~
25112 \SpecialChar ~
25113 \SpecialChar ~
25114 \SpecialChar ~
25115 \SpecialChar ~
25116 \SpecialChar ~
25117 \SpecialChar ~
25118 \SpecialChar ~
25119 \SpecialChar ~
25120 \SpecialChar ~
25121 \SpecialChar ~
25122 \SpecialChar ~
25123 \SpecialChar ~
25124  66 ;\SpecialChar ~
25125  hob.c 8
25126 \newline
25127 0011 E5*01\SpecialChar ~
25128 \SpecialChar ~
25129 \SpecialChar ~
25130 \SpecialChar ~
25131 \SpecialChar ~
25132 \SpecialChar ~
25133 \SpecialChar ~
25134 \SpecialChar ~
25135 \SpecialChar ~
25136 \SpecialChar ~
25137 \SpecialChar ~
25138 \SpecialChar ~
25139 \SpecialChar ~
25140 \SpecialChar ~
25141 \SpecialChar ~
25142  67\SpecialChar ~
25143 \SpecialChar ~
25144 \SpecialChar ~
25145 \SpecialChar ~
25146 \SpecialChar ~
25147 \SpecialChar ~
25148 \SpecialChar ~
25149 \SpecialChar ~
25150  mov\SpecialChar ~
25151 \SpecialChar ~
25152  a,(_gint + 1)
25153 \newline
25154 0013 33\SpecialChar ~
25155 \SpecialChar ~
25156 \SpecialChar ~
25157 \SpecialChar ~
25158 \SpecialChar ~
25159 \SpecialChar ~
25160 \SpecialChar ~
25161 \SpecialChar ~
25162 \SpecialChar ~
25163 \SpecialChar ~
25164 \SpecialChar ~
25165 \SpecialChar ~
25166 \SpecialChar ~
25167 \SpecialChar ~
25168 \SpecialChar ~
25169 \SpecialChar ~
25170 \SpecialChar ~
25171 \SpecialChar ~
25172  68\SpecialChar ~
25173 \SpecialChar ~
25174 \SpecialChar ~
25175 \SpecialChar ~
25176 \SpecialChar ~
25177 \SpecialChar ~
25178 \SpecialChar ~
25179 \SpecialChar ~
25180  rlc\SpecialChar ~
25181 \SpecialChar ~
25182  a
25183 \newline
25184 0014 92*00\SpecialChar ~
25185 \SpecialChar ~
25186 \SpecialChar ~
25187 \SpecialChar ~
25188 \SpecialChar ~
25189 \SpecialChar ~
25190 \SpecialChar ~
25191 \SpecialChar ~
25192 \SpecialChar ~
25193 \SpecialChar ~
25194 \SpecialChar ~
25195 \SpecialChar ~
25196 \SpecialChar ~
25197 \SpecialChar ~
25198 \SpecialChar ~
25199  69\SpecialChar ~
25200 \SpecialChar ~
25201 \SpecialChar ~
25202 \SpecialChar ~
25203 \SpecialChar ~
25204 \SpecialChar ~
25205 \SpecialChar ~
25206 \SpecialChar ~
25207  mov\SpecialChar ~
25208 \SpecialChar ~
25209  _foo_hob2_1_1,c
25210 \newline
25211 \SpecialChar ~
25212 \SpecialChar ~
25213 \SpecialChar ~
25214 \SpecialChar ~
25215 \SpecialChar ~
25216 \SpecialChar ~
25217 \SpecialChar ~
25218 \SpecialChar ~
25219 \SpecialChar ~
25220 \SpecialChar ~
25221 \SpecialChar ~
25222 \SpecialChar ~
25223 \SpecialChar ~
25224 \SpecialChar ~
25225 \SpecialChar ~
25226 \SpecialChar ~
25227 \SpecialChar ~
25228 \SpecialChar ~
25229 \SpecialChar ~
25230 \SpecialChar ~
25231 \SpecialChar ~
25232 \SpecialChar ~
25233 \SpecialChar ~
25234 \SpecialChar ~
25235 \SpecialChar ~
25236  66 ;\SpecialChar ~
25237  hob.c 9
25238 \newline
25239 0016 E5*01\SpecialChar ~
25240 \SpecialChar ~
25241 \SpecialChar ~
25242 \SpecialChar ~
25243 \SpecialChar ~
25244 \SpecialChar ~
25245 \SpecialChar ~
25246 \SpecialChar ~
25247 \SpecialChar ~
25248 \SpecialChar ~
25249 \SpecialChar ~
25250 \SpecialChar ~
25251 \SpecialChar ~
25252 \SpecialChar ~
25253 \SpecialChar ~
25254  67\SpecialChar ~
25255 \SpecialChar ~
25256 \SpecialChar ~
25257 \SpecialChar ~
25258 \SpecialChar ~
25259 \SpecialChar ~
25260 \SpecialChar ~
25261 \SpecialChar ~
25262  mov\SpecialChar ~
25263 \SpecialChar ~
25264  a,(_gint + 1)
25265 \newline
25266 0018 33\SpecialChar ~
25267 \SpecialChar ~
25268 \SpecialChar ~
25269 \SpecialChar ~
25270 \SpecialChar ~
25271 \SpecialChar ~
25272 \SpecialChar ~
25273 \SpecialChar ~
25274 \SpecialChar ~
25275 \SpecialChar ~
25276 \SpecialChar ~
25277 \SpecialChar ~
25278 \SpecialChar ~
25279 \SpecialChar ~
25280 \SpecialChar ~
25281 \SpecialChar ~
25282 \SpecialChar ~
25283 \SpecialChar ~
25284  68\SpecialChar ~
25285 \SpecialChar ~
25286 \SpecialChar ~
25287 \SpecialChar ~
25288 \SpecialChar ~
25289 \SpecialChar ~
25290 \SpecialChar ~
25291 \SpecialChar ~
25292  rlc\SpecialChar ~
25293 \SpecialChar ~
25294  a
25295 \newline
25296 0019 92*01\SpecialChar ~
25297 \SpecialChar ~
25298 \SpecialChar ~
25299 \SpecialChar ~
25300 \SpecialChar ~
25301 \SpecialChar ~
25302 \SpecialChar ~
25303 \SpecialChar ~
25304 \SpecialChar ~
25305 \SpecialChar ~
25306 \SpecialChar ~
25307 \SpecialChar ~
25308 \SpecialChar ~
25309 \SpecialChar ~
25310 \SpecialChar ~
25311  69\SpecialChar ~
25312 \SpecialChar ~
25313 \SpecialChar ~
25314 \SpecialChar ~
25315 \SpecialChar ~
25316 \SpecialChar ~
25317 \SpecialChar ~
25318 \SpecialChar ~
25319  mov\SpecialChar ~
25320 \SpecialChar ~
25321  _foo_hob3_1_1,c
25322 \newline
25323 \SpecialChar ~
25324 \SpecialChar ~
25325 \SpecialChar ~
25326 \SpecialChar ~
25327 \SpecialChar ~
25328 \SpecialChar ~
25329 \SpecialChar ~
25330 \SpecialChar ~
25331 \SpecialChar ~
25332 \SpecialChar ~
25333 \SpecialChar ~
25334 \SpecialChar ~
25335 \SpecialChar ~
25336 \SpecialChar ~
25337 \SpecialChar ~
25338 \SpecialChar ~
25339 \SpecialChar ~
25340 \SpecialChar ~
25341 \SpecialChar ~
25342 \SpecialChar ~
25343 \SpecialChar ~
25344 \SpecialChar ~
25345 \SpecialChar ~
25346 \SpecialChar ~
25347 \SpecialChar ~
25348  70 ;\SpecialChar ~
25349  hob.c 10
25350 \newline
25351 001B E5*01\SpecialChar ~
25352 \SpecialChar ~
25353 \SpecialChar ~
25354 \SpecialChar ~
25355 \SpecialChar ~
25356 \SpecialChar ~
25357 \SpecialChar ~
25358 \SpecialChar ~
25359 \SpecialChar ~
25360 \SpecialChar ~
25361 \SpecialChar ~
25362 \SpecialChar ~
25363 \SpecialChar ~
25364 \SpecialChar ~
25365 \SpecialChar ~
25366  71\SpecialChar ~
25367 \SpecialChar ~
25368 \SpecialChar ~
25369 \SpecialChar ~
25370 \SpecialChar ~
25371 \SpecialChar ~
25372 \SpecialChar ~
25373 \SpecialChar ~
25374  mov\SpecialChar ~
25375 \SpecialChar ~
25376  a,(_gint + 1)
25377 \newline
25378 001D 03\SpecialChar ~
25379 \SpecialChar ~
25380 \SpecialChar ~
25381 \SpecialChar ~
25382 \SpecialChar ~
25383 \SpecialChar ~
25384 \SpecialChar ~
25385 \SpecialChar ~
25386 \SpecialChar ~
25387 \SpecialChar ~
25388 \SpecialChar ~
25389 \SpecialChar ~
25390 \SpecialChar ~
25391 \SpecialChar ~
25392 \SpecialChar ~
25393 \SpecialChar ~
25394 \SpecialChar ~
25395 \SpecialChar ~
25396  72\SpecialChar ~
25397 \SpecialChar ~
25398 \SpecialChar ~
25399 \SpecialChar ~
25400 \SpecialChar ~
25401 \SpecialChar ~
25402 \SpecialChar ~
25403 \SpecialChar ~
25404  rr\SpecialChar ~
25405 \SpecialChar ~
25406 \SpecialChar ~
25407  a
25408 \newline
25409 001E 54 01\SpecialChar ~
25410 \SpecialChar ~
25411 \SpecialChar ~
25412 \SpecialChar ~
25413 \SpecialChar ~
25414 \SpecialChar ~
25415 \SpecialChar ~
25416 \SpecialChar ~
25417 \SpecialChar ~
25418 \SpecialChar ~
25419 \SpecialChar ~
25420 \SpecialChar ~
25421 \SpecialChar ~
25422 \SpecialChar ~
25423 \SpecialChar ~
25424  73\SpecialChar ~
25425 \SpecialChar ~
25426 \SpecialChar ~
25427 \SpecialChar ~
25428 \SpecialChar ~
25429 \SpecialChar ~
25430 \SpecialChar ~
25431 \SpecialChar ~
25432  anl\SpecialChar ~
25433 \SpecialChar ~
25434  a,#0x01
25435 \newline
25436 0020 F5*03\SpecialChar ~
25437 \SpecialChar ~
25438 \SpecialChar ~
25439 \SpecialChar ~
25440 \SpecialChar ~
25441 \SpecialChar ~
25442 \SpecialChar ~
25443 \SpecialChar ~
25444 \SpecialChar ~
25445 \SpecialChar ~
25446 \SpecialChar ~
25447 \SpecialChar ~
25448 \SpecialChar ~
25449 \SpecialChar ~
25450 \SpecialChar ~
25451  74\SpecialChar ~
25452 \SpecialChar ~
25453 \SpecialChar ~
25454 \SpecialChar ~
25455 \SpecialChar ~
25456 \SpecialChar ~
25457 \SpecialChar ~
25458 \SpecialChar ~
25459  mov\SpecialChar ~
25460 \SpecialChar ~
25461  _foo_aob1_1_1,a
25462 \newline
25463 \SpecialChar ~
25464 \SpecialChar ~
25465 \SpecialChar ~
25466 \SpecialChar ~
25467 \SpecialChar ~
25468 \SpecialChar ~
25469 \SpecialChar ~
25470 \SpecialChar ~
25471 \SpecialChar ~
25472 \SpecialChar ~
25473 \SpecialChar ~
25474 \SpecialChar ~
25475 \SpecialChar ~
25476 \SpecialChar ~
25477 \SpecialChar ~
25478 \SpecialChar ~
25479 \SpecialChar ~
25480 \SpecialChar ~
25481 \SpecialChar ~
25482 \SpecialChar ~
25483 \SpecialChar ~
25484 \SpecialChar ~
25485 \SpecialChar ~
25486 \SpecialChar ~
25487 \SpecialChar ~
25488  75 ;\SpecialChar ~
25489  hob.c 11
25490 \newline
25491 0022 E5*01\SpecialChar ~
25492 \SpecialChar ~
25493 \SpecialChar ~
25494 \SpecialChar ~
25495 \SpecialChar ~
25496 \SpecialChar ~
25497 \SpecialChar ~
25498 \SpecialChar ~
25499 \SpecialChar ~
25500 \SpecialChar ~
25501 \SpecialChar ~
25502 \SpecialChar ~
25503 \SpecialChar ~
25504 \SpecialChar ~
25505 \SpecialChar ~
25506  76\SpecialChar ~
25507 \SpecialChar ~
25508 \SpecialChar ~
25509 \SpecialChar ~
25510 \SpecialChar ~
25511 \SpecialChar ~
25512 \SpecialChar ~
25513 \SpecialChar ~
25514  mov\SpecialChar ~
25515 \SpecialChar ~
25516  a,(_gint + 1)
25517 \newline
25518 0024 13\SpecialChar ~
25519 \SpecialChar ~
25520 \SpecialChar ~
25521 \SpecialChar ~
25522 \SpecialChar ~
25523 \SpecialChar ~
25524 \SpecialChar ~
25525 \SpecialChar ~
25526 \SpecialChar ~
25527 \SpecialChar ~
25528 \SpecialChar ~
25529 \SpecialChar ~
25530 \SpecialChar ~
25531 \SpecialChar ~
25532 \SpecialChar ~
25533 \SpecialChar ~
25534 \SpecialChar ~
25535 \SpecialChar ~
25536  77\SpecialChar ~
25537 \SpecialChar ~
25538 \SpecialChar ~
25539 \SpecialChar ~
25540 \SpecialChar ~
25541 \SpecialChar ~
25542 \SpecialChar ~
25543 \SpecialChar ~
25544  rrc\SpecialChar ~
25545 \SpecialChar ~
25546  a
25547 \newline
25548 0025 92*02\SpecialChar ~
25549 \SpecialChar ~
25550 \SpecialChar ~
25551 \SpecialChar ~
25552 \SpecialChar ~
25553 \SpecialChar ~
25554 \SpecialChar ~
25555 \SpecialChar ~
25556 \SpecialChar ~
25557 \SpecialChar ~
25558 \SpecialChar ~
25559 \SpecialChar ~
25560 \SpecialChar ~
25561 \SpecialChar ~
25562 \SpecialChar ~
25563  78\SpecialChar ~
25564 \SpecialChar ~
25565 \SpecialChar ~
25566 \SpecialChar ~
25567 \SpecialChar ~
25568 \SpecialChar ~
25569 \SpecialChar ~
25570 \SpecialChar ~
25571  mov\SpecialChar ~
25572 \SpecialChar ~
25573  _foo_aob2_1_1,c
25574 \newline
25575 \SpecialChar ~
25576 \SpecialChar ~
25577 \SpecialChar ~
25578 \SpecialChar ~
25579 \SpecialChar ~
25580 \SpecialChar ~
25581 \SpecialChar ~
25582 \SpecialChar ~
25583 \SpecialChar ~
25584 \SpecialChar ~
25585 \SpecialChar ~
25586 \SpecialChar ~
25587 \SpecialChar ~
25588 \SpecialChar ~
25589 \SpecialChar ~
25590 \SpecialChar ~
25591 \SpecialChar ~
25592 \SpecialChar ~
25593 \SpecialChar ~
25594 \SpecialChar ~
25595 \SpecialChar ~
25596 \SpecialChar ~
25597 \SpecialChar ~
25598 \SpecialChar ~
25599 \SpecialChar ~
25600  79 ;\SpecialChar ~
25601  hob.c 12
25602 \newline
25603 0027 E5*01\SpecialChar ~
25604 \SpecialChar ~
25605 \SpecialChar ~
25606 \SpecialChar ~
25607 \SpecialChar ~
25608 \SpecialChar ~
25609 \SpecialChar ~
25610 \SpecialChar ~
25611 \SpecialChar ~
25612 \SpecialChar ~
25613 \SpecialChar ~
25614 \SpecialChar ~
25615 \SpecialChar ~
25616 \SpecialChar ~
25617 \SpecialChar ~
25618  80\SpecialChar ~
25619 \SpecialChar ~
25620 \SpecialChar ~
25621 \SpecialChar ~
25622 \SpecialChar ~
25623 \SpecialChar ~
25624 \SpecialChar ~
25625 \SpecialChar ~
25626  mov\SpecialChar ~
25627 \SpecialChar ~
25628  a,(_gint + 1)
25629 \newline
25630 0029 A2 E3\SpecialChar ~
25631 \SpecialChar ~
25632 \SpecialChar ~
25633 \SpecialChar ~
25634 \SpecialChar ~
25635 \SpecialChar ~
25636 \SpecialChar ~
25637 \SpecialChar ~
25638 \SpecialChar ~
25639 \SpecialChar ~
25640 \SpecialChar ~
25641 \SpecialChar ~
25642 \SpecialChar ~
25643 \SpecialChar ~
25644 \SpecialChar ~
25645  81\SpecialChar ~
25646 \SpecialChar ~
25647 \SpecialChar ~
25648 \SpecialChar ~
25649 \SpecialChar ~
25650 \SpecialChar ~
25651 \SpecialChar ~
25652 \SpecialChar ~
25653  mov\SpecialChar ~
25654 \SpecialChar ~
25655  c,acc[3]
25656 \newline
25657 002B 92*03\SpecialChar ~
25658 \SpecialChar ~
25659 \SpecialChar ~
25660 \SpecialChar ~
25661 \SpecialChar ~
25662 \SpecialChar ~
25663 \SpecialChar ~
25664 \SpecialChar ~
25665 \SpecialChar ~
25666 \SpecialChar ~
25667 \SpecialChar ~
25668 \SpecialChar ~
25669 \SpecialChar ~
25670 \SpecialChar ~
25671 \SpecialChar ~
25672  82\SpecialChar ~
25673 \SpecialChar ~
25674 \SpecialChar ~
25675 \SpecialChar ~
25676 \SpecialChar ~
25677 \SpecialChar ~
25678 \SpecialChar ~
25679 \SpecialChar ~
25680  mov\SpecialChar ~
25681 \SpecialChar ~
25682  _foo_aob3_1_1,c
25683 \layout Standard
25684
25685 Other variations of these cases however will
25686 \emph on
25687 not
25688 \emph default
25689  be recognized.
25690  They are standard C expressions, so I heartily recommend these be the only
25691  way to get the highest order bit, (it is portable).
25692  Of course it will be recognized even if it is embedded in other expressions,
25693  e.g.:
25694 \layout Verse
25695
25696
25697 \family typewriter
25698 xyz = gint + ((gint >> 15) & 1);
25699 \layout Standard
25700
25701 will still be recognized.
25702 \layout Subsection
25703
25704 Higher Order Byte
25705 \begin_inset LatexCommand \index{Higher Order Byte}
25706
25707 \end_inset
25708
25709  / Higher Order Word
25710 \begin_inset LatexCommand \index{Higher Order Word}
25711
25712 \end_inset
25713
25714
25715 \layout Standard
25716
25717 It is also frequently required to obtain a higher order byte or word of
25718  a larger integral type (long, int or short types).
25719  SDCC recognizes the following expressions to yield the higher order byte
25720  or word and generates optimized code for it, e.g.:
25721 \layout Verse
25722
25723
25724 \family typewriter
25725 unsigned int gint;
25726 \newline
25727 unsigned long int glong;
25728 \newline
25729
25730 \newline
25731 foo () {
25732 \newline
25733 \SpecialChar ~
25734 \SpecialChar ~
25735 unsigned char hob1, hob2;
25736 \newline
25737 \SpecialChar ~
25738 \SpecialChar ~
25739 unsigned int how1, how2;
25740 \newline
25741 \SpecialChar ~
25742 \SpecialChar ~
25743 ...
25744
25745 \newline
25746 \SpecialChar ~
25747 \SpecialChar ~
25748 hob1 = (gint >> 8) & 0xFF;
25749 \newline
25750 \SpecialChar ~
25751 \SpecialChar ~
25752 hob2 = glong >> 24;
25753 \newline
25754 \SpecialChar ~
25755 \SpecialChar ~
25756 how1 = (glong >> 16) & 0xFFFF;
25757 \newline
25758 \SpecialChar ~
25759 \SpecialChar ~
25760 how2 = glong >> 8;
25761 \newline
25762 \SpecialChar ~
25763 \SpecialChar ~
25764 ..
25765
25766 \newline
25767 }
25768 \layout Standard
25769
25770 will generate the following code:
25771 \layout Verse
25772
25773
25774 \family typewriter
25775 \SpecialChar ~
25776 \SpecialChar ~
25777 \SpecialChar ~
25778 \SpecialChar ~
25779 \SpecialChar ~
25780 \SpecialChar ~
25781 \SpecialChar ~
25782 \SpecialChar ~
25783 \SpecialChar ~
25784 \SpecialChar ~
25785 \SpecialChar ~
25786 \SpecialChar ~
25787 \SpecialChar ~
25788 \SpecialChar ~
25789 \SpecialChar ~
25790 \SpecialChar ~
25791 \SpecialChar ~
25792 \SpecialChar ~
25793 \SpecialChar ~
25794 \SpecialChar ~
25795 \SpecialChar ~
25796 \SpecialChar ~
25797 \SpecialChar ~
25798 \SpecialChar ~
25799 \SpecialChar ~
25800  91 ;\SpecialChar ~
25801  hob.c 15
25802 \newline
25803 0037 85*01*06\SpecialChar ~
25804 \SpecialChar ~
25805 \SpecialChar ~
25806 \SpecialChar ~
25807 \SpecialChar ~
25808 \SpecialChar ~
25809 \SpecialChar ~
25810 \SpecialChar ~
25811 \SpecialChar ~
25812 \SpecialChar ~
25813 \SpecialChar ~
25814 \SpecialChar ~
25815  92\SpecialChar ~
25816 \SpecialChar ~
25817 \SpecialChar ~
25818 \SpecialChar ~
25819 \SpecialChar ~
25820 \SpecialChar ~
25821 \SpecialChar ~
25822 \SpecialChar ~
25823  mov\SpecialChar ~
25824 \SpecialChar ~
25825  _foo_hob1_1_1,(_gint + 1)
25826 \newline
25827 \SpecialChar ~
25828 \SpecialChar ~
25829 \SpecialChar ~
25830 \SpecialChar ~
25831 \SpecialChar ~
25832 \SpecialChar ~
25833 \SpecialChar ~
25834 \SpecialChar ~
25835 \SpecialChar ~
25836 \SpecialChar ~
25837 \SpecialChar ~
25838 \SpecialChar ~
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  93 ;\SpecialChar ~
25853  hob.c 16
25854 \newline
25855 003A 85*05*07\SpecialChar ~
25856 \SpecialChar ~
25857 \SpecialChar ~
25858 \SpecialChar ~
25859 \SpecialChar ~
25860 \SpecialChar ~
25861 \SpecialChar ~
25862 \SpecialChar ~
25863 \SpecialChar ~
25864 \SpecialChar ~
25865 \SpecialChar ~
25866 \SpecialChar ~
25867  94\SpecialChar ~
25868 \SpecialChar ~
25869 \SpecialChar ~
25870 \SpecialChar ~
25871 \SpecialChar ~
25872 \SpecialChar ~
25873 \SpecialChar ~
25874 \SpecialChar ~
25875  mov\SpecialChar ~
25876 \SpecialChar ~
25877  _foo_hob2_1_1,(_glong + 3)
25878 \newline
25879 \SpecialChar ~
25880 \SpecialChar ~
25881 \SpecialChar ~
25882 \SpecialChar ~
25883 \SpecialChar ~
25884 \SpecialChar ~
25885 \SpecialChar ~
25886 \SpecialChar ~
25887 \SpecialChar ~
25888 \SpecialChar ~
25889 \SpecialChar ~
25890 \SpecialChar ~
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  95 ;\SpecialChar ~
25905  hob.c 17
25906 \newline
25907 003D 85*04*08\SpecialChar ~
25908 \SpecialChar ~
25909 \SpecialChar ~
25910 \SpecialChar ~
25911 \SpecialChar ~
25912 \SpecialChar ~
25913 \SpecialChar ~
25914 \SpecialChar ~
25915 \SpecialChar ~
25916 \SpecialChar ~
25917 \SpecialChar ~
25918 \SpecialChar ~
25919  96\SpecialChar ~
25920 \SpecialChar ~
25921 \SpecialChar ~
25922 \SpecialChar ~
25923 \SpecialChar ~
25924 \SpecialChar ~
25925 \SpecialChar ~
25926 \SpecialChar ~
25927  mov\SpecialChar ~
25928 \SpecialChar ~
25929  _foo_how1_1_1,(_glong + 2)
25930 \newline
25931 0040 85*05*09\SpecialChar ~
25932 \SpecialChar ~
25933 \SpecialChar ~
25934 \SpecialChar ~
25935 \SpecialChar ~
25936 \SpecialChar ~
25937 \SpecialChar ~
25938 \SpecialChar ~
25939 \SpecialChar ~
25940 \SpecialChar ~
25941 \SpecialChar ~
25942 \SpecialChar ~
25943  97\SpecialChar ~
25944 \SpecialChar ~
25945 \SpecialChar ~
25946 \SpecialChar ~
25947 \SpecialChar ~
25948 \SpecialChar ~
25949 \SpecialChar ~
25950 \SpecialChar ~
25951  mov\SpecialChar ~
25952 \SpecialChar ~
25953  (_foo_how1_1_1 + 1),(_glong + 3)
25954 \newline
25955 0043 85*03*0A\SpecialChar ~
25956 \SpecialChar ~
25957 \SpecialChar ~
25958 \SpecialChar ~
25959 \SpecialChar ~
25960 \SpecialChar ~
25961 \SpecialChar ~
25962 \SpecialChar ~
25963 \SpecialChar ~
25964 \SpecialChar ~
25965 \SpecialChar ~
25966 \SpecialChar ~
25967  98\SpecialChar ~
25968 \SpecialChar ~
25969 \SpecialChar ~
25970 \SpecialChar ~
25971 \SpecialChar ~
25972 \SpecialChar ~
25973 \SpecialChar ~
25974 \SpecialChar ~
25975  mov\SpecialChar ~
25976 \SpecialChar ~
25977  _foo_how2_1_1,(_glong + 1)
25978 \newline
25979 0046 85*04*0B\SpecialChar ~
25980 \SpecialChar ~
25981 \SpecialChar ~
25982 \SpecialChar ~
25983 \SpecialChar ~
25984 \SpecialChar ~
25985 \SpecialChar ~
25986 \SpecialChar ~
25987 \SpecialChar ~
25988 \SpecialChar ~
25989 \SpecialChar ~
25990 \SpecialChar ~
25991  99\SpecialChar ~
25992 \SpecialChar ~
25993 \SpecialChar ~
25994 \SpecialChar ~
25995 \SpecialChar ~
25996 \SpecialChar ~
25997 \SpecialChar ~
25998 \SpecialChar ~
25999  mov\SpecialChar ~
26000 \SpecialChar ~
26001  (_foo_how2_1_1 + 1),(_glong + 2)
26002 \layout Standard
26003
26004 Again, variations of these cases may
26005 \emph on
26006 not
26007 \emph default
26008  be recognized.
26009  They are standard C expressions, so I heartily recommend these be the only
26010  way to get the higher order byte/word, (it is portable).
26011  Of course it will be recognized even if it is embedded in other expressions,
26012  e.g.:
26013 \layout Verse
26014
26015
26016 \family typewriter
26017 xyz = gint + ((gint >> 8) & 0xFF);
26018 \layout Standard
26019
26020 will still be recognized.
26021 \layout Subsection
26022
26023 Peephole Optimizer
26024 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
26025
26026 \end_inset
26027
26028
26029 \begin_inset LatexCommand \index{Peephole optimizer}
26030
26031 \end_inset
26032
26033
26034 \layout Standard
26035
26036 The compiler uses a rule based, pattern matching and re-writing mechanism
26037  for peep-hole optimization.
26038  It is inspired by
26039 \emph on
26040 copt
26041 \emph default
26042  a peep-hole optimizer by Christopher W.
26043  Fraser (cwfraser\SpecialChar ~
26044 @\SpecialChar ~
26045 microsoft.com).
26046  A default set of rules are compiled into the compiler, additional rules
26047  may be added with the
26048 \emph on
26049 -
26050 \begin_inset ERT
26051 status Collapsed
26052
26053 \layout Standard
26054
26055 \backslash
26056 /
26057 \end_inset
26058
26059 -peep-file
26060 \begin_inset LatexCommand \index{-\/-peep-file}
26061
26062 \end_inset
26063
26064  <filename>
26065 \emph default
26066  option.
26067  The rule language is best illustrated with examples.
26068 \layout Verse
26069
26070
26071 \family typewriter
26072 replace {
26073 \newline
26074 \SpecialChar ~
26075 \SpecialChar ~
26076 mov %1,a
26077 \newline
26078 \SpecialChar ~
26079 \SpecialChar ~
26080 mov a,%1
26081 \newline
26082 } by {
26083 \newline
26084 \SpecialChar ~
26085 \SpecialChar ~
26086 mov %1,a
26087 \newline
26088 }
26089 \layout Standard
26090
26091 The above rule will change the following assembly
26092 \begin_inset LatexCommand \index{Assembler routines}
26093
26094 \end_inset
26095
26096  sequence:
26097 \layout Verse
26098
26099
26100 \family typewriter
26101 mov r1,a
26102 \newline
26103 mov a,r1
26104 \layout Standard
26105
26106 to
26107 \layout Verse
26108
26109
26110 \family typewriter
26111 mov r1,a
26112 \layout Standard
26113
26114 Note: All occurrences of a
26115 \emph on
26116 %n
26117 \emph default
26118  (pattern variable) must denote the same string.
26119  With the above rule, the assembly sequence:
26120 \layout Verse
26121
26122
26123 \family typewriter
26124 mov r1,a
26125 \newline
26126 mov a,r2
26127 \layout Standard
26128
26129 will remain unmodified.
26130 \newline
26131
26132 \newline
26133 Other special case optimizations may be added by the user (via
26134 \emph on
26135 -
26136 \begin_inset ERT
26137 status Collapsed
26138
26139 \layout Standard
26140
26141 \backslash
26142 /
26143 \end_inset
26144
26145 -peep-file option
26146 \emph default
26147 ).
26148  E.g.
26149  some variants of the 8051 MCU
26150 \begin_inset LatexCommand \index{MCS51 variants}
26151
26152 \end_inset
26153
26154  allow only
26155 \family typewriter
26156 ajmp
26157 \family default
26158  and
26159 \family typewriter
26160 acall
26161 \family default
26162 .
26163  The following two rules will change all
26164 \family typewriter
26165 ljmp
26166 \family default
26167  and
26168 \family typewriter
26169 lcall
26170 \family default
26171  to
26172 \family typewriter
26173 ajmp
26174 \family default
26175  and
26176 \family typewriter
26177 acall
26178 \layout Verse
26179
26180
26181 \family typewriter
26182 replace { lcall %1 } by { acall %1 }
26183 \newline
26184 replace { ljmp %1 } by { ajmp %1 }
26185 \layout Standard
26186
26187 The
26188 \emph on
26189 inline-assembler code
26190 \emph default
26191  is also passed through the peep hole optimizer, thus the peephole optimizer
26192  can also be used as an assembly level macro expander.
26193  The rules themselves are MCU dependent whereas the rule language infra-structur
26194 e is MCU independent.
26195  Peephole optimization rules for other MCU can be easily programmed using
26196  the rule language.
26197 \newline
26198
26199 \newline
26200 The syntax for a rule is as follows:
26201 \layout Verse
26202
26203
26204 \family typewriter
26205 rule := replace [ restart ] '{' <assembly sequence> '
26206 \backslash
26207 n'
26208 \newline
26209 \SpecialChar ~
26210  \SpecialChar ~
26211  \SpecialChar ~
26212  \SpecialChar ~
26213  \SpecialChar ~
26214  \SpecialChar ~
26215  \SpecialChar ~
26216  \SpecialChar ~
26217  \SpecialChar ~
26218  \SpecialChar ~
26219  \SpecialChar ~
26220  \SpecialChar ~
26221  \SpecialChar ~
26222  \SpecialChar ~
26223  '}' by '{' '
26224 \backslash
26225 n'
26226 \newline
26227 \SpecialChar ~
26228  \SpecialChar ~
26229  \SpecialChar ~
26230  \SpecialChar ~
26231  \SpecialChar ~
26232  \SpecialChar ~
26233  \SpecialChar ~
26234  \SpecialChar ~
26235  \SpecialChar ~
26236  \SpecialChar ~
26237  \SpecialChar ~
26238  \SpecialChar ~
26239  \SpecialChar ~
26240  \SpecialChar ~
26241  \SpecialChar ~
26242  \SpecialChar ~
26243  <assembly sequence> '
26244 \backslash
26245 n'
26246 \newline
26247 \SpecialChar ~
26248  \SpecialChar ~
26249  \SpecialChar ~
26250  \SpecialChar ~
26251  \SpecialChar ~
26252  \SpecialChar ~
26253  \SpecialChar ~
26254  \SpecialChar ~
26255  \SpecialChar ~
26256  \SpecialChar ~
26257  \SpecialChar ~
26258  \SpecialChar ~
26259  \SpecialChar ~
26260  \SpecialChar ~
26261  '}' [if <functionName> ] '
26262 \backslash
26263 n'
26264 \layout Standard
26265
26266 <assembly sequence> := assembly instruction (each instruction including
26267  labels must be on a separate line).
26268 \newline
26269
26270 \newline
26271 The optimizer will apply to the rules one by one from the top in the sequence
26272  of their appearance, it will terminate when all rules are exhausted.
26273  If the 'restart' option is specified, then the optimizer will start matching
26274  the rules again from the top, this option for a rule is expensive (performance)
26275 , it is intended to be used in situations where a transformation will trigger
26276  the same rule again.
26277  An example of this (not a good one, it has side effects) is the following
26278  rule:
26279 \layout Verse
26280
26281
26282 \family typewriter
26283 replace restart {
26284 \newline
26285 \SpecialChar ~
26286 \SpecialChar ~
26287 pop %1
26288 \newline
26289 \SpecialChar ~
26290 \SpecialChar ~
26291 push %1 } by {
26292 \newline
26293 \SpecialChar ~
26294 \SpecialChar ~
26295 ; nop
26296 \newline
26297 }
26298 \layout Standard
26299
26300 Note that the replace pattern cannot be a blank, but can be a comment line.
26301  Without the 'restart' option only the innermost 'pop' 'push' pair would
26302  be eliminated, i.e.:
26303 \layout Verse
26304
26305
26306 \family typewriter
26307 pop ar1
26308 \newline
26309 pop ar2
26310 \newline
26311 push ar2
26312 \newline
26313 push ar1
26314 \layout Standard
26315
26316 would result in:
26317 \layout Verse
26318
26319
26320 \family typewriter
26321 pop ar1
26322 \newline
26323 ; nop
26324 \newline
26325 push ar1
26326 \layout Standard
26327
26328
26329 \emph on
26330 with
26331 \emph default
26332  the restart option the rule will be applied again to the resulting code
26333  and then all the pop-push pairs will be eliminated to yield:
26334 \layout Verse
26335
26336
26337 \family typewriter
26338 ; nop
26339 \newline
26340 ; nop
26341 \layout Standard
26342
26343 A conditional function can be attached to a rule.
26344  Attaching rules are somewhat more involved, let me illustrate this with
26345  an example.
26346 \layout Verse
26347
26348
26349 \family typewriter
26350 replace {
26351 \newline
26352 \SpecialChar ~
26353  \SpecialChar ~
26354  \SpecialChar ~
26355 ljmp %5
26356 \newline
26357 %2:
26358 \newline
26359 } by {
26360 \newline
26361 \SpecialChar ~
26362  \SpecialChar ~
26363  \SpecialChar ~
26364 sjmp %5
26365 \newline
26366 %2:
26367 \newline
26368 } if labelInRange
26369 \layout Standard
26370
26371 The optimizer does a look-up of a function name table defined in function
26372
26373 \emph on
26374 callFuncByName
26375 \emph default
26376  in the source file SDCCpeeph.c, with the name
26377 \emph on
26378 labelInRange
26379 \emph default
26380 .
26381  If it finds a corresponding entry the function is called.
26382  Note there can be no parameters specified for these functions, in this
26383  case the use of
26384 \emph on
26385 %5
26386 \emph default
26387  is crucial, since the function
26388 \emph on
26389 labelInRange
26390 \emph default
26391  expects to find the label in that particular variable (the hash table containin
26392 g the variable bindings is passed as a parameter).
26393  If you want to code more such functions, take a close look at the function
26394  labelInRange and the calling mechanism in source file SDCCpeeph.c.
26395  Currently implemented are
26396 \emph on
26397 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
26398  24bitMode, portIsDS390, 24bitModeAndPortDS390
26399 \emph default
26400 and
26401 \emph on
26402  notVolatile
26403 \emph default
26404 .
26405 \layout Standard
26406
26407 I know this whole thing is a little kludgey, but maybe some day we will
26408  have some better means.
26409  If you are looking at this file, you will see the default rules that are
26410  compiled into the compiler, you can add your own rules in the default set
26411  there if you get tired of specifying the -
26412 \begin_inset ERT
26413 status Collapsed
26414
26415 \layout Standard
26416
26417 \backslash
26418 /
26419 \end_inset
26420
26421 -peep-file option.
26422 \layout Section
26423
26424 ANSI-Compliance
26425 \begin_inset LatexCommand \index{ANSI-compliance}
26426
26427 \end_inset
26428
26429
26430 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
26431
26432 \end_inset
26433
26434
26435 \layout Standard
26436
26437 Deviations from the compliance:
26438 \layout Itemize
26439
26440 functions are not reentrant
26441 \begin_inset LatexCommand \index{reentrant}
26442
26443 \end_inset
26444
26445  unless explicitly declared as such or the
26446 \series bold
26447 -
26448 \begin_inset ERT
26449 status Collapsed
26450
26451 \layout Standard
26452
26453 \backslash
26454 /
26455 \end_inset
26456
26457 -stack-auto
26458 \begin_inset LatexCommand \index{-\/-stack-auto}
26459
26460 \end_inset
26461
26462
26463 \series default
26464  command line option is specified.
26465 \layout Itemize
26466
26467 structures and unions cannot be assigned values directly, cannot be passed
26468  as function parameters or assigned to each other and cannot be a return
26469  value from a function, e.g.:
26470 \begin_deeper
26471 \layout Verse
26472
26473
26474 \family typewriter
26475 struct s { ...
26476  };
26477 \newline
26478 struct s s1, s2;
26479 \newline
26480 foo()
26481 \newline
26482 {
26483 \newline
26484 \SpecialChar ~
26485 \SpecialChar ~
26486 \SpecialChar ~
26487 \SpecialChar ~
26488 ...
26489
26490 \newline
26491 \SpecialChar ~
26492 \SpecialChar ~
26493 \SpecialChar ~
26494 \SpecialChar ~
26495 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
26496 \newline
26497 \SpecialChar ~
26498 \SpecialChar ~
26499 \SpecialChar ~
26500 \SpecialChar ~
26501 ...
26502
26503 \newline
26504 }
26505 \newline
26506 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
26507  */
26508 \newline
26509 {
26510 \newline
26511 \SpecialChar ~
26512 \SpecialChar ~
26513 \SpecialChar ~
26514 \SpecialChar ~
26515 struct s rets;
26516 \newline
26517 \SpecialChar ~
26518 \SpecialChar ~
26519 \SpecialChar ~
26520 \SpecialChar ~
26521 ...
26522
26523 \newline
26524 \SpecialChar ~
26525 \SpecialChar ~
26526 \SpecialChar ~
26527 \SpecialChar ~
26528 return rets;/* is invalid in SDCC although allowed in ANSI */
26529 \newline
26530 }
26531 \end_deeper
26532 \layout Itemize
26533
26534 initialization of structure arrays must be fully braced.
26535 \begin_deeper
26536 \layout Verse
26537
26538
26539 \family typewriter
26540 struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
26541 \newline
26542 struct s { char x } a[] = {{1}, {2}}; /* OK */
26543 \end_deeper
26544 \layout Itemize
26545
26546 'long long
26547 \begin_inset LatexCommand \index{long long (not supported)}
26548
26549 \end_inset
26550
26551 ' (64 bit integers
26552 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
26553
26554 \end_inset
26555
26556 ) not supported.
26557 \layout Itemize
26558
26559 'double
26560 \begin_inset LatexCommand \index{double (not supported)}
26561
26562 \end_inset
26563
26564 ' precision floating point
26565 \begin_inset LatexCommand \index{Floating point support}
26566
26567 \end_inset
26568
26569 not supported.
26570 \layout Itemize
26571
26572 Old K&R style
26573 \begin_inset LatexCommand \index{K\&R style}
26574
26575 \end_inset
26576
26577  function declarations are NOT allowed.
26578 \begin_deeper
26579 \layout Verse
26580
26581
26582 \family typewriter
26583 foo(i,j) /* this old style of function declarations */
26584 \newline
26585 int i,j; /* are valid in ANSI but not valid in SDCC */
26586 \newline
26587 {
26588 \newline
26589 \SpecialChar ~
26590 \SpecialChar ~
26591 \SpecialChar ~
26592 \SpecialChar ~
26593 ...
26594
26595 \newline
26596 }
26597 \end_deeper
26598 \layout Itemize
26599
26600 Most enhancements in C99 are not supported, f.e.:
26601 \begin_deeper
26602 \layout Verse
26603
26604
26605 \family typewriter
26606 \series bold
26607 inline
26608 \series default
26609  int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
26610  in C99 */
26611 \newline
26612 for (
26613 \series bold
26614 int
26615 \series default
26616  i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
26617 \end_deeper
26618 \layout Itemize
26619
26620 Certain words that are valid identifiers in the standard may be reserved
26621  words in SDCC unless the
26622 \series bold
26623 -
26624 \begin_inset ERT
26625 status Collapsed
26626
26627 \layout Standard
26628
26629 \backslash
26630 /
26631 \end_inset
26632
26633 -std-c89
26634 \begin_inset LatexCommand \index{-\/-std-c89}
26635
26636 \end_inset
26637
26638  or -
26639 \begin_inset ERT
26640 status Collapsed
26641
26642 \layout Standard
26643
26644 \backslash
26645 /
26646 \end_inset
26647
26648 -std-c99
26649 \begin_inset LatexCommand \index{-\/-std-c99}
26650
26651 \end_inset
26652
26653
26654 \series default
26655  command line options are used.
26656  These may include (depending on the selected processor): 'at', 'banked',
26657  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
26658 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
26659  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
26660  '_naked'.
26661  Compliant equivalents of these keywords are always available in a form
26662  that begin with two underscores
26663 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
26664
26665 \end_inset
26666
26667 , f.e.
26668  '__data' instead of 'data'.
26669 \layout Section
26670
26671 Cyclomatic Complexity
26672 \begin_inset LatexCommand \index{Cyclomatic complexity}
26673
26674 \end_inset
26675
26676
26677 \layout Standard
26678
26679 Cyclomatic complexity of a function is defined as the number of independent
26680  paths the program can take during execution of the function.
26681  This is an important number since it defines the number test cases you
26682  have to generate to validate the function.
26683  The accepted industry standard for complexity number is 10, if the cyclomatic
26684  complexity reported by SDCC exceeds 10 you should think about simplification
26685  of the function logic.
26686  Note that the complexity level is not related to the number of lines of
26687  code in a function.
26688  Large functions can have low complexity, and small functions can have large
26689  complexity levels.
26690
26691 \newline
26692
26693 \newline
26694 SDCC uses the following formula to compute the complexity:
26695 \newline
26696
26697 \layout Standard
26698
26699 complexity = (number of edges in control flow graph) - (number of nodes
26700  in control flow graph) + 2;
26701 \newline
26702
26703 \newline
26704 Having said that the industry standard is 10, you should be aware that in
26705  some cases it be may unavoidable to have a complexity level of less than
26706  10.
26707  For example if you have switch statement with more than 10 case labels,
26708  each case label adds one to the complexity level.
26709  The complexity level is by no means an absolute measure of the algorithmic
26710  complexity of the function, it does however provide a good starting point
26711  for which functions you might look at for further optimization.
26712 \layout Section
26713
26714 Retargetting for other Processors
26715 \layout Standard
26716
26717 The issues for retargetting the compiler are far too numerous to be covered
26718  by this document.
26719  What follows is a brief description of each of the seven phases of the
26720  compiler and its MCU dependency.
26721 \layout Itemize
26722
26723 Parsing the source and building the annotated parse tree.
26724  This phase is largely MCU independent (except for the language extensions).
26725  Syntax & semantic checks are also done in this phase, along with some initial
26726  optimizations like back patching labels and the pattern matching optimizations
26727  like bit-rotation etc.
26728 \layout Itemize
26729
26730 The second phase involves generating an intermediate code which can be easy
26731  manipulated during the later phases.
26732  This phase is entirely MCU independent.
26733  The intermediate code generation assumes the target machine has unlimited
26734  number of registers, and designates them with the name iTemp.
26735  The compiler can be made to dump a human readable form of the code generated
26736  by using the -
26737 \begin_inset ERT
26738 status Collapsed
26739
26740 \layout Standard
26741
26742 \backslash
26743 /
26744 \end_inset
26745
26746 -dumpraw option.
26747 \layout Itemize
26748
26749 This phase does the bulk of the standard optimizations and is also MCU independe
26750 nt.
26751  This phase can be broken down into several sub-phases:
26752 \newline
26753
26754 \newline
26755 Break down intermediate code (iCode) into basic blocks.
26756 \newline
26757 Do control flow & data flow analysis on the basic blocks.
26758 \newline
26759 Do local common subexpression elimination, then global subexpression elimination
26760 \newline
26761 Dead code elimination
26762 \newline
26763 Loop optimizations
26764 \newline
26765 If loop optimizations caused any changes then do 'global subexpression eliminati
26766 on' and 'dead code elimination' again.
26767 \layout Itemize
26768
26769 This phase determines the live-ranges; by live range I mean those iTemp
26770  variables defined by the compiler that still survive after all the optimization
26771 s.
26772  Live range analysis
26773 \begin_inset LatexCommand \index{Live range analysis}
26774
26775 \end_inset
26776
26777  is essential for register allocation, since these computation determines
26778  which of these iTemps will be assigned to registers, and for how long.
26779 \layout Itemize
26780
26781 Phase five is register allocation.
26782  There are two parts to this process.
26783 \newline
26784
26785 \newline
26786 The first part I call 'register packing' (for lack of a better term).
26787  In this case several MCU specific expression folding is done to reduce
26788  register pressure.
26789 \newline
26790
26791 \newline
26792 The second part is more MCU independent and deals with allocating registers
26793  to the remaining live ranges.
26794  A lot of MCU specific code does creep into this phase because of the limited
26795  number of index registers available in the 8051.
26796 \layout Itemize
26797
26798 The Code generation phase is (unhappily), entirely MCU dependent and very
26799  little (if any at all) of this code can be reused for other MCU.
26800  However the scheme for allocating a homogenized assembler operand for each
26801  iCode operand may be reused.
26802 \layout Itemize
26803
26804 As mentioned in the optimization section the peep-hole optimizer is rule
26805  based system, which can reprogrammed for other MCUs.
26806 \layout Chapter
26807
26808 Compiler internals
26809 \begin_inset LatexCommand \index{Compiler internals}
26810
26811 \end_inset
26812
26813
26814 \layout Section
26815
26816 The anatomy of the compiler
26817 \begin_inset LatexCommand \label{sub:The-anatomy-of}
26818
26819 \end_inset
26820
26821
26822 \layout Standard
26823
26824
26825 \shape italic
26826 This is an excerpt from an article published in Circuit Cellar Magazine
26827  in
26828 \series bold
26829 August 2000
26830 \series default
26831 .
26832  It's a little outdated (the compiler is much more efficient now and user/develo
26833 per friendly), but pretty well exposes the guts of it all.
26834 \shape default
26835
26836 \newline
26837
26838 \newline
26839 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
26840  It is fairly easy to retarget for other 8-bit MCU.
26841  Here we take a look at some of the internals of the compiler.
26842
26843 \layout Paragraph*
26844
26845 Parsing
26846 \begin_inset LatexCommand \index{Parsing}
26847
26848 \end_inset
26849
26850
26851 \layout Standard
26852
26853 Parsing the input source file and creating an AST (Annotated Syntax Tree
26854 \begin_inset LatexCommand \index{Annotated syntax tree}
26855
26856 \end_inset
26857
26858 ).
26859  This phase also involves propagating types (annotating each node of the
26860  parse tree with type information) and semantic analysis.
26861  There are some MCU specific parsing rules.
26862  For example the storage classes, the extended storage classes are MCU specific
26863  while there may be a xdata storage class for 8051 there is no such storage
26864  class for z80 or Atmel AVR.
26865  SDCC allows MCU specific storage class extensions, i.e.
26866  xdata will be treated as a storage class specifier when parsing 8051 C
26867  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
26868  C code.
26869 \layout Paragraph*
26870
26871 Generating iCode
26872 \begin_inset LatexCommand \index{iCode}
26873
26874 \end_inset
26875
26876
26877 \layout Standard
26878
26879 Intermediate code generation.
26880  In this phase the AST is broken down into three-operand form (iCode).
26881  These three operand forms are represented as doubly linked lists.
26882  ICode is the term given to the intermediate form generated by the compiler.
26883  ICode example section shows some examples of iCode generated for some simple
26884  C source functions.
26885 \layout Paragraph*
26886
26887 Optimizations
26888 \begin_inset LatexCommand \index{Optimizations}
26889
26890 \end_inset
26891
26892 .
26893 \layout Standard
26894
26895 Bulk of the target independent optimizations is performed in this phase.
26896  The optimizations include constant propagation, common sub-expression eliminati
26897 on, loop invariant code movement, strength reduction of loop induction variables
26898  and dead-code elimination.
26899 \layout Paragraph*
26900
26901 Live range analysis
26902 \begin_inset LatexCommand \index{Live range analysis}
26903
26904 \end_inset
26905
26906
26907 \layout Standard
26908
26909 During intermediate code generation phase, the compiler assumes the target
26910  machine has infinite number of registers and generates a lot of temporary
26911  variables.
26912  The live range computation determines the lifetime of each of these compiler-ge
26913 nerated temporaries.
26914  A picture speaks a thousand words.
26915  ICode example sections show the live range annotations for each of the
26916  operand.
26917  It is important to note here, each iCode is assigned a number in the order
26918  of its execution in the function.
26919  The live ranges are computed in terms of these numbers.
26920  The from number is the number of the iCode which first defines the operand
26921  and the to number signifies the iCode which uses this operand last.
26922 \layout Paragraph*
26923
26924 Register Allocation
26925 \begin_inset LatexCommand \index{Register allocation}
26926
26927 \end_inset
26928
26929
26930 \layout Standard
26931
26932 The register allocation determines the type and number of registers needed
26933  by each operand.
26934  In most MCUs only a few registers can be used for indirect addressing.
26935  In case of 8051 for example the registers R0 & R1 can be used to indirectly
26936  address the internal ram and DPTR to indirectly address the external ram.
26937  The compiler will try to allocate the appropriate register to pointer variables
26938  if it can.
26939  ICode example section shows the operands annotated with the registers assigned
26940  to them.
26941  The compiler will try to keep operands in registers as much as possible;
26942  there are several schemes the compiler uses to do achieve this.
26943  When the compiler runs out of registers the compiler will check to see
26944  if there are any live operands which is not used or defined in the current
26945  basic block being processed, if there are any found then it will push that
26946  operand and use the registers in this block, the operand will then be popped
26947  at the end of the basic block.
26948
26949 \layout Standard
26950
26951 There are other MCU specific considerations in this phase.
26952  Some MCUs have an accumulator; very short-lived operands could be assigned
26953  to the accumulator instead of a general-purpose register.
26954 \layout Paragraph*
26955
26956 Code generation
26957 \layout Standard
26958
26959 Figure II gives a table of iCode operations supported by the compiler.
26960  The code generation involves translating these operations into corresponding
26961  assembly code for the processor.
26962  This sounds overly simple but that is the essence of code generation.
26963  Some of the iCode operations are generated on a MCU specific manner for
26964  example, the z80 port does not use registers to pass parameters so the
26965  SEND and RECV iCode operations will not be generated, and it also does
26966  not support JUMPTABLES.
26967
26968 \newline
26969
26970 \series bold
26971 \shape italic
26972 \color red
26973 <Where is Figure II?>
26974 \layout Comment
26975
26976 In the original article Figure II was announced to be downloadable on
26977 \shape italic
26978 Circuit Cellar
26979 \shape default
26980 's web site.
26981  Unfortunately it never seemed to have shown up there, so: where is Figure
26982  II?
26983 \layout Paragraph*
26984
26985 ICode Example
26986 \begin_inset LatexCommand \index{iCode}
26987
26988 \end_inset
26989
26990
26991 \layout Standard
26992
26993 This section shows some details of iCode.
26994  The example C code does not do anything useful; it is used as an example
26995  to illustrate the intermediate code generated by the compiler.
26996 \layout Verse
26997
26998
26999 \family typewriter
27000 1.\SpecialChar ~
27001 xdata int * p;
27002 \newline
27003 2.\SpecialChar ~
27004 int gint;
27005 \newline
27006 3.\SpecialChar ~
27007 /* This function does nothing useful.
27008  It is used
27009 \newline
27010 4.\SpecialChar ~
27011 \SpecialChar ~
27012 \SpecialChar ~
27013 \SpecialChar ~
27014 for the purpose of explaining iCode */
27015 \newline
27016 5.\SpecialChar ~
27017 short function (data int *x)
27018 \newline
27019 6.\SpecialChar ~
27020 {
27021 \newline
27022 7.\SpecialChar ~
27023 \SpecialChar ~
27024 \SpecialChar ~
27025 short i=10; \SpecialChar ~
27026 \SpecialChar ~
27027 /* dead initialization eliminated */
27028 \newline
27029 8.\SpecialChar ~
27030 \SpecialChar ~
27031 \SpecialChar ~
27032 short sum=10; /* dead initialization eliminated */
27033 \newline
27034 9.\SpecialChar ~
27035 \SpecialChar ~
27036 \SpecialChar ~
27037 short mul;
27038 \newline
27039 10.\SpecialChar ~
27040 \SpecialChar ~
27041 int j ;
27042 \newline
27043 11.\SpecialChar ~
27044 \SpecialChar ~
27045 while (*x) *x++ = *p++;
27046 \newline
27047 12.\SpecialChar ~
27048 \SpecialChar ~
27049 \SpecialChar ~
27050 \SpecialChar ~
27051 sum = 0 ;
27052 \newline
27053 13.\SpecialChar ~
27054 \SpecialChar ~
27055 mul = 0;
27056 \newline
27057 14.\SpecialChar ~
27058 \SpecialChar ~
27059 /* compiler detects i,j to be induction variables */
27060 \newline
27061 15.\SpecialChar ~
27062 \SpecialChar ~
27063 for (i = 0, j = 10 ; i < 10 ; i++, j
27064 \family default
27065 -
27066 \begin_inset ERT
27067 status Collapsed
27068
27069 \layout Standard
27070
27071 \backslash
27072 /
27073 \end_inset
27074
27075 -
27076 \family typewriter
27077 ) {
27078 \newline
27079 16.\SpecialChar ~
27080 \SpecialChar ~
27081 \SpecialChar ~
27082 \SpecialChar ~
27083 sum += i;
27084 \newline
27085 17.\SpecialChar ~
27086 \SpecialChar ~
27087 \SpecialChar ~
27088 \SpecialChar ~
27089 mul += i * 3; \SpecialChar ~
27090 \SpecialChar ~
27091 /* this multiplication remains */
27092 \newline
27093 18.\SpecialChar ~
27094 \SpecialChar ~
27095 \SpecialChar ~
27096 \SpecialChar ~
27097 gint += j * 3;\SpecialChar ~
27098 \SpecialChar ~
27099 /* this multiplication changed to addition */
27100 \newline
27101 19.\SpecialChar ~
27102 \SpecialChar ~
27103 }
27104 \newline
27105 20.\SpecialChar ~
27106 \SpecialChar ~
27107 return sum+mul;
27108 \newline
27109 21.\SpecialChar ~
27110 }
27111 \layout Standard
27112
27113 In addition to the operands each iCode contains information about the filename
27114  and line it corresponds to in the source file.
27115  The first field in the listing should be interpreted as follows:
27116 \newline
27117
27118 \shape italic
27119 \size footnotesize
27120 Filename(linenumber: iCode Execution sequence number : ICode hash table
27121  key : loop depth of the iCode).
27122 \shape default
27123 \size default
27124
27125 \newline
27126 Then follows the human readable form of the ICode operation.
27127  Each operand of this triplet form can be of three basic types a) compiler
27128  generated temporary b) user defined variable c) a constant value.
27129  Note that local variables and parameters are replaced by compiler generated
27130  temporaries.
27131  Live ranges
27132 \begin_inset LatexCommand \index{Live range analysis}
27133
27134 \end_inset
27135
27136  are computed only for temporaries (i.e.
27137  live ranges are not computed for global variables).
27138  Registers
27139 \begin_inset LatexCommand \index{Register allocation}
27140
27141 \end_inset
27142
27143  are allocated for temporaries only.
27144  Operands are formatted in the following manner:
27145 \newline
27146
27147 \shape italic
27148 \size footnotesize
27149 Operand Name [lr live-from : live-to ] { type information } [ registers
27150  allocated ].
27151 \shape default
27152 \size default
27153
27154 \newline
27155 As mentioned earlier the live ranges are computed in terms of the execution
27156  sequence number of the iCodes, for example
27157 \newline
27158 the iTemp0 is live from (i.e.
27159  first defined in iCode with execution sequence number 3, and is last used
27160  in the iCode with sequence number 5).
27161  For induction variables such as iTemp21 the live range computation extends
27162  the lifetime from the start to the end of the loop.
27163 \newline
27164 The register allocator used the live range information to allocate registers,
27165  the same registers may be used for different temporaries if their live
27166  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
27167  iTemp17 since their live ranges do not overlap.
27168  In addition the allocator also takes into consideration the type and usage
27169  of a temporary, for example itemp6 is a pointer to near space and is used
27170  as to fetch data from (i.e.
27171  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
27172  Some short lived temporaries are allocated to special registers which have
27173  meaning to the code generator e.g.
27174  iTemp13 is allocated to a pseudo register CC which tells the back end that
27175  the temporary is used only for a conditional jump the code generation makes
27176  use of this information to optimize a compare and jump ICode.
27177 \newline
27178 There are several loop optimizations
27179 \begin_inset LatexCommand \index{Loop optimization}
27180
27181 \end_inset
27182
27183  performed by the compiler.
27184  It can detect induction variables iTemp21(i) and iTemp23(j).
27185  Also note the compiler does selective strength reduction
27186 \begin_inset LatexCommand \index{Strength reduction}
27187
27188 \end_inset
27189
27190 , i.e.
27191  the multiplication of an induction variable in line 18 (gint = j * 3) is
27192  changed to addition, a new temporary iTemp17 is allocated and assigned
27193  a initial value, a constant 3 is then added for each iteration of the loop.
27194  The compiler does not change the multiplication
27195 \begin_inset LatexCommand \index{Multiplication}
27196
27197 \end_inset
27198
27199  in line 17 however since the processor does support an 8 * 8 bit multiplication.
27200 \newline
27201 Note the dead code elimination
27202 \begin_inset LatexCommand \index{Dead-code elimination}
27203
27204 \end_inset
27205
27206  optimization eliminated the dead assignments in line 7 & 8 to I and sum
27207  respectively.
27208 \newline
27209
27210 \layout Standard
27211
27212
27213 \size footnotesize
27214 Sample.c (5:1:0:0) _entry($9) :
27215 \layout Standard
27216
27217
27218 \size footnotesize
27219 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
27220 \layout Standard
27221
27222
27223 \size footnotesize
27224 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
27225 \layout Standard
27226
27227
27228 \size footnotesize
27229 Sample.c(11:4:53:0) preHeaderLbl0($11) :
27230 \layout Standard
27231
27232
27233 \size footnotesize
27234 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
27235  * int}[r2]
27236 \layout Standard
27237
27238
27239 \size footnotesize
27240 Sample.c(11:6:5:1) _whilecontinue_0($1) :
27241 \layout Standard
27242
27243
27244 \size footnotesize
27245 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
27246  int}[r0]]
27247 \layout Standard
27248
27249
27250 \size footnotesize
27251 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27252 \layout Standard
27253
27254
27255 \size footnotesize
27256 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
27257  * int}
27258 \layout Standard
27259
27260
27261 \size footnotesize
27262 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
27263  {short}
27264 \layout Standard
27265
27266
27267 \size footnotesize
27268 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
27269  * int}[DPTR]]
27270 \layout Standard
27271
27272
27273 \size footnotesize
27274 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
27275 }[r2 r3]
27276 \layout Standard
27277
27278
27279 \size footnotesize
27280 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
27281  * int}[r0] + 0x2 {short}
27282 \layout Standard
27283
27284
27285 \size footnotesize
27286 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
27287 \layout Standard
27288
27289
27290 \size footnotesize
27291 Sample.c(11:17:21:0)_whilebreak_0($3) :
27292 \layout Standard
27293
27294
27295 \size footnotesize
27296 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27297 \layout Standard
27298
27299
27300 \size footnotesize
27301 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27302 \layout Standard
27303
27304
27305 \size footnotesize
27306 Sample.c(15:20:54:0)preHeaderLbl1($13) :
27307 \layout Standard
27308
27309
27310 \size footnotesize
27311 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27312 \layout Standard
27313
27314
27315 \size footnotesize
27316 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27317 \layout Standard
27318
27319
27320 \size footnotesize
27321 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27322 \layout Standard
27323
27324
27325 \size footnotesize
27326 Sample.c(15:24:26:1)_forcond_0($4) :
27327 \layout Standard
27328
27329
27330 \size footnotesize
27331 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
27332  < 0xa {short}
27333 \layout Standard
27334
27335
27336 \size footnotesize
27337 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27338 \layout Standard
27339
27340
27341 \size footnotesize
27342 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
27343  + ITemp21 [lr21:38]{short}[r4]
27344 \layout Standard
27345
27346
27347 \size footnotesize
27348 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
27349  * 0x3 {short}
27350 \layout Standard
27351
27352
27353 \size footnotesize
27354 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
27355  + iTemp15 [lr29:30]{short}[r1]
27356 \layout Standard
27357
27358
27359 \size footnotesize
27360 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
27361  r0]- 0x3 {short}
27362 \layout Standard
27363
27364
27365 \size footnotesize
27366 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
27367 int}[r7 r0]
27368 \layout Standard
27369
27370
27371 \size footnotesize
27372 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
27373  + 0x1 {short}
27374 \layout Standard
27375
27376
27377 \size footnotesize
27378 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
27379  r6]- 0x1 {short}
27380 \layout Standard
27381
27382
27383 \size footnotesize
27384 Sample.c(19:38:47:1) goto _forcond_0($4)
27385 \layout Standard
27386
27387
27388 \size footnotesize
27389 Sample.c(19:39:48:0)_forbreak_0($7) :
27390 \layout Standard
27391
27392
27393 \size footnotesize
27394 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
27395  + ITemp11 [lr19:40]{short}[r3]
27396 \layout Standard
27397
27398
27399 \size footnotesize
27400 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
27401 \layout Standard
27402
27403
27404 \size footnotesize
27405 Sample.c(20:42:51:0)_return($8) :
27406 \layout Standard
27407
27408
27409 \size footnotesize
27410 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
27411 \size default
27412
27413 \newline
27414
27415 \newline
27416 Finally the code generated for this function:
27417 \newline
27418
27419 \layout Standard
27420
27421
27422 \size footnotesize
27423 .area DSEG (DATA)
27424 \layout Standard
27425
27426
27427 \size footnotesize
27428 _p::
27429 \layout Standard
27430
27431
27432 \size footnotesize
27433 \SpecialChar ~
27434 \SpecialChar ~
27435 .ds 2
27436 \layout Standard
27437
27438
27439 \size footnotesize
27440 _gint::
27441 \layout Standard
27442
27443
27444 \size footnotesize
27445 \SpecialChar ~
27446 \SpecialChar ~
27447 .ds 2
27448 \layout Standard
27449
27450
27451 \size footnotesize
27452 ; sample.c 5
27453 \layout Standard
27454
27455
27456 \size footnotesize
27457 ; ----------------------------------------------
27458 \layout Standard
27459
27460
27461 \size footnotesize
27462 ; function function
27463 \layout Standard
27464
27465
27466 \size footnotesize
27467 ; ----------------------------------------------
27468 \layout Standard
27469
27470
27471 \size footnotesize
27472 _function:
27473 \layout Standard
27474
27475
27476 \size footnotesize
27477 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
27478 \layout Standard
27479
27480
27481 \size footnotesize
27482 \SpecialChar ~
27483 \SpecialChar ~
27484 mov r2,dpl
27485 \layout Standard
27486
27487
27488 \size footnotesize
27489 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
27490 \layout Standard
27491
27492
27493 \size footnotesize
27494 \SpecialChar ~
27495 \SpecialChar ~
27496 mov ar0,r2
27497 \layout Standard
27498
27499
27500 \size footnotesize
27501 ;_whilecontinue_0($1) :
27502 \layout Standard
27503
27504
27505 \size footnotesize
27506 00101$:
27507 \layout Standard
27508
27509
27510 \size footnotesize
27511 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
27512 \layout Standard
27513
27514
27515 \size footnotesize
27516 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27517 \layout Standard
27518
27519
27520 \size footnotesize
27521 \SpecialChar ~
27522 \SpecialChar ~
27523 mov ar2,@r0
27524 \layout Standard
27525
27526
27527 \size footnotesize
27528 \SpecialChar ~
27529 \SpecialChar ~
27530 inc r0
27531 \layout Standard
27532
27533
27534 \size footnotesize
27535 \SpecialChar ~
27536 \SpecialChar ~
27537 mov ar3,@r0
27538 \layout Standard
27539
27540
27541 \size footnotesize
27542 \SpecialChar ~
27543 \SpecialChar ~
27544 dec r0
27545 \layout Standard
27546
27547
27548 \size footnotesize
27549 \SpecialChar ~
27550 \SpecialChar ~
27551 mov a,r2
27552 \layout Standard
27553
27554
27555 \size footnotesize
27556 \SpecialChar ~
27557 \SpecialChar ~
27558 orl a,r3
27559 \layout Standard
27560
27561
27562 \size footnotesize
27563 \SpecialChar ~
27564 \SpecialChar ~
27565 jz 00103$
27566 \layout Standard
27567
27568
27569 \size footnotesize
27570 00114$:
27571 \layout Standard
27572
27573
27574 \size footnotesize
27575 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
27576 \layout Standard
27577
27578
27579 \size footnotesize
27580 \SpecialChar ~
27581 \SpecialChar ~
27582 mov dpl,_p
27583 \layout Standard
27584
27585
27586 \size footnotesize
27587 \SpecialChar ~
27588 \SpecialChar ~
27589 mov dph,(_p + 1)
27590 \layout Standard
27591
27592
27593 \size footnotesize
27594 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
27595 \layout Standard
27596
27597
27598 \size footnotesize
27599 \SpecialChar ~
27600 \SpecialChar ~
27601 mov a,#0x02
27602 \layout Standard
27603
27604
27605 \size footnotesize
27606 \SpecialChar ~
27607 \SpecialChar ~
27608 add a,_p
27609 \layout Standard
27610
27611
27612 \size footnotesize
27613 \SpecialChar ~
27614 \SpecialChar ~
27615 mov _p,a
27616 \layout Standard
27617
27618
27619 \size footnotesize
27620 \SpecialChar ~
27621 \SpecialChar ~
27622 clr a
27623 \layout Standard
27624
27625
27626 \size footnotesize
27627 \SpecialChar ~
27628 \SpecialChar ~
27629 addc a,(_p + 1)
27630 \layout Standard
27631
27632
27633 \size footnotesize
27634 \SpecialChar ~
27635 \SpecialChar ~
27636 mov (_p + 1),a
27637 \layout Standard
27638
27639
27640 \size footnotesize
27641 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
27642 \layout Standard
27643
27644
27645 \size footnotesize
27646 \SpecialChar ~
27647 \SpecialChar ~
27648 movx a,@dptr
27649 \layout Standard
27650
27651
27652 \size footnotesize
27653 \SpecialChar ~
27654 \SpecialChar ~
27655 mov r2,a
27656 \layout Standard
27657
27658
27659 \size footnotesize
27660 \SpecialChar ~
27661 \SpecialChar ~
27662 inc dptr
27663 \layout Standard
27664
27665
27666 \size footnotesize
27667 \SpecialChar ~
27668 \SpecialChar ~
27669 movx a,@dptr
27670 \layout Standard
27671
27672
27673 \size footnotesize
27674 \SpecialChar ~
27675 \SpecialChar ~
27676 mov r3,a
27677 \layout Standard
27678
27679
27680 \size footnotesize
27681 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
27682 \layout Standard
27683
27684
27685 \size footnotesize
27686 \SpecialChar ~
27687 \SpecialChar ~
27688 mov @r0,ar2
27689 \layout Standard
27690
27691
27692 \size footnotesize
27693 \SpecialChar ~
27694 \SpecialChar ~
27695 inc r0
27696 \layout Standard
27697
27698
27699 \size footnotesize
27700 \SpecialChar ~
27701 \SpecialChar ~
27702 mov @r0,ar3
27703 \layout Standard
27704
27705
27706 \size footnotesize
27707 ; iTemp6 [lr5:16]{_near * int}[r0] =
27708 \layout Standard
27709
27710
27711 \size footnotesize
27712 ; iTemp6 [lr5:16]{_near * int}[r0] +
27713 \layout Standard
27714
27715
27716 \size footnotesize
27717 ; 0x2 {short}
27718 \layout Standard
27719
27720
27721 \size footnotesize
27722 \SpecialChar ~
27723 \SpecialChar ~
27724 inc r0
27725 \layout Standard
27726
27727
27728 \size footnotesize
27729 ; goto _whilecontinue_0($1)
27730 \layout Standard
27731
27732
27733 \size footnotesize
27734 \SpecialChar ~
27735 \SpecialChar ~
27736 sjmp 00101$
27737 \layout Standard
27738
27739
27740 \size footnotesize
27741 ; _whilebreak_0($3) :
27742 \layout Standard
27743
27744
27745 \size footnotesize
27746 00103$:
27747 \layout Standard
27748
27749
27750 \size footnotesize
27751 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27752 \layout Standard
27753
27754
27755 \size footnotesize
27756 \SpecialChar ~
27757 \SpecialChar ~
27758 mov r2,#0x00
27759 \layout Standard
27760
27761
27762 \size footnotesize
27763 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27764 \layout Standard
27765
27766
27767 \size footnotesize
27768 \SpecialChar ~
27769 \SpecialChar ~
27770 mov r3,#0x00
27771 \layout Standard
27772
27773
27774 \size footnotesize
27775 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27776 \layout Standard
27777
27778
27779 \size footnotesize
27780 \SpecialChar ~
27781 \SpecialChar ~
27782 mov r4,#0x00
27783 \layout Standard
27784
27785
27786 \size footnotesize
27787 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27788 \layout Standard
27789
27790
27791 \size footnotesize
27792 \SpecialChar ~
27793 \SpecialChar ~
27794 mov r5,#0x0A
27795 \layout Standard
27796
27797
27798 \size footnotesize
27799 \SpecialChar ~
27800 \SpecialChar ~
27801 mov r6,#0x00
27802 \layout Standard
27803
27804
27805 \size footnotesize
27806 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27807 \layout Standard
27808
27809
27810 \size footnotesize
27811 \SpecialChar ~
27812 \SpecialChar ~
27813 mov r7,#0x1E
27814 \layout Standard
27815
27816
27817 \size footnotesize
27818 \SpecialChar ~
27819 \SpecialChar ~
27820 mov r0,#0x00
27821 \layout Standard
27822
27823
27824 \size footnotesize
27825 ; _forcond_0($4) :
27826 \layout Standard
27827
27828
27829 \size footnotesize
27830 00104$:
27831 \layout Standard
27832
27833
27834 \size footnotesize
27835 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
27836 \layout Standard
27837
27838
27839 \size footnotesize
27840 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27841 \layout Standard
27842
27843
27844 \size footnotesize
27845 \SpecialChar ~
27846 \SpecialChar ~
27847 clr c
27848 \layout Standard
27849
27850
27851 \size footnotesize
27852 \SpecialChar ~
27853 \SpecialChar ~
27854 mov a,r4
27855 \layout Standard
27856
27857
27858 \size footnotesize
27859 \SpecialChar ~
27860 \SpecialChar ~
27861 xrl a,#0x80
27862 \layout Standard
27863
27864
27865 \size footnotesize
27866 \SpecialChar ~
27867 \SpecialChar ~
27868 subb a,#0x8a
27869 \layout Standard
27870
27871
27872 \size footnotesize
27873 \SpecialChar ~
27874 \SpecialChar ~
27875 jnc 00107$
27876 \layout Standard
27877
27878
27879 \size footnotesize
27880 00115$:
27881 \layout Standard
27882
27883
27884 \size footnotesize
27885 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
27886 \layout Standard
27887
27888
27889 \size footnotesize
27890 ; iTemp21 [lr21:38]{short}[r4]
27891 \layout Standard
27892
27893
27894 \size footnotesize
27895 \SpecialChar ~
27896 \SpecialChar ~
27897 mov a,r4
27898 \layout Standard
27899
27900
27901 \size footnotesize
27902 \SpecialChar ~
27903 \SpecialChar ~
27904 add a,r2
27905 \layout Standard
27906
27907
27908 \size footnotesize
27909 \SpecialChar ~
27910 \SpecialChar ~
27911 mov r2,a
27912 \layout Standard
27913
27914
27915 \size footnotesize
27916 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
27917 \layout Standard
27918
27919
27920 \size footnotesize
27921 \SpecialChar ~
27922 \SpecialChar ~
27923 mov b,#0x03
27924 \layout Standard
27925
27926
27927 \size footnotesize
27928 \SpecialChar ~
27929 \SpecialChar ~
27930 mov a,r4
27931 \layout Standard
27932
27933
27934 \size footnotesize
27935 \SpecialChar ~
27936 \SpecialChar ~
27937 mul ab
27938 \layout Standard
27939
27940
27941 \size footnotesize
27942 \SpecialChar ~
27943 \SpecialChar ~
27944 mov r1,a
27945 \layout Standard
27946
27947
27948 \size footnotesize
27949 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
27950 \layout Standard
27951
27952
27953 \size footnotesize
27954 ; iTemp15 [lr29:30]{short}[r1]
27955 \layout Standard
27956
27957
27958 \size footnotesize
27959 \SpecialChar ~
27960 \SpecialChar ~
27961 add a,r3
27962 \layout Standard
27963
27964
27965 \size footnotesize
27966 \SpecialChar ~
27967 \SpecialChar ~
27968 mov r3,a
27969 \layout Standard
27970
27971
27972 \size footnotesize
27973 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
27974 \layout Standard
27975
27976
27977 \size footnotesize
27978 \SpecialChar ~
27979 \SpecialChar ~
27980 mov a,r7
27981 \layout Standard
27982
27983
27984 \size footnotesize
27985 \SpecialChar ~
27986 \SpecialChar ~
27987 add a,#0xfd
27988 \layout Standard
27989
27990
27991 \size footnotesize
27992 \SpecialChar ~
27993 \SpecialChar ~
27994 mov r7,a
27995 \layout Standard
27996
27997
27998 \size footnotesize
27999 \SpecialChar ~
28000 \SpecialChar ~
28001 mov a,r0
28002 \layout Standard
28003
28004
28005 \size footnotesize
28006 \SpecialChar ~
28007 \SpecialChar ~
28008 addc a,#0xff
28009 \layout Standard
28010
28011
28012 \size footnotesize
28013 \SpecialChar ~
28014 \SpecialChar ~
28015 mov r0,a
28016 \layout Standard
28017
28018
28019 \size footnotesize
28020 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
28021 \layout Standard
28022
28023
28024 \size footnotesize
28025 \SpecialChar ~
28026 \SpecialChar ~
28027 mov a,r7
28028 \layout Standard
28029
28030
28031 \size footnotesize
28032 \SpecialChar ~
28033 \SpecialChar ~
28034 add a,_gint
28035 \layout Standard
28036
28037
28038 \size footnotesize
28039 \SpecialChar ~
28040 \SpecialChar ~
28041 mov _gint,a
28042 \layout Standard
28043
28044
28045 \size footnotesize
28046 \SpecialChar ~
28047 \SpecialChar ~
28048 mov a,r0
28049 \layout Standard
28050
28051
28052 \size footnotesize
28053 \SpecialChar ~
28054 \SpecialChar ~
28055 addc a,(_gint + 1)
28056 \layout Standard
28057
28058
28059 \size footnotesize
28060 \SpecialChar ~
28061 \SpecialChar ~
28062 mov (_gint + 1),a
28063 \layout Standard
28064
28065
28066 \size footnotesize
28067 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
28068 \layout Standard
28069
28070
28071 \size footnotesize
28072 \SpecialChar ~
28073 \SpecialChar ~
28074 inc r4
28075 \layout Standard
28076
28077
28078 \size footnotesize
28079 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
28080 \layout Standard
28081
28082
28083 \size footnotesize
28084 \SpecialChar ~
28085 \SpecialChar ~
28086 dec r5
28087 \layout Standard
28088
28089
28090 \size footnotesize
28091 \SpecialChar ~
28092 \SpecialChar ~
28093 cjne r5,#0xff,00104$
28094 \layout Standard
28095
28096
28097 \size footnotesize
28098 \SpecialChar ~
28099 \SpecialChar ~
28100 dec r6
28101 \layout Standard
28102
28103
28104 \size footnotesize
28105 ; goto _forcond_0($4)
28106 \layout Standard
28107
28108
28109 \size footnotesize
28110 \SpecialChar ~
28111 \SpecialChar ~
28112 sjmp 00104$
28113 \layout Standard
28114
28115
28116 \size footnotesize
28117 ; _forbreak_0($7) :
28118 \layout Standard
28119
28120
28121 \size footnotesize
28122 00107$:
28123 \layout Standard
28124
28125
28126 \size footnotesize
28127 ; ret iTemp24 [lr40:41]{short}
28128 \layout Standard
28129
28130
28131 \size footnotesize
28132 \SpecialChar ~
28133 \SpecialChar ~
28134 mov a,r3
28135 \layout Standard
28136
28137
28138 \size footnotesize
28139 \SpecialChar ~
28140 \SpecialChar ~
28141 add a,r2
28142 \layout Standard
28143
28144
28145 \size footnotesize
28146 \SpecialChar ~
28147 \SpecialChar ~
28148 mov dpl,a
28149 \layout Standard
28150
28151
28152 \size footnotesize
28153 ; _return($8) :
28154 \layout Standard
28155
28156
28157 \size footnotesize
28158 00108$:
28159 \layout Standard
28160
28161
28162 \size footnotesize
28163 \SpecialChar ~
28164 \SpecialChar ~
28165 ret
28166 \newline
28167
28168 \layout Section
28169
28170 A few words about basic block successors, predecessors and dominators
28171 \layout Standard
28172
28173 Successors are basic blocks
28174 \begin_inset LatexCommand \index{Basic blocks}
28175
28176 \end_inset
28177
28178  that might execute after this basic block.
28179 \newline
28180 Predecessors are basic blocks that might execute before reaching this basic
28181  block.
28182 \newline
28183 Dominators are basic blocks that WILL execute before reaching this basic
28184  block.
28185 \newline
28186
28187 \layout Standard
28188
28189 [basic block 1]
28190 \layout Standard
28191
28192 if (something)
28193 \layout Standard
28194
28195 \SpecialChar ~
28196 \SpecialChar ~
28197 \SpecialChar ~
28198 \SpecialChar ~
28199 [basic block 2]
28200 \layout Standard
28201
28202 else
28203 \layout Standard
28204
28205 \SpecialChar ~
28206 \SpecialChar ~
28207 \SpecialChar ~
28208 \SpecialChar ~
28209 [basic block 3]
28210 \layout Standard
28211
28212 [basic block 4]
28213 \newline
28214
28215 \layout Standard
28216
28217 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
28218 \layout Standard
28219
28220 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
28221 \layout Standard
28222
28223 c) domVect of [BB4] = BB1 ...
28224  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
28225  was executed.
28226 \layout Chapter
28227
28228 Acknowledgments
28229 \layout Standard
28230
28231
28232 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
28233
28234 \end_inset
28235
28236
28237 \newline
28238
28239 \newline
28240
28241 \emph on
28242 Thanks to all the other volunteer developers who have helped with coding,
28243  testing, web-page creation, distribution sets, etc.
28244  You know who you are :-)
28245 \emph default
28246
28247 \newline
28248
28249 \layout Standard
28250
28251 This document was initially written by Sandeep Dutta
28252 \layout Standard
28253
28254 All product names mentioned herein may be trademarks
28255 \begin_inset LatexCommand \index{Trademarks}
28256
28257 \end_inset
28258
28259  of their respective companies.
28260
28261 \layout Section*
28262
28263 Alphabetical index
28264 \layout Standard
28265
28266 To avoid confusion, the installation and building options for SDCC itself
28267  (chapter 2) are not part of the index.
28268 \layout Standard
28269
28270
28271 \begin_inset LatexCommand \printindex{}
28272
28273 \end_inset
28274
28275
28276 \the_end