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.3
  86 \size footnotesize
  87
  88 \newline
  89 $Date$
  90 \newline
  91 $Revision$
  92 \layout Comment
  93
  94 The above strings enclosed in $ are automatically updated by cvs
  95 \layout Standard
  96
  97
  98 \begin_inset LatexCommand \tableofcontents{}
  99
 100 \end_inset
 101
 102
 103 \layout Chapter
 104
 105 Introduction
 106 \layout Section
 107
 108 About SDCC
 109 \layout Standard
 110
 111
 112 \series bold
 113 SDCC
 114 \series default
 115  (
 116 \emph on
 117 S
 118 \emph default
 119 mall
 120 \emph on
 121 D
 122 \emph default
 123 evice
 124 \emph on
 125 C
 126 \emph default
 127
 128 \emph on
 129 C
 130 \emph default
 131 ompiler) is 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
 249 \newline
 250
 251 \newline
 252 The latest version can be downloaded from
 253 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 254
 255 \end_inset
 256
 257 .
 258
 259 \series bold
 260
 261 \series default
 262 \emph on
 263 Please note: the compiler will probably always be some steps ahead of this
 264  documentation
 265 \series bold
 266 \emph default
 267
 268 \begin_inset LatexCommand \index{Status of documentation}
 269
 270 \end_inset
 271
 272
 273 \begin_inset Foot
 274 collapsed false
 275
 276 \layout Standard
 277
 278 Obviously this has pros and cons
 279 \end_inset
 280
 281 .
 282 \layout Section
 283
 284 Open Source
 285 \layout Standard
 286
 287 All packages used in this compiler system are
 288 \emph on
 289 open source
 290 \emph default
 291  and
 292 \emph on
 293 freeware
 294 \emph default
 295 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 296  etc) is distributed with the package.
 297  This documentation is maintained using a freeware word processor (LyX).
 298 \newline
 299 This program is free software; you can redistribute it and/or modify it
 300  under the terms of the GNU General Public License
 301 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 302
 303 \end_inset
 304
 305  as published by the Free Software Foundation; either version 2, or (at
 306  your option) any later version.
 307  This program is distributed in the hope that it will be useful, but WITHOUT
 308  ANY WARRANTY; without even the implied warranty
 309 \begin_inset LatexCommand \index{warranty}
 310
 311 \end_inset
 312
 313  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 314  See the GNU General Public License for more details.
 315  You should have received a copy of the GNU General Public License along
 316  with this program; if not, write to the Free Software Foundation, 59 Temple
 317  Place - Suite 330, Boston, MA 02111-1307, USA.
 318  In other words, you are welcome to use, share and improve this program.
 319  You are forbidden to forbid anyone else to use, share and improve what
 320  you give them.
 321  Help stamp out software-hoarding!
 322 \layout Section
 323
 324 Typographic conventions
 325 \begin_inset LatexCommand \index{Typographic conventions}
 326
 327 \end_inset
 328
 329
 330 \layout Standard
 331
 332 Throughout this manual, we will use the following convention.
 333  Commands you have to type in are printed in
 334 \family sans
 335 \series bold
 336 "sans serif"
 337 \series default
 338 .
 339
 340 \family default
 341  Code samples are printed in
 342 \family typewriter
 343 typewriter font.
 344
 345 \family default
 346  Interesting items and new terms are printed in
 347 \emph on
 348 italic.
 349 \layout Section
 350
 351 Compatibility with previous versions
 352 \begin_inset LatexCommand \index{Compatibility with previous versions}
 353
 354 \end_inset
 355
 356
 357 \layout Standard
 358
 359 This version has numerous bug fixes compared with the previous version.
 360  But we also introduced some incompatibilities with older versions.
 361  Not just for the fun of it, but to make the compiler more stable, efficient
 362  and ANSI compliant
 363 \begin_inset LatexCommand \index{ANSI-compliance}
 364
 365 \end_inset
 366
 367  (see section
 368 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 369
 370 \end_inset
 371
 372  for ANSI-Compliance).
 373
 374 \newline
 375
 376 \layout Itemize
 377
 378 short is now equivalent to int (16 bits), it used to be equivalent to char
 379  (8 bits) which is not ANSI compliant.
 380 \layout Itemize
 381
 382 the default directory for gcc-builds where include, library and documentation
 383  files are stored is now in /usr/local/share.
 384 \layout Itemize
 385
 386 char type parameters to vararg functions are casted to int unless explicitly
 387  casted, e.g.:
 388 \newline
 389
 390 \family typewriter
 391 \SpecialChar ~
 392 \SpecialChar ~
 393 char a=3;
 394 \newline
 395 \SpecialChar ~
 396 \SpecialChar ~
 397 printf ("%d %c
 398 \backslash
 399 n", a, (char)a);
 400 \family default
 401
 402 \newline
 403  will push a as an int and as a char resp.
 404 \layout Itemize
 405
 406 option -
 407 \begin_inset ERT
 408 status Collapsed
 409
 410 \layout Standard
 411
 412 \backslash
 413 /
 414 \end_inset
 415
 416 -regextend has been removed.
 417 \layout Itemize
 418
 419 option -
 420 \begin_inset ERT
 421 status Collapsed
 422
 423 \layout Standard
 424
 425 \backslash
 426 /
 427 \end_inset
 428
 429 -noregparms has been removed.
 430 \layout Itemize
 431
 432 option -
 433 \begin_inset ERT
 434 status Collapsed
 435
 436 \layout Standard
 437
 438 \backslash
 439 /
 440 \end_inset
 441
 442 -stack-after-data has been removed.
 443 \layout Itemize
 444
 445 bit
 446 \begin_inset LatexCommand \index{bit}
 447
 448 \end_inset
 449
 450  and sbit
 451 \begin_inset LatexCommand \index{sbit}
 452
 453 \end_inset
 454
 455
 456 \begin_inset LatexCommand \index{\_\_sbit}
 457
 458 \end_inset
 459
 460  types now consistently behave like the C99 _Bool type with respect to type
 461  conversion
 462 \begin_inset LatexCommand \index{type conversion}
 463
 464 \end_inset
 465
 466
 467 \begin_inset LatexCommand \index{type promotion}
 468
 469 \end_inset
 470
 471 .
 472  The most common incompatibility resulting from this change is related to
 473  bit toggling
 474 \begin_inset LatexCommand \index{Bit toggling}
 475
 476 \end_inset
 477
 478  idioms, e.g.:
 479 \newline
 480
 481 \family typewriter
 482 \SpecialChar ~
 483 \SpecialChar ~
 484 bit b;
 485 \newline
 486 \SpecialChar ~
 487 \SpecialChar ~
 488 b = ~b; /* equivalent to b=1 instead of toggling b */
 489 \newline
 490 \SpecialChar ~
 491 \SpecialChar ~
 492 b = !b; /* toggles b */
 493 \newline
 494
 495 \family default
 496 In previous versions, both forms would have toggled the bit.
 497 \layout Standard
 498
 499
 500 \emph on
 501 <pending: more incompatibilities?>
 502 \layout Section
 503
 504 System Requirements
 505 \layout Standard
 506
 507 What do you need before you start installation of SDCC? A computer, and
 508  a desire to compute.
 509  The preferred method of installation is to compile SDCC from source using
 510  GNU gcc and make.
 511  For Windows some pre-compiled binary distributions are available for your
 512  convenience.
 513  You should have some experience with command line tools and compiler use.
 514 \layout Section
 515
 516 Other Resources
 517 \layout Standard
 518
 519 The SDCC home page at
 520 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 521
 522 \end_inset
 523
 524  is a great place to find distribution sets.
 525  You can also find links to the user mailing lists that offer help or discuss
 526  SDCC with other SDCC users.
 527  Web links to other SDCC related sites can also be found here.
 528  This document can be found in the DOC directory of the source package as
 529  a text or HTML file.
 530  A pdf version of this document is available at
 531 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 532
 533 \end_inset
 534
 535 .
 536  Some of the other tools (simulator and assembler) included with SDCC contain
 537  their own documentation and can be found in the source distribution.
 538  If you want the latest unreleased software, the complete source package
 539  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 540 \layout Section
 541
 542 Wishes for the future
 543 \layout Standard
 544
 545 There are (and always will be) some things that could be done.
 546  Here are some I can think of:
 547 \newline
 548
 549 \layout Standard
 550
 551
 552 \family typewriter
 553 char KernelFunction3(char p) at 0x340;
 554 \newline
 555
 556 \layout Standard
 557
 558
 559 \family typewriter
 560 better code banking
 561 \begin_inset LatexCommand \index{code banking (limited support)}
 562
 563 \end_inset
 564
 565  support for mcs51
 566 \newline
 567
 568 \newline
 569
 570 \family default
 571 If you can think of some more, please see the section
 572 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 573
 574 \end_inset
 575
 576  about filing feature requests
 577 \begin_inset LatexCommand \index{Requesting features}
 578
 579 \end_inset
 580
 581
 582 \begin_inset LatexCommand \index{Feature request}
 583
 584 \end_inset
 585
 586 .
 587 \newline
 588
 589 \layout Chapter
 590
 591 Installing SDCC
 592 \begin_inset LatexCommand \index{Installation}
 593
 594 \end_inset
 595
 596
 597 \layout Standard
 598
 599 For most users it is sufficient to skip to either section
 600 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 601
 602 \end_inset
 603
 604  or section
 605 \begin_inset LatexCommand \ref{sub:Windows-Install}
 606
 607 \end_inset
 608
 609 .
 610  More detailled instructions follow below.
 611 \layout Section
 612
 613 Configure Options
 614 \begin_inset LatexCommand \index{Options SDCC configuration}
 615
 616 \end_inset
 617
 618
 619 \layout Standard
 620
 621 The install paths, search paths and other options are defined when running
 622  'configure'.
 623  The defaults can be overridden by:
 624 \layout List
 625 \labelwidthstring 00.00.0000
 626
 627 -
 628 \begin_inset ERT
 629 status Collapsed
 630
 631 \layout Standard
 632
 633 \backslash
 634 /
 635 \end_inset
 636
 637 -prefix see table below
 638 \layout List
 639 \labelwidthstring 00.00.0000
 640
 641 -
 642 \begin_inset ERT
 643 status Collapsed
 644
 645 \layout Standard
 646
 647 \backslash
 648 /
 649 \end_inset
 650
 651 -exec_prefix see table below
 652 \layout List
 653 \labelwidthstring 00.00.0000
 654
 655 -
 656 \begin_inset ERT
 657 status Collapsed
 658
 659 \layout Standard
 660
 661 \backslash
 662 /
 663 \end_inset
 664
 665 -bindir see table below
 666 \layout List
 667 \labelwidthstring 00.00.0000
 668
 669 -
 670 \begin_inset ERT
 671 status Collapsed
 672
 673 \layout Standard
 674
 675 \backslash
 676 /
 677 \end_inset
 678
 679 -datadir see table below
 680 \layout List
 681 \labelwidthstring 00.00.0000
 682
 683 docdir environment variable, see table below
 684 \layout List
 685 \labelwidthstring 00.00.0000
 686
 687 include_dir_suffix environment variable, see table below
 688 \layout List
 689 \labelwidthstring 00.00.0000
 690
 691 lib_dir_suffix environment variable, see table below
 692 \layout List
 693 \labelwidthstring 00.00.0000
 694
 695 sdccconf_h_dir_separator environment variable, either / or
 696 \backslash
 697
 698 \backslash
 699  makes sense here.
 700  This character will only be used in sdccconf.h; don't forget it's a C-header,
 701  therefore a double-backslash is needed there.
 702 \layout List
 703 \labelwidthstring 00.00.0000
 704
 705 -
 706 \begin_inset ERT
 707 status Collapsed
 708
 709 \layout Standard
 710
 711 \backslash
 712 /
 713 \end_inset
 714
 715 -disable-mcs51-port Excludes the Intel mcs51 port
 716 \layout List
 717 \labelwidthstring 00.00.0000
 718
 719 -
 720 \begin_inset ERT
 721 status Collapsed
 722
 723 \layout Standard
 724
 725 \backslash
 726 /
 727 \end_inset
 728
 729 -disable-gbz80-port Excludes the Gameboy gbz80 port
 730 \layout List
 731 \labelwidthstring 00.00.0000
 732
 733 -
 734 \begin_inset ERT
 735 status Collapsed
 736
 737 \layout Standard
 738
 739 \backslash
 740 /
 741 \end_inset
 742
 743 -disable-z80-port Excludes the z80 port
 744 \layout List
 745 \labelwidthstring 00.00.0000
 746
 747 -
 748 \begin_inset ERT
 749 status Collapsed
 750
 751 \layout Standard
 752
 753 \backslash
 754 /
 755 \end_inset
 756
 757 -disable-avr-port Excludes the AVR port
 758 \layout List
 759 \labelwidthstring 00.00.0000
 760
 761 -
 762 \begin_inset ERT
 763 status Collapsed
 764
 765 \layout Standard
 766
 767 \backslash
 768 /
 769 \end_inset
 770
 771 -disable-ds390-port Excludes the DS390 port
 772 \layout List
 773 \labelwidthstring 00.00.0000
 774
 775 -
 776 \begin_inset ERT
 777 status Collapsed
 778
 779 \layout Standard
 780
 781 \backslash
 782 /
 783 \end_inset
 784
 785 -disable-hc08-port Excludes the HC08 port
 786 \layout List
 787 \labelwidthstring 00.00.0000
 788
 789 -
 790 \begin_inset ERT
 791 status Collapsed
 792
 793 \layout Standard
 794
 795 \backslash
 796 /
 797 \end_inset
 798
 799 -disable-pic-port Excludes the PIC port
 800 \layout List
 801 \labelwidthstring 00.00.0000
 802
 803 -
 804 \begin_inset ERT
 805 status Collapsed
 806
 807 \layout Standard
 808
 809 \backslash
 810 /
 811 \end_inset
 812
 813 -disable-xa51-port Excludes the XA51 port
 814 \layout List
 815 \labelwidthstring 00.00.0000
 816
 817 -
 818 \begin_inset ERT
 819 status Collapsed
 820
 821 \layout Standard
 822
 823 \backslash
 824 /
 825 \end_inset
 826
 827 -disable-ucsim Disables configuring and building of ucsim
 828 \layout List
 829 \labelwidthstring 00.00.0000
 830
 831 -
 832 \begin_inset ERT
 833 status Collapsed
 834
 835 \layout Standard
 836
 837 \backslash
 838 /
 839 \end_inset
 840
 841 -disable-device-lib-build Disables automatically building device libraries
 842 \layout List
 843 \labelwidthstring 00.00.0000
 844
 845 -
 846 \begin_inset ERT
 847 status Collapsed
 848
 849 \layout Standard
 850
 851 \backslash
 852 /
 853 \end_inset
 854
 855 -disable-packihx Disables building packihx
 856 \layout List
 857 \labelwidthstring 00.00.0000
 858
 859 -
 860 \begin_inset ERT
 861 status Collapsed
 862
 863 \layout Standard
 864
 865 \backslash
 866 /
 867 \end_inset
 868
 869 -enable-libgc Use the Bohem memory allocator.
 870  Lower runtime footprint.
 871 \layout Standard
 872
 873 Furthermore the environment variables CC, CFLAGS, ...
 874  the tools and their arguments can be influenced.
 875  Please see `configure -
 876 \begin_inset ERT
 877 status Collapsed
 878
 879 \layout Standard
 880
 881 \backslash
 882 /
 883 \end_inset
 884
 885 -help` and the man/info pages of `configure` for details.
 886 \newline
 887
 888 \newline
 889 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 890  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 891 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 892  At the moment it's not possible to change the default settings (it was
 893  simply never required).
 894 \newline
 895
 896 \newline
 897 These configure options are compiled into the binaries, and can only be
 898  changed by rerunning 'configure' and recompiling SDCC.
 899  The configure options are written in
 900 \emph on
 901 italics
 902 \emph default
 903  to distinguish them from run time environment variables (see section search
 904  paths).
 905 \newline
 906
 907 \newline
 908 The settings for
 909 \begin_inset Quotes sld
 910 \end_inset
 911
 912 Win32 builds
 913 \begin_inset Quotes srd
 914 \end_inset
 915
 916  are used by the SDCC team to build the official Win32 binaries.
 917  The SDCC team uses Mingw32 to build the official Windows binaries, because
 918  it's
 919 \layout Enumerate
 920
 921 open source,
 922 \layout Enumerate
 923
 924 a gcc compiler and last but not least
 925 \layout Enumerate
 926
 927 the binaries can be built by cross compiling on Sourceforge's compile farm.
 928 \layout Standard
 929
 930 See the examples, how to pass the Win32 settings to 'configure'.
 931  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 932  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 933  for Win32.
 934 \newline
 935
 936 \newline
 937 These defaults are:
 938 \newline
 939
 940 \layout Standard
 941 \align center
 942
 943 \begin_inset  Tabular
 944 <lyxtabular version="3" rows="8" columns="3">
 945 <features>
 946 <column alignment="block" valignment="top" leftline="true" width="0in">
 947 <column alignment="block" valignment="top" leftline="true" width="0in">
 948 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 949 <row topline="true" bottomline="true">
 950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 951 \begin_inset Text
 952
 953 \layout Standard
 954
 955 Variable
 956 \end_inset
 957 </cell>
 958 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 959 \begin_inset Text
 960
 961 \layout Standard
 962
 963 default
 964 \end_inset
 965 </cell>
 966 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 967 \begin_inset Text
 968
 969 \layout Standard
 970
 971 Win32 builds
 972 \end_inset
 973 </cell>
 974 </row>
 975 <row topline="true">
 976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 977 \begin_inset Text
 978
 979 \layout Standard
 980
 981
 982 \emph on
 983 PREFIX
 984 \end_inset
 985 </cell>
 986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 987 \begin_inset Text
 988
 989 \layout Standard
 990
 991 /usr/local
 992 \end_inset
 993 </cell>
 994 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 995 \begin_inset Text
 996
 997 \layout Standard
 998
 999
1000 \backslash
1001 sdcc
1002 \end_inset
1003 </cell>
1004 </row>
1005 <row topline="true">
1006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1007 \begin_inset Text
1008
1009 \layout Standard
1010
1011
1012 \emph on
1013 EXEC_PREFIX
1014 \end_inset
1015 </cell>
1016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1017 \begin_inset Text
1018
1019 \layout Standard
1020
1021
1022 \emph on
1023 $PREFIX
1024 \end_inset
1025 </cell>
1026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1027 \begin_inset Text
1028
1029 \layout Standard
1030
1031
1032 \emph on
1033 $PREFIX
1034 \end_inset
1035 </cell>
1036 </row>
1037 <row topline="true">
1038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1039 \begin_inset Text
1040
1041 \layout Standard
1042
1043
1044 \emph on
1045 BINDIR
1046 \end_inset
1047 </cell>
1048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1049 \begin_inset Text
1050
1051 \layout Standard
1052
1053
1054 \emph on
1055 $EXECPREFIX
1056 \emph default
1057 /bin
1058 \end_inset
1059 </cell>
1060 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1061 \begin_inset Text
1062
1063 \layout Standard
1064
1065
1066 \emph on
1067 $EXECPREFIX
1068 \emph default
1069
1070 \backslash
1071 bin
1072 \end_inset
1073 </cell>
1074 </row>
1075 <row topline="true">
1076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1077 \begin_inset Text
1078
1079 \layout Standard
1080
1081
1082 \emph on
1083 DATADIR
1084 \end_inset
1085 </cell>
1086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1087 \begin_inset Text
1088
1089 \layout Standard
1090
1091
1092 \emph on
1093 $PREFIX
1094 \emph default
1095 /share
1096 \end_inset
1097 </cell>
1098 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1099 \begin_inset Text
1100
1101 \layout Standard
1102
1103
1104 \emph on
1105 $PREFIX
1106 \end_inset
1107 </cell>
1108 </row>
1109 <row topline="true">
1110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1111 \begin_inset Text
1112
1113 \layout Standard
1114
1115
1116 \emph on
1117 DOCDIR
1118 \end_inset
1119 </cell>
1120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1121 \begin_inset Text
1122
1123 \layout Standard
1124
1125
1126 \emph on
1127 $DATADIR
1128 \emph default
1129 /sdcc/doc
1130 \end_inset
1131 </cell>
1132 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1133 \begin_inset Text
1134
1135 \layout Standard
1136
1137
1138 \emph on
1139 $DATADIR
1140 \emph default
1141
1142 \backslash
1143 doc
1144 \end_inset
1145 </cell>
1146 </row>
1147 <row topline="true">
1148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1149 \begin_inset Text
1150
1151 \layout Standard
1152
1153
1154 \emph on
1155 INCLUDE_DIR_SUFFIX
1156 \end_inset
1157 </cell>
1158 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1159 \begin_inset Text
1160
1161 \layout Standard
1162
1163 sdcc/include
1164 \end_inset
1165 </cell>
1166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1167 \begin_inset Text
1168
1169 \layout Standard
1170
1171 include
1172 \end_inset
1173 </cell>
1174 </row>
1175 <row topline="true" bottomline="true">
1176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1177 \begin_inset Text
1178
1179 \layout Standard
1180
1181
1182 \emph on
1183 LIB_DIR_SUFFIX
1184 \end_inset
1185 </cell>
1186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1187 \begin_inset Text
1188
1189 \layout Standard
1190
1191 sdcc/lib
1192 \end_inset
1193 </cell>
1194 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1195 \begin_inset Text
1196
1197 \layout Standard
1198
1199 lib
1200 \end_inset
1201 </cell>
1202 </row>
1203 </lyxtabular>
1204
1205 \end_inset
1206
1207
1208 \newline
1209
1210 \layout Standard
1211 \noindent
1212 'configure' also computes relative paths.
1213  This is needed for full relocatability of a binary package and to complete
1214  search paths (see section search paths below):
1215 \newline
1216
1217 \layout Standard
1218 \align center
1219
1220 \begin_inset  Tabular
1221 <lyxtabular version="3" rows="4" columns="3">
1222 <features>
1223 <column alignment="block" valignment="top" leftline="true" width="0in">
1224 <column alignment="block" valignment="top" leftline="true" width="0in">
1225 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1226 <row topline="true" bottomline="true">
1227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1228 \begin_inset Text
1229
1230 \layout Standard
1231
1232 Variable (computed)
1233 \end_inset
1234 </cell>
1235 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1236 \begin_inset Text
1237
1238 \layout Standard
1239
1240 default
1241 \end_inset
1242 </cell>
1243 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1244 \begin_inset Text
1245
1246 \layout Standard
1247
1248 Win32 builds
1249 \end_inset
1250 </cell>
1251 </row>
1252 <row topline="true" bottomline="true">
1253 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1254 \begin_inset Text
1255
1256 \layout Standard
1257
1258
1259 \emph on
1260 BIN2DATA_DIR
1261 \end_inset
1262 </cell>
1263 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1264 \begin_inset Text
1265
1266 \layout Standard
1267
1268 ../share
1269 \end_inset
1270 </cell>
1271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1272 \begin_inset Text
1273
1274 \layout Standard
1275
1276 ..
1277 \end_inset
1278 </cell>
1279 </row>
1280 <row bottomline="true">
1281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1282 \begin_inset Text
1283
1284 \layout Standard
1285
1286
1287 \emph on
1288 PREFIX2BIN_DIR
1289 \end_inset
1290 </cell>
1291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1292 \begin_inset Text
1293
1294 \layout Standard
1295
1296 bin
1297 \end_inset
1298 </cell>
1299 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1300 \begin_inset Text
1301
1302 \layout Standard
1303
1304 bin
1305 \end_inset
1306 </cell>
1307 </row>
1308 <row bottomline="true">
1309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1310 \begin_inset Text
1311
1312 \layout Standard
1313
1314
1315 \emph on
1316 PREFIX2DATA_DIR
1317 \end_inset
1318 </cell>
1319 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1320 \begin_inset Text
1321
1322 \layout Standard
1323
1324 share/sdcc
1325 \end_inset
1326 </cell>
1327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1328 \begin_inset Text
1329
1330 \layout Standard
1331
1332 \end_inset
1333 </cell>
1334 </row>
1335 </lyxtabular>
1336
1337 \end_inset
1338
1339
1340 \newline
1341
1342 \layout Standard
1343 \noindent
1344 Examples:
1345 \layout LyX-Code
1346
1347 ./configure
1348 \newline
1349 ./configure -
1350 \begin_inset ERT
1351 status Collapsed
1352
1353 \layout Standard
1354
1355 \backslash
1356 /
1357 \end_inset
1358
1359 -prefix=
1360 \begin_inset Quotes srd
1361 \end_inset
1362
1363 /usr/bin
1364 \begin_inset Quotes srd
1365 \end_inset
1366
1367  -
1368 \begin_inset ERT
1369 status Collapsed
1370
1371 \layout Standard
1372
1373 \backslash
1374 /
1375 \end_inset
1376
1377 -datadir=
1378 \begin_inset Quotes srd
1379 \end_inset
1380
1381 /usr/share
1382 \begin_inset Quotes srd
1383 \end_inset
1384
1385
1386 \newline
1387 ./configure -
1388 \begin_inset ERT
1389 status Collapsed
1390
1391 \layout Standard
1392
1393 \backslash
1394 /
1395 \end_inset
1396
1397 -disable-avr-port -
1398 \begin_inset ERT
1399 status Collapsed
1400
1401 \layout Standard
1402
1403 \backslash
1404 /
1405 \end_inset
1406
1407 -disable-xa51-port
1408 \layout Standard
1409
1410 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1411 32'):
1412 \layout LyX-Code
1413
1414 ./configure
1415 \backslash
1416
1417 \newline
1418 CC=
1419 \begin_inset Quotes srd
1420 \end_inset
1421
1422 i586-mingw32msvc-gcc
1423 \begin_inset Quotes srd
1424 \end_inset
1425
1426  CXX=
1427 \begin_inset Quotes srd
1428 \end_inset
1429
1430 i586-mingw32msvc-g++
1431 \begin_inset Quotes srd
1432 \end_inset
1433
1434
1435 \backslash
1436
1437 \newline
1438 RANLIB=
1439 \begin_inset Quotes srd
1440 \end_inset
1441
1442 i586-mingw32msvc-ranlib
1443 \begin_inset Quotes srd
1444 \end_inset
1445
1446
1447 \backslash
1448
1449 \newline
1450 STRIP=
1451 \begin_inset Quotes srd
1452 \end_inset
1453
1454 i586-mingw32msvc-strip
1455 \begin_inset Quotes srd
1456 \end_inset
1457
1458
1459 \backslash
1460
1461 \newline
1462 -
1463 \begin_inset ERT
1464 status Collapsed
1465
1466 \layout Standard
1467
1468 \backslash
1469 /
1470 \end_inset
1471
1472 -prefix=
1473 \begin_inset Quotes srd
1474 \end_inset
1475
1476 /sdcc
1477 \begin_inset Quotes srd
1478 \end_inset
1479
1480
1481 \backslash
1482
1483 \newline
1484 -
1485 \begin_inset ERT
1486 status Collapsed
1487
1488 \layout Standard
1489
1490 \backslash
1491 /
1492 \end_inset
1493
1494 -datadir=
1495 \begin_inset Quotes srd
1496 \end_inset
1497
1498 /sdcc
1499 \begin_inset Quotes srd
1500 \end_inset
1501
1502
1503 \backslash
1504
1505 \newline
1506 docdir=
1507 \begin_inset Quotes srd
1508 \end_inset
1509
1510 /sdcc/doc
1511 \begin_inset Quotes srd
1512 \end_inset
1513
1514
1515 \backslash
1516
1517 \newline
1518 include_dir_suffix=
1519 \begin_inset Quotes srd
1520 \end_inset
1521
1522 include
1523 \begin_inset Quotes srd
1524 \end_inset
1525
1526
1527 \backslash
1528
1529 \newline
1530 lib_dir_suffix=
1531 \begin_inset Quotes srd
1532 \end_inset
1533
1534 lib
1535 \begin_inset Quotes srd
1536 \end_inset
1537
1538
1539 \backslash
1540
1541 \newline
1542 sdccconf_h_dir_separator=
1543 \begin_inset Quotes srd
1544 \end_inset
1545
1546
1547 \backslash
1548
1549 \backslash
1550
1551 \backslash
1552
1553 \backslash
1554
1555 \begin_inset Quotes srd
1556 \end_inset
1557
1558
1559 \backslash
1560
1561 \newline
1562 -
1563 \begin_inset ERT
1564 status Collapsed
1565
1566 \layout Standard
1567
1568 \backslash
1569 /
1570 \end_inset
1571
1572 -disable-device-lib-build
1573 \backslash
1574
1575 \newline
1576 -
1577 \begin_inset ERT
1578 status Collapsed
1579
1580 \layout Standard
1581
1582 \backslash
1583 /
1584 \end_inset
1585
1586 -disable-ucsim
1587 \backslash
1588
1589 \newline
1590 -
1591 \begin_inset ERT
1592 status Collapsed
1593
1594 \layout Standard
1595
1596 \backslash
1597 /
1598 \end_inset
1599
1600 -host=i586-mingw32msvc -
1601 \begin_inset ERT
1602 status Collapsed
1603
1604 \layout Standard
1605
1606 \backslash
1607 /
1608 \end_inset
1609
1610 -build=unknown-unknown-linux-gnu
1611 \layout Standard
1612
1613 To
1614 \begin_inset Quotes sld
1615 \end_inset
1616
1617 cross
1618 \begin_inset Quotes srd
1619 \end_inset
1620
1621 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1622 ):
1623 \layout LyX-Code
1624
1625 ./configure -C
1626 \backslash
1627
1628 \newline
1629 CFLAGS=
1630 \begin_inset Quotes srd
1631 \end_inset
1632
1633 -mno-cygwin -O2
1634 \begin_inset Quotes srd
1635 \end_inset
1636
1637
1638 \backslash
1639
1640 \newline
1641 LDFLAGS=
1642 \begin_inset Quotes srd
1643 \end_inset
1644
1645 -mno-cygwin
1646 \begin_inset Quotes srd
1647 \end_inset
1648
1649
1650 \backslash
1651
1652 \newline
1653 -
1654 \begin_inset ERT
1655 status Collapsed
1656
1657 \layout Standard
1658
1659 \backslash
1660 /
1661 \end_inset
1662
1663 -prefix=
1664 \begin_inset Quotes srd
1665 \end_inset
1666
1667 /sdcc
1668 \begin_inset Quotes srd
1669 \end_inset
1670
1671
1672 \backslash
1673
1674 \newline
1675 -
1676 \begin_inset ERT
1677 status Collapsed
1678
1679 \layout Standard
1680
1681 \backslash
1682 /
1683 \end_inset
1684
1685 -datadir=
1686 \begin_inset Quotes srd
1687 \end_inset
1688
1689 /sdcc
1690 \begin_inset Quotes srd
1691 \end_inset
1692
1693
1694 \backslash
1695
1696 \newline
1697 docdir=
1698 \begin_inset Quotes srd
1699 \end_inset
1700
1701 /sdcc/doc
1702 \begin_inset Quotes srd
1703 \end_inset
1704
1705
1706 \backslash
1707
1708 \newline
1709 include_dir_suffix=
1710 \begin_inset Quotes srd
1711 \end_inset
1712
1713 include
1714 \begin_inset Quotes srd
1715 \end_inset
1716
1717
1718 \backslash
1719
1720 \newline
1721 lib_dir_suffix=
1722 \begin_inset Quotes srd
1723 \end_inset
1724
1725 lib
1726 \begin_inset Quotes srd
1727 \end_inset
1728
1729
1730 \backslash
1731
1732 \newline
1733 sdccconf_h_dir_separator=
1734 \begin_inset Quotes srd
1735 \end_inset
1736
1737
1738 \backslash
1739
1740 \backslash
1741
1742 \backslash
1743
1744 \backslash
1745
1746 \begin_inset Quotes srd
1747 \end_inset
1748
1749
1750 \backslash
1751
1752 \newline
1753 -
1754 \begin_inset ERT
1755 status Collapsed
1756
1757 \layout Standard
1758
1759 \backslash
1760 /
1761 \end_inset
1762
1763 -disable-ucsim
1764 \layout Standard
1765
1766 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1767  The option '-
1768 \begin_inset ERT
1769 status Collapsed
1770
1771 \layout Standard
1772
1773 \backslash
1774 /
1775 \end_inset
1776
1777 -C' turns on caching, which gives a little bit extra speed.
1778  However if options are changed, it can be necessary to delete the config.cache
1779  file.
1780 \layout Section
1781
1782 Install paths
1783 \begin_inset LatexCommand \label{sub:Install-paths}
1784
1785 \end_inset
1786
1787
1788 \begin_inset LatexCommand \index{Install paths}
1789
1790 \end_inset
1791
1792
1793 \layout Standard
1794 \added_space_top medskip \align center
1795
1796 \begin_inset  Tabular
1797 <lyxtabular version="3" rows="5" columns="4">
1798 <features>
1799 <column alignment="center" valignment="top" leftline="true" width="0">
1800 <column alignment="center" valignment="top" leftline="true" width="0">
1801 <column alignment="center" valignment="top" leftline="true" width="0">
1802 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1803 <row topline="true" bottomline="true">
1804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1805 \begin_inset Text
1806
1807 \layout Standard
1808
1809
1810 \series bold
1811 Description
1812 \end_inset
1813 </cell>
1814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1815 \begin_inset Text
1816
1817 \layout Standard
1818
1819
1820 \series bold
1821 Path
1822 \end_inset
1823 </cell>
1824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1825 \begin_inset Text
1826
1827 \layout Standard
1828
1829
1830 \series bold
1831 Default
1832 \end_inset
1833 </cell>
1834 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1835 \begin_inset Text
1836
1837 \layout Standard
1838
1839
1840 \series bold
1841 Win32 builds
1842 \end_inset
1843 </cell>
1844 </row>
1845 <row topline="true">
1846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1847 \begin_inset Text
1848
1849 \layout Standard
1850
1851 Binary files*
1852 \end_inset
1853 </cell>
1854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1855 \begin_inset Text
1856
1857 \layout Standard
1858
1859
1860 \emph on
1861 $EXEC_PREFIX
1862 \end_inset
1863 </cell>
1864 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1865 \begin_inset Text
1866
1867 \layout Standard
1868
1869 /usr/local/bin
1870 \end_inset
1871 </cell>
1872 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1873 \begin_inset Text
1874
1875 \layout Standard
1876
1877
1878 \backslash
1879 sdcc
1880 \backslash
1881 bin
1882 \end_inset
1883 </cell>
1884 </row>
1885 <row topline="true">
1886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1887 \begin_inset Text
1888
1889 \layout Standard
1890
1891 Include files
1892 \end_inset
1893 </cell>
1894 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1895 \begin_inset Text
1896
1897 \layout Standard
1898
1899
1900 \emph on
1901 $DATADIR/ $INCLUDE_DIR_SUFFIX
1902 \end_inset
1903 </cell>
1904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1905 \begin_inset Text
1906
1907 \layout Standard
1908
1909 /usr/local/share/sdcc/include
1910 \end_inset
1911 </cell>
1912 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1913 \begin_inset Text
1914
1915 \layout Standard
1916
1917
1918 \backslash
1919 sdcc
1920 \backslash
1921 include
1922 \end_inset
1923 </cell>
1924 </row>
1925 <row topline="true">
1926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1927 \begin_inset Text
1928
1929 \layout Standard
1930
1931 Library file**
1932 \end_inset
1933 </cell>
1934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1935 \begin_inset Text
1936
1937 \layout Standard
1938
1939
1940 \emph on
1941 $DATADIR/$LIB_DIR_SUFFIX
1942 \end_inset
1943 </cell>
1944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1945 \begin_inset Text
1946
1947 \layout Standard
1948
1949 /usr/local/share/sdcc/lib
1950 \end_inset
1951 </cell>
1952 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1953 \begin_inset Text
1954
1955 \layout Standard
1956
1957
1958 \backslash
1959 sdcc
1960 \backslash
1961 lib
1962 \end_inset
1963 </cell>
1964 </row>
1965 <row topline="true" bottomline="true">
1966 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1967 \begin_inset Text
1968
1969 \layout Standard
1970
1971 Documentation
1972 \end_inset
1973 </cell>
1974 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1975 \begin_inset Text
1976
1977 \layout Standard
1978
1979
1980 \emph on
1981 $DOCDIR
1982 \end_inset
1983 </cell>
1984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1985 \begin_inset Text
1986
1987 \layout Standard
1988
1989 /usr/local/share/sdcc/doc
1990 \end_inset
1991 </cell>
1992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1993 \begin_inset Text
1994
1995 \layout Standard
1996
1997
1998 \backslash
1999 sdcc
2000 \backslash
2001 doc
2002 \end_inset
2003 </cell>
2004 </row>
2005 </lyxtabular>
2006
2007 \end_inset
2008
2009
2010 \layout Verse
2011
2012
2013 \size footnotesize
2014 *compiler, preprocessor, assembler, and linker
2015 \newline
2016 **the
2017 \shape italic
2018 model
2019 \shape default
2020  is auto-appended by the compiler, e.g.
2021  small, large, z80, ds390 etc
2022 \layout Standard
2023 \noindent
2024 The install paths can still be changed during `make install` with e.g.:
2025 \layout LyX-Code
2026
2027 make install prefix=$(HOME)/local/sdcc
2028 \layout Standard
2029
2030 Of course this doesn't change the search paths compiled into the binaries.
2031 \newline
2032
2033 \newline
2034 Moreover the install path can be changed by defining DESTDIR
2035 \begin_inset LatexCommand \index{DESTDIR}
2036
2037 \end_inset
2038
2039 :
2040 \layout LyX-Code
2041
2042 make install DESTDIR=$(HOME)/sdcc.rpm/
2043 \layout Standard
2044
2045 Please note that DESTDIR must have a trailing slash!
2046 \layout Section
2047
2048 Search Paths
2049 \begin_inset LatexCommand \label{sub:Search-Paths}
2050
2051 \end_inset
2052
2053
2054 \begin_inset LatexCommand \index{Search path}
2055
2056 \end_inset
2057
2058
2059 \layout Standard
2060
2061 Some search paths or parts of them are determined by configure variables
2062  (in
2063 \emph on
2064 italics
2065 \emph default
2066 , see section above).
2067  Further search paths are determined by environment variables during runtime.
2068
2069 \newline
2070 The paths searched when running the compiler are as follows (the first catch
2071  wins):
2072 \newline
2073
2074 \newline
2075 1.
2076  Binary files (preprocessor, assembler and linker)
2077 \newline
2078
2079 \layout Standard
2080 \align center
2081
2082 \begin_inset  Tabular
2083 <lyxtabular version="3" rows="4" columns="3">
2084 <features>
2085 <column alignment="block" valignment="top" leftline="true" width="0in">
2086 <column alignment="block" valignment="top" leftline="true" width="0in">
2087 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2088 <row topline="true" bottomline="true">
2089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2090 \begin_inset Text
2091
2092 \layout Standard
2093
2094 Search path
2095 \end_inset
2096 </cell>
2097 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2098 \begin_inset Text
2099
2100 \layout Standard
2101
2102 default
2103 \end_inset
2104 </cell>
2105 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2106 \begin_inset Text
2107
2108 \layout Standard
2109
2110 Win32 builds
2111 \end_inset
2112 </cell>
2113 </row>
2114 <row topline="true">
2115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2116 \begin_inset Text
2117
2118 \layout Standard
2119
2120 $SDCC_HOME/
2121 \emph on
2122 $PPREFIX2BIN_DIR
2123 \end_inset
2124 </cell>
2125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2126 \begin_inset Text
2127
2128 \layout Standard
2129
2130 $SDCC_HOME/bin
2131 \end_inset
2132 </cell>
2133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2134 \begin_inset Text
2135
2136 \layout Standard
2137
2138 $SDCC_HOME
2139 \backslash
2140 bin
2141 \end_inset
2142 </cell>
2143 </row>
2144 <row topline="true">
2145 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2146 \begin_inset Text
2147
2148 \layout Standard
2149
2150 Path of argv[0] (if available)
2151 \end_inset
2152 </cell>
2153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2154 \begin_inset Text
2155
2156 \layout Standard
2157
2158 Path of argv[0]
2159 \end_inset
2160 </cell>
2161 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2162 \begin_inset Text
2163
2164 \layout Standard
2165
2166 Path of argv[0]
2167 \end_inset
2168 </cell>
2169 </row>
2170 <row topline="true" bottomline="true">
2171 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2172 \begin_inset Text
2173
2174 \layout Standard
2175
2176 $PATH
2177 \end_inset
2178 </cell>
2179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2180 \begin_inset Text
2181
2182 \layout Standard
2183
2184 $PATH
2185 \end_inset
2186 </cell>
2187 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2188 \begin_inset Text
2189
2190 \layout Standard
2191
2192 $PATH
2193 \end_inset
2194 </cell>
2195 </row>
2196 </lyxtabular>
2197
2198 \end_inset
2199
2200
2201 \newline
2202
2203 \layout Standard
2204 \noindent
2205 2.
2206  Include files
2207 \newline
2208
2209 \layout Standard
2210 \align center
2211
2212 \begin_inset  Tabular
2213 <lyxtabular version="3" rows="6" columns="3">
2214 <features>
2215 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2216 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2217 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2218 <row topline="true" bottomline="true">
2219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2220 \begin_inset Text
2221
2222 \layout Standard
2223
2224 Search path
2225 \end_inset
2226 </cell>
2227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2228 \begin_inset Text
2229
2230 \layout Standard
2231
2232 default
2233 \end_inset
2234 </cell>
2235 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2236 \begin_inset Text
2237
2238 \layout Standard
2239
2240 Win32 builds
2241 \end_inset
2242 </cell>
2243 </row>
2244 <row topline="true">
2245 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2246 \begin_inset Text
2247
2248 \layout Standard
2249
2250 -
2251 \begin_inset ERT
2252 status Collapsed
2253
2254 \layout Standard
2255
2256 \backslash
2257 /
2258 \end_inset
2259
2260 -I dir
2261 \end_inset
2262 </cell>
2263 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2264 \begin_inset Text
2265
2266 \layout Standard
2267
2268 -
2269 \begin_inset ERT
2270 status Collapsed
2271
2272 \layout Standard
2273
2274 \backslash
2275 /
2276 \end_inset
2277
2278 -I dir
2279 \end_inset
2280 </cell>
2281 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2282 \begin_inset Text
2283
2284 \layout Standard
2285
2286 -
2287 \begin_inset ERT
2288 status Collapsed
2289
2290 \layout Standard
2291
2292 \backslash
2293 /
2294 \end_inset
2295
2296 -I dir
2297 \end_inset
2298 </cell>
2299 </row>
2300 <row topline="true">
2301 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2302 \begin_inset Text
2303
2304 \layout Standard
2305
2306 $SDCC_INCLUDE
2307 \end_inset
2308 </cell>
2309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2310 \begin_inset Text
2311
2312 \layout Standard
2313
2314 $SDCC_INCLUDE
2315 \end_inset
2316 </cell>
2317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2318 \begin_inset Text
2319
2320 \layout Standard
2321
2322 $SDCC_INCLUDE
2323 \end_inset
2324 </cell>
2325 </row>
2326 <row topline="true">
2327 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2328 \begin_inset Text
2329
2330 \layout Standard
2331
2332 $SDCC_HOME/
2333 \newline
2334
2335 \emph on
2336 $PREFIX2DATA_DIR/
2337 \newline
2338 $INCLUDE_DIR_SUFFIX
2339 \end_inset
2340 </cell>
2341 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2342 \begin_inset Text
2343
2344 \layout Standard
2345
2346 $SDCC_ HOME/
2347 \newline
2348 share/sdcc/
2349 \newline
2350 include
2351 \end_inset
2352 </cell>
2353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2354 \begin_inset Text
2355
2356 \layout Standard
2357
2358 $SDCC_HOME
2359 \backslash
2360 include
2361 \end_inset
2362 </cell>
2363 </row>
2364 <row topline="true">
2365 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2366 \begin_inset Text
2367
2368 \layout Standard
2369
2370 path(argv[0])/
2371 \newline
2372
2373 \emph on
2374 $BIN2DATADIR/
2375 \emph default
2376
2377 \newline
2378
2379 \emph on
2380 $INCLUDE_DIR_SUFFIX
2381 \end_inset
2382 </cell>
2383 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2384 \begin_inset Text
2385
2386 \layout Standard
2387
2388 path(argv[0])/
2389 \newline
2390 ../sdcc/include
2391 \newline
2392 \SpecialChar ~
2393 \SpecialChar ~
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
2431 \end_inset
2432 </cell>
2433 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2434 \begin_inset Text
2435
2436 \layout Standard
2437
2438 path(argv[0])
2439 \backslash
2440 ..
2441 \backslash
2442 include
2443 \end_inset
2444 </cell>
2445 </row>
2446 <row topline="true" bottomline="true">
2447 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2448 \begin_inset Text
2449
2450 \layout Standard
2451
2452
2453 \emph on
2454 $DATADIR/
2455 \emph default
2456
2457 \newline
2458
2459 \emph on
2460 $INCLUDE_DIR_SUFFIX
2461 \end_inset
2462 </cell>
2463 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2464 \begin_inset Text
2465
2466 \layout Standard
2467
2468 /usr/local/share/sdcc/
2469 \newline
2470 include
2471 \end_inset
2472 </cell>
2473 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2474 \begin_inset Text
2475
2476 \layout Standard
2477
2478 (not on Win32)
2479 \end_inset
2480 </cell>
2481 </row>
2482 </lyxtabular>
2483
2484 \end_inset
2485
2486
2487 \newline
2488
2489 \layout Standard
2490 \noindent
2491 The option -
2492 \begin_inset ERT
2493 status Collapsed
2494
2495 \layout Standard
2496
2497 \backslash
2498 /
2499 \end_inset
2500
2501 -nostdinc disables the last two search paths.
2502 \newline
2503
2504 \newline
2505 3.
2506  Library files
2507 \newline
2508
2509 \layout Standard
2510
2511 With the exception of
2512 \begin_inset Quotes sld
2513 \end_inset
2514
2515 -
2516 \begin_inset ERT
2517 status Collapsed
2518
2519 \layout Standard
2520
2521 \backslash
2522 /
2523 \end_inset
2524
2525 -L dir
2526 \begin_inset Quotes srd
2527 \end_inset
2528
2529  the
2530 \shape italic
2531 model
2532 \shape default
2533  is auto-appended by the compiler (e.g.
2534  small, large, z80, ds390 etc.).
2535
2536 \newline
2537
2538 \layout Standard
2539 \align center
2540
2541 \begin_inset  Tabular
2542 <lyxtabular version="3" rows="6" columns="3">
2543 <features>
2544 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2545 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2546 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2547 <row topline="true" bottomline="true">
2548 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2549 \begin_inset Text
2550
2551 \layout Standard
2552
2553 Search path
2554 \end_inset
2555 </cell>
2556 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2557 \begin_inset Text
2558
2559 \layout Standard
2560
2561 default
2562 \end_inset
2563 </cell>
2564 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2565 \begin_inset Text
2566
2567 \layout Standard
2568
2569 Win32 builds
2570 \end_inset
2571 </cell>
2572 </row>
2573 <row topline="true">
2574 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2575 \begin_inset Text
2576
2577 \layout Standard
2578
2579 -
2580 \begin_inset ERT
2581 status Collapsed
2582
2583 \layout Standard
2584
2585 \backslash
2586 /
2587 \end_inset
2588
2589 -L dir
2590 \end_inset
2591 </cell>
2592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2593 \begin_inset Text
2594
2595 \layout Standard
2596
2597 -
2598 \begin_inset ERT
2599 status Collapsed
2600
2601 \layout Standard
2602
2603 \backslash
2604 /
2605 \end_inset
2606
2607 -L dir
2608 \end_inset
2609 </cell>
2610 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2611 \begin_inset Text
2612
2613 \layout Standard
2614
2615 -
2616 \begin_inset ERT
2617 status Collapsed
2618
2619 \layout Standard
2620
2621 \backslash
2622 /
2623 \end_inset
2624
2625 -L dir
2626 \end_inset
2627 </cell>
2628 </row>
2629 <row topline="true">
2630 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2631 \begin_inset Text
2632
2633 \layout Standard
2634
2635 $SDCC_LIB/
2636 \newline
2637
2638 \emph on
2639 <model>
2640 \end_inset
2641 </cell>
2642 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2643 \begin_inset Text
2644
2645 \layout Standard
2646
2647 $SDCC_LIB/
2648 \newline
2649
2650 \emph on
2651 <model>
2652 \end_inset
2653 </cell>
2654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2655 \begin_inset Text
2656
2657 \layout Standard
2658
2659 $SDCC_LIB
2660 \backslash
2661
2662 \newline
2663
2664 \emph on
2665 <model>
2666 \end_inset
2667 </cell>
2668 </row>
2669 <row topline="true">
2670 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2671 \begin_inset Text
2672
2673 \layout Standard
2674
2675 $SDCC_HOME/
2676 \newline
2677
2678 \emph on
2679 $PREFIX2DATA_DIR/
2680 \newline
2681 $LIB_DIR_SUFFIX/<model>
2682 \end_inset
2683 </cell>
2684 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2685 \begin_inset Text
2686
2687 \layout Standard
2688
2689 $SDCC_HOME/
2690 \newline
2691 share/sdcc/
2692 \newline
2693 lib/
2694 \emph on
2695 <model>
2696 \end_inset
2697 </cell>
2698 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2699 \begin_inset Text
2700
2701 \layout Standard
2702
2703 $SDCC_HOME
2704 \backslash
2705 lib
2706 \backslash
2707
2708 \emph on
2709
2710 \newline
2711 <model>
2712 \end_inset
2713 </cell>
2714 </row>
2715 <row topline="true">
2716 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2717 \begin_inset Text
2718
2719 \layout Standard
2720
2721 path(argv[0])/
2722 \newline
2723
2724 \emph on
2725 $BIN2DATADIR/
2726 \emph default
2727
2728 \newline
2729
2730 \emph on
2731 $LIB_DIR_SUFFIX/<model>
2732 \end_inset
2733 </cell>
2734 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2735 \begin_inset Text
2736
2737 \layout Standard
2738
2739 path(argv[0])/
2740 \newline
2741 ../sdcc/lib/
2742 \emph on
2743 <model>
2744 \newline
2745 \SpecialChar ~
2746 \SpecialChar ~
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
2785 \end_inset
2786 </cell>
2787 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2788 \begin_inset Text
2789
2790 \layout Standard
2791
2792 path(argv[0])
2793 \backslash
2794
2795 \newline
2796 ..
2797 \backslash
2798 lib
2799 \backslash
2800
2801 \emph on
2802 <model>
2803 \newline
2804 \SpecialChar ~
2805 \SpecialChar ~
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
2840 \end_inset
2841 </cell>
2842 </row>
2843 <row topline="true" bottomline="true">
2844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2845 \begin_inset Text
2846
2847 \layout Standard
2848
2849
2850 \emph on
2851 $DATADIR/
2852 \newline
2853 $LIB_DIR_SUFFIX/<model>
2854 \end_inset
2855 </cell>
2856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2857 \begin_inset Text
2858
2859 \layout Standard
2860
2861 /usr/local/share/sdcc/
2862 \newline
2863 lib/
2864 \emph on
2865 <model>
2866 \end_inset
2867 </cell>
2868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2869 \begin_inset Text
2870
2871 \layout Standard
2872
2873 (not on Win32)
2874 \end_inset
2875 </cell>
2876 </row>
2877 </lyxtabular>
2878
2879 \end_inset
2880
2881
2882 \newline
2883
2884 \layout Comment
2885
2886 Don't delete any of the stray spaces in the table above without checking
2887  the HTML output (last line)!
2888 \layout Standard
2889
2890 \SpecialChar ~
2891
2892 \newline
2893 The option -
2894 \begin_inset ERT
2895 status Collapsed
2896
2897 \layout Standard
2898
2899 \backslash
2900 /
2901 \end_inset
2902
2903 -nostdlib disables the last two search paths.
2904 \layout Section
2905
2906 Building SDCC
2907 \begin_inset LatexCommand \index{Building SDCC}
2908
2909 \end_inset
2910
2911
2912 \layout Subsection
2913
2914 Building SDCC on Linux
2915 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2916
2917 \end_inset
2918
2919
2920 \layout Enumerate
2921
2922
2923 \series medium
2924 Download the source package
2925 \series default
2926  either from the SDCC CVS repository or from the nightly snapshots
2927 \series medium
2928 , it will be named something like sdcc
2929 \series default
2930 .src
2931 \series medium
2932 .t
2933 \series default
2934 ar.
2935 \series medium
2936 gz
2937 \series default
2938
2939 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2940
2941 \end_inset
2942
2943 .
2944 \layout Enumerate
2945
2946
2947 \series medium
2948 Bring up a command line terminal, such as xterm.
2949 \layout Enumerate
2950
2951
2952 \series medium
2953 Unpack the file using a command like:
2954 \family sans
2955 \series bold
2956 "tar -xvzf sdcc.src.tar.gz
2957 \family default
2958 \series default
2959 "
2960 \series medium
2961 , this will create a sub-directory called sdcc with all of the sources.
2962 \layout Enumerate
2963
2964 Change directory into the main SDCC directory, for example type:
2965 \family sans
2966 \series bold
2967 "cd sdcc
2968 \series default
2969 ".
2970 \layout Enumerate
2971
2972
2973 \series medium
2974 Type
2975 \family sans
2976 \series bold
2977 "./configure
2978 \family default
2979 \series default
2980 ".
2981  This configures the package for compilation on your system.
2982 \layout Enumerate
2983
2984
2985 \series medium
2986 Type
2987 \family sans
2988 \series bold
2989 "make
2990 \family default
2991 \series default
2992 "
2993 \series medium
2994 .
2995
2996 \series default
2997  All of the source packages will compile, this can take a while.
2998 \layout Enumerate
2999
3000
3001 \series medium
3002 Type
3003 \family sans
3004 \series bold
3005 "make install"
3006 \family default
3007 \series default
3008  as root
3009 \series medium
3010 .
3011
3012 \series default
3013  This copies the binary executables, the include files, the libraries and
3014  the documentation to the install directories.
3015  Proceed with section
3016 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
3017
3018 \end_inset
3019
3020 .
3021 \layout Subsection
3022
3023 Building SDCC on OSX 2.x
3024 \layout Standard
3025
3026 Follow the instruction for Linux.
3027 \newline
3028
3029 \newline
3030 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
3031 )) fails to compile SDCC.
3032  Fortunately there's also gcc 2.9.x installed, which works fine.
3033  This compiler can be selected by running 'configure' with:
3034 \layout LyX-Code
3035
3036 ./configure CC=gcc2 CXX=g++2
3037 \layout Subsection
3038
3039 Cross compiling SDCC on Linux for Windows
3040 \layout Standard
3041
3042 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
3043  See section 'Configure Options'.
3044 \layout Subsection
3045
3046 Building SDCC on Windows
3047 \layout Standard
3048
3049 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
3050  built on Windows.
3051  They use Unix-sockets, which are not available on Win32.
3052 \layout Subsection
3053
3054 Building SDCC using Cygwin and Mingw32
3055 \layout Standard
3056
3057 For building and installing a Cygwin executable follow the instructions
3058  for Linux.
3059 \newline
3060
3061 \newline
3062 On Cygwin a
3063 \begin_inset Quotes sld
3064 \end_inset
3065
3066 native
3067 \begin_inset Quotes srd
3068 \end_inset
3069
3070  Win32-binary can be built, which will not need the Cygwin-DLL.
3071  For the necessary 'configure' options see section 'configure options' or
3072  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3073 \newline
3074
3075 \newline
3076 In order to install Cygwin on Windows download setup.exe from
3077 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3078
3079 \end_inset
3080
3081 .
3082  Run it, set the
3083 \begin_inset Quotes sld
3084 \end_inset
3085
3086 default text file type
3087 \begin_inset Quotes srd
3088 \end_inset
3089
3090  to
3091 \begin_inset Quotes sld
3092 \end_inset
3093
3094 unix
3095 \begin_inset Quotes srd
3096 \end_inset
3097
3098  and download/install at least the following packages.
3099  Some packages are selected by default, others will be automatically selected
3100  because of dependencies with the manually selected packages.
3101  Never deselect these packages!
3102 \layout Itemize
3103
3104 flex
3105 \layout Itemize
3106
3107 bison
3108 \layout Itemize
3109
3110 gcc ; version 3.x is fine, no need to use the old 2.9x
3111 \layout Itemize
3112
3113 binutils ; selected with gcc
3114 \layout Itemize
3115
3116 make
3117 \layout Itemize
3118
3119 rxvt ; a nice console, which makes life much easier under windoze (see below)
3120 \layout Itemize
3121
3122 man ; not really needed for building SDCC, but you'll miss it sooner or
3123  later
3124 \layout Itemize
3125
3126 less ; not really needed for building SDCC, but you'll miss it sooner or
3127  later
3128 \layout Itemize
3129
3130 cvs ; only if you use CVS access
3131 \layout Standard
3132
3133 If you want to develop something you'll need:
3134 \layout Itemize
3135
3136 python ; for the regression tests
3137 \layout Itemize
3138
3139 gdb ; the gnu debugger, together with the nice GUI
3140 \begin_inset Quotes sld
3141 \end_inset
3142
3143 insight
3144 \begin_inset Quotes srd
3145 \end_inset
3146
3147
3148 \layout Itemize
3149
3150 openssh ; to access the CF or commit changes
3151 \layout Itemize
3152
3153 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3154  use autoconf-stable!
3155 \layout Standard
3156
3157 rxvt is a nice console with history.
3158  Replace in your cygwin.bat the line
3159 \layout LyX-Code
3160
3161 bash -
3162 \begin_inset ERT
3163 status Collapsed
3164
3165 \layout Standard
3166
3167 \backslash
3168 /
3169 \end_inset
3170
3171 -login -i
3172 \layout Standard
3173
3174 with (one line):
3175 \layout LyX-Code
3176
3177 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3178 \layout LyX-Code
3179
3180      -bg black -fg white -geometry 100x65 -e bash -
3181 \begin_inset ERT
3182 status Collapsed
3183
3184 \layout Standard
3185
3186 \backslash
3187 /
3188 \end_inset
3189
3190 -login
3191 \layout Standard
3192
3193 Text selected with the mouse is automatically copied to the clipboard, pasting
3194  works with shift-insert.
3195 \newline
3196
3197 \newline
3198 The other good tip is to make sure you have no //c/-style paths anywhere,
3199  use /cygdrive/c/ instead.
3200  Using // invokes a network lookup which is very slow.
3201  If you think
3202 \begin_inset Quotes sld
3203 \end_inset
3204
3205 cygdrive
3206 \begin_inset Quotes srd
3207 \end_inset
3208
3209  is too long, you can change it with e.g.
3210 \layout LyX-Code
3211
3212 mount -s -u -c /mnt
3213 \layout Standard
3214
3215 SDCC sources use the unix line ending LF.
3216  Life is much easier, if you store the source tree on a drive which is mounted
3217  in binary mode.
3218  And use an editor which can handle LF-only line endings.
3219  Make sure not to commit files with windows line endings.
3220  The tabulator spacing
3221 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3222
3223 \end_inset
3224
3225  used in the project is 8.
3226  Although a tabulator spacing of 8 is a sensible choice for programmers
3227  (it's a power of 2 and allows to display 8/16 bit signed variables without
3228  loosing columns) the plan is to move towards using only spaces in the source.
3229 \layout Subsection
3230
3231 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3232 \layout Standard
3233
3234
3235 \series medium
3236 Download the source package
3237 \series default
3238  either from the SDCC CVS repository or from the
3239 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3240
3241 \end_inset
3242
3243
3244 \series medium
3245 , it will be named something like sdcc
3246 \series default
3247 .src
3248 \series medium
3249 .tgz.
3250
3251 \series default
3252  SDCC is distributed with all the projects, workspaces, and files you need
3253  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3254  doesn't build under MSVC).
3255  The workspace name is 'sdcc.dsw'.
3256  Please note that as it is now, all the executables are created in a folder
3257  called sdcc
3258 \backslash
3259 bin_vc.
3260  Once built you need to copy the executables from sdcc
3261 \backslash
3262 bin_vc to sdcc
3263 \backslash
3264 bin before running SDCC.
3265
3266 \newline
3267
3268 \newline
3269 WARNING: Visual studio is very picky with line terminations; it expects
3270  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3271  When using the CVS repository it's easiest to configure the cvs client
3272  to convert automatically for you.
3273  If however you are getting a message such as "This makefile was not generated
3274  by Developer Studio etc.
3275  etc.
3276 \begin_inset Quotes srd
3277 \end_inset
3278
3279  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3280  need to convert the Unix style line endings to DOS style line endings.
3281  To do so you can use the
3282 \begin_inset Quotes sld
3283 \end_inset
3284
3285 unix2dos
3286 \begin_inset Quotes srd
3287 \end_inset
3288
3289  utility freely available on the internet.
3290  Doug Hawkins reported in the sdcc-user list that this works:
3291 \newline
3292
3293 \newline
3294 C:
3295 \backslash
3296 Programming
3297 \backslash
3298 SDCC> unix2dos sdcc.dsw
3299 \newline
3300 C:
3301 \backslash
3302 Programming
3303 \backslash
3304 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3305 \newline
3306
3307 \newline
3308 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3309  flex.exe, and gawk.exe.
3310  One good place to get them is
3311 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3312
3313 \end_inset
3314
3315
3316 \newline
3317
3318 \newline
3319 Download the file UnxUtils
3320 \begin_inset LatexCommand \index{UnxUtils}
3321
3322 \end_inset
3323
3324 .zip.
3325  Now you have to install the utilities and setup MSVC so it can locate the
3326  required programs.
3327  Here there are two alternatives (choose one!):
3328 \layout Enumerate
3329
3330 The easy way:
3331 \newline
3332
3333 \newline
3334 a) Extract UnxUtils.zip to your C:
3335 \backslash
3336  hard disk PRESERVING the original paths, otherwise bison won't work.
3337  (If you are using WinZip make certain that 'Use folder names' is selected)
3338 \newline
3339
3340 \newline
3341 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3342  in 'Show directories for:' select 'Executable files', and in the directories
3343  window add a new path: 'C:
3344 \backslash
3345 user
3346 \backslash
3347 local
3348 \backslash
3349 wbin', click ok.
3350 \newline
3351
3352 \newline
3353 (As a side effect, you get a bunch of Unix utilities that could be useful,
3354  such as diff and patch.)
3355 \layout Enumerate
3356
3357 A more compact way:
3358 \newline
3359
3360 \newline
3361 This one avoids extracting a bunch of files you may not use, but requires
3362  some extra work:
3363 \newline
3364
3365 \newline
3366 a) Create a directory were to put the tools needed, or use a directory already
3367  present.
3368  Say for example 'C:
3369 \backslash
3370 util'.
3371 \newline
3372
3373 \newline
3374 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3375  to such directory WITHOUT preserving the original paths.
3376  (If you are using WinZip make certain that 'Use folder names' is not selected)
3377 \newline
3378
3379 \newline
3380 c) Rename bison.exe to '_bison.exe'.
3381 \newline
3382
3383 \newline
3384 d) Create a batch file 'bison.bat' in 'C:
3385 \backslash
3386 util
3387 \backslash
3388 ' and add these lines:
3389 \newline
3390 \SpecialChar ~
3391 \SpecialChar ~
3392 set BISON_SIMPLE=C:
3393 \backslash
3394 util
3395 \backslash
3396 bison.simple
3397 \newline
3398 \SpecialChar ~
3399 \SpecialChar ~
3400 set BISON_HAIRY=C:
3401 \backslash
3402 util
3403 \backslash
3404 bison.hairy
3405 \newline
3406 \SpecialChar ~
3407 \SpecialChar ~
3408 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3409 \newline
3410
3411 \newline
3412 Steps 'c' and 'd' are needed because bison requires by default that the
3413  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3414  '/usr/local/share/' I think.
3415  So it is necessary to tell bison where those files are located if they
3416  are not in such directory.
3417  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3418 \newline
3419
3420 \newline
3421 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3422  in 'Show directories for:' select 'Executable files', and in the directories
3423  window add a new path: 'c:
3424 \backslash
3425 util', click ok.
3426  Note that you can use any other path instead of 'c:
3427 \backslash
3428 util', even the path where the Visual C++ tools are, probably: 'C:
3429 \backslash
3430 Program Files
3431 \backslash
3432 Microsoft Visual Studio
3433 \backslash
3434 Common
3435 \backslash
3436 Tools'.
3437  So you don't have to execute step 'e' :)
3438 \layout Standard
3439
3440 That is it.
3441  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3442  the executables from sdcc
3443 \backslash
3444 bin_vc to sdcc
3445 \backslash
3446 bin, and you can compile using SDCC.
3447 \layout Subsection
3448
3449 Building SDCC Using Borland
3450 \layout Enumerate
3451
3452 From the sdcc directory, run the command "make -f Makefile.bcc".
3453  This should regenerate all the .exe files in the bin directory except for
3454  sdcdb.exe (which currently doesn't build under Borland C++).
3455 \layout Enumerate
3456
3457 If you modify any source files and need to rebuild, be aware that the dependenci
3458 es may not be correctly calculated.
3459  The safest option is to delete all .obj files and run the build again.
3460  From a Cygwin BASH prompt, this can easily be done with the command (be
3461  sure you are in the sdcc directory):
3462 \newline
3463
3464 \newline
3465
3466 \family sans
3467 \series bold
3468 find .
3469
3470 \backslash
3471 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3472 \backslash
3473 ) -print -exec rm {}
3474 \backslash
3475 ;
3476 \family default
3477 \series default
3478
3479 \newline
3480
3481 \newline
3482 or on Windows NT/2000/XP from the command prompt with the command:
3483 \newline
3484
3485 \family sans
3486 \series bold
3487
3488 \newline
3489 del /s *.obj *.lib *.rul
3490 \family default
3491 \series default
3492  from the sdcc directory.
3493 \layout Subsection
3494
3495 Windows Install Using a ZIP Package
3496 \layout Enumerate
3497
3498 Download the binary zip package from
3499 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3500
3501 \end_inset
3502
3503  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3504  This should unpack to a group of sub-directories.
3505  An example directory structure after unpacking the mingw32 package is:
3506  c:
3507 \backslash
3508 sdcc
3509 \backslash
3510 bin for the executables, c:
3511 \backslash
3512 sdcc
3513 \backslash
3514 include and c:
3515 \backslash
3516 sdcc
3517 \backslash
3518 lib for the include and libraries.
3519 \layout Enumerate
3520
3521 Adjust your environment variable PATH to include the location of the bin
3522  directory or start sdcc using the full path.
3523 \layout Subsection
3524
3525 Windows Install Using the Setup Program
3526 \begin_inset LatexCommand \label{sub:Windows-Install}
3527
3528 \end_inset
3529
3530
3531 \layout Standard
3532
3533 Download the setup program
3534 \emph on
3535 sdcc-x.y.z-setup.exe
3536 \emph default
3537  for an official release from
3538 \newline
3539
3540 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3541
3542 \end_inset
3543
3544  or a setup program for one of the snapshots
3545 \emph on
3546 sdcc_yyyymmdd_setup.exe
3547 \emph default
3548  from
3549 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3550
3551 \end_inset
3552
3553  and execute it.
3554  A windows typical installer will guide you through the installation process.
3555 \layout Section
3556
3557 Building the Documentation
3558 \layout Standard
3559
3560 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3561  as changing into the doc directory and typing
3562 \family sans
3563 \series bold
3564
3565 \begin_inset Quotes srd
3566 \end_inset
3567
3568 make
3569 \begin_inset Quotes srd
3570 \end_inset
3571
3572
3573 \family default
3574 \series default
3575  there.
3576  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3577 x).
3578  Using LyX
3579 \begin_inset LatexCommand \url{http://www.lyx.org}
3580
3581 \end_inset
3582
3583  as editor this is straightforward.
3584  Prebuilt documentation in html and pdf format is available from
3585 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3586
3587 \end_inset
3588
3589 .
3590 \layout Section
3591
3592 Reading the Documentation
3593 \layout Standard
3594
3595 Currently reading the document in pdf format is recommended, as for unknown
3596  reason the hyperlinks are working there whereas in the html version they
3597  are not
3598 \begin_inset Foot
3599 collapsed false
3600
3601 \layout Standard
3602
3603 If you should know why please drop us a note
3604 \end_inset
3605
3606 .
3607
3608 \newline
3609 You'll find the pdf version
3610 \begin_inset LatexCommand \index{PDF version of this document}
3611
3612 \end_inset
3613
3614  at
3615 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
3616
3617 \end_inset
3618
3619 .
3620
3621 \newline
3622 A html version
3623 \begin_inset LatexCommand \index{HTML version of this document}
3624
3625 \end_inset
3626
3627  should be online at
3628 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
3629
3630 \end_inset
3631
3632 .
3633 \newline
3634 This documentation is in some aspects different from a commercial documentation:
3635
3636 \layout Itemize
3637
3638 It tries to document SDCC for several processor architectures in one document
3639  (commercially these probably would be separate documents/products).
3640  This document
3641 \begin_inset LatexCommand \index{Status of documentation}
3642
3643 \end_inset
3644
3645  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3646 on about f.e.
3647  Z80, PIC14, PIC16 and HC08.
3648 \layout Itemize
3649
3650 There are many references pointing away from this documentation.
3651  Don't let this distract you.
3652  If there f.e.
3653  was a reference like
3654 \begin_inset LatexCommand \url{http://www.opencores.org}
3655
3656 \end_inset
3657
3658  together with a statement
3659 \begin_inset Quotes sld
3660 \end_inset
3661
3662 some processors which are targetted by SDCC can be implemented in a
3663 \emph on
3664 f
3665 \emph default
3666 ield
3667 \emph on
3668 p
3669 \emph default
3670 rogrammable
3671 \emph on
3672 g
3673 \emph default
3674 ate
3675 \emph on
3676 a
3677 \emph default
3678 rray
3679 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3680
3681 \end_inset
3682
3683
3684 \begin_inset Quotes srd
3685 \end_inset
3686
3687  we expect you to have a quick look there and come back.
3688  If you read this you are on the right track.
3689 \layout Itemize
3690
3691 Some sections attribute more space to problems, restrictions and warnings
3692  than to the solution.
3693 \layout Itemize
3694
3695 The installation section and the section about the debugger is intimidating.
3696 \layout Itemize
3697
3698 There are still lots of typos and there are more different writing styles
3699  than pictures.
3700 \layout Section
3701
3702 Testing the SDCC Compiler
3703 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3704
3705 \end_inset
3706
3707
3708 \layout Standard
3709
3710 The first thing you should do after installing your SDCC compiler is to
3711  see if it runs.
3712  Type
3713 \family sans
3714 \series bold
3715 "sdcc -
3716 \begin_inset ERT
3717 status Collapsed
3718
3719 \layout Standard
3720
3721 \backslash
3722 /
3723 \end_inset
3724
3725 -version"
3726 \begin_inset LatexCommand \index{version}
3727
3728 \end_inset
3729
3730
3731 \family default
3732 \series default
3733  at the prompt, and the program should run and tell you the version.
3734  If it doesn't run, or gives a message about not finding sdcc program, then
3735  you need to check over your installation.
3736  Make sure that the sdcc bin directory is in your executable search path
3737  defined by the PATH environment setting (
3738 \series medium
3739 see
3740 \series default
3741 section
3742 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3743
3744 \end_inset
3745
3746 \SpecialChar ~
3747
3748 \series medium
3749 Install trouble-shooting for suggestions
3750 \series default
3751 ).
3752  Make sure that the sdcc program is in the bin folder, if not perhaps something
3753  did not install correctly.
3754 \newline
3755
3756 \newline
3757
3758 \series medium
3759 SDCC
3760 \series default
3761 is commonly installed as described in section
3762 \begin_inset Quotes sld
3763 \end_inset
3764
3765 Install and search paths
3766 \begin_inset Quotes srd
3767 \end_inset
3768
3769 .
3770 \newline
3771
3772 \newline
3773
3774 \series medium
3775 Make sure the compiler works on a very simple example.
3776  Type in the following test.c program using your favorite
3777 \series default
3778 ASCII
3779 \series medium
3780 editor:
3781 \layout Verse
3782
3783
3784 \family typewriter
3785 char test;
3786 \newline
3787
3788 \newline
3789 void main(void) {
3790 \newline
3791 \SpecialChar ~
3792 \SpecialChar ~
3793 \SpecialChar ~
3794 \SpecialChar ~
3795 test=0;
3796 \newline
3797 }
3798 \layout Standard
3799
3800
3801 \series medium
3802 Compile this using the following command:
3803 \family sans
3804 \series bold
3805 "sdcc -c test.c".
3806
3807 \family default
3808 \series default
3809
3810 \series medium
3811 If all goes well, the compiler will generate a test.asm and test.rel file.
3812  Congratulations, you've just compiled your first program with SDCC.
3813  We used the -c option to tell SDCC not to link the generated code, just
3814  to keep things simple for this step.
3815 \series default
3816
3817 \newline
3818
3819 \newline
3820
3821 \series medium
3822 The next step is to try it with the linker.
3823  Type in
3824 \family sans
3825 \series bold
3826 "sdcc test.c
3827 \family default
3828 \series default
3829 "
3830 \series medium
3831 .
3832  If all goes well the compiler will link with the libraries and produce
3833  a test.ihx output file.
3834  If this step fails
3835 \series default
3836
3837 \series medium
3838 (no test.ihx, and the linker generates warnings), then the problem is most
3839  likely that
3840 \series default
3841 SDCC
3842 \series medium
3843  cannot find the
3844 \series default
3845 /
3846 \series medium
3847 usr/local/share/sdcc/lib directory
3848 \series default
3849
3850 \series medium
3851 (see
3852 \series default
3853 section
3854 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3855
3856 \end_inset
3857
3858 \SpecialChar ~
3859
3860 \series medium
3861 Install trouble-shooting for suggestions).
3862 \series default
3863
3864 \newline
3865
3866 \newline
3867
3868 \series medium
3869 The final test is to ensure
3870 \series default
3871 SDCC
3872 \series medium
3873  can use the
3874 \series default
3875 standard
3876 \series medium
3877  header files and libraries.
3878  Edit test.c and change it to the following:
3879 \layout Verse
3880
3881
3882 \family typewriter
3883 #include <string.h>
3884 \newline
3885
3886 \newline
3887 char str1[10];
3888 \newline
3889
3890 \newline
3891 void main(void) {
3892 \newline
3893 \SpecialChar ~
3894 \SpecialChar ~
3895 strcpy(str1, "testing");
3896 \newline
3897 }
3898 \layout Standard
3899
3900
3901 \series medium
3902 Compile this by typing
3903 \family sans
3904 \series bold
3905 "sdcc test.c"
3906 \family default
3907 \series medium
3908 .
3909  This should generate a test.ihx output file, and it should give no warnings
3910  such as not finding the string.h file.
3911  If it cannot find the string.h file, then the problem is that
3912 \series default
3913 SDCC
3914 \series medium
3915  cannot find the /usr/local/share/sdcc/include directory
3916 \series default
3917
3918 \series medium
3919 (see the
3920 \series default
3921 section
3922 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3923
3924 \end_inset
3925
3926 \SpecialChar ~
3927
3928 \series medium
3929 Install trouble-shooting section for suggestions).
3930
3931 \series default
3932  Use option
3933 \series bold
3934 -
3935 \begin_inset ERT
3936 status Collapsed
3937
3938 \layout Standard
3939
3940 \backslash
3941 /
3942 \end_inset
3943
3944 -print-search-dirs
3945 \series default
3946
3947 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3948
3949 \end_inset
3950
3951  to find exactly where SDCC is looking for the include and lib files.
3952 \layout Section
3953
3954 Install Trouble-shooting
3955 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3956
3957 \end_inset
3958
3959
3960 \begin_inset LatexCommand \index{Install trouble-shooting}
3961
3962 \end_inset
3963
3964
3965 \layout Subsection
3966
3967 If SDCC does not build correctly
3968 \layout Standard
3969
3970 A thing to try is starting from scratch by unpacking the .tgz source package
3971  again in an empty directory.
3972  Configure it like:
3973 \newline
3974
3975 \newline
3976
3977 \family sans
3978 \series bold
3979 ./configure 2>&1 | tee configure.log
3980 \family default
3981 \series default
3982
3983 \newline
3984
3985 \newline
3986 and build it like:
3987 \newline
3988
3989 \newline
3990
3991 \family sans
3992 \series bold
3993 make 2>&1 | tee make.log
3994 \family default
3995 \series default
3996
3997 \newline
3998
3999 \newline
4000 If anything goes wrong, you can review the log files to locate the problem.
4001  Or a relevant part of this can be attached to an email that could be helpful
4002  when requesting help from the mailing list.
4003 \layout Subsection
4004
4005 What the
4006 \begin_inset Quotes sld
4007 \end_inset
4008
4009 ./configure
4010 \begin_inset Quotes srd
4011 \end_inset
4012
4013  does
4014 \layout Standard
4015
4016 The
4017 \begin_inset Quotes sld
4018 \end_inset
4019
4020 ./configure
4021 \begin_inset Quotes srd
4022 \end_inset
4023
4024  command is a script that analyzes your system and performs some configuration
4025  to ensure the source package compiles on your system.
4026  It will take a few minutes to run, and will compile a few tests to determine
4027  what compiler features are installed.
4028 \layout Subsection
4029
4030 What the
4031 \begin_inset Quotes sld
4032 \end_inset
4033
4034 make
4035 \begin_inset Quotes srd
4036 \end_inset
4037
4038  does
4039 \layout Standard
4040
4041 This runs the GNU make tool, which automatically compiles all the source
4042  packages into the final installed binary executables.
4043 \layout Subsection
4044
4045 What the
4046 \begin_inset Quotes sld
4047 \end_inset
4048
4049 make install
4050 \begin_inset Quotes erd
4051 \end_inset
4052
4053  command does.
4054 \layout Standard
4055
4056 This will install the compiler, other executables libraries and include
4057  files into the appropriate directories.
4058  See sections
4059 \begin_inset LatexCommand \ref{sub:Install-paths}
4060
4061 \end_inset
4062
4063 ,\SpecialChar ~
4064
4065 \begin_inset LatexCommand \ref{sub:Search-Paths}
4066
4067 \end_inset
4068
4069 \SpecialChar ~
4070 about install and search paths.
4071 \newline
4072 On most systems you will need super-user privileges to do this.
4073 \layout Section
4074
4075 Components of SDCC
4076 \layout Standard
4077
4078 SDCC is not just a compiler, but a collection of tools by various developers.
4079  These include linkers, assemblers, simulators and other components.
4080  Here is a summary of some of the components.
4081  Note that the included simulator and assembler have separate documentation
4082  which you can find in the source package in their respective directories.
4083  As SDCC grows to include support for other processors, other packages from
4084  various developers are included and may have their own sets of documentation.
4085 \newline
4086
4087 \newline
4088 You might want to look at the files which are installed in <installdir>.
4089  At the time of this writing, we find the following programs for gcc-builds:
4090 \newline
4091
4092 \newline
4093 In <installdir>/bin:
4094 \layout Itemize
4095
4096 sdcc - The compiler.
4097 \layout Itemize
4098
4099 sdcpp - The C preprocessor.
4100 \layout Itemize
4101
4102 asx8051 - The assembler for 8051 type processors.
4103 \layout Itemize
4104
4105 as-z80
4106 \series bold
4107 ,
4108 \series default
4109 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4110 \layout Itemize
4111
4112 aslink -The linker for 8051 type processors.
4113 \layout Itemize
4114
4115 link-z80
4116 \series bold
4117 ,
4118 \series default
4119 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4120 \layout Itemize
4121
4122 s51 - The ucSim 8051 simulator.
4123 \layout Itemize
4124
4125 sdcdb - The source debugger.
4126 \layout Itemize
4127
4128 packihx - A tool to pack (compress) Intel hex files.
4129 \layout Standard
4130
4131 In <installdir>/share/sdcc/include
4132 \layout Itemize
4133
4134 the include files
4135 \layout Standard
4136
4137 In <installdir>/share/sdcc/lib
4138 \layout Itemize
4139
4140 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4141  relocatables.
4142 \layout Standard
4143
4144 In <installdir>/share/sdcc/doc
4145 \layout Itemize
4146
4147 the documentation
4148 \layout Standard
4149
4150 As development for other processors proceeds, this list will expand to include
4151  executables to support processors like AVR, PIC, etc.
4152 \layout Subsection
4153
4154 sdcc - The Compiler
4155 \layout Standard
4156
4157 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4158  the assembler and linkage editor.
4159 \layout Subsection
4160
4161 sdcpp - The C-Preprocessor
4162 \layout Standard
4163
4164 The preprocessor
4165 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4166
4167 \end_inset
4168
4169  is a modified version of the GNU preprocessor.
4170  The C preprocessor is used to pull in #include sources, process #ifdef
4171  statements, #defines and so on.
4172 \layout Subsection
4173
4174 as
4175 \emph on
4176 xxxx
4177 \emph default
4178 , aslink, link-
4179 \emph on
4180 xxx
4181 \emph default
4182  - The Assemblers and Linkage Editors
4183 \layout Standard
4184
4185 This is retargettable assembler & linkage editor, it was developed by Alan
4186  Baldwin.
4187  John Hartman created the version for 8051, and I (Sandeep) have made some
4188  enhancements and bug fixes for it to work properly with SDCC.
4189 \layout Subsection
4190
4191 s51 - The Simulator
4192 \layout Standard
4193
4194 S51
4195 \begin_inset LatexCommand \index{s51}
4196
4197 \end_inset
4198
4199  is a freeware, opensource simulator developed by Daniel Drotos.
4200  The simulator is built as part of the build process.
4201  For more information visit Daniel's web site at:
4202 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4203
4204 \end_inset
4205
4206 .
4207  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4208  XA51 family.
4209 \layout Subsection
4210
4211 sdcdb - Source Level Debugger
4212 \layout Standard
4213
4214 Sdcdb
4215 \begin_inset LatexCommand \index{sdcdb (debugger)}
4216
4217 \end_inset
4218
4219  is the companion source level debugger.
4220  More about sdcdb in section
4221 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4222
4223 \end_inset
4224
4225 .
4226  The current version of the debugger uses Daniel's Simulator S51
4227 \begin_inset LatexCommand \index{s51}
4228
4229 \end_inset
4230
4231 , but can be easily changed to use other simulators.
4232
4233 \layout Chapter
4234
4235 Using SDCC
4236 \layout Section
4237
4238 Compiling
4239 \layout Subsection
4240
4241 Single Source File Projects
4242 \layout Standard
4243
4244 For single source file 8051 projects the process is very simple.
4245  Compile your programs with the following command
4246 \family sans
4247 \series bold
4248 "sdcc sourcefile.c".
4249
4250 \family default
4251 \series default
4252  This will compile, assemble and link your source file.
4253  Output files are as follows:
4254 \layout Itemize
4255
4256 sourcefile.asm
4257 \begin_inset LatexCommand \index{<file>.asm}
4258
4259 \end_inset
4260
4261  - Assembler source
4262 \begin_inset LatexCommand \index{Assembler source}
4263
4264 \end_inset
4265
4266  file created by the compiler
4267 \layout Itemize
4268
4269 sourcefile.lst
4270 \begin_inset LatexCommand \index{<file>.lst}
4271
4272 \end_inset
4273
4274  - Assembler listing
4275 \begin_inset LatexCommand \index{Assembler listing}
4276
4277 \end_inset
4278
4279  file created by the Assembler
4280 \layout Itemize
4281
4282 sourcefile.rst
4283 \begin_inset LatexCommand \index{<file>.rst}
4284
4285 \end_inset
4286
4287  - Assembler listing
4288 \begin_inset LatexCommand \index{Assembler listing}
4289
4290 \end_inset
4291
4292  file updated with linkedit information, created by linkage editor
4293 \layout Itemize
4294
4295 sourcefile.sym
4296 \begin_inset LatexCommand \index{<file>.sym}
4297
4298 \end_inset
4299
4300  - symbol listing
4301 \begin_inset LatexCommand \index{Symbol listing}
4302
4303 \end_inset
4304
4305  for the sourcefile, created by the assembler
4306 \layout Itemize
4307
4308 sourcefile.rel
4309 \begin_inset LatexCommand \index{<file>.rel}
4310
4311 \end_inset
4312
4313  or sourcefile.o
4314 \begin_inset LatexCommand \index{<file>.o}
4315
4316 \end_inset
4317
4318  - Object file
4319 \begin_inset LatexCommand \index{Object file}
4320
4321 \end_inset
4322
4323  created by the assembler, input to Linkage editor
4324 \layout Itemize
4325
4326 sourcefile.map
4327 \begin_inset LatexCommand \index{<file>.map}
4328
4329 \end_inset
4330
4331  - The memory map
4332 \begin_inset LatexCommand \index{Memory map}
4333
4334 \end_inset
4335
4336  for the load module, created by the Linker
4337 \layout Itemize
4338
4339 sourcefile.mem
4340 \begin_inset LatexCommand \index{<file>.mem}
4341
4342 \end_inset
4343
4344  - A file with a summary of the memory usage
4345 \layout Itemize
4346
4347 sourcefile.ihx
4348 \begin_inset LatexCommand \index{<file>.ihx}
4349
4350 \end_inset
4351
4352  - The load module in Intel hex format
4353 \begin_inset LatexCommand \index{Intel hex format}
4354
4355 \end_inset
4356
4357  (you can select the Motorola S19 format
4358 \begin_inset LatexCommand \index{Motorola S19 format}
4359
4360 \end_inset
4361
4362  with -
4363 \begin_inset ERT
4364 status Collapsed
4365
4366 \layout Standard
4367
4368 \backslash
4369 /
4370 \end_inset
4371
4372 -out-fmt-s19
4373 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4374
4375 \end_inset
4376
4377 .
4378  If you need another format you might want to use
4379 \family sans
4380 \shape italic
4381 objdump
4382 \family default
4383 \shape default
4384
4385 \begin_inset LatexCommand \index{objdump (tool)}
4386
4387 \end_inset
4388
4389  or
4390 \family sans
4391 \shape italic
4392  srecord
4393 \family default
4394 \shape default
4395
4396 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4397
4398 \end_inset
4399
4400 ).
4401  Both formats are documented in the documentation of srecord
4402 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4403
4404 \end_inset
4405
4406
4407 \layout Itemize
4408
4409 sourcefile.adb
4410 \begin_inset LatexCommand \index{<file>.adb}
4411
4412 \end_inset
4413
4414  - An intermediate file containing debug information needed to create the
4415  .cdb file (with -
4416 \begin_inset ERT
4417 status Open
4418
4419 \layout Standard
4420
4421 \backslash
4422 /
4423 \end_inset
4424
4425 -debug
4426 \begin_inset LatexCommand \index{-\/-debug}
4427
4428 \end_inset
4429
4430 )
4431 \layout Itemize
4432
4433 sourcefile.cdb
4434 \begin_inset LatexCommand \index{<file>.cdb}
4435
4436 \end_inset
4437
4438  - An optional file (with -
4439 \begin_inset ERT
4440 status Collapsed
4441
4442 \layout Standard
4443
4444 \backslash
4445 /
4446 \end_inset
4447
4448 -debug) containing debug information.
4449  The format is documented in cdbfileformat.pdf
4450 \layout Itemize
4451
4452 sourcefile.
4453  - (no extension)
4454 \begin_inset LatexCommand \index{<file> (no extension)}
4455
4456 \end_inset
4457
4458  An optional AOMF or AOMF51
4459 \begin_inset LatexCommand \index{AOMF, AOMF51}
4460
4461 \end_inset
4462
4463  file containing debug information (generated with option -
4464 \begin_inset ERT
4465 status Collapsed
4466
4467 \layout Standard
4468
4469 \backslash
4470 /
4471 \end_inset
4472
4473 -debug).
4474  The (Intel)
4475 \emph on
4476  a
4477 \emph default
4478 bsolute
4479 \emph on
4480 o
4481 \emph default
4482 bject
4483 \emph on
4484 m
4485 \emph default
4486 odule
4487 \emph on
4488 f
4489 \emph default
4490 ormat is commonly used by third party tools (debuggers
4491 \begin_inset LatexCommand \index{Debugger}
4492
4493 \end_inset
4494
4495 , simulators, emulators)
4496 \layout Itemize
4497
4498 sourcefile.dump*
4499 \begin_inset LatexCommand \index{<file>.dump*}
4500
4501 \end_inset
4502
4503  - Dump file to debug the compiler it self (generated with option -
4504 \begin_inset ERT
4505 status Collapsed
4506
4507 \layout Standard
4508
4509 \backslash
4510 /
4511 \end_inset
4512
4513 -dumpall) (see section
4514 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4515
4516 \end_inset
4517
4518 \SpecialChar ~
4519  and section
4520 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4521
4522 \end_inset
4523
4524 \SpecialChar ~
4525
4526 \begin_inset Quotes sld
4527 \end_inset
4528
4529 Anatomy of the compiler
4530 \begin_inset Quotes srd
4531 \end_inset
4532
4533 ).
4534 \layout Subsection
4535
4536 Projects with Multiple Source Files
4537 \layout Standard
4538
4539 SDCC can compile only ONE file at a time.
4540  Let us for example assume that you have a project containing the following
4541  files:
4542 \newline
4543
4544 \newline
4545 foo1.c (contains some functions)
4546 \newline
4547 foo2.c (contains some more functions)
4548 \newline
4549 foomain.c (contains more functions and the function main)
4550 \newline
4551
4552 \size footnotesize
4553
4554 \newline
4555
4556 \size default
4557 The first two files will need to be compiled separately with the commands:
4558 \size footnotesize
4559
4560 \size default
4561
4562 \newline
4563
4564 \newline
4565
4566 \family sans
4567 \series bold
4568 sdcc\SpecialChar ~
4569 -c\SpecialChar ~
4570 foo1.c
4571 \family default
4572 \series default
4573 \size footnotesize
4574
4575 \newline
4576
4577 \family sans
4578 \series bold
4579 \size default
4580 sdcc\SpecialChar ~
4581 -c\SpecialChar ~
4582 foo2.c
4583 \family default
4584 \series default
4585
4586 \newline
4587
4588 \newline
4589 Then compile the source file containing the
4590 \emph on
4591 main()
4592 \emph default
4593  function and link
4594 \begin_inset LatexCommand \index{Linker}
4595
4596 \end_inset
4597
4598  the files together with the following command:
4599 \newline
4600
4601 \newline
4602
4603 \family sans
4604 \series bold
4605 sdcc\SpecialChar ~
4606 foomain.c\SpecialChar ~
4607 foo1.rel\SpecialChar ~
4608 foo2.rel
4609 \family default
4610 \series default
4611
4612 \begin_inset LatexCommand \index{<file>.rel}
4613
4614 \end_inset
4615
4616
4617 \newline
4618
4619 \newline
4620 Alternatively,
4621 \emph on
4622 foomain.c
4623 \emph default
4624 can be separately compiled as well:
4625 \family sans
4626 \series bold
4627
4628 \newline
4629
4630 \newline
4631 sdcc\SpecialChar ~
4632 -c\SpecialChar ~
4633 foomain.c
4634 \newline
4635 sdcc foomain.rel foo1.rel foo2.rel
4636 \newline
4637
4638 \newline
4639
4640 \family default
4641 \series default
4642 The file containing the
4643 \emph on
4644 main()
4645 \emph default
4646  function
4647 \emph on
4648
4649 \emph default
4650 \noun on
4651 must
4652 \noun default
4653  be the
4654 \noun on
4655 first
4656 \noun default
4657  file specified in the command line, since the linkage editor processes
4658  file in the order they are presented to it.
4659  The linker is invoked from SDCC using a script file with extension .lnk
4660 \begin_inset LatexCommand \index{<file>.lnk}
4661
4662 \end_inset
4663
4664 .
4665  You can view this file to troubleshoot linking problems such as those arising
4666  from missing libraries.
4667 \layout Subsection
4668
4669 Projects with Additional Libraries
4670 \begin_inset LatexCommand \index{Libraries}
4671
4672 \end_inset
4673
4674
4675 \layout Standard
4676
4677 Some reusable routines may be compiled into a library, see the documentation
4678  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4679  for how to create a
4680 \emph on
4681 .lib
4682 \begin_inset LatexCommand \index{<file>.lib}
4683
4684 \end_inset
4685
4686
4687 \emph default
4688  library file.
4689  Libraries created in this manner can be included in the command line.
4690  Make sure you include the -L <library-path> option to tell the linker where
4691  to look for these files if they are not in the current directory.
4692  Here is an example, assuming you have the source file
4693 \emph on
4694 foomain.c
4695 \emph default
4696  and a library
4697 \emph on
4698  foolib.lib
4699 \emph default
4700  in the directory
4701 \emph on
4702 mylib
4703 \emph default
4704  (if that is not the same as your current project):
4705 \newline
4706
4707 \newline
4708
4709 \family sans
4710 \series bold
4711 sdcc foomain.c foolib.lib -L mylib
4712 \newline
4713
4714 \newline
4715
4716 \family default
4717 \series default
4718 Note here that
4719 \emph on
4720  mylib
4721 \emph default
4722  must be an absolute path name.
4723 \newline
4724
4725 \newline
4726 The most efficient way to use libraries is to keep separate modules in separate
4727  source files.
4728  The lib file now should name all the modules.rel
4729 \begin_inset LatexCommand \index{<file>.rel}
4730
4731 \end_inset
4732
4733  files.
4734  For an example see the standard library file
4735 \emph on
4736 libsdcc.lib
4737 \emph default
4738  in the directory <installdir>/share/lib/small.
4739 \layout Subsection
4740
4741 Using sdcclib to Create and Manage Libraries
4742 \begin_inset LatexCommand \index{sdcclib}
4743
4744 \end_inset
4745
4746
4747 \layout Standard
4748
4749 Alternatively, instead of having a .rel file for each entry on the library
4750  file as described in the preceding section, sdcclib can be used to embed
4751  all the modules belonging to such library in the library file itself.
4752  This results in a larger library file, but it greatly reduces the number
4753  of disk files accessed by the linker.
4754   Additionally, the packed library file contains an index of all include
4755  modules and symbols that significantly speeds up the linking process.
4756  To display a list of options supported by sdcclib type:
4757 \newline
4758
4759 \layout Standard
4760
4761
4762 \family sans
4763 \series bold
4764 sdcclib -?
4765 \begin_inset LatexCommand \index{sdcclib}
4766
4767 \end_inset
4768
4769
4770 \newline
4771
4772 \newline
4773
4774 \family default
4775 \series default
4776 To create a new library file, start by compiling all the required modules.
4777  For example:
4778 \newline
4779
4780 \layout Standard
4781
4782
4783 \family sans
4784 \series bold
4785 sdcc -c _divsint.c
4786 \layout Standard
4787
4788
4789 \family sans
4790 \series bold
4791 sdcc -c _divuint.c
4792 \layout Standard
4793
4794
4795 \family sans
4796 \series bold
4797 sdcc -c _modsint.c
4798 \layout Standard
4799
4800
4801 \family sans
4802 \series bold
4803 sdcc -c _moduint.c
4804 \layout Standard
4805
4806
4807 \family sans
4808 \series bold
4809 sdcc -c _mulint.c
4810 \newline
4811
4812 \layout Standard
4813
4814 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4815  and _mulint.rel.
4816  The next step is to add the .rel files to the library file:
4817 \newline
4818
4819 \layout Standard
4820
4821
4822 \family sans
4823 \series bold
4824 sdcclib libint.lib _divsint.rel
4825 \family default
4826
4827 \begin_inset LatexCommand \index{sdcclib}
4828
4829 \end_inset
4830
4831
4832 \layout Standard
4833
4834
4835 \family sans
4836 \series bold
4837 sdcclib libint.lib _divuint.rel
4838 \layout Standard
4839
4840
4841 \family sans
4842 \series bold
4843 sdcclib libint.lib _modsint.rel
4844 \layout Standard
4845
4846
4847 \family sans
4848 \series bold
4849 sdcclib libint.lib _moduint.rel
4850 \layout Standard
4851
4852
4853 \family sans
4854 \series bold
4855 sdcclib libint.lib _mulint.rel
4856 \series default
4857
4858 \newline
4859
4860 \layout Standard
4861
4862 If the file already exists in the library, it will be replaced.
4863  To see what modules and symbols are included in the library, options -s
4864  and -m are available.
4865  For example:
4866 \newline
4867
4868 \newline
4869
4870 \family sans
4871 \series bold
4872 sdcclib -s libint.lib
4873 \family default
4874
4875 \begin_inset LatexCommand \index{sdcclib}
4876
4877 \end_inset
4878
4879
4880 \newline
4881
4882 \family typewriter
4883 \series default
4884 _divsint.rel:
4885 \layout Standard
4886
4887
4888 \family typewriter
4889 __divsint_a_1_1
4890 \layout Standard
4891
4892
4893 \family typewriter
4894 __divsint_PARM_2
4895 \layout Standard
4896
4897
4898 \family typewriter
4899 __divsint
4900 \newline
4901 _divuint.rel:
4902 \layout Standard
4903
4904
4905 \family typewriter
4906 __divuint_a_1_1
4907 \layout Standard
4908
4909
4910 \family typewriter
4911 __divuint_PARM_2
4912 \layout Standard
4913
4914
4915 \family typewriter
4916 __divuint_reste_1_1
4917 \layout Standard
4918
4919
4920 \family typewriter
4921 __divuint_count_1_1
4922 \layout Standard
4923
4924
4925 \family typewriter
4926 __divuint
4927 \newline
4928 _modsint.rel:
4929 \layout Standard
4930
4931
4932 \family typewriter
4933 __modsint_a_1_1
4934 \layout Standard
4935
4936
4937 \family typewriter
4938 __modsint_PARM_2
4939 \layout Standard
4940
4941
4942 \family typewriter
4943 __modsint
4944 \newline
4945 _moduint.rel:
4946 \layout Standard
4947
4948
4949 \family typewriter
4950 __moduint_a_1_1
4951 \layout Standard
4952
4953
4954 \family typewriter
4955 __moduint_PARM_2
4956 \layout Standard
4957
4958
4959 \family typewriter
4960 __moduint_count_1_1
4961 \layout Standard
4962
4963
4964 \family typewriter
4965 __moduint
4966 \newline
4967 _mulint.rel:
4968 \layout Standard
4969
4970
4971 \family typewriter
4972 __mulint_PARM_2
4973 \layout Standard
4974
4975
4976 \family typewriter
4977 __mulint
4978 \family default
4979 \series bold
4980
4981 \newline
4982
4983 \layout Standard
4984
4985 If the source files are compiled using -
4986 \begin_inset ERT
4987 status Open
4988
4989 \layout Standard
4990
4991 \backslash
4992 /
4993 \end_inset
4994
4995 -debug
4996 \begin_inset LatexCommand \index{-\/-debug}
4997
4998 \end_inset
4999
5000 , the corresponding debug information file .adb will be include in the library
5001  file as well.
5002  The library files created with sdcclib are plain text files, so they can
5003  be viewed with a text editor.
5004  It is not recomended to modify a library file created with sdcclib using
5005  a text editor, as there are file indexes numbers located accross the file
5006  used by the linker to quickly locate the required module to link.
5007  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5008  it can be safely deleted, since all the information required for linking
5009  is embedded in the library file itself.
5010  Library files created using sdcclib are used as described in the preceding
5011  sections.
5012 \layout Section
5013
5014 Command Line Options
5015 \begin_inset LatexCommand \index{Command Line Options}
5016
5017 \end_inset
5018
5019
5020 \layout Subsection
5021
5022 Processor Selection Options
5023 \begin_inset LatexCommand \index{Options processor selection}
5024
5025 \end_inset
5026
5027
5028 \begin_inset LatexCommand \index{Processor selection options}
5029
5030 \end_inset
5031
5032
5033 \layout List
5034 \labelwidthstring 00.00.0000
5035
5036
5037 \series bold
5038 -mmcs51
5039 \begin_inset LatexCommand \index{-mmcs51}
5040
5041 \end_inset
5042
5043
5044 \series default
5045  Generate code for the Intel MCS51
5046 \begin_inset LatexCommand \index{MCS51}
5047
5048 \end_inset
5049
5050  family of processors.
5051  This is the default processor target.
5052 \layout List
5053 \labelwidthstring 00.00.0000
5054
5055
5056 \series bold
5057 -mds390
5058 \begin_inset LatexCommand \index{-mds390}
5059
5060 \end_inset
5061
5062
5063 \series default
5064  Generate code for the Dallas DS80C390
5065 \begin_inset LatexCommand \index{DS80C390}
5066
5067 \end_inset
5068
5069  processor.
5070 \layout List
5071 \labelwidthstring 00.00.0000
5072
5073
5074 \series bold
5075 -mds400
5076 \begin_inset LatexCommand \index{-mds400}
5077
5078 \end_inset
5079
5080
5081 \series default
5082  Generate code for the Dallas DS80C400
5083 \begin_inset LatexCommand \index{DS80C400}
5084
5085 \end_inset
5086
5087  processor.
5088 \layout List
5089 \labelwidthstring 00.00.0000
5090
5091
5092 \series bold
5093 -mhc08
5094 \begin_inset LatexCommand \index{-mhc08}
5095
5096 \end_inset
5097
5098
5099 \series default
5100  Generate code for the Freescale/Motorola HC08
5101 \begin_inset LatexCommand \index{HC08}
5102
5103 \end_inset
5104
5105  family of processors.
5106 \layout List
5107 \labelwidthstring 00.00.0000
5108
5109
5110 \series bold
5111 -mz80
5112 \begin_inset LatexCommand \index{-mz80}
5113
5114 \end_inset
5115
5116
5117 \series default
5118  Generate code for the Zilog Z80
5119 \begin_inset LatexCommand \index{Z80}
5120
5121 \end_inset
5122
5123  family of processors.
5124 \layout List
5125 \labelwidthstring 00.00.0000
5126
5127
5128 \series bold
5129 -mgbz80
5130 \begin_inset LatexCommand \index{-mgbz80}
5131
5132 \end_inset
5133
5134
5135 \series default
5136  Generate code for the GameBoy Z80
5137 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5138
5139 \end_inset
5140
5141  processor (Not actively maintained).
5142 \layout List
5143 \labelwidthstring 00.00.0000
5144
5145
5146 \series bold
5147 -mavr
5148 \begin_inset LatexCommand \index{-mavr}
5149
5150 \end_inset
5151
5152
5153 \series default
5154  Generate code for the Atmel AVR
5155 \begin_inset LatexCommand \index{AVR}
5156
5157 \end_inset
5158
5159  processor (In development, not complete).
5160  AVR users should probably have a look at winavr
5161 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5162
5163 \end_inset
5164
5165  or
5166 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5167
5168 \end_inset
5169
5170 .
5171 \layout Comment
5172
5173 I think it is fair to direct users there for now.
5174  Open source is also about avoiding unnecessary work .
5175  But I didn't find the 'official' link.
5176 \layout List
5177 \labelwidthstring 00.00.0000
5178
5179
5180 \series bold
5181 -mpic14
5182 \begin_inset LatexCommand \index{-mpic14}
5183
5184 \end_inset
5185
5186
5187 \series default
5188  Generate code for the Microchip PIC 14
5189 \begin_inset LatexCommand \index{PIC14}
5190
5191 \end_inset
5192
5193 -bit processors (p16f84 and variants.
5194  In development, not complete).
5195 \layout Comment
5196
5197 p16f627 p16f628 p16f84 p16f873 p16f877?
5198 \layout List
5199 \labelwidthstring 00.00.0000
5200
5201
5202 \series bold
5203 -mpic16
5204 \begin_inset LatexCommand \index{-mpic16}
5205
5206 \end_inset
5207
5208
5209 \series default
5210  Generate code for the Microchip PIC 16
5211 \begin_inset LatexCommand \index{PIC16}
5212
5213 \end_inset
5214
5215 -bit processors (p18f452 and variants.
5216  In development, not complete).
5217 \layout List
5218 \labelwidthstring 00.00.0000
5219
5220
5221 \series bold
5222 -mtlcs900h
5223 \series default
5224  Generate code for the Toshiba TLCS-900H
5225 \begin_inset LatexCommand \index{TLCS-900H}
5226
5227 \end_inset
5228
5229  processor (Not maintained, not complete).
5230 \layout List
5231 \labelwidthstring 00.00.0000
5232
5233
5234 \series bold
5235 -mxa51
5236 \begin_inset LatexCommand \index{-mxa51}
5237
5238 \end_inset
5239
5240
5241 \series default
5242  Generate code for the Phillips XA51
5243 \begin_inset LatexCommand \index{XA51}
5244
5245 \end_inset
5246
5247  processor (Not maintained, not complete).
5248 \layout Subsection
5249
5250 Preprocessor Options
5251 \begin_inset LatexCommand \index{Options preprocessor}
5252
5253 \end_inset
5254
5255
5256 \begin_inset LatexCommand \index{Preprocessor options}
5257
5258 \end_inset
5259
5260
5261 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5262
5263 \end_inset
5264
5265
5266 \layout List
5267 \labelwidthstring 00.00.0000
5268
5269
5270 \series bold
5271 -I<path>
5272 \begin_inset LatexCommand \index{-I<path>}
5273
5274 \end_inset
5275
5276
5277 \series default
5278  The additional location where the pre processor will look for <..h> or
5279 \begin_inset Quotes eld
5280 \end_inset
5281
5282 ..h
5283 \begin_inset Quotes erd
5284 \end_inset
5285
5286  files.
5287 \layout List
5288 \labelwidthstring 00.00.0000
5289
5290
5291 \series bold
5292 -D<macro[=value]>
5293 \begin_inset LatexCommand \index{-D<macro[=value]>}
5294
5295 \end_inset
5296
5297
5298 \series default
5299  Command line definition of macros.
5300  Passed to the preprocessor.
5301 \layout List
5302 \labelwidthstring 00.00.0000
5303
5304
5305 \series bold
5306 -M
5307 \begin_inset LatexCommand \index{-M}
5308
5309 \end_inset
5310
5311
5312 \series default
5313  Tell the preprocessor to output a rule suitable for make describing the
5314  dependencies of each object file.
5315  For each source file, the preprocessor outputs one make-rule whose target
5316  is the object file name for that source file and whose dependencies are
5317  all the files `#include'd in it.
5318  This rule may be a single line or may be continued with `
5319 \backslash
5320 '-newline if it is long.
5321  The list of rules is printed on standard output instead of the preprocessed
5322  C program.
5323  `-M' implies `-E
5324 \begin_inset LatexCommand \index{-E}
5325
5326 \end_inset
5327
5328 '.
5329 \layout List
5330 \labelwidthstring 00.00.0000
5331
5332
5333 \series bold
5334 -C
5335 \begin_inset LatexCommand \index{-C}
5336
5337 \end_inset
5338
5339
5340 \series default
5341  Tell the preprocessor not to discard comments.
5342  Used with the `-E' option.
5343 \layout List
5344 \labelwidthstring 00.00.0000
5345
5346
5347 \series bold
5348 -MM
5349 \begin_inset LatexCommand \index{-MM}
5350
5351 \end_inset
5352
5353
5354 \size large
5355 \bar under
5356
5357 \series default
5358 \size default
5359 \bar default
5360 Like `-M' but the output mentions only the user header files included with
5361  `#include
5362 \begin_inset Quotes eld
5363 \end_inset
5364
5365 file"'.
5366  System header files included with `#include <file>' are omitted.
5367 \layout List
5368 \labelwidthstring 00.00.0000
5369
5370
5371 \series bold
5372 -Aquestion(answer)
5373 \begin_inset LatexCommand \index{-Aquestion(answer)}
5374
5375 \end_inset
5376
5377
5378 \series default
5379  Assert the answer answer for question, in case it is tested with a preprocessor
5380  conditional such as `#if #question(answer)'.
5381  `-A-' disables the standard assertions that normally describe the target
5382  machine.
5383 \layout List
5384 \labelwidthstring 00.00.0000
5385
5386
5387 \series bold
5388 -Umacro
5389 \begin_inset LatexCommand \index{-Umacro}
5390
5391 \end_inset
5392
5393
5394 \series default
5395  Undefine macro macro.
5396  `-U' options are evaluated after all `-D' options, but before any `-include'
5397  and `-imacros' options.
5398 \layout List
5399 \labelwidthstring 00.00.0000
5400
5401
5402 \series bold
5403 -dM
5404 \begin_inset LatexCommand \index{-dM}
5405
5406 \end_inset
5407
5408
5409 \series default
5410  Tell the preprocessor to output only a list of the macro definitions that
5411  are in effect at the end of preprocessing.
5412  Used with the `-E' option.
5413 \layout List
5414 \labelwidthstring 00.00.0000
5415
5416
5417 \series bold
5418 -dD
5419 \begin_inset LatexCommand \index{-dD}
5420
5421 \end_inset
5422
5423
5424 \series default
5425  Tell the preprocessor to pass all macro definitions into the output, in
5426  their proper sequence in the rest of the output.
5427 \layout List
5428 \labelwidthstring 00.00.0000
5429
5430
5431 \series bold
5432 -dN
5433 \begin_inset LatexCommand \index{-dN}
5434
5435 \end_inset
5436
5437
5438 \size large
5439 \bar under
5440
5441 \series default
5442 \size default
5443 \bar default
5444 Like `-dD' except that the macro arguments and contents are omitted.
5445  Only `#define name' is included in the output.
5446 \layout List
5447 \labelwidthstring 00.00.0000
5448
5449
5450 \series bold
5451 -Wp\SpecialChar ~
5452 preprocessorOption[,preprocessorOption]
5453 \series default
5454
5455 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5456
5457 \end_inset
5458
5459 ...
5460  Pass the preprocessorOption to the preprocessor
5461 \family typewriter
5462 sdcpp
5463 \family default
5464
5465 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5466
5467 \end_inset
5468
5469 .
5470  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5471  Collection (gcc), if you need more dedicated options please refer to the
5472  documentation at
5473 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5474
5475 \end_inset
5476
5477 .
5478 \layout Subsection
5479
5480 Linker Options
5481 \begin_inset LatexCommand \index{Options linker}
5482
5483 \end_inset
5484
5485
5486 \begin_inset LatexCommand \index{Linker options}
5487
5488 \end_inset
5489
5490
5491 \layout List
5492 \labelwidthstring 00.00.0000
5493
5494
5495 \series bold
5496 -L\SpecialChar ~
5497 -
5498 \series default
5499
5500 \begin_inset ERT
5501 status Collapsed
5502
5503 \layout Standard
5504
5505 \backslash
5506 /
5507 \end_inset
5508
5509
5510 \series bold
5511 -lib-path
5512 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5513
5514 \end_inset
5515
5516
5517 \begin_inset LatexCommand \index{-L -\/-lib-path}
5518
5519 \end_inset
5520
5521
5522 \series default
5523 \SpecialChar ~
5524 <absolute path to additional libraries> This option is passed to the linkage
5525  editor's additional libraries
5526 \begin_inset LatexCommand \index{Libraries}
5527
5528 \end_inset
5529
5530  search path.
5531  The path name must be absolute.
5532  Additional library files may be specified in the command line.
5533  See section Compiling programs for more details.
5534 \layout List
5535 \labelwidthstring 00.00.0000
5536
5537
5538 \series bold
5539 -
5540 \begin_inset ERT
5541 status Collapsed
5542
5543 \layout Standard
5544
5545 \backslash
5546 /
5547 \end_inset
5548
5549 -xram-loc
5550 \series default
5551
5552 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5553
5554 \end_inset
5555
5556 \SpecialChar ~
5557 <Value> The start location of the external ram
5558 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5559
5560 \end_inset
5561
5562 , default value is 0.
5563  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5564 \begin_inset ERT
5565 status Collapsed
5566
5567 \layout Standard
5568
5569 \backslash
5570 /
5571 \end_inset
5572
5573 -xram-loc 0x8000 or -
5574 \begin_inset ERT
5575 status Collapsed
5576
5577 \layout Standard
5578
5579 \backslash
5580 /
5581 \end_inset
5582
5583 -xram-loc 32768.
5584 \layout List
5585 \labelwidthstring 00.00.0000
5586
5587
5588 \series bold
5589 -
5590 \begin_inset ERT
5591 status Collapsed
5592
5593 \layout Standard
5594
5595 \backslash
5596 /
5597 \end_inset
5598
5599 -code-loc
5600 \series default
5601
5602 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5603
5604 \end_inset
5605
5606 \SpecialChar ~
5607 <Value> The start location of the code
5608 \begin_inset LatexCommand \index{code}
5609
5610 \end_inset
5611
5612  segment, default value 0.
5613  Note when this option is used the interrupt vector table is also relocated
5614  to the given address.
5615  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5616 \begin_inset ERT
5617 status Collapsed
5618
5619 \layout Standard
5620
5621 \backslash
5622 /
5623 \end_inset
5624
5625 -code-loc 0x8000 or -
5626 \begin_inset ERT
5627 status Collapsed
5628
5629 \layout Standard
5630
5631 \backslash
5632 /
5633 \end_inset
5634
5635 -code-loc 32768.
5636 \layout List
5637 \labelwidthstring 00.00.0000
5638
5639
5640 \series bold
5641 -
5642 \begin_inset ERT
5643 status Collapsed
5644
5645 \layout Standard
5646
5647 \backslash
5648 /
5649 \end_inset
5650
5651 -stack-loc
5652 \series default
5653
5654 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5655
5656 \end_inset
5657
5658 \SpecialChar ~
5659 <Value> By default the stack
5660 \begin_inset LatexCommand \index{stack}
5661
5662 \end_inset
5663
5664  is placed after the data segment.
5665  Using this option the stack can be placed anywhere in the internal memory
5666  space of the 8051.
5667  The value entered can be in Hexadecimal or Decimal format, e.g.
5668  -
5669 \begin_inset ERT
5670 status Collapsed
5671
5672 \layout Standard
5673
5674 \backslash
5675 /
5676 \end_inset
5677
5678 -stack-loc 0x20 or -
5679 \begin_inset ERT
5680 status Collapsed
5681
5682 \layout Standard
5683
5684 \backslash
5685 /
5686 \end_inset
5687
5688 -stack-loc 32.
5689  Since the sp register is incremented before a push or call, the initial
5690  sp will be set to one byte prior the provided value.
5691  The provided value should not overlap any other memory areas such as used
5692  register banks or the data segment and with enough space for the current
5693  application.
5694  The
5695 \series bold
5696 -
5697 \begin_inset ERT
5698 status Collapsed
5699
5700 \layout Standard
5701
5702 \backslash
5703 /
5704 \end_inset
5705
5706 -pack-iram
5707 \series default
5708 \SpecialChar ~
5709
5710 \begin_inset LatexCommand \index{-\/-pack-iram}
5711
5712 \end_inset
5713
5714  option (which is now a default setting) will override this setting, so
5715  you should also specify the
5716 \series bold
5717 -
5718 \begin_inset ERT
5719 status Collapsed
5720
5721 \layout Standard
5722
5723 \backslash
5724 /
5725 \end_inset
5726
5727 -no-pack-iram
5728 \series default
5729 \SpecialChar ~
5730
5731 \begin_inset LatexCommand \index{-\/-no-pack-iram}
5732
5733 \end_inset
5734
5735  option if you need to manually place the stack.
5736 \layout List
5737 \labelwidthstring 00.00.0000
5738
5739
5740 \series bold
5741 -
5742 \begin_inset ERT
5743 status Collapsed
5744
5745 \layout Standard
5746
5747 \backslash
5748 /
5749 \end_inset
5750
5751 -data-loc
5752 \series default
5753
5754 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5755
5756 \end_inset
5757
5758 \SpecialChar ~
5759 <Value> The start location of the internal ram data
5760 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5761
5762 \end_inset
5763
5764  segment.
5765  The value entered can be in Hexadecimal or Decimal format, eg.
5766  -
5767 \begin_inset ERT
5768 status Collapsed
5769
5770 \layout Standard
5771
5772 \backslash
5773 /
5774 \end_inset
5775
5776 -data-loc 0x20 or -
5777 \begin_inset ERT
5778 status Collapsed
5779
5780 \layout Standard
5781
5782 \backslash
5783 /
5784 \end_inset
5785
5786 -data-loc 32.
5787  (By default, the start location of the internal ram data segment  is set
5788  as low as possible in memory, taking into account the used register banks
5789  and the bit segment at address 0x20.
5790  For example if register banks 0 and 1 are used without bit variables, the
5791  data segment will be set, if -
5792 \begin_inset ERT
5793 status Collapsed
5794
5795 \layout Standard
5796
5797 \backslash
5798 /
5799 \end_inset
5800
5801 -data-loc is not used, to location 0x10.)
5802 \layout List
5803 \labelwidthstring 00.00.0000
5804
5805
5806 \series bold
5807 -
5808 \begin_inset ERT
5809 status Collapsed
5810
5811 \layout Standard
5812
5813 \backslash
5814 /
5815 \end_inset
5816
5817 -idata-loc
5818 \series default
5819
5820 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5821
5822 \end_inset
5823
5824 \SpecialChar ~
5825 <Value> The start location of the indirectly addressable internal ram
5826 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5827
5828 \end_inset
5829
5830  of the 8051, default value is 0x80.
5831  The value entered can be in Hexadecimal or Decimal format, eg.
5832  -
5833 \begin_inset ERT
5834 status Collapsed
5835
5836 \layout Standard
5837
5838 \backslash
5839 /
5840 \end_inset
5841
5842 -idata-loc 0x88 or -
5843 \begin_inset ERT
5844 status Collapsed
5845
5846 \layout Standard
5847
5848 \backslash
5849 /
5850 \end_inset
5851
5852 -idata-loc 136.
5853 \layout List
5854 \labelwidthstring 00.00.0000
5855
5856
5857 \series bold
5858 -
5859 \begin_inset ERT
5860 status Collapsed
5861
5862 \layout Standard
5863
5864 \backslash
5865 /
5866 \end_inset
5867
5868 -bit-loc
5869 \series default
5870 \SpecialChar ~
5871 <Value> The start location of the bit
5872 \begin_inset LatexCommand \index{bit}
5873
5874 \end_inset
5875
5876  addressable internal ram of the 8051.
5877  This is
5878 \emph on
5879 not
5880 \emph default
5881  implemented yet.
5882  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5883 -bBSEG=<Value>.
5884 \layout List
5885 \labelwidthstring 00.00.0000
5886
5887
5888 \series bold
5889 -
5890 \begin_inset ERT
5891 status Collapsed
5892
5893 \layout Standard
5894
5895 \backslash
5896 /
5897 \end_inset
5898
5899 -out-fmt-ihx
5900 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5901
5902 \end_inset
5903
5904
5905 \bar under
5906
5907 \series default
5908 \bar default
5909 The linker output (final object code) is in Intel Hex format.
5910 \begin_inset LatexCommand \index{Intel hex format}
5911
5912 \end_inset
5913
5914  This is the default option.
5915  The format itself is documented in the documentation of srecord
5916 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5917
5918 \end_inset
5919
5920 .
5921 \layout List
5922 \labelwidthstring 00.00.0000
5923
5924
5925 \series bold
5926 -
5927 \begin_inset ERT
5928 status Collapsed
5929
5930 \layout Standard
5931
5932 \backslash
5933 /
5934 \end_inset
5935
5936 -out-fmt-s19
5937 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5938
5939 \end_inset
5940
5941
5942 \bar under
5943
5944 \series default
5945 \bar default
5946 The linker output (final object code) is in Motorola S19 format
5947 \begin_inset LatexCommand \index{Motorola S19 format}
5948
5949 \end_inset
5950
5951 .
5952  The format itself is documented in the documentation of srecord.
5953 \layout List
5954 \labelwidthstring 00.00.0000
5955
5956
5957 \series bold
5958 -
5959 \begin_inset ERT
5960 status Collapsed
5961
5962 \layout Standard
5963
5964 \backslash
5965 /
5966 \end_inset
5967
5968 -out-fmt-elf
5969 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5970
5971 \end_inset
5972
5973
5974 \bar under
5975
5976 \series default
5977 \bar default
5978 The linker output (final object code) is in ELF format
5979 \begin_inset LatexCommand \index{ELF format}
5980
5981 \end_inset
5982
5983 .
5984  (Currently only supported for the HC08 processors)
5985 \layout List
5986 \labelwidthstring 00.00.0000
5987
5988
5989 \series bold
5990 -Wl\SpecialChar ~
5991 linkOption[,linkOption]
5992 \series default
5993
5994 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5995
5996 \end_inset
5997
5998 ...
5999  Pass the linkOption to the linker.
6000  See file sdcc/as/doc/asxhtm.html for more on linker options.
6001 \layout Subsection
6002
6003 MCS51 Options
6004 \begin_inset LatexCommand \index{Options MCS51}
6005
6006 \end_inset
6007
6008
6009 \begin_inset LatexCommand \index{MCS51 options}
6010
6011 \end_inset
6012
6013
6014 \layout List
6015 \labelwidthstring 00.00.0000
6016
6017
6018 \series bold
6019 -
6020 \begin_inset ERT
6021 status Collapsed
6022
6023 \layout Standard
6024
6025 \backslash
6026 /
6027 \end_inset
6028
6029 -model-small
6030 \begin_inset LatexCommand \index{-\/-model-small}
6031
6032 \end_inset
6033
6034
6035 \series default
6036 \size large
6037 \emph on
6038
6039 \size default
6040 \emph default
6041 Generate code for Small Model programs, see section Memory Models for more
6042  details.
6043  This is the default model.
6044 \layout List
6045 \labelwidthstring 00.00.0000
6046
6047
6048 \series bold
6049 -
6050 \begin_inset ERT
6051 status Collapsed
6052
6053 \layout Standard
6054
6055 \backslash
6056 /
6057 \end_inset
6058
6059 -model-large
6060 \begin_inset LatexCommand \index{-\/-model-large}
6061
6062 \end_inset
6063
6064
6065 \series default
6066  Generate code for Large model programs, see section Memory Models for more
6067  details.
6068  If this option is used all source files in the project have to be compiled
6069  with this option.
6070  It must also be used when invoking the linker.
6071 \layout List
6072 \labelwidthstring 00.00.0000
6073
6074
6075 \series bold
6076 -
6077 \begin_inset ERT
6078 status Collapsed
6079
6080 \layout Standard
6081
6082 \backslash
6083 /
6084 \end_inset
6085
6086 -xstack
6087 \begin_inset LatexCommand \index{-\/-xstack}
6088
6089 \end_inset
6090
6091
6092 \series default
6093  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6094  variables and passing parameters.
6095  See section
6096 \begin_inset LatexCommand \ref{sub:External-Stack}
6097
6098 \end_inset
6099
6100 \SpecialChar ~
6101  External Stack for more details.
6102 \layout List
6103 \labelwidthstring 00.00.0000
6104
6105
6106 \series bold
6107 -
6108 \begin_inset ERT
6109 status Collapsed
6110
6111 \layout Standard
6112
6113 \backslash
6114 /
6115 \end_inset
6116
6117 -iram-size
6118 \series default
6119 \SpecialChar ~
6120 <Value>
6121 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6122
6123 \end_inset
6124
6125  Causes the linker to check if the internal ram usage is within limits of
6126  the given value.
6127 \layout List
6128 \labelwidthstring 00.00.0000
6129
6130
6131 \series bold
6132 -
6133 \begin_inset ERT
6134 status Collapsed
6135
6136 \layout Standard
6137
6138 \backslash
6139 /
6140 \end_inset
6141
6142 -xram-size
6143 \series default
6144 \SpecialChar ~
6145 <Value>
6146 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6147
6148 \end_inset
6149
6150  Causes the linker to check if the external ram usage is within limits of
6151  the given value.
6152 \layout List
6153 \labelwidthstring 00.00.0000
6154
6155
6156 \series bold
6157 -
6158 \begin_inset ERT
6159 status Collapsed
6160
6161 \layout Standard
6162
6163 \backslash
6164 /
6165 \end_inset
6166
6167 -code-size
6168 \series default
6169 \SpecialChar ~
6170 <Value>
6171 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6172
6173 \end_inset
6174
6175  Causes the linker to check if the code memory usage is within limits of
6176  the given value.
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 -stack-size
6193 \series default
6194 \SpecialChar ~
6195 <Value>
6196 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6197
6198 \end_inset
6199
6200  Causes the linker to check if there is at minimum <Value> bytes for stack.
6201 \layout List
6202 \labelwidthstring 00.00.0000
6203
6204
6205 \series bold
6206 -
6207 \begin_inset ERT
6208 status Collapsed
6209
6210 \layout Standard
6211
6212 \backslash
6213 /
6214 \end_inset
6215
6216 -pack-iram
6217 \series default
6218 \SpecialChar ~
6219
6220 \begin_inset LatexCommand \index{-\/-pack-iram}
6221
6222 \end_inset
6223
6224  Causes the linker to use unused register banks for data variables and pack
6225  data, idata and stack together.
6226  This is the default now.
6227 \layout List
6228 \labelwidthstring 00.00.0000
6229
6230
6231 \series bold
6232 -
6233 \begin_inset ERT
6234 status Collapsed
6235
6236 \layout Standard
6237
6238 \backslash
6239 /
6240 \end_inset
6241
6242 -no-pack-iram
6243 \series default
6244 \SpecialChar ~
6245
6246 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6247
6248 \end_inset
6249
6250  Causes the linker to use old style for allocating memory areas.
6251 \layout Subsection
6252
6253 DS390 / DS400 Options
6254 \begin_inset LatexCommand \index{Options DS390}
6255
6256 \end_inset
6257
6258
6259 \begin_inset LatexCommand \index{DS390 options}
6260
6261 \end_inset
6262
6263
6264 \layout List
6265 \labelwidthstring 00.00.0000
6266
6267
6268 \series bold
6269 -
6270 \begin_inset ERT
6271 status Collapsed
6272
6273 \layout Standard
6274
6275 \backslash
6276 /
6277 \end_inset
6278
6279 -model-flat24
6280 \series default
6281
6282 \begin_inset LatexCommand \index{-\/-model-flat24}
6283
6284 \end_inset
6285
6286
6287 \size large
6288 \emph on
6289
6290 \size default
6291 \emph default
6292 Generate 24-bit flat mode code.
6293  This is the one and only that the ds390 code generator supports right now
6294  and is default when using
6295 \emph on
6296 -mds390
6297 \emph default
6298 .
6299  See section Memory Models for more details.
6300 \layout List
6301 \labelwidthstring 00.00.0000
6302
6303
6304 \series bold
6305 -
6306 \begin_inset ERT
6307 status Collapsed
6308
6309 \layout Standard
6310
6311 \backslash
6312 /
6313 \end_inset
6314
6315 -protect-sp-update
6316 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6317
6318 \end_inset
6319
6320
6321 \series default
6322  disable interrupts during ESP:SP updates.
6323 \layout List
6324 \labelwidthstring 00.00.0000
6325
6326
6327 \series bold
6328 -
6329 \begin_inset ERT
6330 status Collapsed
6331
6332 \layout Standard
6333
6334 \backslash
6335 /
6336 \end_inset
6337
6338 -stack-10bit
6339 \series default
6340
6341 \begin_inset LatexCommand \index{-\/-stack-10bit}
6342
6343 \end_inset
6344
6345  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6346  This is the one and only that the ds390 code generator supports right now
6347  and is default when using
6348 \emph on
6349 -mds390
6350 \emph default
6351 .
6352  In this mode, the stack is located in the lower 1K of the internal RAM,
6353  which is mapped to 0x400000.
6354  Note that the support is incomplete, since it still uses a single byte
6355  as the stack pointer.
6356  This means that only the lower 256 bytes of the potential 1K stack space
6357  will actually be used.
6358  However, this does allow you to reclaim the precious 256 bytes of low RAM
6359  for use for the DATA and IDATA segments.
6360  The compiler will not generate any code to put the processor into 10 bit
6361  stack mode.
6362  It is important to ensure that the processor is in this mode before calling
6363  any re-entrant functions compiled with this option.
6364  In principle, this should work with the
6365 \emph on
6366 -
6367 \begin_inset ERT
6368 status Collapsed
6369
6370 \layout Standard
6371
6372 \backslash
6373 /
6374 \end_inset
6375
6376 -stack-auto
6377 \begin_inset LatexCommand \index{-\/-stack-auto}
6378
6379 \end_inset
6380
6381
6382 \emph default
6383  option, but that has not been tested.
6384  It is incompatible with the
6385 \emph on
6386 -
6387 \begin_inset ERT
6388 status Collapsed
6389
6390 \layout Standard
6391
6392 \backslash
6393 /
6394 \end_inset
6395
6396 -xstack
6397 \begin_inset LatexCommand \index{-\/-xstack}
6398
6399 \end_inset
6400
6401
6402 \emph default
6403  option.
6404  It also only makes sense if the processor is in 24 bit contiguous addressing
6405  mode (see the
6406 \emph on
6407 -
6408 \begin_inset ERT
6409 status Collapsed
6410
6411 \layout Standard
6412
6413 \backslash
6414 /
6415 \end_inset
6416
6417 -model-flat24 option
6418 \emph default
6419 ).
6420 \layout List
6421 \labelwidthstring 00.00.0000
6422
6423
6424 \series bold
6425 -
6426 \begin_inset ERT
6427 status Collapsed
6428
6429 \layout Standard
6430
6431 \backslash
6432 /
6433 \end_inset
6434
6435 -stack-probe
6436 \begin_inset LatexCommand \index{-\/-stack-probe}
6437
6438 \end_inset
6439
6440
6441 \series default
6442  insert call to function __stack_probe at each function prologue.
6443 \layout List
6444 \labelwidthstring 00.00.0000
6445
6446
6447 \series bold
6448 -
6449 \begin_inset ERT
6450 status Collapsed
6451
6452 \layout Standard
6453
6454 \backslash
6455 /
6456 \end_inset
6457
6458 -tini-libid
6459 \begin_inset LatexCommand \index{-\/-tini-libid}
6460
6461 \end_inset
6462
6463
6464 \series default
6465  <nnnn> LibraryID used in -mTININative.
6466
6467 \layout List
6468 \labelwidthstring 00.00.0000
6469
6470
6471 \series bold
6472 -
6473 \begin_inset ERT
6474 status Collapsed
6475
6476 \layout Standard
6477
6478 \backslash
6479 /
6480 \end_inset
6481
6482 -use-accelerator
6483 \begin_inset LatexCommand \index{-\/-use-accelerator}
6484
6485 \end_inset
6486
6487
6488 \series default
6489  generate code for DS390 Arithmetic Accelerator.
6490
6491 \layout Subsection
6492
6493 Z80 Options
6494 \begin_inset LatexCommand \index{Options Z80}
6495
6496 \end_inset
6497
6498
6499 \begin_inset LatexCommand \index{Z80 options}
6500
6501 \end_inset
6502
6503
6504 \layout List
6505 \labelwidthstring 00.00.0000
6506
6507
6508 \series bold
6509 -
6510 \begin_inset ERT
6511 status Collapsed
6512
6513 \layout Standard
6514
6515 \backslash
6516 /
6517 \end_inset
6518
6519 -callee-saves-bc
6520 \series default
6521
6522 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6523
6524 \end_inset
6525
6526
6527 \size large
6528 \emph on
6529
6530 \size default
6531 \emph default
6532 Force a called function to always save BC.
6533 \layout List
6534 \labelwidthstring 00.00.0000
6535
6536
6537 \series bold
6538 -
6539 \begin_inset ERT
6540 status Collapsed
6541
6542 \layout Standard
6543
6544 \backslash
6545 /
6546 \end_inset
6547
6548 -no-std-crt0
6549 \series default
6550
6551 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6552
6553 \end_inset
6554
6555  When linking, skip the standard crt0.o object file.
6556  You must provide your own crt0.o for your system when linking.
6557
6558 \layout Subsection
6559
6560 Optimization Options
6561 \begin_inset LatexCommand \index{Options optimization}
6562
6563 \end_inset
6564
6565
6566 \begin_inset LatexCommand \index{Optimization options}
6567
6568 \end_inset
6569
6570
6571 \layout List
6572 \labelwidthstring 00.00.0000
6573
6574
6575 \series bold
6576 -
6577 \begin_inset ERT
6578 status Collapsed
6579
6580 \layout Standard
6581
6582 \backslash
6583 /
6584 \end_inset
6585
6586 -nogcse
6587 \begin_inset LatexCommand \index{-\/-nogcse}
6588
6589 \end_inset
6590
6591
6592 \series default
6593  Will not do global subexpression elimination, this option may be used when
6594  the compiler creates undesirably large stack/data spaces to store compiler
6595  temporaries (
6596 \emph on
6597 s
6598 \emph default
6599 pill
6600 \emph on
6601 loc
6602 \emph default
6603 ations, sloc
6604 \begin_inset LatexCommand \index{sloc (spill location)}
6605
6606 \end_inset
6607
6608 ).
6609  A warning message will be generated when this happens and the compiler
6610  will indicate the number of extra bytes it allocated.
6611  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6612 nogcse
6613 \begin_inset LatexCommand \index{\#pragma nogcse}
6614
6615 \end_inset
6616
6617  can be used to turn off global subexpression elimination
6618 \begin_inset LatexCommand \index{Subexpression elimination}
6619
6620 \end_inset
6621
6622  for a given function only.
6623 \layout List
6624 \labelwidthstring 00.00.0000
6625
6626
6627 \series bold
6628 -
6629 \begin_inset ERT
6630 status Collapsed
6631
6632 \layout Standard
6633
6634 \backslash
6635 /
6636 \end_inset
6637
6638 -noinvariant
6639 \begin_inset LatexCommand \index{-\/-noinvariant}
6640
6641 \end_inset
6642
6643
6644 \series default
6645  Will not do loop invariant optimizations, this may be turned off for reasons
6646  explained for the previous option.
6647  For more details of loop optimizations performed see Loop Invariants in
6648  section
6649 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6650
6651 \end_inset
6652
6653 .
6654  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6655 noinvariant
6656 \begin_inset LatexCommand \index{\#pragma noinvariant}
6657
6658 \end_inset
6659
6660  can be used to turn off invariant optimizations for a given function only.
6661 \layout List
6662 \labelwidthstring 00.00.0000
6663
6664
6665 \series bold
6666 -
6667 \begin_inset ERT
6668 status Collapsed
6669
6670 \layout Standard
6671
6672 \backslash
6673 /
6674 \end_inset
6675
6676 -noinduction
6677 \begin_inset LatexCommand \index{-\/-noinduction}
6678
6679 \end_inset
6680
6681
6682 \series default
6683  Will not do loop induction optimizations, see section strength reduction
6684  for more details.
6685  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6686 noinduction
6687 \begin_inset LatexCommand \index{\#pragma noinduction}
6688
6689 \end_inset
6690
6691  can be used to turn off induction optimizations for a given function only.
6692 \layout List
6693 \labelwidthstring 00.00.0000
6694
6695
6696 \series bold
6697 -
6698 \begin_inset ERT
6699 status Collapsed
6700
6701 \layout Standard
6702
6703 \backslash
6704 /
6705 \end_inset
6706
6707 -nojtbound
6708 \begin_inset LatexCommand \index{-\/-nojtbound}
6709
6710 \end_inset
6711
6712
6713 \size large
6714 \bar under
6715
6716 \series default
6717 \size default
6718 \bar default
6719  Will not generate boundary condition check when switch statements
6720 \begin_inset LatexCommand \index{switch statement}
6721
6722 \end_inset
6723
6724  are implemented using jump-tables.
6725  See section
6726 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6727
6728 \end_inset
6729
6730 \SpecialChar ~
6731 Switch Statements for more details.
6732  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6733 nojtbound
6734 \begin_inset LatexCommand \index{\#pragma nojtbound}
6735
6736 \end_inset
6737
6738  can be used to turn off boundary checking for jump tables for a given function
6739  only.
6740 \layout List
6741 \labelwidthstring 00.00.0000
6742
6743
6744 \series bold
6745 -
6746 \begin_inset ERT
6747 status Collapsed
6748
6749 \layout Standard
6750
6751 \backslash
6752 /
6753 \end_inset
6754
6755 -noloopreverse
6756 \begin_inset LatexCommand \index{-\/-noloopreverse}
6757
6758 \end_inset
6759
6760
6761 \series default
6762 \size large
6763
6764 \size default
6765 Will not do loop reversal
6766 \begin_inset LatexCommand \index{Loop reversing}
6767
6768 \end_inset
6769
6770 optimization.
6771 \layout List
6772 \labelwidthstring 00.00.0000
6773
6774 -
6775 \begin_inset ERT
6776 status Collapsed
6777
6778 \layout Standard
6779
6780 \backslash
6781 /
6782 \end_inset
6783
6784 -
6785 \series bold
6786 nolabelopt
6787 \series default
6788
6789 \begin_inset LatexCommand \index{-\/-nolabelopt }
6790
6791 \end_inset
6792
6793 Will not optimize labels (makes the dumpfiles more readable).
6794 \layout List
6795 \labelwidthstring 00.00.0000
6796
6797
6798 \series bold
6799 -
6800 \begin_inset ERT
6801 status Collapsed
6802
6803 \layout Standard
6804
6805 \backslash
6806 /
6807 \end_inset
6808
6809 -no-xinit-opt
6810 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6811
6812 \end_inset
6813
6814
6815 \series default
6816  Will not memcpy initialized data from code space into xdata space.
6817  This saves a few bytes in code space if you don't have initialized data
6818 \begin_inset LatexCommand \index{Variable initialization}
6819
6820 \end_inset
6821
6822 .
6823 \layout List
6824 \labelwidthstring 00.00.0000
6825
6826
6827 \series bold
6828 -
6829 \begin_inset ERT
6830 status Collapsed
6831
6832 \layout Standard
6833
6834 \backslash
6835 /
6836 \end_inset
6837
6838 -nooverlay
6839 \begin_inset LatexCommand \index{-\/-nooverlay}
6840
6841 \end_inset
6842
6843
6844 \series default
6845   The compiler will not overlay parameters and local variables of any function,
6846  see section Parameters and local variables for more details.
6847 \layout List
6848 \labelwidthstring 00.00.0000
6849
6850
6851 \series bold
6852 -
6853 \begin_inset ERT
6854 status Collapsed
6855
6856 \layout Standard
6857
6858 \backslash
6859 /
6860 \end_inset
6861
6862 -no-peep
6863 \begin_inset LatexCommand \index{-\/-no-peep}
6864
6865 \end_inset
6866
6867
6868 \series default
6869  Disable peep-hole optimization.
6870 \layout List
6871 \labelwidthstring 00.00.0000
6872
6873
6874 \series bold
6875 -
6876 \begin_inset ERT
6877 status Collapsed
6878
6879 \layout Standard
6880
6881 \backslash
6882 /
6883 \end_inset
6884
6885 -peep-file
6886 \series default
6887
6888 \begin_inset LatexCommand \index{-\/-peep-file}
6889
6890 \end_inset
6891
6892 \SpecialChar ~
6893 <filename> This option can be used to use additional rules to be used by
6894  the peep hole optimizer.
6895  See section
6896 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6897
6898 \end_inset
6899
6900 \SpecialChar ~
6901 Peep Hole optimizations for details on how to write these rules.
6902 \layout List
6903 \labelwidthstring 00.00.0000
6904
6905
6906 \series bold
6907 -
6908 \begin_inset ERT
6909 status Collapsed
6910
6911 \layout Standard
6912
6913 \backslash
6914 /
6915 \end_inset
6916
6917 -peep-asm
6918 \begin_inset LatexCommand \index{-\/-peep-asm}
6919
6920 \end_inset
6921
6922
6923 \series default
6924  Pass the inline assembler code through the peep hole optimizer.
6925  This can cause unexpected changes to inline assembler code, please go through
6926  the peephole optimizer
6927 \begin_inset LatexCommand \index{Peephole optimizer}
6928
6929 \end_inset
6930
6931  rules defined in the source file tree '<target>/peeph.def' before using
6932  this option.
6933 \layout List
6934 \labelwidthstring 00.00.0000
6935
6936
6937 \series bold
6938 -
6939 \begin_inset ERT
6940 status Collapsed
6941
6942 \layout Standard
6943
6944 \backslash
6945 /
6946 \end_inset
6947
6948 -opt-code-speed
6949 \begin_inset LatexCommand \index{-\/-opt-code-speed}
6950
6951 \end_inset
6952
6953
6954 \series default
6955  The compiler will optimize code generation towards fast code, possibly
6956  at the expense of code size.
6957 \layout List
6958 \labelwidthstring 00.00.0000
6959
6960
6961 \series bold
6962 -
6963 \begin_inset ERT
6964 status Collapsed
6965
6966 \layout Standard
6967
6968 \backslash
6969 /
6970 \end_inset
6971
6972 -opt-code-size
6973 \begin_inset LatexCommand \index{-\/-opt-code-size}
6974
6975 \end_inset
6976
6977
6978 \series default
6979  The compiler will optimize code generation towards compact code, possibly
6980  at the expense of code speed.
6981 \layout Subsection
6982
6983 Other Options
6984 \begin_inset LatexCommand \index{Options other}
6985
6986 \end_inset
6987
6988
6989 \layout List
6990 \labelwidthstring 00.00.0000
6991
6992
6993 \series bold
6994 -c\SpecialChar ~
6995 -
6996 \begin_inset ERT
6997 status Collapsed
6998
6999 \layout Standard
7000
7001 \backslash
7002 /
7003 \end_inset
7004
7005 -compile-only
7006 \begin_inset LatexCommand \index{-\/-compile-only}
7007
7008 \end_inset
7009
7010
7011 \begin_inset LatexCommand \index{-c -\/-compile-only}
7012
7013 \end_inset
7014
7015
7016 \series default
7017  will compile and assemble the source, but will not call the linkage editor.
7018 \layout List
7019 \labelwidthstring 00.00.0000
7020
7021
7022 \series bold
7023 -
7024 \series default
7025
7026 \begin_inset ERT
7027 status Collapsed
7028
7029 \layout Standard
7030
7031 \backslash
7032 /
7033 \end_inset
7034
7035
7036 \series bold
7037 -c1mode
7038 \begin_inset LatexCommand \index{-\/-c1mode}
7039
7040 \end_inset
7041
7042
7043 \series default
7044  reads the preprocessed source from standard input and compiles it.
7045  The file name for the assembler output must be specified using the -o option.
7046 \layout List
7047 \labelwidthstring 00.00.0000
7048
7049
7050 \series bold
7051 -E
7052 \begin_inset LatexCommand \index{-E}
7053
7054 \end_inset
7055
7056
7057 \series default
7058  Run only the C preprocessor.
7059  Preprocess all the C source files specified and output the results to standard
7060  output.
7061 \layout List
7062 \labelwidthstring 00.00.0000
7063
7064
7065 \series bold
7066 -o\SpecialChar ~
7067 <path/file>
7068 \begin_inset LatexCommand \index{-o <path/file>}
7069
7070 \end_inset
7071
7072
7073 \series default
7074 The output path resp.
7075  file where everything will be placed.
7076  If the parameter is a path, it must have a trailing slash (or backslash
7077  for the Windows binaries) to be recognized as a path.
7078
7079 \layout List
7080 \labelwidthstring 00.00.0000
7081
7082
7083 \series bold
7084 -
7085 \begin_inset ERT
7086 status Collapsed
7087
7088 \layout Standard
7089
7090 \backslash
7091 /
7092 \end_inset
7093
7094 -stack-auto
7095 \begin_inset LatexCommand \index{-\/-stack-auto}
7096
7097 \end_inset
7098
7099
7100 \series default
7101 \size large
7102 \emph on
7103
7104 \size default
7105 \emph default
7106 All functions in the source file will be compiled as
7107 \emph on
7108 reentrant
7109 \emph default
7110
7111 \begin_inset LatexCommand \index{reentrant}
7112
7113 \end_inset
7114
7115 , i.e.
7116  the parameters and local variables will be allocated on the stack
7117 \begin_inset LatexCommand \index{stack}
7118
7119 \end_inset
7120
7121 .
7122  See section
7123 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7124
7125 \end_inset
7126
7127  Parameters and Local Variables for more details.
7128  If this option is used all source files in the project should be compiled
7129  with this option.
7130  It automatically implies --int-long-reent and --float-reent.
7131
7132 \layout List
7133 \labelwidthstring 00.00.0000
7134
7135
7136 \series bold
7137 -
7138 \begin_inset ERT
7139 status Collapsed
7140
7141 \layout Standard
7142
7143 \backslash
7144 /
7145 \end_inset
7146
7147 -callee-saves
7148 \begin_inset LatexCommand \index{-\/-callee-saves}
7149
7150 \end_inset
7151
7152  function1[,function2][,function3]....
7153
7154 \series default
7155  The compiler by default uses a caller saves convention for register saving
7156  across function calls, however this can cause unnecessary register pushing
7157  & popping when calling small functions from larger functions.
7158  This option can be used to switch the register saving convention for the
7159  function names specified.
7160  The compiler will not save registers when calling these functions, no extra
7161  code will be generated at the entry & exit (function prologue
7162 \series bold
7163
7164 \begin_inset LatexCommand \index{function prologue}
7165
7166 \end_inset
7167
7168
7169 \series default
7170  & epilogue
7171 \series bold
7172
7173 \begin_inset LatexCommand \index{function epilogue}
7174
7175 \end_inset
7176
7177
7178 \series default
7179 ) for these functions to save & restore the registers used by these functions,
7180  this can SUBSTANTIALLY reduce code & improve run time performance of the
7181  generated code.
7182  In the future the compiler (with inter procedural analysis) will be able
7183  to determine the appropriate scheme to use for each function call.
7184  DO NOT use this option for built-in functions such as _mulint..., if this
7185  option is used for a library function the appropriate library function
7186  needs to be recompiled with the same option.
7187  If the project consists of multiple source files then all the source file
7188  should be compiled with the same -
7189 \begin_inset ERT
7190 status Collapsed
7191
7192 \layout Standard
7193
7194 \backslash
7195 /
7196 \end_inset
7197
7198 -callee-saves option string.
7199  Also see #pragma\SpecialChar ~
7200 callee_saves
7201 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7202
7203 \end_inset
7204
7205 .
7206 \layout List
7207 \labelwidthstring 00.00.0000
7208
7209
7210 \series bold
7211 -
7212 \begin_inset ERT
7213 status Collapsed
7214
7215 \layout Standard
7216
7217 \backslash
7218 /
7219 \end_inset
7220
7221 -debug
7222 \begin_inset LatexCommand \index{-\/-debug}
7223
7224 \end_inset
7225
7226
7227 \bar under
7228
7229 \series default
7230 \bar default
7231 When this option is used the compiler will generate debug information.
7232  The debug information collected in a file with .cdb extension can be used
7233  with the SDCDB.
7234  For more information see documentation for SDCDB.
7235  Another file with no extension contains debug information in AOMF or AOMF51
7236 \begin_inset LatexCommand \index{AOMF, AOMF51}
7237
7238 \end_inset
7239
7240  format which is commonly used by third party tools.
7241 \layout List
7242 \labelwidthstring 00.00.0000
7243
7244
7245 \series bold
7246 -S
7247 \begin_inset LatexCommand \index{-S}
7248
7249 \end_inset
7250
7251
7252 \size large
7253 \bar under
7254
7255 \series default
7256 \size default
7257 \bar default
7258 Stop after the stage of compilation proper; do not assemble.
7259  The output is an assembler code file for the input file specified.
7260 \layout List
7261 \labelwidthstring 00.00.0000
7262
7263
7264 \series bold
7265 -
7266 \begin_inset ERT
7267 status Collapsed
7268
7269 \layout Standard
7270
7271 \backslash
7272 /
7273 \end_inset
7274
7275 -int-long-reent
7276 \begin_inset LatexCommand \index{-\/-int-long-reent}
7277
7278 \end_inset
7279
7280
7281 \series default
7282  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7283  Note by default these libraries are compiled as non-reentrant.
7284  See section Installation for more details.
7285 \layout List
7286 \labelwidthstring 00.00.0000
7287
7288
7289 \series bold
7290 -
7291 \begin_inset ERT
7292 status Collapsed
7293
7294 \layout Standard
7295
7296 \backslash
7297 /
7298 \end_inset
7299
7300 -cyclomatic
7301 \begin_inset LatexCommand \index{-\/-cyclomatic}
7302
7303 \end_inset
7304
7305
7306 \bar under
7307
7308 \series default
7309 \bar default
7310 This option will cause the compiler to generate an information message for
7311  each function in the source file.
7312  The message contains some
7313 \emph on
7314 important
7315 \emph default
7316  information about the function.
7317  The number of edges and nodes the compiler detected in the control flow
7318  graph of the function, and most importantly the
7319 \emph on
7320 cyclomatic complexity
7321 \begin_inset LatexCommand \index{Cyclomatic complexity}
7322
7323 \end_inset
7324
7325
7326 \emph default
7327  see section on Cyclomatic Complexity for more details.
7328 \layout List
7329 \labelwidthstring 00.00.0000
7330
7331
7332 \series bold
7333 -
7334 \begin_inset ERT
7335 status Collapsed
7336
7337 \layout Standard
7338
7339 \backslash
7340 /
7341 \end_inset
7342
7343 -float-reent
7344 \begin_inset LatexCommand \index{-\/-float-reent}
7345
7346 \end_inset
7347
7348
7349 \series default
7350  Floating point library is compiled as reentrant
7351 \begin_inset LatexCommand \index{reentrant}
7352
7353 \end_inset
7354
7355 .
7356  See section Installation for more details.
7357 \layout List
7358 \labelwidthstring 00.00.0000
7359
7360
7361 \series bold
7362 -
7363 \begin_inset ERT
7364 status Collapsed
7365
7366 \layout Standard
7367
7368 \backslash
7369 /
7370 \end_inset
7371
7372 -main-return
7373 \begin_inset LatexCommand \index{-\/-main-return}
7374
7375 \end_inset
7376
7377
7378 \series default
7379  This option can be used if the code generated is called by a monitor program
7380  or if the main routine includes an endless loop.
7381  This option might result in slightly smaller code and save two bytes of
7382  stack space.
7383  The return from the 'main'
7384 \begin_inset LatexCommand \index{main return}
7385
7386 \end_inset
7387
7388  function will return to the function calling main.
7389  The default setting is to lock up i.e.
7390  generate a '
7391 \family typewriter
7392 sjmp .
7393 \family default
7394 '.
7395 \layout List
7396 \labelwidthstring 00.00.0000
7397
7398
7399 \series bold
7400 -
7401 \begin_inset ERT
7402 status Collapsed
7403
7404 \layout Standard
7405
7406 \backslash
7407 /
7408 \end_inset
7409
7410 -nostdinc
7411 \begin_inset LatexCommand \index{-\/-nostdinc}
7412
7413 \end_inset
7414
7415
7416 \series default
7417  This will prevent the compiler from passing on the default include path
7418  to the preprocessor.
7419 \layout List
7420 \labelwidthstring 00.00.0000
7421
7422
7423 \series bold
7424 -
7425 \begin_inset ERT
7426 status Collapsed
7427
7428 \layout Standard
7429
7430 \backslash
7431 /
7432 \end_inset
7433
7434 -nostdlib
7435 \begin_inset LatexCommand \index{-\/-nostdlib}
7436
7437 \end_inset
7438
7439
7440 \series default
7441  This will prevent the compiler from passing on the default library
7442 \begin_inset LatexCommand \index{Libraries}
7443
7444 \end_inset
7445
7446  path to the linker.
7447 \layout List
7448 \labelwidthstring 00.00.0000
7449
7450
7451 \series bold
7452 -
7453 \begin_inset ERT
7454 status Collapsed
7455
7456 \layout Standard
7457
7458 \backslash
7459 /
7460 \end_inset
7461
7462 -verbose
7463 \begin_inset LatexCommand \index{-\/-verbose}
7464
7465 \end_inset
7466
7467
7468 \series default
7469  Shows the various actions the compiler is performing.
7470 \layout List
7471 \labelwidthstring 00.00.0000
7472
7473
7474 \series bold
7475 -V
7476 \begin_inset LatexCommand \index{-V}
7477
7478 \end_inset
7479
7480
7481 \series default
7482  Shows the actual commands the compiler is executing.
7483 \layout List
7484 \labelwidthstring 00.00.0000
7485
7486
7487 \series bold
7488 -
7489 \begin_inset ERT
7490 status Collapsed
7491
7492 \layout Standard
7493
7494 \backslash
7495 /
7496 \end_inset
7497
7498 -no-c-code-in-asm
7499 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7500
7501 \end_inset
7502
7503
7504 \series default
7505  Hides your ugly and inefficient c-code from the asm file, so you can always
7506  blame the compiler :)
7507 \layout List
7508 \labelwidthstring 00.00.0000
7509
7510
7511 \series bold
7512 -
7513 \begin_inset ERT
7514 status Collapsed
7515
7516 \layout Standard
7517
7518 \backslash
7519 /
7520 \end_inset
7521
7522 -no-peep-comments
7523 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7524
7525 \end_inset
7526
7527
7528 \series default
7529  Will not include peep-hole comments in the generated files.
7530 \layout List
7531 \labelwidthstring 00.00.0000
7532
7533
7534 \series bold
7535 -
7536 \begin_inset ERT
7537 status Collapsed
7538
7539 \layout Standard
7540
7541 \backslash
7542 /
7543 \end_inset
7544
7545 -i-code-in-asm
7546 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7547
7548 \end_inset
7549
7550
7551 \series default
7552  Include i-codes in the asm file.
7553  Sounds like noise but is most helpful for debugging the compiler itself.
7554 \layout List
7555 \labelwidthstring 00.00.0000
7556
7557
7558 \series bold
7559 -
7560 \begin_inset ERT
7561 status Collapsed
7562
7563 \layout Standard
7564
7565 \backslash
7566 /
7567 \end_inset
7568
7569 -less-pedantic
7570 \begin_inset LatexCommand \index{-\/-less-pedantic}
7571
7572 \end_inset
7573
7574
7575 \series default
7576  Disable some of the more pedantic warnings
7577 \begin_inset LatexCommand \index{Warnings}
7578
7579 \end_inset
7580
7581  (jwk burps: please be more specific here, please!).
7582 \layout List
7583 \labelwidthstring 00.00.0000
7584
7585
7586 \series bold
7587 -
7588 \begin_inset ERT
7589 status Collapsed
7590
7591 \layout Standard
7592
7593 \backslash
7594 /
7595 \end_inset
7596
7597 -disable-warning\SpecialChar ~
7598 <nnnn>
7599 \begin_inset LatexCommand \index{-\/-disable-warning}
7600
7601 \end_inset
7602
7603
7604 \series default
7605  Disable specific warning with number <nnnn>.
7606 \layout List
7607 \labelwidthstring 00.00.0000
7608
7609
7610 \series bold
7611 -
7612 \begin_inset ERT
7613 status Collapsed
7614
7615 \layout Standard
7616
7617 \backslash
7618 /
7619 \end_inset
7620
7621 -print-search-dirs
7622 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7623
7624 \end_inset
7625
7626
7627 \series default
7628  Display the directories in the compiler's search path
7629 \layout List
7630 \labelwidthstring 00.00.0000
7631
7632
7633 \series bold
7634 -
7635 \begin_inset ERT
7636 status Collapsed
7637
7638 \layout Standard
7639
7640 \backslash
7641 /
7642 \end_inset
7643
7644 -vc
7645 \begin_inset LatexCommand \index{-\/-vc}
7646
7647 \end_inset
7648
7649
7650 \series default
7651  Display errors and warnings using MSVC style, so you can use SDCC with
7652  visual studio.
7653 \layout List
7654 \labelwidthstring 00.00.0000
7655
7656
7657 \series bold
7658 -
7659 \begin_inset ERT
7660 status Collapsed
7661
7662 \layout Standard
7663
7664 \backslash
7665 /
7666 \end_inset
7667
7668 -use-stdout
7669 \begin_inset LatexCommand \index{-\/-use-stdout}
7670
7671 \end_inset
7672
7673
7674 \series default
7675  Send errors and warnings to stdout instead of stderr.
7676 \layout List
7677 \labelwidthstring 00.00.0000
7678
7679
7680 \series bold
7681 -Wa\SpecialChar ~
7682 asmOption[,asmOption]
7683 \series default
7684
7685 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7686
7687 \end_inset
7688
7689 ...
7690  Pass the asmOption to the assembler
7691 \begin_inset LatexCommand \index{Options assembler}
7692
7693 \end_inset
7694
7695
7696 \begin_inset LatexCommand \index{Assembler options}
7697
7698 \end_inset
7699
7700 .
7701  See file sdcc/as/doc/asxhtm.html for assembler options.cd
7702 \layout List
7703 \labelwidthstring 00.00.0000
7704
7705
7706 \series bold
7707 -
7708 \begin_inset ERT
7709 status Collapsed
7710
7711 \layout Standard
7712
7713 \backslash
7714 /
7715 \end_inset
7716
7717 -std-sdcc89
7718 \begin_inset LatexCommand \index{-\/-std-sdcc89}
7719
7720 \end_inset
7721
7722
7723 \series default
7724  Generally follow the C89 standard, but allow SDCC features that conflict
7725  with the standard (default).
7726 \layout List
7727 \labelwidthstring 00.00.0000
7728
7729
7730 \series bold
7731 -
7732 \begin_inset ERT
7733 status Collapsed
7734
7735 \layout Standard
7736
7737 \backslash
7738 /
7739 \end_inset
7740
7741 -std-c89
7742 \begin_inset LatexCommand \index{-\/-std-c89}
7743
7744 \end_inset
7745
7746
7747 \series default
7748  Follow the C89 standard and disable SDCC features that conflict with the
7749  standard.
7750 \layout List
7751 \labelwidthstring 00.00.0000
7752
7753
7754 \series bold
7755 -
7756 \begin_inset ERT
7757 status Collapsed
7758
7759 \layout Standard
7760
7761 \backslash
7762 /
7763 \end_inset
7764
7765 -std-sdcc99
7766 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7767
7768 \end_inset
7769
7770
7771 \series default
7772  Generally follow the C99 standard, but allow SDCC features that conflict
7773  with the standard (incomplete support).
7774 \layout List
7775 \labelwidthstring 00.00.0000
7776
7777
7778 \series bold
7779 -
7780 \begin_inset ERT
7781 status Collapsed
7782
7783 \layout Standard
7784
7785 \backslash
7786 /
7787 \end_inset
7788
7789 -std-c99
7790 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7791
7792 \end_inset
7793
7794
7795 \series default
7796  Follow the C99 standard and disable SDCC features that conflict with the
7797  standard (incomplete support).
7798 \layout List
7799 \labelwidthstring 00.00.0000
7800
7801
7802 \series bold
7803 -
7804 \begin_inset ERT
7805 status Collapsed
7806
7807 \layout Standard
7808
7809 \backslash
7810 /
7811 \end_inset
7812
7813 -codeseg
7814 \series default
7815
7816 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
7817
7818 \end_inset
7819
7820 \SpecialChar ~
7821 <Name> The name to be used for the code
7822 \begin_inset LatexCommand \index{code}
7823
7824 \end_inset
7825
7826  segment, default CSEG.
7827  This is useful if you need to tell the compiler to put the code in a special
7828  segment so you can later on tell the linker to put this segment in a special
7829  place in memory.
7830  Can be used for instance when using bank switching to put the code in a
7831  bank.
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 -constseg
7848 \series default
7849
7850 \begin_inset LatexCommand \index{-\/-constseg <Value>}
7851
7852 \end_inset
7853
7854 \SpecialChar ~
7855 <Name> The name to be used for the const
7856 \begin_inset LatexCommand \index{code}
7857
7858 \end_inset
7859
7860  segment, default CONST.
7861  This is useful if you need to tell the compiler to put the const data in
7862  a special segment so you can later on tell the linker to put this segment
7863  in a special place in memory.
7864  Can be used for instance when using bank switching to put the const data
7865  in a bank.
7866 \layout List
7867 \labelwidthstring 00.00.0000
7868
7869
7870 \series bold
7871 more-pedantic
7872 \series default
7873  Actually this is
7874 \series bold
7875 \emph on
7876 not
7877 \series default
7878 \emph default
7879  a SDCC compiler option but if you want
7880 \emph on
7881 more
7882 \emph default
7883  warnings you can use a separate tool dedicated to syntax checking like
7884  splint
7885 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
7886
7887 \end_inset
7888
7889
7890 \begin_inset LatexCommand \index{lint (syntax checking tool)}
7891
7892 \end_inset
7893
7894
7895 \begin_inset LatexCommand \url{http://www.splint.org}
7896
7897 \end_inset
7898
7899 .
7900  To make your source files parseable by splint you will have to include
7901
7902 \family sans
7903 lint.h
7904 \family default
7905
7906 \begin_inset LatexCommand \index{splint (syntax checking tool)}
7907
7908 \end_inset
7909
7910  in your source file and add brackets around extended keywords (like
7911 \family sans
7912
7913 \begin_inset Quotes sld
7914 \end_inset
7915
7916 __at\SpecialChar ~
7917
7918 \series bold
7919 (
7920 \series default
7921 0xab
7922 \series bold
7923 )
7924 \series default
7925
7926 \begin_inset Quotes srd
7927 \end_inset
7928
7929
7930 \family default
7931  and
7932 \family sans
7933
7934 \begin_inset Quotes sld
7935 \end_inset
7936
7937 __interrupt\SpecialChar ~
7938 (2)
7939 \begin_inset Quotes srd
7940 \end_inset
7941
7942
7943 \family default
7944 ).
7945
7946 \newline
7947 Splint has an excellent on line manual at
7948 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
7949
7950 \end_inset
7951
7952  and it's capabilities go beyond pure syntax checking.
7953  You'll need to tell splint the location of SDCC's include files so a typical
7954  command line could look like this:
7955 \newline
7956
7957 \family sans
7958 splint\SpecialChar ~
7959 -I\SpecialChar ~
7960 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
7961 \SpecialChar ~
7962 myprogram.c
7963 \layout Subsection
7964
7965 Intermediate Dump Options
7966 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7967
7968 \end_inset
7969
7970
7971 \begin_inset LatexCommand \index{Options intermediate dump}
7972
7973 \end_inset
7974
7975
7976 \begin_inset LatexCommand \index{Intermediate dump options}
7977
7978 \end_inset
7979
7980
7981 \layout Standard
7982
7983 The following options are provided for the purpose of retargetting and debugging
7984  the compiler.
7985  They provide a means to dump the intermediate code (iCode
7986 \begin_inset LatexCommand \index{iCode}
7987
7988 \end_inset
7989
7990 ) generated by the compiler in human readable form at various stages of
7991  the compilation process.
7992  More on iCodes see chapter
7993 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7994
7995 \end_inset
7996
7997
7998 \begin_inset Quotes srd
7999 \end_inset
8000
8001 The anatomy of the compiler
8002 \begin_inset Quotes srd
8003 \end_inset
8004
8005 .
8006 \layout List
8007 \labelwidthstring 00.00.0000
8008
8009
8010 \series bold
8011 -
8012 \begin_inset ERT
8013 status Collapsed
8014
8015 \layout Standard
8016
8017 \backslash
8018 /
8019 \end_inset
8020
8021 -dumpraw
8022 \begin_inset LatexCommand \index{-\/-dumpraw}
8023
8024 \end_inset
8025
8026
8027 \series default
8028  This option will cause the compiler to dump the intermediate code into
8029  a file of named
8030 \emph on
8031 <source filename>.dumpraw
8032 \emph default
8033  just after the intermediate code has been generated for a function, i.e.
8034  before any optimizations are done.
8035  The basic blocks
8036 \begin_inset LatexCommand \index{Basic blocks}
8037
8038 \end_inset
8039
8040  at this stage ordered in the depth first number, so they may not be in
8041  sequence of execution.
8042 \layout List
8043 \labelwidthstring 00.00.0000
8044
8045
8046 \series bold
8047 -
8048 \begin_inset ERT
8049 status Collapsed
8050
8051 \layout Standard
8052
8053 \backslash
8054 /
8055 \end_inset
8056
8057 -dumpgcse
8058 \begin_inset LatexCommand \index{-\/-dumpgcse}
8059
8060 \end_inset
8061
8062
8063 \series default
8064  Will create a dump of iCode's, after global subexpression elimination
8065 \begin_inset LatexCommand \index{Global subexpression elimination}
8066
8067 \end_inset
8068
8069 , into a file named
8070 \emph on
8071 <source filename>.dumpgcse.
8072 \layout List
8073 \labelwidthstring 00.00.0000
8074
8075
8076 \series bold
8077 -
8078 \begin_inset ERT
8079 status Collapsed
8080
8081 \layout Standard
8082
8083 \backslash
8084 /
8085 \end_inset
8086
8087 -dumpdeadcode
8088 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8089
8090 \end_inset
8091
8092
8093 \series default
8094  Will create a dump of iCode's, after deadcode elimination
8095 \begin_inset LatexCommand \index{Dead-code elimination}
8096
8097 \end_inset
8098
8099 , into a file named
8100 \emph on
8101 <source filename>.dumpdeadcode.
8102 \layout List
8103 \labelwidthstring 00.00.0000
8104
8105
8106 \series bold
8107 -
8108 \begin_inset ERT
8109 status Collapsed
8110
8111 \layout Standard
8112
8113 \backslash
8114 /
8115 \end_inset
8116
8117 -dumploop
8118 \begin_inset LatexCommand \index{-\/-dumploop}
8119
8120 \end_inset
8121
8122
8123 \series default
8124 \size large
8125
8126 \size default
8127 Will create a dump of iCode's, after loop optimizations
8128 \begin_inset LatexCommand \index{Loop optimization}
8129
8130 \end_inset
8131
8132 , into a file named
8133 \emph on
8134 <source filename>.dumploop.
8135 \layout List
8136 \labelwidthstring 00.00.0000
8137
8138
8139 \series bold
8140 -
8141 \begin_inset ERT
8142 status Collapsed
8143
8144 \layout Standard
8145
8146 \backslash
8147 /
8148 \end_inset
8149
8150 -dumprange
8151 \begin_inset LatexCommand \index{-\/-dumprange}
8152
8153 \end_inset
8154
8155
8156 \series default
8157 \size large
8158
8159 \size default
8160 Will create a dump of iCode's, after live range analysis
8161 \begin_inset LatexCommand \index{Live range analysis}
8162
8163 \end_inset
8164
8165 , into a file named
8166 \emph on
8167 <source filename>.dumprange.
8168 \layout List
8169 \labelwidthstring 00.00.0000
8170
8171
8172 \series bold
8173 -
8174 \begin_inset ERT
8175 status Collapsed
8176
8177 \layout Standard
8178
8179 \backslash
8180 /
8181 \end_inset
8182
8183 -dumlrange
8184 \begin_inset LatexCommand \index{-\/-dumlrange}
8185
8186 \end_inset
8187
8188
8189 \series default
8190  Will dump the life ranges
8191 \begin_inset LatexCommand \index{Live range analysis}
8192
8193 \end_inset
8194
8195  for all symbols.
8196 \layout List
8197 \labelwidthstring 00.00.0000
8198
8199
8200 \series bold
8201 -
8202 \begin_inset ERT
8203 status Collapsed
8204
8205 \layout Standard
8206
8207 \backslash
8208 /
8209 \end_inset
8210
8211 -dumpregassign
8212 \begin_inset LatexCommand \index{-\/-dumpregassign}
8213
8214 \end_inset
8215
8216
8217 \bar under
8218
8219 \series default
8220 \bar default
8221 Will create a dump of iCode's, after register assignment
8222 \begin_inset LatexCommand \index{Register assignment}
8223
8224 \end_inset
8225
8226 , into a file named
8227 \emph on
8228 <source filename>.dumprassgn.
8229 \layout List
8230 \labelwidthstring 00.00.0000
8231
8232
8233 \series bold
8234 -
8235 \begin_inset ERT
8236 status Collapsed
8237
8238 \layout Standard
8239
8240 \backslash
8241 /
8242 \end_inset
8243
8244 -dumplrange
8245 \begin_inset LatexCommand \index{-\/-dumplrange}
8246
8247 \end_inset
8248
8249
8250 \series default
8251  Will create a dump of the live ranges of iTemp's
8252 \layout List
8253 \labelwidthstring 00.00.0000
8254
8255
8256 \series bold
8257 -
8258 \begin_inset ERT
8259 status Collapsed
8260
8261 \layout Standard
8262
8263 \backslash
8264 /
8265 \end_inset
8266
8267 -dumpall
8268 \begin_inset LatexCommand \index{-\/-dumpall}
8269
8270 \end_inset
8271
8272
8273 \size large
8274 \bar under
8275
8276 \series default
8277 \size default
8278 \bar default
8279 Will cause all the above mentioned dumps to be created.
8280 \layout Subsection
8281
8282 Redirecting output on Windows Shells
8283 \layout Standard
8284
8285 By default SDCC writes it's error messages to
8286 \begin_inset Quotes sld
8287 \end_inset
8288
8289 standard error
8290 \begin_inset Quotes srd
8291 \end_inset
8292
8293 .
8294  To force all messages to
8295 \begin_inset Quotes sld
8296 \end_inset
8297
8298 standard output
8299 \begin_inset Quotes srd
8300 \end_inset
8301
8302  use
8303 \series bold
8304 -
8305 \series default
8306 \emph on
8307
8308 \begin_inset ERT
8309 status Collapsed
8310
8311 \layout Standard
8312
8313 \backslash
8314 /
8315 \end_inset
8316
8317
8318 \series bold
8319 \emph default
8320 -
8321 \series default
8322 use-stdout
8323 \begin_inset LatexCommand \index{-\/-use-stdout}
8324
8325 \end_inset
8326
8327 .
8328  Additionally, if you happen to have visual studio installed in your windows
8329  machine, you can use it to compile your sources using a custom build and
8330  the SDCC -
8331 \emph on
8332
8333 \begin_inset ERT
8334 status Collapsed
8335
8336 \layout Standard
8337
8338 \backslash
8339 /
8340 \end_inset
8341
8342
8343 \emph default
8344 -vc
8345 \begin_inset LatexCommand \index{-\/-vc}
8346
8347 \end_inset
8348
8349  option.
8350  Something like this should work:
8351 \newline
8352
8353 \newline
8354
8355 \series bold
8356 c:
8357 \backslash
8358 sdcc
8359 \backslash
8360 bin
8361 \backslash
8362 sdcc.exe -
8363 \series default
8364 \emph on
8365
8366 \begin_inset ERT
8367 status Collapsed
8368
8369 \layout Standard
8370
8371 \backslash
8372 /
8373 \end_inset
8374
8375
8376 \series bold
8377 \emph default
8378 -vc -
8379 \series default
8380 \emph on
8381
8382 \begin_inset ERT
8383 status Collapsed
8384
8385 \layout Standard
8386
8387 \backslash
8388 /
8389 \end_inset
8390
8391
8392 \series bold
8393 \emph default
8394 -model-large -c $(InputPath)
8395 \layout Section
8396
8397 Environment variables
8398 \begin_inset LatexCommand \index{Environment variables}
8399
8400 \end_inset
8401
8402
8403 \layout Standard
8404
8405 SDCC recognizes the following environment variables:
8406 \layout List
8407 \labelwidthstring 00.00.0000
8408
8409
8410 \series bold
8411 SDCC_LEAVE_SIGNALS
8412 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
8413
8414 \end_inset
8415
8416
8417 \series default
8418  SDCC installs a signal handler
8419 \begin_inset LatexCommand \index{signal handler}
8420
8421 \end_inset
8422
8423  to be able to delete temporary files after an user break (^C) or an exception.
8424  If this environment variable is set, SDCC won't install the signal handler
8425  in order to be able to debug SDCC.
8426 \layout List
8427 \labelwidthstring 00.00.0000
8428
8429
8430 \series bold
8431 TMP,\SpecialChar ~
8432 TEMP,\SpecialChar ~
8433 TMPDIR
8434 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
8435
8436 \end_inset
8437
8438
8439 \series default
8440  Path, where temporary files will be created.
8441  The order of the variables is the search order.
8442  In a standard *nix environment these variables are not set, and there's
8443  no need to set them.
8444  On Windows it's recommended to set one of them.
8445 \layout List
8446 \labelwidthstring 00.00.0000
8447
8448
8449 \series bold
8450 SDCC_HOME
8451 \begin_inset LatexCommand \index{SDCC\_HOME}
8452
8453 \end_inset
8454
8455
8456 \series default
8457  Path, see section
8458 \begin_inset LatexCommand \ref{sub:Install-paths}
8459
8460 \end_inset
8461
8462 \SpecialChar ~
8463
8464 \begin_inset Quotes sld
8465 \end_inset
8466
8467  Install Paths
8468 \begin_inset Quotes srd
8469 \end_inset
8470
8471 .
8472 \layout List
8473 \labelwidthstring 00.00.0000
8474
8475
8476 \series bold
8477 SDCC_INCLUDE
8478 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8479
8480 \end_inset
8481
8482
8483 \series default
8484  Path, see section
8485 \begin_inset LatexCommand \ref{sub:Search-Paths}
8486
8487 \end_inset
8488
8489 \SpecialChar ~
8490
8491 \begin_inset Quotes sld
8492 \end_inset
8493
8494 Search Paths
8495 \begin_inset Quotes srd
8496 \end_inset
8497
8498 .
8499 \layout List
8500 \labelwidthstring 00.00.0000
8501
8502
8503 \series bold
8504 SDCC_LIB
8505 \begin_inset LatexCommand \index{SDCC\_LIB}
8506
8507 \end_inset
8508
8509
8510 \series default
8511  Path, see section
8512 \begin_inset LatexCommand \ref{sub:Search-Paths}
8513
8514 \end_inset
8515
8516 \SpecialChar ~
8517
8518 \begin_inset Quotes sld
8519 \end_inset
8520
8521 Search Paths
8522 \begin_inset Quotes srd
8523 \end_inset
8524
8525 ..
8526 \layout Standard
8527
8528 There are some more environment variables recognized by SDCC, but these
8529  are solely used for debugging purposes.
8530  They can change or disappear very quickly, and will never be documented.
8531 \layout Section
8532
8533 Storage Class Language Extensions
8534 \layout Subsection
8535
8536 MCS51/DS390 Storage Class
8537 \begin_inset LatexCommand \index{Storage class}
8538
8539 \end_inset
8540
8541  Language Extensions
8542 \layout Standard
8543
8544 In addition to the ANSI storage classes SDCC allows the following MCS51
8545  specific storage classes:
8546 \layout Subsubsection
8547
8548 data
8549 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8550
8551 \end_inset
8552
8553
8554 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
8555
8556 \end_inset
8557
8558  / near
8559 \begin_inset LatexCommand \index{near (storage class)}
8560
8561 \end_inset
8562
8563
8564 \begin_inset LatexCommand \index{\_\_near (storage class)}
8565
8566 \end_inset
8567
8568
8569 \layout Standard
8570
8571 This is the
8572 \series bold
8573 default
8574 \series default
8575  storage class for the Small Memory model (
8576 \emph on
8577 data
8578 \emph default
8579  and
8580 \emph on
8581 near
8582 \emph default
8583  can be used synonymously).
8584  Variables declared with this storage class will be allocated in the directly
8585  addressable portion of the internal RAM of a 8051, e.g.:
8586 \layout Verse
8587
8588
8589 \family typewriter
8590 data unsigned char test_data;
8591 \layout Standard
8592
8593 Writing 0x01 to this variable generates the assembly code:
8594 \layout Verse
8595
8596
8597 \family typewriter
8598 75*00 01\SpecialChar ~
8599 \SpecialChar ~
8600 \SpecialChar ~
8601 mov\SpecialChar ~
8602 \SpecialChar ~
8603 _test_data,#0x01
8604 \layout Subsubsection
8605
8606 xdata
8607 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8608
8609 \end_inset
8610
8611
8612 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
8613
8614 \end_inset
8615
8616  / far
8617 \begin_inset LatexCommand \index{far (storage class)}
8618
8619 \end_inset
8620
8621
8622 \begin_inset LatexCommand \index{\_\_far (storage class)}
8623
8624 \end_inset
8625
8626
8627 \layout Standard
8628
8629 Variables declared with this storage class will be placed in the external
8630  RAM.
8631  This is the
8632 \series bold
8633 default
8634 \series default
8635  storage class for the Large Memory model, e.g.:
8636 \layout Verse
8637
8638
8639 \family typewriter
8640 xdata unsigned char test_xdata;
8641 \layout Standard
8642
8643 Writing 0x01 to this variable generates the assembly code:
8644 \layout Verse
8645
8646
8647 \family typewriter
8648 90s00r00\SpecialChar ~
8649 \SpecialChar ~
8650 \SpecialChar ~
8651 mov\SpecialChar ~
8652 \SpecialChar ~
8653 dptr,#_test_xdata
8654 \newline
8655 74\SpecialChar ~
8656 01\SpecialChar ~
8657 \SpecialChar ~
8658 \SpecialChar ~
8659 \SpecialChar ~
8660 \SpecialChar ~
8661 \SpecialChar ~
8662 mov\SpecialChar ~
8663 \SpecialChar ~
8664 a,#0x01
8665 \newline
8666 F0\SpecialChar ~
8667 \SpecialChar ~
8668 \SpecialChar ~
8669 \SpecialChar ~
8670 \SpecialChar ~
8671 \SpecialChar ~
8672 \SpecialChar ~
8673 \SpecialChar ~
8674 \SpecialChar ~
8675 movx\SpecialChar ~
8676 @dptr,a
8677 \layout Subsubsection
8678
8679 idata
8680 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8681
8682 \end_inset
8683
8684
8685 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
8686
8687 \end_inset
8688
8689
8690 \layout Standard
8691
8692 Variables declared with this storage class will be allocated into the indirectly
8693  addressable portion of the internal ram of a 8051, e.g.:
8694 \layout Verse
8695
8696
8697 \family typewriter
8698 idata unsigned char test_idata;
8699 \layout Standard
8700
8701 Writing 0x01 to this variable generates the assembly code:
8702 \layout Verse
8703
8704
8705 \family typewriter
8706 78r00\SpecialChar ~
8707 \SpecialChar ~
8708 \SpecialChar ~
8709 \SpecialChar ~
8710 \SpecialChar ~
8711 \SpecialChar ~
8712 \SpecialChar ~
8713 mov\SpecialChar ~
8714 \SpecialChar ~
8715 r0,#_test_idata
8716 \newline
8717 76\SpecialChar ~
8718 01\SpecialChar ~
8719 \SpecialChar ~
8720 \SpecialChar ~
8721 \SpecialChar ~
8722 \SpecialChar ~
8723 \SpecialChar ~
8724 \SpecialChar ~
8725 mov\SpecialChar ~
8726 \SpecialChar ~
8727 @r0,#0x01
8728 \layout Standard
8729
8730 Please note, the first 128 byte of idata physically access the same RAM
8731  as the data memory.
8732  The original 8051 had 128 byte idata memory, nowadays most devices have
8733  256 byte idata memory.
8734  The stack
8735 \begin_inset LatexCommand \index{stack}
8736
8737 \end_inset
8738
8739  is located in idata memory.
8740 \layout Subsubsection
8741
8742 pdata
8743 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8744
8745 \end_inset
8746
8747
8748 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
8749
8750 \end_inset
8751
8752
8753 \layout Standard
8754
8755 Paged xdata access is just as straightforward as using the other addressing
8756  modes of a 8051.
8757  It is typically located at the start of xdata and has a maximum size of
8758  256 bytes.
8759  The following example writes 0x01 to the pdata variable.
8760  Please note, pdata access physically accesses xdata memory.
8761  The high byte of the address is determined by port P2
8762 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8763
8764 \end_inset
8765
8766 (or in case of some 8051 variants by a separate Special Function Register,
8767  see section
8768 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8769
8770 \end_inset
8771
8772 ).
8773 \layout Verse
8774
8775
8776 \family typewriter
8777 pdata unsigned char test_pdata;
8778 \layout Standard
8779
8780 Writing 0x01 to this variable generates the assembly code:
8781 \layout Verse
8782
8783
8784 \family typewriter
8785 78r00\SpecialChar ~
8786 \SpecialChar ~
8787 \SpecialChar ~
8788 \SpecialChar ~
8789 \SpecialChar ~
8790 \SpecialChar ~
8791 mov r0,#_test_pdata
8792 \newline
8793 74 01\SpecialChar ~
8794 \SpecialChar ~
8795 \SpecialChar ~
8796 \SpecialChar ~
8797 \SpecialChar ~
8798 \SpecialChar ~
8799 mov a,#0x01
8800 \newline
8801 F2\SpecialChar ~
8802 \SpecialChar ~
8803 \SpecialChar ~
8804 \SpecialChar ~
8805 \SpecialChar ~
8806 \SpecialChar ~
8807 \SpecialChar ~
8808 \SpecialChar ~
8809 \SpecialChar ~
8810 movx @r0,a
8811 \layout Standard
8812
8813 If the -
8814 \begin_inset ERT
8815 status Collapsed
8816
8817 \layout Standard
8818
8819 \backslash
8820 /
8821 \end_inset
8822
8823 -xstack
8824 \begin_inset LatexCommand \index{-\/-xstack}
8825
8826 \end_inset
8827
8828  option is used the pdata memory area is followed by the xstack memory area
8829  and the sum of their sizes is limited to 256 bytes.
8830 \layout Subsubsection
8831
8832 code
8833 \begin_inset LatexCommand \index{code}
8834
8835 \end_inset
8836
8837
8838 \begin_inset LatexCommand \index{\_\_code}
8839
8840 \end_inset
8841
8842
8843 \layout Standard
8844
8845 'Variables' declared with this storage class will be placed in the code
8846  memory:
8847 \layout Verse
8848
8849
8850 \family typewriter
8851 code unsigned char test_code;
8852 \layout Standard
8853
8854 Read access to this variable generates the assembly code:
8855 \layout Verse
8856
8857
8858 \family typewriter
8859 90s00r6F\SpecialChar ~
8860 \SpecialChar ~
8861 \SpecialChar ~
8862 mov dptr,#_test_code
8863 \newline
8864 E4\SpecialChar ~
8865 \SpecialChar ~
8866 \SpecialChar ~
8867 \SpecialChar ~
8868 \SpecialChar ~
8869 \SpecialChar ~
8870 \SpecialChar ~
8871 \SpecialChar ~
8872 \SpecialChar ~
8873 clr a
8874 \newline
8875 93\SpecialChar ~
8876 \SpecialChar ~
8877 \SpecialChar ~
8878 \SpecialChar ~
8879 \SpecialChar ~
8880 \SpecialChar ~
8881 \SpecialChar ~
8882 \SpecialChar ~
8883 \SpecialChar ~
8884 movc a,@a+dptr
8885 \layout Standard
8886
8887
8888 \family typewriter
8889 char
8890 \family default
8891  indexed arrays of characters in code memory can be accessed efficiently:
8892 \layout Verse
8893
8894
8895 \family typewriter
8896 code char test_array[] = {'c','h','e','a','p'};
8897 \layout Standard
8898
8899 Read access to this array using an 8-bit unsigned index generates the assembly
8900  code:
8901 \layout Verse
8902
8903
8904 \family typewriter
8905 E5*00\SpecialChar ~
8906 \SpecialChar ~
8907 \SpecialChar ~
8908 \SpecialChar ~
8909 \SpecialChar ~
8910 \SpecialChar ~
8911 mov a,_index
8912 \layout Verse
8913
8914
8915 \family typewriter
8916 90s00r41\SpecialChar ~
8917 \SpecialChar ~
8918 \SpecialChar ~
8919 mov dptr,#_test_array
8920 \layout Verse
8921
8922
8923 \family typewriter
8924 93\SpecialChar ~
8925 \SpecialChar ~
8926 \SpecialChar ~
8927 \SpecialChar ~
8928 \SpecialChar ~
8929 \SpecialChar ~
8930 \SpecialChar ~
8931 \SpecialChar ~
8932 \SpecialChar ~
8933 movc a,@a+dptr
8934 \layout Subsubsection
8935
8936 bit
8937 \begin_inset LatexCommand \index{bit}
8938
8939 \end_inset
8940
8941
8942 \begin_inset LatexCommand \index{\_\_bit}
8943
8944 \end_inset
8945
8946
8947 \layout Standard
8948
8949 This is a data-type and a storage class specifier.
8950  When a variable is declared as a bit, it is allocated into the bit addressable
8951  memory of 8051, e.g.:
8952 \layout Verse
8953
8954
8955 \family typewriter
8956 bit test_bit;
8957 \layout Standard
8958
8959 Writing 1 to this variable generates the assembly code:
8960 \layout Verse
8961
8962
8963 \family typewriter
8964 D2*00\SpecialChar ~
8965 \SpecialChar ~
8966 \SpecialChar ~
8967 \SpecialChar ~
8968 \SpecialChar ~
8969 \SpecialChar ~
8970 \SpecialChar ~
8971 setb\SpecialChar ~
8972 _test_bit
8973 \layout Standard
8974
8975 The bit addressable memory consists of 128 bits which are located from 0x20
8976  to 0x2f in data memory.
8977
8978 \newline
8979 Apart from this 8051 specific storage class most architectures support ANSI-C
8980  bitfields
8981 \begin_inset LatexCommand \index{bitfields}
8982
8983 \end_inset
8984
8985
8986 \begin_inset Foot
8987 collapsed false
8988
8989 \layout Standard
8990
8991 Not really meant as examples, but nevertheless showing what bitfields are
8992  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8993 \end_inset
8994
8995 .
8996  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
8997  signed modifier are implemented as unsigned.
8998 \layout Subsubsection
8999
9000 sfr
9001 \begin_inset LatexCommand \index{sfr}
9002
9003 \end_inset
9004
9005
9006 \begin_inset LatexCommand \index{\_\_sfr}
9007
9008 \end_inset
9009
9010  / sfr16
9011 \begin_inset LatexCommand \index{sfr16}
9012
9013 \end_inset
9014
9015
9016 \begin_inset LatexCommand \index{\_\_sfr16}
9017
9018 \end_inset
9019
9020  / sfr32
9021 \begin_inset LatexCommand \index{sfr32}
9022
9023 \end_inset
9024
9025
9026 \begin_inset LatexCommand \index{\_\_sfr32}
9027
9028 \end_inset
9029
9030  / sbit
9031 \begin_inset LatexCommand \index{\_\_sbit}
9032
9033 \end_inset
9034
9035
9036 \layout Standard
9037
9038 Like the bit keyword,
9039 \emph on
9040 sfr / sfr16 / sfr32 / sbit
9041 \emph default
9042 signify both a data-type and storage class, they are used to describe the
9043
9044 \emph on
9045 s
9046 \emph default
9047 pecial
9048 \emph on
9049 f
9050 \emph default
9051 unction
9052 \emph on
9053 r
9054 \emph default
9055 egisters and
9056 \emph on
9057 s
9058 \emph default
9059 pecial
9060 \emph on
9061 bit
9062 \emph default
9063  variables of a 8051, eg:
9064 \layout Verse
9065
9066
9067 \family typewriter
9068 sfr at
9069 \begin_inset LatexCommand \index{at}
9070
9071 \end_inset
9072
9073
9074 \begin_inset LatexCommand \index{\_\_at}
9075
9076 \end_inset
9077
9078  0x80 P0;\SpecialChar ~
9079  /* special function register P0 at location 0x80 */
9080 \newline
9081 /* 16 bit special function register combination for timer 0 */
9082 \newline
9083 /* with the high byte at location 0x8C and the low byte at location 0x8A
9084  */
9085 \newline
9086 sfr16 at
9087 \begin_inset LatexCommand \index{at}
9088
9089 \end_inset
9090
9091
9092 \begin_inset LatexCommand \index{\_\_at}
9093
9094 \end_inset
9095
9096  0x8C8A TMR0;
9097 \newline
9098 sbit at 0xd7 CY; /* CY (Carry Flag
9099 \begin_inset LatexCommand \index{Flags}
9100
9101 \end_inset
9102
9103
9104 \begin_inset LatexCommand \index{Carry flag}
9105
9106 \end_inset
9107
9108 ) */
9109 \layout Standard
9110
9111 Special function registers which are located on an address dividable by
9112  8 are bit-addressable, an
9113 \emph on
9114  sbit
9115 \emph default
9116  addresses a specific bit within these sfr.
9117 \newline
9118 16 Bit and 32 bit special function register combinations which require a
9119  certain access order are better not declared using
9120 \emph on
9121 sfr16
9122 \emph default
9123  or
9124 \emph on
9125 sfr32.
9126
9127 \emph default
9128  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9129  this is not guaranteed.
9130 \layout Subsubsection
9131
9132 Pointers
9133 \begin_inset LatexCommand \index{Pointer}
9134
9135 \end_inset
9136
9137  to MCS51/DS390 specific memory spaces
9138 \layout Standard
9139
9140 SDCC allows (via language extensions) pointers to explicitly point to any
9141  of the memory spaces
9142 \begin_inset LatexCommand \index{Memory model}
9143
9144 \end_inset
9145
9146  of the 8051.
9147  In addition to the explicit pointers, the compiler uses (by default) generic
9148  pointers which can be used to point to any of the memory spaces.
9149 \newline
9150
9151 \newline
9152 Pointer declaration examples:
9153 \layout Verse
9154
9155
9156 \family typewriter
9157 /* pointer physically in internal ram pointing to object in external ram
9158  */
9159 \newline
9160 xdata unsigned char * data p;
9161 \newline
9162
9163 \newline
9164 /* pointer physically in external ram pointing to object in internal ram
9165  */
9166 \newline
9167 data unsigned char * xdata p;
9168 \newline
9169
9170 \newline
9171 /* pointer physically in code rom pointing to data in xdata space */
9172 \newline
9173 xdata unsigned char * code p;
9174 \newline
9175
9176 \newline
9177 /* pointer physically in code space pointing to data in code space */
9178 \newline
9179 code unsigned char * code p;
9180 \newline
9181
9182 \newline
9183 /* the following is a generic pointer physically located in xdata space
9184  */
9185 \newline
9186 char * xdata p;
9187 \newline
9188
9189 \newline
9190 /* the following is a function pointer physically located in data space
9191  */
9192 \newline
9193 char (* data fp)(void);
9194 \layout Standard
9195
9196 Well you get the idea.
9197
9198 \newline
9199
9200 \newline
9201 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9202 \emph on
9203 generic
9204 \emph default
9205  pointers.
9206
9207 \size small
9208
9209 \newline
9210
9211 \newline
9212
9213 \size default
9214 The highest order byte of the
9215 \emph on
9216 generic
9217 \emph default
9218  pointers contains the data space information.
9219  Assembler support routines are called whenever data is stored or retrieved
9220  using
9221 \emph on
9222 generic
9223 \emph default
9224  pointers.
9225  These are useful for developing reusable library
9226 \begin_inset LatexCommand \index{Libraries}
9227
9228 \end_inset
9229
9230  routines.
9231  Explicitly specifying the pointer type will generate the most efficient
9232  code.
9233 \layout Subsubsection
9234
9235 Notes on MCS51 memory
9236 \begin_inset LatexCommand \index{MCS51 memory}
9237
9238 \end_inset
9239
9240  layout
9241 \layout Standard
9242
9243 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9244  RAM memory which is structured as follows:
9245 \newline
9246
9247 \newline
9248 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9249
9250 \newline
9251 - Bytes 20-2F - 16 bytes to hold 128 bit
9252 \begin_inset LatexCommand \index{bit}
9253
9254 \end_inset
9255
9256  variables and,
9257 \newline
9258 - Bytes 30-7F - 80 bytes for general purpose use.
9259 \newline
9260
9261 \layout Standard
9262
9263 Additionally some members of the MCS51 family may have up to 128 bytes of
9264  additional, indirectly addressable, internal RAM memory (
9265 \emph on
9266 idata
9267 \emph default
9268
9269 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9270
9271 \end_inset
9272
9273
9274 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9275
9276 \end_inset
9277
9278 ).
9279  Furthermore, some chips may have some built in external memory (
9280 \emph on
9281 xdata
9282 \emph default
9283
9284 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9285
9286 \end_inset
9287
9288
9289 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9290
9291 \end_inset
9292
9293 ) which should not be confused with the internal, directly addressable RAM
9294  memory (
9295 \emph on
9296 data
9297 \emph default
9298
9299 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9300
9301 \end_inset
9302
9303
9304 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9305
9306 \end_inset
9307
9308 ).
9309  Sometimes this built in
9310 \emph on
9311 xdata
9312 \emph default
9313  memory has to be activated before using it (you can probably find this
9314  information on the datasheet of the microcontroller your are using, see
9315  also section
9316 \begin_inset LatexCommand \ref{sub:Startup-Code}
9317
9318 \end_inset
9319
9320 \SpecialChar ~
9321 Startup-Code).
9322 \layout Standard
9323
9324 Normally SDCC will only use the first bank
9325 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9326
9327 \end_inset
9328
9329  of registers (register bank 0), but it is possible to specify that other
9330  banks of registers (keyword
9331 \emph on
9332 using
9333 \emph default
9334
9335 \emph on
9336
9337 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9338
9339 \end_inset
9340
9341
9342 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9343
9344 \end_inset
9345
9346
9347 \emph default
9348 ) should be used in interrupt
9349 \begin_inset LatexCommand \index{interrupt}
9350
9351 \end_inset
9352
9353
9354 \begin_inset LatexCommand \index{\_\_interrupt}
9355
9356 \end_inset
9357
9358  routines.
9359  By default, the compiler will place the stack after the last byte of allocated
9360  memory for variables.
9361  For example, if the first 2 banks of registers are used, and only four
9362  bytes are used for
9363 \emph on
9364 data
9365 \emph default
9366  variables, it will position the base of the internal stack at address 20
9367  (0x14).
9368  This implies that as the stack
9369 \begin_inset LatexCommand \index{stack}
9370
9371 \end_inset
9372
9373  grows, it will use up the remaining register banks, and the 16 bytes used
9374  by the 128 bit variables, and 80 bytes for general purpose use.
9375  If any bit variables are used, the data variables will be placed in unused
9376  register banks and after the byte holding the last bit variable.
9377  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9378  (two bytes used),
9379 \emph on
9380 data
9381 \emph default
9382  variables will be placed starting from address 0x10 to 0x20 and continue
9383  at address 0x22.
9384  You can also use -
9385 \begin_inset ERT
9386 status Collapsed
9387
9388 \layout Standard
9389
9390 \backslash
9391 /
9392 \end_inset
9393
9394 -data-loc
9395 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
9396
9397 \end_inset
9398
9399  to specify the start address of the
9400 \emph on
9401 data
9402 \emph default
9403  and -
9404 \begin_inset ERT
9405 status Collapsed
9406
9407 \layout Standard
9408
9409 \backslash
9410 /
9411 \end_inset
9412
9413 -iram-size
9414 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
9415
9416 \end_inset
9417
9418  to specify the size of the total internal RAM (
9419 \emph on
9420 data
9421 \emph default
9422 +
9423 \emph on
9424 idata
9425 \emph default
9426 ).
9427
9428 \layout Standard
9429
9430 By default the 8051 linker will place the stack after the last byte of (i)data
9431  variables.
9432  Option -
9433 \begin_inset ERT
9434 status Collapsed
9435
9436 \layout Standard
9437
9438 \backslash
9439 /
9440 \end_inset
9441
9442 -stack-loc
9443 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
9444
9445 \end_inset
9446
9447  allows you to specify the start of the stack, i.e.
9448  you could start it after any data in the general purpose area.
9449  If your microcontroller has additional indirectly addressable internal
9450  RAM (
9451 \emph on
9452 idata
9453 \emph default
9454 ) you can place the stack on it.
9455  You may also need to use -
9456 \begin_inset ERT
9457 status Collapsed
9458
9459 \layout Standard
9460
9461 \backslash
9462 /
9463 \end_inset
9464
9465 -xdata-loc
9466 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
9467
9468 \end_inset
9469
9470  to set the start address of the external RAM (
9471 \emph on
9472 xdata
9473 \emph default
9474 ) and -
9475 \begin_inset ERT
9476 status Collapsed
9477
9478 \layout Standard
9479
9480 \backslash
9481 /
9482 \end_inset
9483
9484 -xram-size
9485 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
9486
9487 \end_inset
9488
9489  to specify its size.
9490  Same goes for the code memory, using -
9491 \begin_inset ERT
9492 status Collapsed
9493
9494 \layout Standard
9495
9496 \backslash
9497 /
9498 \end_inset
9499
9500 -code-loc
9501 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
9502
9503 \end_inset
9504
9505  and -
9506 \begin_inset ERT
9507 status Collapsed
9508
9509 \layout Standard
9510
9511 \backslash
9512 /
9513 \end_inset
9514
9515 -code-size
9516 \begin_inset LatexCommand \index{-\/-code-size <Value>}
9517
9518 \end_inset
9519
9520 .
9521  If in doubt, don't specify any options and see if the resulting memory
9522  layout is appropriate, then you can adjust it.
9523 \layout Standard
9524
9525 The linker generates two files with memory allocation information.
9526  The first, with extension .map
9527 \begin_inset LatexCommand \index{<file>.map}
9528
9529 \end_inset
9530
9531  shows all the variables and segments.
9532  The second with extension .mem
9533 \begin_inset LatexCommand \index{<file>.mem}
9534
9535 \end_inset
9536
9537  shows the final memory layout.
9538  The linker will complain either if memory segments overlap, there is not
9539  enough memory, or there is not enough space for stack.
9540  If you get any linking warnings and/or errors related to stack or segments
9541  allocation, take a look at either the .map or .mem files to find out what
9542  the problem is.
9543  The .mem file may even suggest a solution to the problem.
9544 \layout Subsection
9545
9546 Z80/Z180 Storage Class
9547 \begin_inset LatexCommand \index{Storage class}
9548
9549 \end_inset
9550
9551  Language Extensions
9552 \layout Subsubsection
9553
9554 sfr
9555 \begin_inset LatexCommand \index{sfr}
9556
9557 \end_inset
9558
9559
9560 \begin_inset LatexCommand \index{\_\_sfr}
9561
9562 \end_inset
9563
9564  (in/out to 8-bit addresses)
9565 \layout Standard
9566
9567 The Z80
9568 \begin_inset LatexCommand \index{Z80}
9569
9570 \end_inset
9571
9572  family has separate address spaces for memory and
9573 \emph on
9574 i
9575 \emph default
9576 nput/
9577 \emph on
9578 o
9579 \emph default
9580 utput memory.
9581  I/O memory
9582 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9583
9584 \end_inset
9585
9586  is accessed with special instructions, e.g.:
9587 \layout Verse
9588
9589
9590 \family typewriter
9591 sfr at 0x78 IoPort;\SpecialChar ~
9592 \SpecialChar ~
9593 /* define a var in I/O space at 78h called IoPort */
9594
9595 \layout Standard
9596
9597 Writing 0x01 to this variable generates the assembly code:
9598 \layout Verse
9599
9600
9601 \family typewriter
9602 3E 01\SpecialChar ~
9603 \SpecialChar ~
9604 \SpecialChar ~
9605 \SpecialChar ~
9606 \SpecialChar ~
9607 \SpecialChar ~
9608 ld a,#0x01
9609 \newline
9610 D3 78\SpecialChar ~
9611 \SpecialChar ~
9612 \SpecialChar ~
9613 \SpecialChar ~
9614 \SpecialChar ~
9615 \SpecialChar ~
9616 out (_IoPort),a
9617 \layout Subsubsection
9618
9619 banked sfr
9620 \begin_inset LatexCommand \index{sfr}
9621
9622 \end_inset
9623
9624
9625 \begin_inset LatexCommand \index{\_\_sfr}
9626
9627 \end_inset
9628
9629  (in/out to 16-bit addresses)
9630 \layout Standard
9631
9632 The keyword
9633 \emph on
9634 banked
9635 \emph default
9636  is used to support 16 bit addresses in I/O memory e.g.:
9637 \layout Verse
9638
9639
9640 \family typewriter
9641 sfr banked at
9642 \begin_inset LatexCommand \index{at}
9643
9644 \end_inset
9645
9646
9647 \begin_inset LatexCommand \index{\_\_at}
9648
9649 \end_inset
9650
9651  0x123 IoPort;
9652 \layout Standard
9653
9654 Writing 0x01 to this variable generates the assembly code:
9655 \layout Verse
9656
9657
9658 \family typewriter
9659 01 23 01\SpecialChar ~
9660 \SpecialChar ~
9661 \SpecialChar ~
9662 ld bc,#_IoPort
9663 \newline
9664 3E 01\SpecialChar ~
9665 \SpecialChar ~
9666 \SpecialChar ~
9667 \SpecialChar ~
9668 \SpecialChar ~
9669 \SpecialChar ~
9670 ld a,#0x01
9671 \newline
9672 ED 79\SpecialChar ~
9673 \SpecialChar ~
9674 \SpecialChar ~
9675 \SpecialChar ~
9676 \SpecialChar ~
9677 \SpecialChar ~
9678 out (c),a
9679 \layout Subsubsection
9680
9681 sfr
9682 \begin_inset LatexCommand \index{sfr}
9683
9684 \end_inset
9685
9686
9687 \begin_inset LatexCommand \index{\_\_sfr}
9688
9689 \end_inset
9690
9691  (in0/out0 to 8 bit addresses on Z180
9692 \begin_inset LatexCommand \index{Z180}
9693
9694 \end_inset
9695
9696 /HD64180
9697 \begin_inset LatexCommand \index{HD64180}
9698
9699 \end_inset
9700
9701 )
9702 \layout Standard
9703
9704 The compiler option -
9705 \begin_inset ERT
9706 status Collapsed
9707
9708 \layout Standard
9709
9710 \backslash
9711 /
9712 \end_inset
9713
9714 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9715 portmode
9716 \begin_inset LatexCommand \index{\#pragma portmode}
9717
9718 \end_inset
9719
9720 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9721 ns
9722 \family typewriter
9723 in0/out0
9724 \family default
9725  instead of
9726 \family typewriter
9727 in/out
9728 \family default
9729 .
9730  If you include the file z180.h this will be set automatically.
9731 \layout Subsection
9732
9733 HC08 Storage Class
9734 \begin_inset LatexCommand \index{Storage class}
9735
9736 \end_inset
9737
9738  Language Extensions
9739 \layout Subsubsection
9740
9741 data
9742 \begin_inset LatexCommand \index{data (hc08 storage class)}
9743
9744 \end_inset
9745
9746
9747 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
9748
9749 \end_inset
9750
9751
9752 \layout Standard
9753
9754 The data storage class declares a variable that resides in the first 256
9755  bytes of memory (the direct page).
9756  The HC08 is most efficient at accessing variables (especially pointers)
9757  stored here.
9758 \layout Subsubsection
9759
9760 xdata
9761 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
9762
9763 \end_inset
9764
9765
9766 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
9767
9768 \end_inset
9769
9770
9771 \layout Standard
9772
9773 The xdata storage class declares a variable that can reside anywhere in
9774  memory.
9775  This is the default if no storage class is specified.
9776
9777 \layout Section
9778
9779 Absolute Addressing
9780 \begin_inset LatexCommand \index{Absolute addressing}
9781
9782 \end_inset
9783
9784
9785 \layout Standard
9786
9787 Data items can be assigned an absolute address with the
9788 \emph on
9789 at
9790 \begin_inset LatexCommand \index{at}
9791
9792 \end_inset
9793
9794
9795 \begin_inset LatexCommand \index{\_\_at}
9796
9797 \end_inset
9798
9799  <address>
9800 \emph default
9801  keyword, in addition to a storage class, e.g.:
9802 \layout Verse
9803
9804
9805 \family typewriter
9806 xdata
9807 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9808
9809 \end_inset
9810
9811
9812 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9813
9814 \end_inset
9815
9816  at
9817 \begin_inset LatexCommand \index{at}
9818
9819 \end_inset
9820
9821
9822 \begin_inset LatexCommand \index{\_\_at}
9823
9824 \end_inset
9825
9826  0x7ffe unsigned int chksum;
9827 \layout Standard
9828
9829 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9830  of the external ram.
9831  The compiler does
9832 \emph on
9833 not
9834 \emph default
9835  reserve any space for variables declared in this way (they are implemented
9836  with an equate in the assembler).
9837  Thus it is left to the programmer to make sure there are no overlaps with
9838  other variables that are declared without the absolute address.
9839  The assembler listing file (.lst
9840 \begin_inset LatexCommand \index{<file>.lst}
9841
9842 \end_inset
9843
9844 ) and the linker output files (.rst
9845 \begin_inset LatexCommand \index{<file>.rst}
9846
9847 \end_inset
9848
9849 ) and (.map
9850 \begin_inset LatexCommand \index{<file>.map}
9851
9852 \end_inset
9853
9854 ) are good places to look for such overlaps.
9855  Variables with an absolute address are
9856 \emph on
9857 not
9858 \emph default
9859  initialized
9860 \begin_inset LatexCommand \index{Variable initialization}
9861
9862 \end_inset
9863
9864 .
9865 \layout Standard
9866
9867 In case of memory mapped I/O devices the keyword
9868 \emph on
9869 volatile
9870 \emph default
9871  has to be used to tell the compiler that accesses might not be removed:
9872 \layout Verse
9873
9874
9875 \family typewriter
9876 volatile
9877 \begin_inset LatexCommand \index{volatile}
9878
9879 \end_inset
9880
9881  xdata
9882 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9883
9884 \end_inset
9885
9886  at
9887 \begin_inset LatexCommand \index{at}
9888
9889 \end_inset
9890
9891  0x8000 unsigned char PORTA_8255;
9892 \layout Standard
9893
9894 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9895 r) array
9896 \family typewriter
9897 \size footnotesize
9898
9899 \begin_inset LatexCommand \index{Aligned array}
9900
9901 \end_inset
9902
9903
9904 \family default
9905 \size default
9906  starts at a block (256 byte) boundary
9907 \begin_inset LatexCommand \index{block boundary}
9908
9909 \end_inset
9910
9911  (section
9912 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9913
9914 \end_inset
9915
9916  has an example).
9917 \newline
9918 Absolute addresses can be specified for variables in all storage classes,
9919  e.g.:
9920 \layout Verse
9921
9922
9923 \family typewriter
9924 bit
9925 \begin_inset LatexCommand \index{bit}
9926
9927 \end_inset
9928
9929  at
9930 \begin_inset LatexCommand \index{at}
9931
9932 \end_inset
9933
9934  0x02 bvar;
9935 \layout Standard
9936
9937 The above example will allocate the variable at offset 0x02 in the bit-addressab
9938 le space.
9939  There is no real advantage to assigning absolute addresses to variables
9940  in this manner, unless you want strict control over all the variables allocated.
9941  One possible use would be to write hardware portable code.
9942  For example, if you have a routine that uses one or more of the microcontroller
9943  I/O pins, and such pins are different for two different hardwares, you
9944  can declare the I/O pins in your routine using:
9945 \layout Verse
9946
9947
9948 \family typewriter
9949 extern volatile
9950 \begin_inset LatexCommand \index{volatile}
9951
9952 \end_inset
9953
9954  bit MOSI;\SpecialChar ~
9955 \SpecialChar ~
9956 \SpecialChar ~
9957 \SpecialChar ~
9958 /* master out, slave in */
9959 \newline
9960 extern volatile bit MISO;\SpecialChar ~
9961 \SpecialChar ~
9962 \SpecialChar ~
9963 \SpecialChar ~
9964 /* master in, slave out */
9965 \newline
9966 extern volatile bit MCLK;\SpecialChar ~
9967 \SpecialChar ~
9968 \SpecialChar ~
9969 \SpecialChar ~
9970 /* master clock */
9971 \newline
9972
9973 \newline
9974 /* Input and Output of a byte on a 3-wire serial bus.
9975 \newline
9976 \SpecialChar ~
9977 \SpecialChar ~
9978 \SpecialChar ~
9979 If needed adapt polarity of clock, polarity of data and bit order
9980 \newline
9981 \SpecialChar ~
9982 */
9983 \newline
9984 unsigned char spi_io(unsigned char out_byte)
9985 \newline
9986 {
9987 \newline
9988 \SpecialChar ~
9989 \SpecialChar ~
9990 \SpecialChar ~
9991 \SpecialChar ~
9992 unsigned char i=8;
9993 \newline
9994 \SpecialChar ~
9995 \SpecialChar ~
9996 \SpecialChar ~
9997 \SpecialChar ~
9998 do {
9999 \newline
10000 \SpecialChar ~
10001 \SpecialChar ~
10002 \SpecialChar ~
10003 \SpecialChar ~
10004 \SpecialChar ~
10005 \SpecialChar ~
10006 \SpecialChar ~
10007 \SpecialChar ~
10008 MOSI = out_byte & 0x80;
10009 \newline
10010 \SpecialChar ~
10011 \SpecialChar ~
10012 \SpecialChar ~
10013 \SpecialChar ~
10014 \SpecialChar ~
10015 \SpecialChar ~
10016 \SpecialChar ~
10017 \SpecialChar ~
10018 out_byte <<= 1;
10019 \newline
10020 \SpecialChar ~
10021 \SpecialChar ~
10022 \SpecialChar ~
10023 \SpecialChar ~
10024 \SpecialChar ~
10025 \SpecialChar ~
10026 \SpecialChar ~
10027 \SpecialChar ~
10028 MCLK = 1;
10029 \newline
10030 \SpecialChar ~
10031 \SpecialChar ~
10032 \SpecialChar ~
10033 \SpecialChar ~
10034 \SpecialChar ~
10035 \SpecialChar ~
10036 \SpecialChar ~
10037 \SpecialChar ~
10038 /* _asm nop _endasm; */\SpecialChar ~
10039 \SpecialChar ~
10040 \SpecialChar ~
10041 \SpecialChar ~
10042 \SpecialChar ~
10043 \SpecialChar ~
10044 \SpecialChar ~
10045 \SpecialChar ~
10046 /* for slow peripherals */
10047 \newline
10048 \SpecialChar ~
10049 \SpecialChar ~
10050 \SpecialChar ~
10051 \SpecialChar ~
10052 \SpecialChar ~
10053 \SpecialChar ~
10054 \SpecialChar ~
10055 \SpecialChar ~
10056 if(MISO)
10057 \newline
10058 \SpecialChar ~
10059 \SpecialChar ~
10060 \SpecialChar ~
10061 \SpecialChar ~
10062 \SpecialChar ~
10063 \SpecialChar ~
10064 \SpecialChar ~
10065 \SpecialChar ~
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 \SpecialChar ~
10069 \SpecialChar ~
10070 out_byte += 1;
10071 \newline
10072 \SpecialChar ~
10073 \SpecialChar ~
10074 \SpecialChar ~
10075 \SpecialChar ~
10076 \SpecialChar ~
10077 \SpecialChar ~
10078 \SpecialChar ~
10079 \SpecialChar ~
10080 MCLK = 0;
10081 \newline
10082 \SpecialChar ~
10083 \SpecialChar ~
10084 \SpecialChar ~
10085 \SpecialChar ~
10086 } while(--i);
10087 \newline
10088 \SpecialChar ~
10089 \SpecialChar ~
10090 \SpecialChar ~
10091 \SpecialChar ~
10092 return out_byte;
10093 \newline
10094 }
10095 \layout Standard
10096
10097 Then, someplace in the code for the first hardware you would use
10098 \layout Verse
10099
10100
10101 \family typewriter
10102 bit at
10103 \begin_inset LatexCommand \index{at}
10104
10105 \end_inset
10106
10107
10108 \begin_inset LatexCommand \index{\_\_at}
10109
10110 \end_inset
10111
10112  0x80 MOSI;\SpecialChar ~
10113 \SpecialChar ~
10114 \SpecialChar ~
10115 \SpecialChar ~
10116 /* I/O port 0, bit 0 */
10117 \newline
10118 bit at 0x81 MISO;\SpecialChar ~
10119 \SpecialChar ~
10120 \SpecialChar ~
10121 \SpecialChar ~
10122 /* I/O port 0, bit 1 */
10123 \newline
10124 bit at 0x82 MCLK;\SpecialChar ~
10125 \SpecialChar ~
10126 \SpecialChar ~
10127 \SpecialChar ~
10128 /* I/O port 0, bit 2 */
10129 \layout Standard
10130
10131 Similarly, for the second hardware you would use
10132 \layout Verse
10133
10134
10135 \family typewriter
10136 bit at 0x83 MOSI;\SpecialChar ~
10137 \SpecialChar ~
10138 \SpecialChar ~
10139 \SpecialChar ~
10140 /* I/O port 0, bit 3 */
10141 \newline
10142 bit at 0x91 MISO;\SpecialChar ~
10143 \SpecialChar ~
10144 \SpecialChar ~
10145 \SpecialChar ~
10146 /* I/O port 1, bit 1 */
10147 \newline
10148 bit
10149 \begin_inset LatexCommand \index{bit}
10150
10151 \end_inset
10152
10153  at 0x92 MCLK;\SpecialChar ~
10154 \SpecialChar ~
10155 \SpecialChar ~
10156 \SpecialChar ~
10157 /* I/O port 1, bit 2 */
10158 \layout Standard
10159
10160 and you can use the same hardware dependent routine without changes, as
10161  for example in a library.
10162  This is somehow similar to sbit, but only one absolute address has to be
10163  specified in the whole project.
10164 \layout Section
10165
10166 Parameters
10167 \begin_inset LatexCommand \index{Parameters}
10168
10169 \end_inset
10170
10171
10172 \begin_inset LatexCommand \index{function parameter}
10173
10174 \end_inset
10175
10176  & Local Variables
10177 \begin_inset LatexCommand \index{local variables}
10178
10179 \end_inset
10180
10181
10182 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10183
10184 \end_inset
10185
10186
10187 \layout Standard
10188
10189 Automatic (local) variables and parameters to functions can either be placed
10190  on the stack or in data-space.
10191  The default action of the compiler is to place these variables in the internal
10192  RAM (for small model) or external RAM (for large model).
10193  This in fact makes them similar to
10194 \emph on
10195 static
10196 \begin_inset LatexCommand \index{static}
10197
10198 \end_inset
10199
10200
10201 \emph default
10202  so by default functions are non-reentrant
10203 \begin_inset LatexCommand \index{reentrant}
10204
10205 \end_inset
10206
10207 .
10208
10209 \newline
10210
10211 \newline
10212 They can be placed on the stack
10213 \begin_inset LatexCommand \index{stack}
10214
10215 \end_inset
10216
10217  by using the
10218 \emph on
10219  -
10220 \begin_inset ERT
10221 status Collapsed
10222
10223 \layout Standard
10224
10225 \backslash
10226 /
10227 \end_inset
10228
10229 -stack-auto
10230 \begin_inset LatexCommand \index{-\/-stack-auto}
10231
10232 \end_inset
10233
10234
10235 \emph default
10236  option, by using
10237 \emph on
10238 #pragma\SpecialChar ~
10239 stackauto
10240 \emph default
10241
10242 \begin_inset LatexCommand \index{\#pragma stackauto}
10243
10244 \end_inset
10245
10246  or by using the
10247 \emph on
10248 reentrant
10249 \begin_inset LatexCommand \index{reentrant}
10250
10251 \end_inset
10252
10253
10254 \emph default
10255  keyword in the function declaration, e.g.:
10256 \layout Verse
10257
10258
10259 \family typewriter
10260 unsigned char foo(char i) reentrant
10261 \newline
10262 {
10263 \newline
10264 \SpecialChar ~
10265 \SpecialChar ~
10266 \SpecialChar ~
10267 \SpecialChar ~
10268 ...
10269
10270 \newline
10271 }
10272 \layout Standard
10273
10274 Since stack space on 8051 is limited, the
10275 \emph on
10276 reentrant
10277 \emph default
10278 keyword or the
10279 \emph on
10280  -
10281 \begin_inset ERT
10282 status Collapsed
10283
10284 \layout Standard
10285
10286 \backslash
10287 /
10288 \end_inset
10289
10290 -stack-auto
10291 \emph default
10292  option should be used sparingly.
10293  Note that the reentrant keyword just means that the parameters & local
10294  variables will be allocated to the stack, it
10295 \emph on
10296 does not
10297 \emph default
10298  mean that the function is register bank
10299 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10300
10301 \end_inset
10302
10303  independent.
10304 \newline
10305
10306 \newline
10307 Local variables
10308 \begin_inset LatexCommand \index{local variables}
10309
10310 \end_inset
10311
10312  can be assigned storage classes and absolute
10313 \begin_inset LatexCommand \index{Absolute addressing}
10314
10315 \end_inset
10316
10317  addresses, e.g.:
10318 \layout Verse
10319
10320
10321 \family typewriter
10322 unsigned char foo()
10323 \newline
10324 {
10325 \newline
10326 \SpecialChar ~
10327 \SpecialChar ~
10328 \SpecialChar ~
10329 \SpecialChar ~
10330 xdata unsigned char i;
10331 \newline
10332 \SpecialChar ~
10333 \SpecialChar ~
10334 \SpecialChar ~
10335 \SpecialChar ~
10336 bit bvar;
10337 \newline
10338 \SpecialChar ~
10339 \SpecialChar ~
10340 \SpecialChar ~
10341 \SpecialChar ~
10342 data at
10343 \begin_inset LatexCommand \index{at}
10344
10345 \end_inset
10346
10347  0x31 unsigned char j;
10348 \newline
10349 \SpecialChar ~
10350 \SpecialChar ~
10351 \SpecialChar ~
10352 \SpecialChar ~
10353 ...
10354
10355 \newline
10356 }
10357 \layout Standard
10358
10359 In the above example the variable
10360 \emph on
10361 i
10362 \emph default
10363  will be allocated in the external ram,
10364 \emph on
10365 bvar
10366 \emph default
10367  in bit addressable space and
10368 \emph on
10369  j
10370 \emph default
10371  in internal ram.
10372  When compiled with
10373 \emph on
10374 -
10375 \begin_inset ERT
10376 status Collapsed
10377
10378 \layout Standard
10379
10380 \backslash
10381 /
10382 \end_inset
10383
10384 -stack-auto
10385 \emph default
10386  or when a function is declared as
10387 \emph on
10388 reentrant
10389 \emph default
10390  this should only be done for static variables.
10391 \layout Standard
10392
10393 Parameters
10394 \begin_inset LatexCommand \index{function parameter}
10395
10396 \end_inset
10397
10398  however are not allowed any storage class
10399 \begin_inset LatexCommand \index{Storage class}
10400
10401 \end_inset
10402
10403 , (storage classes for parameters will be ignored), their allocation is
10404  governed by the memory model in use, and the reentrancy options.
10405 \layout Standard
10406
10407 It is however allowed to use bit parameters in reentrant functions and also
10408  non-static local bit variables are supported.
10409  Efficient use is limited to 8 semi-bitregisters in bit space.
10410  They are pushed and popped to stack as a single byte just like the normal
10411  registers.
10412 \layout Section
10413
10414 Overlaying
10415 \begin_inset LatexCommand \label{sub:Overlaying}
10416
10417 \end_inset
10418
10419
10420 \begin_inset LatexCommand \index{Overlaying}
10421
10422 \end_inset
10423
10424
10425 \layout Standard
10426
10427 For non-reentrant
10428 \begin_inset LatexCommand \index{reentrant}
10429
10430 \end_inset
10431
10432  functions SDCC will try to reduce internal ram space usage by overlaying
10433  parameters and local variables of a function (if possible).
10434  Parameters and local variables
10435 \begin_inset LatexCommand \index{local variables}
10436
10437 \end_inset
10438
10439  of a function will be allocated to an overlayable segment if the function
10440  has
10441 \emph on
10442 no other function calls and the function is non-reentrant and the memory
10443  model
10444 \begin_inset LatexCommand \index{Memory model}
10445
10446 \end_inset
10447
10448  is small.
10449
10450 \emph default
10451  If an explicit storage class
10452 \begin_inset LatexCommand \index{Storage class}
10453
10454 \end_inset
10455
10456  is specified for a local variable, it will NOT be overlayed.
10457 \layout Standard
10458
10459 Note that the compiler (not the linkage editor) makes the decision for overlayin
10460 g the data items.
10461  Functions that are called from an interrupt service routine should be preceded
10462  by a #pragma\SpecialChar ~
10463 nooverlay
10464 \begin_inset LatexCommand \index{\#pragma nooverlay}
10465
10466 \end_inset
10467
10468  if they are not reentrant.
10469 \layout Standard
10470
10471 Also note that the compiler does not do any processing of inline assembler
10472  code, so the compiler might incorrectly assign local variables and parameters
10473  of a function into the overlay segment if the inline assembler code calls
10474  other c-functions that might use the overlay.
10475  In that case the #pragma\SpecialChar ~
10476 nooverlay should be used.
10477 \layout Standard
10478
10479 Parameters and local variables of functions that contain 16 or 32 bit multiplica
10480 tion
10481 \begin_inset LatexCommand \index{Multiplication}
10482
10483 \end_inset
10484
10485  or division
10486 \begin_inset LatexCommand \index{Division}
10487
10488 \end_inset
10489
10490  will NOT be overlayed since these are implemented using external functions,
10491  e.g.:
10492 \layout Verse
10493
10494
10495 \family typewriter
10496 #pragma save
10497 \newline
10498 #pragma nooverlay
10499 \begin_inset LatexCommand \index{\#pragma nooverlay}
10500
10501 \end_inset
10502
10503
10504 \newline
10505 void set_error(unsigned char errcd)
10506 \newline
10507 {
10508 \newline
10509 \SpecialChar ~
10510 \SpecialChar ~
10511 \SpecialChar ~
10512 \SpecialChar ~
10513 P3 = errcd;
10514 \newline
10515 }
10516 \newline
10517 #pragma restore
10518 \newline
10519
10520 \newline
10521 void some_isr () interrupt
10522 \begin_inset LatexCommand \index{interrupt}
10523
10524 \end_inset
10525
10526  2
10527 \newline
10528 {
10529 \newline
10530 \SpecialChar ~
10531 \SpecialChar ~
10532 \SpecialChar ~
10533 \SpecialChar ~
10534 ...
10535 \newline
10536 \SpecialChar ~
10537 \SpecialChar ~
10538 \SpecialChar ~
10539 \SpecialChar ~
10540 set_error(10);
10541 \newline
10542 \SpecialChar ~
10543 \SpecialChar ~
10544 \SpecialChar ~
10545 \SpecialChar ~
10546 ...
10547
10548 \newline
10549 }
10550 \layout Standard
10551
10552 In the above example the parameter
10553 \emph on
10554 errcd
10555 \emph default
10556  for the function
10557 \emph on
10558 set_error
10559 \emph default
10560  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
10561 nooverlay was
10562  not present, this could cause unpredictable runtime behavior when called
10563  from an interrupt service routine.
10564  The #pragma\SpecialChar ~
10565 nooverlay ensures that the parameters and local variables for
10566  the function are NOT overlayed.
10567 \layout Section
10568
10569 Interrupt Service Routines
10570 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
10571
10572 \end_inset
10573
10574
10575 \layout Subsection
10576
10577 General Information
10578 \layout Standard
10579
10580 SDCC allows
10581 \emph on
10582 i
10583 \emph default
10584 nterrupt
10585 \emph on
10586 s
10587 \emph default
10588 ervice
10589 \emph on
10590 r
10591 \emph default
10592 outines to be coded in C, with some extended keywords.
10593 \layout Verse
10594
10595
10596 \family typewriter
10597 void timer_isr (void) interrupt 1 using 1
10598 \newline
10599 {
10600 \newline
10601 \SpecialChar ~
10602 \SpecialChar ~
10603 \SpecialChar ~
10604 \SpecialChar ~
10605 ...
10606
10607 \newline
10608 }
10609 \layout Standard
10610
10611 The optional number following the
10612 \emph on
10613 interrupt
10614 \begin_inset LatexCommand \index{interrupt}
10615
10616 \end_inset
10617
10618
10619 \begin_inset LatexCommand \index{\_\_interrupt}
10620
10621 \end_inset
10622
10623
10624 \emph default
10625  keyword is the interrupt number this routine will service.
10626  When present, the compiler will insert a call to this routine in the interrupt
10627  vector table for the interrupt number specified.
10628  If you have multiple source files in your project, interrupt service routines
10629  can be present in any of them, but a prototype of the isr MUST be present
10630  or included in the file that contains the function
10631 \emph on
10632 main
10633 \emph default
10634 .
10635  The optional
10636 \emph on
10637 using
10638 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10639
10640 \end_inset
10641
10642
10643 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10644
10645 \end_inset
10646
10647
10648 \emph default
10649  keyword can be used to tell the compiler to use the specified register
10650  bank (8051 specific) when generating code for this function.
10651
10652 \newline
10653
10654 \layout Standard
10655
10656 Interrupt service routines open the door for some very interesting bugs:
10657 \newline
10658 If an interrupt service routine changes variables which are accessed by
10659  other functions these variables have to be declared
10660 \emph on
10661 volatile
10662 \emph default
10663
10664 \begin_inset LatexCommand \index{volatile}
10665
10666 \end_inset
10667
10668 .
10669
10670 \layout Standard
10671
10672 If the access to these variables is not
10673 \emph on
10674 atomic
10675 \begin_inset LatexCommand \index{atomic}
10676
10677 \end_inset
10678
10679
10680 \emph default
10681  (i.e.
10682  the processor needs more than one instruction for the access and could
10683  be interrupted while accessing the variable) the interrupt must be disabled
10684  during the access to avoid inconsistent data.
10685  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10686  and should be protected by disabling interrupts.
10687  You're not automatically on the safe side if you use 8 bit variables though.
10688  We need an example here: f.e.
10689  on the 8051 the harmless looking
10690 \begin_inset Quotes srd
10691 \end_inset
10692
10693
10694 \family typewriter
10695 flags\SpecialChar ~
10696 |=\SpecialChar ~
10697 0x80;
10698 \family default
10699
10700 \begin_inset Quotes sld
10701 \end_inset
10702
10703  is not atomic if
10704 \family typewriter
10705 flags
10706 \family default
10707  resides in xdata.
10708  Setting
10709 \begin_inset Quotes srd
10710 \end_inset
10711
10712
10713 \family typewriter
10714 flags\SpecialChar ~
10715 |=\SpecialChar ~
10716 0x40;
10717 \family default
10718
10719 \begin_inset Quotes sld
10720 \end_inset
10721
10722  from within an interrupt routine might get lost if the interrupt occurs
10723  at the wrong time.
10724
10725 \begin_inset Quotes sld
10726 \end_inset
10727
10728
10729 \family typewriter
10730 counter\SpecialChar ~
10731 +=\SpecialChar ~
10732 8;
10733 \family default
10734
10735 \begin_inset Quotes srd
10736 \end_inset
10737
10738  is not atomic on the 8051 even if
10739 \family typewriter
10740 counter
10741 \family default
10742  is located in data memory.
10743  Bugs like these are hard to reproduce and can cause a lot of trouble.
10744
10745 \layout Standard
10746
10747 The return address and the registers used in the interrupt service routine
10748  are saved on the stack
10749 \begin_inset LatexCommand \index{stack}
10750
10751 \end_inset
10752
10753  so there must be sufficient stack space.
10754  If there isn't variables or registers (or even the return address itself)
10755  will be corrupted.
10756  This
10757 \emph on
10758 stack overflow
10759 \emph default
10760
10761 \begin_inset LatexCommand \index{stack overflow}
10762
10763 \end_inset
10764
10765  is most likely to happen if the interrupt occurs during the
10766 \begin_inset Quotes sld
10767 \end_inset
10768
10769 deepest
10770 \begin_inset Quotes srd
10771 \end_inset
10772
10773  subroutine when the stack is already in use for f.e.
10774  many return addresses.
10775 \layout Standard
10776
10777 A special note here, int (16 bit) and long (32 bit) integer division
10778 \begin_inset LatexCommand \index{Division}
10779
10780 \end_inset
10781
10782 , multiplication
10783 \begin_inset LatexCommand \index{Multiplication}
10784
10785 \end_inset
10786
10787  & modulus
10788 \begin_inset LatexCommand \index{Modulus}
10789
10790 \end_inset
10791
10792  and floating-point
10793 \begin_inset LatexCommand \index{Floating point support}
10794
10795 \end_inset
10796
10797  operations are implemented using external support routines developed in
10798  ANSI-C.
10799  If an interrupt service routine needs to do any of these operations then
10800  the support routines (as mentioned in a following section) will have to
10801  be recompiled using the
10802 \emph on
10803  -
10804 \begin_inset ERT
10805 status Collapsed
10806
10807 \layout Standard
10808
10809 \backslash
10810 /
10811 \end_inset
10812
10813 -stack-auto
10814 \begin_inset LatexCommand \index{-\/-stack-auto}
10815
10816 \end_inset
10817
10818
10819 \emph default
10820  option and the source file will need to be compiled using the
10821 \emph on
10822 -
10823 \begin_inset ERT
10824 status Collapsed
10825
10826 \layout Standard
10827
10828 \backslash
10829 /
10830 \end_inset
10831
10832 -int-long-reent
10833 \emph default
10834
10835 \begin_inset LatexCommand \index{-\/-int-long-reent}
10836
10837 \end_inset
10838
10839  compiler option.
10840 \layout Standard
10841
10842 Calling other functions from an interrupt service routine is not recommended,
10843  avoid it if possible.
10844  Note that when some function is called from an interrupt service routine
10845  it should be preceded by a #pragma\SpecialChar ~
10846 nooverlay
10847 \begin_inset LatexCommand \index{\#pragma nooverlay}
10848
10849 \end_inset
10850
10851  if it is not reentrant.
10852  Furthermore nonreentrant functions should not be called from the main program
10853  while the interrupt service routine might be active.
10854
10855 \newline
10856
10857 \newline
10858 Also see section
10859 \begin_inset LatexCommand \ref{sub:Overlaying}
10860
10861 \end_inset
10862
10863 \SpecialChar ~
10864 about Overlaying and section
10865 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10866
10867 \end_inset
10868
10869 \SpecialChar ~
10870 about Functions using private register banks.
10871 \layout Subsection
10872
10873 MCS51/DS390 Interrupt Service Routines
10874 \layout Standard
10875
10876 Interrupt numbers and the corresponding address & descriptions for the Standard
10877  8051/8052 are listed below.
10878  SDCC will automatically adjust the interrupt vector table to the maximum
10879  interrupt number specified.
10880 \newline
10881
10882 \layout Standard
10883 \align center
10884
10885 \begin_inset  Tabular
10886 <lyxtabular version="3" rows="7" columns="3">
10887 <features>
10888 <column alignment="center" valignment="top" leftline="true" width="0in">
10889 <column alignment="center" valignment="top" leftline="true" width="0in">
10890 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10891 <row topline="true" bottomline="true">
10892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10893 \begin_inset Text
10894
10895 \layout Standard
10896
10897 Interrupt #
10898 \end_inset
10899 </cell>
10900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10901 \begin_inset Text
10902
10903 \layout Standard
10904
10905 Description
10906 \end_inset
10907 </cell>
10908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10909 \begin_inset Text
10910
10911 \layout Standard
10912
10913 Vector Address
10914 \end_inset
10915 </cell>
10916 </row>
10917 <row topline="true">
10918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10919 \begin_inset Text
10920
10921 \layout Standard
10922
10923 0
10924 \end_inset
10925 </cell>
10926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10927 \begin_inset Text
10928
10929 \layout Standard
10930
10931 External 0
10932 \end_inset
10933 </cell>
10934 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10935 \begin_inset Text
10936
10937 \layout Standard
10938
10939 0x0003
10940 \end_inset
10941 </cell>
10942 </row>
10943 <row topline="true">
10944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10945 \begin_inset Text
10946
10947 \layout Standard
10948
10949 1
10950 \end_inset
10951 </cell>
10952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10953 \begin_inset Text
10954
10955 \layout Standard
10956
10957 Timer 0
10958 \end_inset
10959 </cell>
10960 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10961 \begin_inset Text
10962
10963 \layout Standard
10964
10965 0x000B
10966 \end_inset
10967 </cell>
10968 </row>
10969 <row topline="true">
10970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10971 \begin_inset Text
10972
10973 \layout Standard
10974
10975 2
10976 \end_inset
10977 </cell>
10978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10979 \begin_inset Text
10980
10981 \layout Standard
10982
10983 External 1
10984 \end_inset
10985 </cell>
10986 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10987 \begin_inset Text
10988
10989 \layout Standard
10990
10991 0x0013
10992 \end_inset
10993 </cell>
10994 </row>
10995 <row topline="true">
10996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10997 \begin_inset Text
10998
10999 \layout Standard
11000
11001 3
11002 \end_inset
11003 </cell>
11004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11005 \begin_inset Text
11006
11007 \layout Standard
11008
11009 Timer 1
11010 \end_inset
11011 </cell>
11012 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11013 \begin_inset Text
11014
11015 \layout Standard
11016
11017 0x001B
11018 \end_inset
11019 </cell>
11020 </row>
11021 <row topline="true">
11022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11023 \begin_inset Text
11024
11025 \layout Standard
11026
11027 4
11028 \end_inset
11029 </cell>
11030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11031 \begin_inset Text
11032
11033 \layout Standard
11034
11035 Serial
11036 \end_inset
11037 </cell>
11038 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11039 \begin_inset Text
11040
11041 \layout Standard
11042
11043 0x0023
11044 \end_inset
11045 </cell>
11046 </row>
11047 <row topline="true" bottomline="true">
11048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11049 \begin_inset Text
11050
11051 \layout Standard
11052
11053 5
11054 \end_inset
11055 </cell>
11056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11057 \begin_inset Text
11058
11059 \layout Standard
11060
11061 Timer 2 (8052)
11062 \end_inset
11063 </cell>
11064 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11065 \begin_inset Text
11066
11067 \layout Standard
11068
11069 0x002B
11070 \end_inset
11071 </cell>
11072 </row>
11073 </lyxtabular>
11074
11075 \end_inset
11076
11077
11078 \newline
11079
11080 \layout Standard
11081
11082 If the interrupt service routine is defined without
11083 \emph on
11084 using
11085 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11086
11087 \end_inset
11088
11089
11090 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11091
11092 \end_inset
11093
11094
11095 \emph default
11096  a register bank or with register bank 0 (
11097 \emph on
11098 using
11099 \emph default
11100  0), the compiler will save the registers used by itself on the stack upon
11101  entry and restore them at exit, however if such an interrupt service routine
11102  calls another function then the entire register bank will be saved on the
11103  stack.
11104  This scheme may be advantageous for small interrupt service routines which
11105  have low register usage.
11106 \layout Standard
11107
11108 If the interrupt service routine is defined to be using a specific register
11109  bank then only
11110 \emph on
11111 a, b, dptr
11112 \emph default
11113  & psw are saved and restored, if such an interrupt service routine calls
11114  another function (using another register bank) then the entire register
11115  bank of the called function will be saved on the stack.
11116  This scheme is recommended for larger interrupt service routines.
11117 \layout Subsection
11118
11119 HC08 Interrupt Service Routines
11120 \layout Standard
11121
11122 Since the number of interrupts available is chip specific and the interrupt
11123  vector table always ends at the last byte of memory, the interrupt numbers
11124  corresponds to the interrupt vectors in reverse order of address.
11125  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11126  2 will use the interrupt vector at 0xfffa, and so on.
11127  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11128  this way; instead see section
11129 \begin_inset LatexCommand \ref{sub:Startup-Code}
11130
11131 \end_inset
11132
11133  for details on customizing startup.
11134 \layout Subsection
11135
11136 Z80 Interrupt Service Routines
11137 \layout Standard
11138
11139 The Z80 uses several different methods for determining the correct interrupt
11140  vector depending on the hardware implementation.
11141  Therefore, SDCC ignores the optional interrupt number and does not attempt
11142  to generate an interrupt vector table.
11143 \layout Standard
11144
11145 By default, SDCC generates code for a maskable interrupt, which uses an
11146  RETI instruction to return from the interrupt.
11147  To write an interrupt handler for the non-maskable interrupt, which needs
11148  an RETN instruction instead, add the
11149 \emph on
11150 critical
11151 \emph default
11152  keyword:
11153 \layout Verse
11154
11155
11156 \family typewriter
11157 void nmi_isr (void) critical interrupt
11158 \newline
11159 {
11160 \newline
11161 \SpecialChar ~
11162 \SpecialChar ~
11163 \SpecialChar ~
11164 \SpecialChar ~
11165 ...
11166
11167 \newline
11168 }
11169 \layout Section
11170
11171 Enabling and Disabling Interrupts
11172 \layout Subsection
11173
11174 Critical Functions and Critical Statements
11175 \layout Standard
11176
11177 A special keyword may be associated with a block or a function declaring
11178  it as
11179 \emph on
11180 critical
11181 \emph default
11182 .
11183  SDCC will generate code to disable all interrupts
11184 \begin_inset LatexCommand \index{interrupt}
11185
11186 \end_inset
11187
11188  upon entry to a critical function and restore the interrupt enable to the
11189  previous state before returning.
11190  Nesting critical functions will need one additional byte on the stack
11191 \begin_inset LatexCommand \index{stack}
11192
11193 \end_inset
11194
11195  for each call.
11196 \layout Verse
11197
11198
11199 \family typewriter
11200 int foo () critical
11201 \begin_inset LatexCommand \index{critical}
11202
11203 \end_inset
11204
11205
11206 \begin_inset LatexCommand \index{\_\_critical}
11207
11208 \end_inset
11209
11210
11211 \newline
11212 {
11213 \newline
11214 \SpecialChar ~
11215 \SpecialChar ~
11216 \SpecialChar ~
11217 \SpecialChar ~
11218 ...
11219
11220 \newline
11221 \SpecialChar ~
11222 \SpecialChar ~
11223 \SpecialChar ~
11224 \SpecialChar ~
11225 ...
11226
11227 \newline
11228 }
11229 \layout Standard
11230
11231 The critical attribute maybe used with other attributes like
11232 \emph on
11233 reentrant.
11234 \emph default
11235
11236 \newline
11237 The keyword
11238 \emph on
11239 critical
11240 \emph default
11241  may also be used to disable interrupts more locally:
11242 \layout Verse
11243
11244
11245 \family typewriter
11246 critical{ i++; }
11247 \layout Standard
11248
11249 More than one statement could have been included in the block.
11250 \layout Subsection
11251
11252 Enabling and Disabling Interrupts directly
11253 \layout Standard
11254
11255 Interrupts
11256 \begin_inset LatexCommand \index{interrupt}
11257
11258 \end_inset
11259
11260  can also be disabled and enabled directly (8051):
11261 \layout Verse
11262
11263
11264 \family typewriter
11265 EA = 0;\SpecialChar ~
11266 \SpecialChar ~
11267 \SpecialChar ~
11268 \SpecialChar ~
11269 \SpecialChar ~
11270 \SpecialChar ~
11271 \SpecialChar ~
11272 \SpecialChar ~
11273 \SpecialChar ~
11274 \SpecialChar ~
11275 \SpecialChar ~
11276 \SpecialChar ~
11277 or:\SpecialChar ~
11278 \SpecialChar ~
11279 \SpecialChar ~
11280 \SpecialChar ~
11281 \SpecialChar ~
11282 \SpecialChar ~
11283 \SpecialChar ~
11284 \SpecialChar ~
11285 \SpecialChar ~
11286 \SpecialChar ~
11287 \SpecialChar ~
11288 EA_SAVE = EA;
11289 \layout Verse
11290
11291
11292 \family typewriter
11293 ...\SpecialChar ~
11294 \SpecialChar ~
11295 \SpecialChar ~
11296 \SpecialChar ~
11297 \SpecialChar ~
11298 \SpecialChar ~
11299 \SpecialChar ~
11300 \SpecialChar ~
11301 \SpecialChar ~
11302 \SpecialChar ~
11303 \SpecialChar ~
11304 \SpecialChar ~
11305 \SpecialChar ~
11306 \SpecialChar ~
11307 \SpecialChar ~
11308 \SpecialChar ~
11309 \SpecialChar ~
11310 \SpecialChar ~
11311 \SpecialChar ~
11312 \SpecialChar ~
11313 \SpecialChar ~
11314 \SpecialChar ~
11315 \SpecialChar ~
11316 \SpecialChar ~
11317 \SpecialChar ~
11318 \SpecialChar ~
11319 \SpecialChar ~
11320 \SpecialChar ~
11321 \SpecialChar ~
11322 \SpecialChar ~
11323 EA = 0;
11324 \layout Verse
11325
11326
11327 \family typewriter
11328 EA = 1;\SpecialChar ~
11329 \SpecialChar ~
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 \SpecialChar ~
11334 \SpecialChar ~
11335 \SpecialChar ~
11336 \SpecialChar ~
11337 \SpecialChar ~
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 \SpecialChar ~
11341 \SpecialChar ~
11342 \SpecialChar ~
11343 \SpecialChar ~
11344 \SpecialChar ~
11345 \SpecialChar ~
11346 \SpecialChar ~
11347 \SpecialChar ~
11348 \SpecialChar ~
11349 \SpecialChar ~
11350 \SpecialChar ~
11351 \SpecialChar ~
11352 \SpecialChar ~
11353 \SpecialChar ~
11354 ...
11355 \layout Verse
11356
11357
11358 \family typewriter
11359 \SpecialChar ~
11360 \SpecialChar ~
11361 \SpecialChar ~
11362 \SpecialChar ~
11363 \SpecialChar ~
11364 \SpecialChar ~
11365 \SpecialChar ~
11366 \SpecialChar ~
11367 \SpecialChar ~
11368 \SpecialChar ~
11369 \SpecialChar ~
11370 \SpecialChar ~
11371 \SpecialChar ~
11372 \SpecialChar ~
11373 \SpecialChar ~
11374 \SpecialChar ~
11375 \SpecialChar ~
11376 \SpecialChar ~
11377 \SpecialChar ~
11378 \SpecialChar ~
11379 \SpecialChar ~
11380 \SpecialChar ~
11381 \SpecialChar ~
11382 \SpecialChar ~
11383 \SpecialChar ~
11384 \SpecialChar ~
11385 \SpecialChar ~
11386 \SpecialChar ~
11387 \SpecialChar ~
11388 \SpecialChar ~
11389 \SpecialChar ~
11390 \SpecialChar ~
11391 \SpecialChar ~
11392 EA = EA_SAVE;
11393 \layout Standard
11394
11395 On other architectures which have seperate opcodes for enabling and disabling
11396  interrupts you might want to make use of defines with inline assembly
11397 \begin_inset LatexCommand \index{Assembler routines}
11398
11399 \end_inset
11400
11401  (HC08):
11402 \layout Verse
11403
11404
11405 \family typewriter
11406 #define CLI _asm
11407 \begin_inset LatexCommand \index{\_asm}
11408
11409 \end_inset
11410
11411 \SpecialChar ~
11412 \SpecialChar ~
11413 cli\SpecialChar ~
11414 \SpecialChar ~
11415 _endasm
11416 \begin_inset LatexCommand \index{\_endasm}
11417
11418 \end_inset
11419
11420 ;
11421 \layout Verse
11422
11423
11424 \family typewriter
11425 #define SEI _asm\SpecialChar ~
11426 \SpecialChar ~
11427 sei\SpecialChar ~
11428 \SpecialChar ~
11429 _endasm;
11430 \layout Verse
11431
11432
11433 \family typewriter
11434 ...
11435 \layout Standard
11436
11437 Note: it is sometimes sufficient to disable only a specific interrupt source
11438  like f.e.
11439  a timer or serial interrupt by manipulating an
11440 \emph on
11441 interrupt mask
11442 \begin_inset LatexCommand \index{interrupt mask}
11443
11444 \end_inset
11445
11446
11447 \emph default
11448  register.
11449
11450 \layout Standard
11451
11452 Usually the time during which interrupts are disabled should be kept as
11453  short as possible.
11454  This minimizes both
11455 \emph on
11456 interrupt latency
11457 \emph default
11458
11459 \begin_inset LatexCommand \index{interrupt latency}
11460
11461 \end_inset
11462
11463  (the time between the occurrence of the interrupt and the execution of
11464  the first code in the interrupt routine) and
11465 \emph on
11466 interrupt jitter
11467 \emph default
11468
11469 \begin_inset LatexCommand \index{interrupt jitter}
11470
11471 \end_inset
11472
11473  (the difference between the shortest and the longest interrupt latency).
11474  These really are something different, f.e.
11475  a serial interrupt has to be served before its buffer overruns so it cares
11476  for the maximum interrupt latency, whereas it does not care about jitter.
11477  On a loudspeaker driven via a digital to analog converter which is fed
11478  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11479  a much smaller jitter will be very audible.
11480 \layout Standard
11481
11482 You can reenable interrupts within an interrupt routine and on some architecture
11483 s you can make use of two (or more) levels of
11484 \emph on
11485 interrupt priorities
11486 \emph default
11487
11488 \begin_inset LatexCommand \index{interrupt priority}
11489
11490 \end_inset
11491
11492 .
11493  On some architectures which don't support interrupt priorities these can
11494  be implemented by manipulating the interrupt mask and reenabling interrupts
11495  within the interrupt routine.
11496  Check there is sufficient space on the stack
11497 \begin_inset LatexCommand \index{stack}
11498
11499 \end_inset
11500
11501  and don't add complexity unless you have to.
11502
11503 \layout Subsection
11504
11505 Semaphore
11506 \begin_inset LatexCommand \index{semaphore}
11507
11508 \end_inset
11509
11510  locking (mcs51/ds390)
11511 \layout Standard
11512
11513 Some architectures (mcs51/ds390) have an atomic
11514 \begin_inset LatexCommand \index{atomic}
11515
11516 \end_inset
11517
11518  bit test and
11519 \emph on
11520
11521 \emph default
11522 clear
11523 \emph on
11524
11525 \emph default
11526 instruction.
11527  These type of instructions are typically used in preemptive multitasking
11528  systems, where a routine f.e.
11529  claims the use of a data structure ('acquires a lock
11530 \begin_inset LatexCommand \index{lock}
11531
11532 \end_inset
11533
11534  on it'), makes some modifications and then releases the lock when the data
11535  structure is consistent again.
11536  The instruction may also be used if interrupt and non-interrupt code have
11537  to compete for a resource.
11538  With the atomic bit test and clear instruction interrupts
11539 \begin_inset LatexCommand \index{interrupt}
11540
11541 \end_inset
11542
11543  don't have to be disabled for the locking operation.
11544
11545 \layout Standard
11546
11547 SDCC generates this instruction if the source follows this pattern:
11548 \layout Verse
11549
11550
11551 \family typewriter
11552 volatile
11553 \begin_inset LatexCommand \index{volatile}
11554
11555 \end_inset
11556
11557  bit resource_is_free;
11558 \newline
11559
11560 \newline
11561 if (resource_is_free)
11562 \newline
11563 \SpecialChar ~
11564 \SpecialChar ~
11565 {
11566 \newline
11567 \SpecialChar ~
11568 \SpecialChar ~
11569 \SpecialChar ~
11570 \SpecialChar ~
11571 resource_is_free=0;
11572 \newline
11573 \SpecialChar ~
11574 \SpecialChar ~
11575 \SpecialChar ~
11576 \SpecialChar ~
11577 ...
11578
11579 \newline
11580 \SpecialChar ~
11581 \SpecialChar ~
11582 \SpecialChar ~
11583 \SpecialChar ~
11584 resource_is_free=1;
11585 \newline
11586 \SpecialChar ~
11587 \SpecialChar ~
11588 }
11589 \layout Standard
11590
11591 Note, mcs51 and ds390 support only an atomic
11592 \begin_inset LatexCommand \index{atomic}
11593
11594 \end_inset
11595
11596  bit test and
11597 \emph on
11598 clear
11599 \emph default
11600  instruction (as opposed to atomic bit test and
11601 \emph on
11602 set).
11603 \layout Section
11604
11605 Functions using private register banks
11606 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11607
11608 \end_inset
11609
11610  (mcs51/ds390)
11611 \layout Standard
11612
11613 Some architectures have support for quickly changing register sets.
11614  SDCC supports this feature with the
11615 \emph on
11616 using
11617 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11618
11619 \end_inset
11620
11621
11622 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11623
11624 \end_inset
11625
11626
11627 \emph default
11628  attribute (which tells the compiler to use a register bank
11629 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11630
11631 \end_inset
11632
11633  other than the default bank zero).
11634  It should only be applied to
11635 \emph on
11636 interrupt
11637 \begin_inset LatexCommand \index{interrupt}
11638
11639 \end_inset
11640
11641
11642 \emph default
11643  functions (see footnote below).
11644  This will in most circumstances make the generated ISR code more efficient
11645  since it will not have to save registers on the stack.
11646 \layout Standard
11647
11648 The
11649 \emph on
11650 using
11651 \emph default
11652  attribute will have no effect on the generated code for a
11653 \emph on
11654 non-interrupt
11655 \emph default
11656  function (but may occasionally be useful anyway
11657 \begin_inset Foot
11658 collapsed false
11659
11660 \layout Standard
11661
11662 possible exception: if a function is called ONLY from 'interrupt' functions
11663  using a particular bank, it can be declared with the same 'using' attribute
11664  as the calling 'interrupt' functions.
11665  For instance, if you have several ISRs using bank one, and all of them
11666  call memcpy(), it might make sense to create a specialized version of memcpy()
11667  'using 1', since this would prevent the ISR from having to save bank zero
11668  to the stack on entry and switch to bank zero before calling the function
11669 \end_inset
11670
11671 ).
11672 \newline
11673
11674 \emph on
11675 (pending: I don't think this has been done yet)
11676 \layout Standard
11677
11678 An
11679 \emph on
11680 interrupt
11681 \emph default
11682  function using a non-zero bank will assume that it can trash that register
11683  bank, and will not save it.
11684  Since high-priority interrupts
11685 \begin_inset LatexCommand \index{interrupts}
11686
11687 \end_inset
11688
11689
11690 \begin_inset LatexCommand \index{interrupt priority}
11691
11692 \end_inset
11693
11694  can interrupt low-priority ones on the 8051 and friends, this means that
11695  if a high-priority ISR
11696 \emph on
11697 using
11698 \emph default
11699  a particular bank occurs while processing a low-priority ISR
11700 \emph on
11701 using
11702 \emph default
11703  the same bank, terrible and bad things can happen.
11704  To prevent this, no single register bank should be
11705 \emph on
11706 used
11707 \emph default
11708  by both a high priority and a low priority ISR.
11709  This is probably most easily done by having all high priority ISRs use
11710  one bank and all low priority ISRs use another.
11711  If you have an ISR which can change priority at runtime, you're on your
11712  own: I suggest using the default bank zero and taking the small performance
11713  hit.
11714 \layout Standard
11715
11716 It is most efficient if your ISR calls no other functions.
11717  If your ISR must call other functions, it is most efficient if those functions
11718  use the same bank as the ISR (see note 1 below); the next best is if the
11719  called functions use bank zero.
11720  It is very inefficient to call a function using a different, non-zero bank
11721  from an ISR.
11722
11723 \layout Section
11724
11725 Startup Code
11726 \begin_inset LatexCommand \label{sub:Startup-Code}
11727
11728 \end_inset
11729
11730
11731 \begin_inset LatexCommand \index{Startup code}
11732
11733 \end_inset
11734
11735
11736 \layout Subsection
11737
11738 MCS51/DS390 Startup Code
11739 \layout Standard
11740
11741 The compiler inserts a call to the C routine
11742 \emph on
11743 _sdcc_external_startup()
11744 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11745
11746 \end_inset
11747
11748
11749 \series bold
11750 \emph default
11751
11752 \series default
11753 at the start of the CODE area.
11754  This routine is in the runtime library
11755 \begin_inset LatexCommand \index{Runtime library}
11756
11757 \end_inset
11758
11759 .
11760  By default this routine returns 0, if this routine returns a non-zero value,
11761  the static & global variable initialization will be skipped and the function
11762  main will be invoked.
11763  Otherwise static & global variables will be initialized before the function
11764  main is invoked.
11765  You could add a
11766 \emph on
11767 _sdcc_external_startup()
11768 \emph default
11769  routine to your program to override the default if you need to setup hardware
11770  or perform some other critical operation prior to static & global variable
11771  initialization
11772 \begin_inset LatexCommand \index{Variable initialization}
11773
11774 \end_inset
11775
11776 .
11777  On some mcs51 variants xdata
11778 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11779
11780 \end_inset
11781
11782  memory has to be explicitly enabled before it can be accessed or if the
11783  watchdog needs to be disabled, this is the place to do it.
11784  The startup code clears all internal data memory, 256 bytes by default,
11785  but from 0 to n-1 if
11786 \emph on
11787 -
11788 \begin_inset ERT
11789 status Collapsed
11790
11791 \layout Standard
11792
11793 \backslash
11794 /
11795 \end_inset
11796
11797 -iram-size
11798 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
11799
11800 \end_inset
11801
11802 n
11803 \emph default
11804  is used.
11805  (recommended for Chipcon CC1010).
11806 \layout Standard
11807
11808 See also the compiler option
11809 \emph on
11810 -
11811 \begin_inset ERT
11812 status Collapsed
11813
11814 \layout Standard
11815
11816 \backslash
11817 /
11818 \end_inset
11819
11820 -no-xinit
11821 \emph default
11822 -
11823 \emph on
11824 opt
11825 \emph default
11826
11827 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11828
11829 \end_inset
11830
11831  and section
11832 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11833
11834 \end_inset
11835
11836 \SpecialChar ~
11837 about MCS51-variants.
11838 \layout Subsection
11839
11840 HC08 Startup Code
11841 \layout Standard
11842
11843 The HC08 startup code follows the same scheme as the MCS51 startup code.
11844 \layout Subsection
11845
11846 Z80 Startup Code
11847 \layout Standard
11848
11849 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11850  from sdcc/device/lib/z80/crt0.s.
11851  If you need a different startup code you can use the compiler option
11852 \emph on
11853 -
11854 \series bold
11855 \emph default
11856
11857 \begin_inset ERT
11858 status Collapsed
11859
11860 \layout Standard
11861
11862 \backslash
11863 /
11864 \end_inset
11865
11866
11867 \series default
11868 \emph on
11869 -no-std-crt0
11870 \emph default
11871
11872 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11873
11874 \end_inset
11875
11876  and provide your own crt0.o.
11877
11878 \layout Section
11879
11880 Inline Assembler Code
11881 \begin_inset LatexCommand \index{Assembler routines}
11882
11883 \end_inset
11884
11885
11886 \layout Subsection
11887
11888 A Step by Step Introduction
11889 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11890
11891 \end_inset
11892
11893
11894 \layout Standard
11895
11896 Starting from a small snippet of c-code this example shows for the MCS51
11897  how to use inline assembly, access variables, a function parameter and
11898  an array in xdata memory.
11899  The example uses an MCS51 here but is easily adapted for other architectures.
11900  This is a buffer routine which should be optimized:
11901 \layout Verse
11902
11903
11904 \family typewriter
11905 \size footnotesize
11906 unsigned char far
11907 \begin_inset LatexCommand \index{far (storage class)}
11908
11909 \end_inset
11910
11911
11912 \begin_inset LatexCommand \index{\_\_far (storage class)}
11913
11914 \end_inset
11915
11916  at
11917 \begin_inset LatexCommand \index{at}
11918
11919 \end_inset
11920
11921
11922 \begin_inset LatexCommand \index{\_\_at}
11923
11924 \end_inset
11925
11926  0x7f00 buf[0x100];
11927 \begin_inset LatexCommand \index{Aligned array}
11928
11929 \end_inset
11930
11931
11932 \newline
11933 unsigned char head,tail;
11934 \newline
11935
11936 \newline
11937 void to_buffer( unsigned char c )
11938 \newline
11939 {
11940 \newline
11941 \SpecialChar ~
11942 \SpecialChar ~
11943 \SpecialChar ~
11944 \SpecialChar ~
11945 if( head != tail-1 )
11946 \newline
11947 \SpecialChar ~
11948 \SpecialChar ~
11949 \SpecialChar ~
11950 \SpecialChar ~
11951 \SpecialChar ~
11952 \SpecialChar ~
11953 \SpecialChar ~
11954 \SpecialChar ~
11955 buf[ head++ ] = c;\SpecialChar ~
11956 \SpecialChar ~
11957 \SpecialChar ~
11958 \SpecialChar ~
11959 /* access to a 256 byte aligned array */
11960 \newline
11961 }
11962 \layout Standard
11963
11964 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
11965  then a corresponding buffer.asm file is generated.
11966  We define a new function
11967 \family typewriter
11968 to_buffer_asm()
11969 \family default
11970  in file buffer.c in which we cut and paste the generated code, removing
11971  unwanted comments and some ':'.
11972  Then add
11973 \begin_inset Quotes sld
11974 \end_inset
11975
11976 _asm
11977 \begin_inset Quotes srd
11978 \end_inset
11979
11980  and
11981 \begin_inset Quotes sld
11982 \end_inset
11983
11984 _endasm;
11985 \begin_inset Quotes srd
11986 \end_inset
11987
11988  to the beginning and the end of the function body:
11989 \layout Verse
11990
11991
11992 \family typewriter
11993 \size footnotesize
11994 /* With a cut and paste from the .asm file, we have something to start with.
11995 \newline
11996 \SpecialChar ~
11997 \SpecialChar ~
11998 \SpecialChar ~
11999 The function is not yet OK! (registers aren't saved) */
12000 \newline
12001 void to_buffer_asm( unsigned char c )
12002 \newline
12003 {
12004 \newline
12005 \SpecialChar ~
12006 \SpecialChar ~
12007 \SpecialChar ~
12008 \SpecialChar ~
12009 _asm
12010 \begin_inset LatexCommand \index{\_asm}
12011
12012 \end_inset
12013
12014
12015 \begin_inset LatexCommand \index{\_\_asm}
12016
12017 \end_inset
12018
12019
12020 \newline
12021 \SpecialChar ~
12022 \SpecialChar ~
12023 \SpecialChar ~
12024 \SpecialChar ~
12025 mov\SpecialChar ~
12026 \SpecialChar ~
12027 r2,dpl
12028 \newline
12029 ;buffer.c if( head != tail-1 )
12030 \newline
12031 \SpecialChar ~
12032 \SpecialChar ~
12033 \SpecialChar ~
12034 \SpecialChar ~
12035 mov\SpecialChar ~
12036 \SpecialChar ~
12037 a,_tail
12038 \newline
12039 \SpecialChar ~
12040 \SpecialChar ~
12041 \SpecialChar ~
12042 \SpecialChar ~
12043 dec\SpecialChar ~
12044 \SpecialChar ~
12045 a
12046 \newline
12047 \SpecialChar ~
12048 \SpecialChar ~
12049 \SpecialChar ~
12050 \SpecialChar ~
12051 mov\SpecialChar ~
12052 \SpecialChar ~
12053 r3,a
12054 \newline
12055 \SpecialChar ~
12056 \SpecialChar ~
12057 \SpecialChar ~
12058 \SpecialChar ~
12059 mov\SpecialChar ~
12060 \SpecialChar ~
12061 a,_head
12062 \newline
12063 \SpecialChar ~
12064 \SpecialChar ~
12065 \SpecialChar ~
12066 \SpecialChar ~
12067 cjne a,ar3,00106$
12068 \newline
12069 \SpecialChar ~
12070 \SpecialChar ~
12071 \SpecialChar ~
12072 \SpecialChar ~
12073 ret
12074 \newline
12075 00106$:
12076 \newline
12077 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12078 \begin_inset LatexCommand \index{Aligned array}
12079
12080 \end_inset
12081
12082
12083 \newline
12084 \SpecialChar ~
12085 \SpecialChar ~
12086 \SpecialChar ~
12087 \SpecialChar ~
12088 mov\SpecialChar ~
12089 \SpecialChar ~
12090 r3,_head
12091 \newline
12092 \SpecialChar ~
12093 \SpecialChar ~
12094 \SpecialChar ~
12095 \SpecialChar ~
12096 inc\SpecialChar ~
12097 \SpecialChar ~
12098 _head
12099 \newline
12100 \SpecialChar ~
12101 \SpecialChar ~
12102 \SpecialChar ~
12103 \SpecialChar ~
12104 mov\SpecialChar ~
12105 \SpecialChar ~
12106 dpl,r3
12107 \newline
12108 \SpecialChar ~
12109 \SpecialChar ~
12110 \SpecialChar ~
12111 \SpecialChar ~
12112 mov\SpecialChar ~
12113 \SpecialChar ~
12114 dph,#(_buf >> 8)
12115 \newline
12116 \SpecialChar ~
12117 \SpecialChar ~
12118 \SpecialChar ~
12119 \SpecialChar ~
12120 mov\SpecialChar ~
12121 \SpecialChar ~
12122 a,r2
12123 \newline
12124 \SpecialChar ~
12125 \SpecialChar ~
12126 \SpecialChar ~
12127 \SpecialChar ~
12128 movx @dptr,a
12129 \newline
12130 00103$:
12131 \newline
12132 \SpecialChar ~
12133 \SpecialChar ~
12134 \SpecialChar ~
12135 \SpecialChar ~
12136 ret
12137 \newline
12138 \SpecialChar ~
12139 \SpecialChar ~
12140 \SpecialChar ~
12141 \SpecialChar ~
12142 _endasm
12143 \begin_inset LatexCommand \index{\_endasm}
12144
12145 \end_inset
12146
12147
12148 \begin_inset LatexCommand \index{\_\_endasm}
12149
12150 \end_inset
12151
12152 ;
12153 \newline
12154 }
12155 \layout Standard
12156
12157 The new file buffer.c should compile with only one warning about the unreferenced
12158  function argument 'c'.
12159  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12160  (1) and finally have:
12161 \layout Verse
12162
12163
12164 \family typewriter
12165 \size footnotesize
12166 unsigned char far at 0x7f00 buf[0x100];
12167 \newline
12168 unsigned char head,tail;
12169 \newline
12170 #define USE_ASSEMBLY (1)
12171 \newline
12172
12173 \newline
12174 #if !USE_ASSEMBLY
12175 \newline
12176
12177 \newline
12178 void to_buffer( unsigned char c )
12179 \newline
12180 {
12181 \newline
12182 \SpecialChar ~
12183 \SpecialChar ~
12184 \SpecialChar ~
12185 \SpecialChar ~
12186 if( head != tail-1 )
12187 \newline
12188 \SpecialChar ~
12189 \SpecialChar ~
12190 \SpecialChar ~
12191 \SpecialChar ~
12192 \SpecialChar ~
12193 \SpecialChar ~
12194 \SpecialChar ~
12195 \SpecialChar ~
12196 buf[ head++ ] = c;
12197 \newline
12198 }
12199 \newline
12200
12201 \newline
12202 #else
12203 \newline
12204
12205 \newline
12206 void to_buffer( unsigned char c )
12207 \newline
12208 {
12209 \newline
12210 \SpecialChar ~
12211 \SpecialChar ~
12212 \SpecialChar ~
12213 \SpecialChar ~
12214 c; // to avoid warning: unreferenced function argument
12215 \newline
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 \SpecialChar ~
12219 \SpecialChar ~
12220 _asm
12221 \begin_inset LatexCommand \index{\_asm}
12222
12223 \end_inset
12224
12225
12226 \begin_inset LatexCommand \index{\_\_asm}
12227
12228 \end_inset
12229
12230
12231 \newline
12232 \SpecialChar ~
12233 \SpecialChar ~
12234 \SpecialChar ~
12235 \SpecialChar ~
12236 \SpecialChar ~
12237 \SpecialChar ~
12238 \SpecialChar ~
12239 \SpecialChar ~
12240 ; save used registers here.
12241
12242 \newline
12243 \SpecialChar ~
12244 \SpecialChar ~
12245 \SpecialChar ~
12246 \SpecialChar ~
12247 \SpecialChar ~
12248 \SpecialChar ~
12249 \SpecialChar ~
12250 \SpecialChar ~
12251 ; If we were still using r2,r3 we would have to push them here.
12252
12253 \newline
12254 ; if( head != tail-1 )
12255 \newline
12256 \SpecialChar ~
12257 \SpecialChar ~
12258 \SpecialChar ~
12259 \SpecialChar ~
12260 \SpecialChar ~
12261 \SpecialChar ~
12262 \SpecialChar ~
12263 \SpecialChar ~
12264 mov\SpecialChar ~
12265  a,_tail
12266 \newline
12267 \SpecialChar ~
12268 \SpecialChar ~
12269 \SpecialChar ~
12270 \SpecialChar ~
12271 \SpecialChar ~
12272 \SpecialChar ~
12273 \SpecialChar ~
12274 \SpecialChar ~
12275 dec\SpecialChar ~
12276  a
12277 \newline
12278 \SpecialChar ~
12279 \SpecialChar ~
12280 \SpecialChar ~
12281 \SpecialChar ~
12282 \SpecialChar ~
12283 \SpecialChar ~
12284 \SpecialChar ~
12285 \SpecialChar ~
12286 xrl\SpecialChar ~
12287  a,_head
12288 \newline
12289 \SpecialChar ~
12290 \SpecialChar ~
12291 \SpecialChar ~
12292 \SpecialChar ~
12293 \SpecialChar ~
12294 \SpecialChar ~
12295 \SpecialChar ~
12296 \SpecialChar ~
12297 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
12298 \newline
12299 \SpecialChar ~
12300 \SpecialChar ~
12301 \SpecialChar ~
12302 \SpecialChar ~
12303 \SpecialChar ~
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 jz\SpecialChar ~
12308 \SpecialChar ~
12309  t_b_end$
12310 \newline
12311 \SpecialChar ~
12312 \SpecialChar ~
12313 \SpecialChar ~
12314 \SpecialChar ~
12315 \SpecialChar ~
12316 \SpecialChar ~
12317 \SpecialChar ~
12318 \SpecialChar ~
12319 ;
12320 \newline
12321 ; buf[ head++ ] = c;
12322 \newline
12323 \SpecialChar ~
12324 \SpecialChar ~
12325 \SpecialChar ~
12326 \SpecialChar ~
12327 \SpecialChar ~
12328 \SpecialChar ~
12329 \SpecialChar ~
12330 \SpecialChar ~
12331 mov\SpecialChar ~
12332  a,dpl \SpecialChar ~
12333 \SpecialChar ~
12334 \SpecialChar ~
12335 \SpecialChar ~
12336 \SpecialChar ~
12337 \SpecialChar ~
12338 \SpecialChar ~
12339 ; dpl holds lower byte of function argument
12340 \newline
12341 \SpecialChar ~
12342 \SpecialChar ~
12343 \SpecialChar ~
12344 \SpecialChar ~
12345 \SpecialChar ~
12346 \SpecialChar ~
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 mov\SpecialChar ~
12350  dpl,_head \SpecialChar ~
12351 \SpecialChar ~
12352 \SpecialChar ~
12353 ; buf is 0x100 byte aligned so head can be used directly
12354 \newline
12355 \SpecialChar ~
12356 \SpecialChar ~
12357 \SpecialChar ~
12358 \SpecialChar ~
12359 \SpecialChar ~
12360 \SpecialChar ~
12361 \SpecialChar ~
12362 \SpecialChar ~
12363 mov\SpecialChar ~
12364  dph,#(_buf>>8)
12365 \newline
12366 \SpecialChar ~
12367 \SpecialChar ~
12368 \SpecialChar ~
12369 \SpecialChar ~
12370 \SpecialChar ~
12371 \SpecialChar ~
12372 \SpecialChar ~
12373 \SpecialChar ~
12374 movx @dptr,a
12375 \newline
12376 \SpecialChar ~
12377 \SpecialChar ~
12378 \SpecialChar ~
12379 \SpecialChar ~
12380 \SpecialChar ~
12381 \SpecialChar ~
12382 \SpecialChar ~
12383 \SpecialChar ~
12384 inc \SpecialChar ~
12385 _head
12386 \newline
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 \SpecialChar ~
12392 \SpecialChar ~
12393 \SpecialChar ~
12394 \SpecialChar ~
12395 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
12396 \newline
12397 t_b_end$:
12398 \newline
12399 \SpecialChar ~
12400 \SpecialChar ~
12401 \SpecialChar ~
12402 \SpecialChar ~
12403 \SpecialChar ~
12404 \SpecialChar ~
12405 \SpecialChar ~
12406 \SpecialChar ~
12407 ; restore used registers here
12408 \newline
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 _endasm
12414 \begin_inset LatexCommand \index{\_endasm}
12415
12416 \end_inset
12417
12418
12419 \begin_inset LatexCommand \index{\_\_endasm}
12420
12421 \end_inset
12422
12423 ;
12424 \newline
12425 }
12426 \newline
12427 #endif
12428 \layout Standard
12429
12430 The inline assembler code can contain any valid code understood by the assembler
12431 , this includes any assembler directives and comment lines
12432 \begin_inset Foot
12433 collapsed false
12434
12435 \layout Standard
12436
12437 The assembler does not like some characters like ':' or ''' in comments.
12438  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
12439 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
12440
12441 \end_inset
12442
12443
12444 \begin_inset LatexCommand \index{Assembler documentation}
12445
12446 \end_inset
12447
12448
12449 \end_inset
12450
12451 .
12452  The compiler does not do any validation of the code within the
12453 \family typewriter
12454 _asm
12455 \begin_inset LatexCommand \index{\_asm}
12456
12457 \end_inset
12458
12459
12460 \begin_inset LatexCommand \index{\_\_asm}
12461
12462 \end_inset
12463
12464  ...
12465  _endasm
12466 \size footnotesize
12467
12468 \begin_inset LatexCommand \index{\_endasm}
12469
12470 \end_inset
12471
12472
12473 \begin_inset LatexCommand \index{\_\_endasm}
12474
12475 \end_inset
12476
12477
12478 \size default
12479 ;
12480 \family default
12481  keyword pair.
12482  Specifically it will not know which registers are used and thus register
12483  pushing/popping
12484 \begin_inset LatexCommand \index{push/pop}
12485
12486 \end_inset
12487
12488  has to be done manually.
12489
12490 \layout Standard
12491
12492 It is recommended that each assembly instruction (including labels) be placed
12493  in a separate line (as the example shows).
12494  When the -
12495 \begin_inset ERT
12496 status Collapsed
12497
12498 \layout Standard
12499
12500 \backslash
12501 /
12502 \end_inset
12503
12504 -
12505 \emph on
12506 peep-asm
12507 \begin_inset LatexCommand \index{-\/-peep-asm}
12508
12509 \end_inset
12510
12511
12512 \emph default
12513  command line option is used, the inline assembler code will be passed through
12514  the peephole optimizer
12515 \begin_inset LatexCommand \index{Peephole optimizer}
12516
12517 \end_inset
12518
12519 .
12520  There are only a few (if any) cases where this option makes sense, it might
12521  cause some unexpected changes in the inline assembler code.
12522  Please go through the peephole optimizer rules defined in file
12523 \emph on
12524 SDCCpeeph.def
12525 \emph default
12526  before using this option.
12527 \layout Subsection
12528
12529 Naked Functions
12530 \begin_inset LatexCommand \label{sub:Naked-Functions}
12531
12532 \end_inset
12533
12534
12535 \begin_inset LatexCommand \index{Naked functions}
12536
12537 \end_inset
12538
12539
12540 \layout Standard
12541
12542 A special keyword may be associated with a function declaring it as
12543 \emph on
12544 _naked
12545 \begin_inset LatexCommand \index{\_naked}
12546
12547 \end_inset
12548
12549
12550 \begin_inset LatexCommand \index{\_\_naked}
12551
12552 \end_inset
12553
12554 .
12555
12556 \emph default
12557 The
12558 \emph on
12559 _naked
12560 \emph default
12561  function modifier attribute prevents the compiler from generating prologue
12562 \begin_inset LatexCommand \index{function prologue}
12563
12564 \end_inset
12565
12566  and epilogue
12567 \begin_inset LatexCommand \index{function epilogue}
12568
12569 \end_inset
12570
12571  code for that function.
12572  This means that the user is entirely responsible for such things as saving
12573  any registers that may need to be preserved, selecting the proper register
12574  bank, generating the
12575 \emph on
12576 return
12577 \emph default
12578  instruction at the end, etc.
12579  Practically, this means that the contents of the function must be written
12580  in inline assembler.
12581  This is particularly useful for interrupt functions, which can have a large
12582  (and often unnecessary) prologue/epilogue.
12583  For example, compare the code generated by these two functions:
12584 \layout Verse
12585
12586
12587 \family typewriter
12588 volatile
12589 \begin_inset LatexCommand \index{volatile}
12590
12591 \end_inset
12592
12593  data unsigned char counter;
12594 \newline
12595
12596 \newline
12597 void simpleInterrupt(void) interrupt
12598 \begin_inset LatexCommand \index{interrupt}
12599
12600 \end_inset
12601
12602
12603 \begin_inset LatexCommand \index{\_\_interrupt}
12604
12605 \end_inset
12606
12607  1
12608 \newline
12609 {
12610 \newline
12611 \SpecialChar ~
12612 \SpecialChar ~
12613 \SpecialChar ~
12614 \SpecialChar ~
12615 counter++;
12616 \newline
12617 }
12618 \newline
12619
12620 \newline
12621 void nakedInterrupt(void) interrupt 2 _naked
12622 \newline
12623 {
12624 \newline
12625 \SpecialChar ~
12626 \SpecialChar ~
12627 \SpecialChar ~
12628 \SpecialChar ~
12629 _asm
12630 \begin_inset LatexCommand \index{\_asm}
12631
12632 \end_inset
12633
12634
12635 \begin_inset LatexCommand \index{\_\_asm}
12636
12637 \end_inset
12638
12639
12640 \newline
12641 \SpecialChar ~
12642 \SpecialChar ~
12643 \SpecialChar ~
12644 \SpecialChar ~
12645 \SpecialChar ~
12646 \SpecialChar ~
12647 inc\SpecialChar ~
12648 \SpecialChar ~
12649 \SpecialChar ~
12650 \SpecialChar ~
12651 \SpecialChar ~
12652 _counter ; does not change flags, no need to save psw
12653 \newline
12654 \SpecialChar ~
12655 \SpecialChar ~
12656 \SpecialChar ~
12657 \SpecialChar ~
12658 \SpecialChar ~
12659 \SpecialChar ~
12660 reti\SpecialChar ~
12661 \SpecialChar ~
12662 \SpecialChar ~
12663 \SpecialChar ~
12664 ; MUST explicitly include ret or reti in _naked function.
12665 \newline
12666 \SpecialChar ~
12667 \SpecialChar ~
12668 \SpecialChar ~
12669 \SpecialChar ~
12670 _endasm
12671 \begin_inset LatexCommand \index{\_endasm}
12672
12673 \end_inset
12674
12675
12676 \begin_inset LatexCommand \index{\_\_endasm}
12677
12678 \end_inset
12679
12680 ;
12681 \newline
12682 }
12683 \layout Standard
12684
12685 For an 8051 target, the generated simpleInterrupt looks like:
12686 \layout Verse
12687
12688
12689 \family typewriter
12690 _simpleInterrupt:
12691 \newline
12692 \SpecialChar ~
12693 \SpecialChar ~
12694 \SpecialChar ~
12695 \SpecialChar ~
12696 push\SpecialChar ~
12697 \SpecialChar ~
12698 \SpecialChar ~
12699 \SpecialChar ~
12700 acc
12701 \newline
12702 \SpecialChar ~
12703 \SpecialChar ~
12704 \SpecialChar ~
12705 \SpecialChar ~
12706 push\SpecialChar ~
12707 \SpecialChar ~
12708 \SpecialChar ~
12709 \SpecialChar ~
12710 b
12711 \newline
12712 \SpecialChar ~
12713 \SpecialChar ~
12714 \SpecialChar ~
12715 \SpecialChar ~
12716 push\SpecialChar ~
12717 \SpecialChar ~
12718 \SpecialChar ~
12719 \SpecialChar ~
12720 dpl
12721 \newline
12722 \SpecialChar ~
12723 \SpecialChar ~
12724 \SpecialChar ~
12725 \SpecialChar ~
12726 push\SpecialChar ~
12727 \SpecialChar ~
12728 \SpecialChar ~
12729 \SpecialChar ~
12730 dph
12731 \newline
12732 \SpecialChar ~
12733 \SpecialChar ~
12734 \SpecialChar ~
12735 \SpecialChar ~
12736 push\SpecialChar ~
12737 \SpecialChar ~
12738 \SpecialChar ~
12739 \SpecialChar ~
12740 psw
12741 \newline
12742 \SpecialChar ~
12743 \SpecialChar ~
12744 \SpecialChar ~
12745 \SpecialChar ~
12746 mov\SpecialChar ~
12747 \SpecialChar ~
12748 \SpecialChar ~
12749 \SpecialChar ~
12750 \SpecialChar ~
12751 psw,#0x00
12752 \newline
12753 \SpecialChar ~
12754 \SpecialChar ~
12755 \SpecialChar ~
12756 \SpecialChar ~
12757 inc\SpecialChar ~
12758 \SpecialChar ~
12759 \SpecialChar ~
12760 \SpecialChar ~
12761 \SpecialChar ~
12762 _counter
12763 \newline
12764 \SpecialChar ~
12765 \SpecialChar ~
12766 \SpecialChar ~
12767 \SpecialChar ~
12768 pop\SpecialChar ~
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 \SpecialChar ~
12773 psw
12774 \newline
12775 \SpecialChar ~
12776 \SpecialChar ~
12777 \SpecialChar ~
12778 \SpecialChar ~
12779 pop\SpecialChar ~
12780 \SpecialChar ~
12781 \SpecialChar ~
12782 \SpecialChar ~
12783 \SpecialChar ~
12784 dph
12785 \newline
12786 \SpecialChar ~
12787 \SpecialChar ~
12788 \SpecialChar ~
12789 \SpecialChar ~
12790 pop\SpecialChar ~
12791 \SpecialChar ~
12792 \SpecialChar ~
12793 \SpecialChar ~
12794 \SpecialChar ~
12795 dpl
12796 \newline
12797 \SpecialChar ~
12798 \SpecialChar ~
12799 \SpecialChar ~
12800 \SpecialChar ~
12801 pop\SpecialChar ~
12802 \SpecialChar ~
12803 \SpecialChar ~
12804 \SpecialChar ~
12805 \SpecialChar ~
12806 b
12807 \newline
12808 \SpecialChar ~
12809 \SpecialChar ~
12810 \SpecialChar ~
12811 \SpecialChar ~
12812 pop\SpecialChar ~
12813 \SpecialChar ~
12814 \SpecialChar ~
12815 \SpecialChar ~
12816 \SpecialChar ~
12817 acc
12818 \newline
12819 \SpecialChar ~
12820 \SpecialChar ~
12821 \SpecialChar ~
12822 \SpecialChar ~
12823 reti
12824 \layout Standard
12825
12826 whereas nakedInterrupt looks like:
12827 \layout Verse
12828
12829
12830 \family typewriter
12831 _nakedInterrupt:
12832 \newline
12833 \SpecialChar ~
12834 \SpecialChar ~
12835 \SpecialChar ~
12836 \SpecialChar ~
12837 inc\SpecialChar ~
12838 \SpecialChar ~
12839 \SpecialChar ~
12840 \SpecialChar ~
12841 _counter ; does not change flags, no need to save psw
12842 \newline
12843 \SpecialChar ~
12844 \SpecialChar ~
12845 \SpecialChar ~
12846 \SpecialChar ~
12847 reti\SpecialChar ~
12848 \SpecialChar ~
12849 \SpecialChar ~
12850 \SpecialChar ~
12851 \SpecialChar ~
12852 \SpecialChar ~
12853 \SpecialChar ~
12854 \SpecialChar ~
12855 \SpecialChar ~
12856 \SpecialChar ~
12857 \SpecialChar ~
12858 \SpecialChar ~
12859 ; MUST explicitly include ret or reti in _naked function
12860 \layout Standard
12861
12862 The related directive #pragma exclude
12863 \begin_inset LatexCommand \index{\#pragma exclude}
12864
12865 \end_inset
12866
12867  allows a more fine grained control over pushing & popping
12868 \begin_inset LatexCommand \index{push/pop}
12869
12870 \end_inset
12871
12872  the registers.
12873 \layout Standard
12874
12875 While there is nothing preventing you from writing C code inside a
12876 \family typewriter
12877 _naked
12878 \family default
12879  function, there are many ways to shoot yourself in the foot doing this,
12880  and it is recommended that you stick to inline assembler.
12881 \layout Subsection
12882
12883 Use of Labels within Inline Assembler
12884 \layout Standard
12885
12886 SDCC allows the use of in-line assembler with a few restrictions regarding
12887  labels.
12888  In older versions of the compiler all labels defined within inline assembler
12889  code
12890 \emph on
12891 had to be
12892 \emph default
12893  of the form
12894 \emph on
12895 nnnnn$
12896 \emph default
12897  where nnnn is a number less than 100 (which implies a limit of utmost 100
12898  inline assembler labels
12899 \emph on
12900 per function
12901 \emph default
12902 \noun on
12903 )
12904 \noun default
12905 .
12906
12907 \layout Verse
12908
12909
12910 \family typewriter
12911 _asm
12912 \begin_inset LatexCommand \index{\_asm}
12913
12914 \end_inset
12915
12916
12917 \begin_inset LatexCommand \index{\_\_asm}
12918
12919 \end_inset
12920
12921
12922 \newline
12923 \SpecialChar ~
12924 \SpecialChar ~
12925 \SpecialChar ~
12926 \SpecialChar ~
12927 mov\SpecialChar ~
12928 \SpecialChar ~
12929 \SpecialChar ~
12930 \SpecialChar ~
12931 \SpecialChar ~
12932 b,#10
12933 \newline
12934 00001$:
12935 \newline
12936 \SpecialChar ~
12937 \SpecialChar ~
12938 \SpecialChar ~
12939 \SpecialChar ~
12940 djnz\SpecialChar ~
12941 \SpecialChar ~
12942 \SpecialChar ~
12943 \SpecialChar ~
12944 b,00001$
12945 \newline
12946 _endasm
12947 \begin_inset LatexCommand \index{\_endasm}
12948
12949 \end_inset
12950
12951
12952 \begin_inset LatexCommand \index{\_\_endasm}
12953
12954 \end_inset
12955
12956  ;
12957 \layout Standard
12958
12959 Inline assembler code cannot reference any C-Labels, however it can reference
12960  labels
12961 \begin_inset LatexCommand \index{Labels}
12962
12963 \end_inset
12964
12965  defined by the inline assembler, e.g.:
12966 \layout Verse
12967
12968
12969 \family typewriter
12970 foo() {
12971 \newline
12972 \SpecialChar ~
12973 \SpecialChar ~
12974 \SpecialChar ~
12975 \SpecialChar ~
12976 /* some c code */
12977 \newline
12978 \SpecialChar ~
12979 \SpecialChar ~
12980 \SpecialChar ~
12981 \SpecialChar ~
12982 _asm
12983 \newline
12984 \SpecialChar ~
12985 \SpecialChar ~
12986 \SpecialChar ~
12987 \SpecialChar ~
12988 \SpecialChar ~
12989 \SpecialChar ~
12990 ; some assembler code
12991 \newline
12992 \SpecialChar ~
12993 \SpecialChar ~
12994 \SpecialChar ~
12995 \SpecialChar ~
12996 \SpecialChar ~
12997 \SpecialChar ~
12998 ljmp $0003
12999 \newline
13000 \SpecialChar ~
13001 \SpecialChar ~
13002 \SpecialChar ~
13003 \SpecialChar ~
13004 _endasm;
13005 \newline
13006 \SpecialChar ~
13007 \SpecialChar ~
13008 \SpecialChar ~
13009 \SpecialChar ~
13010 /* some more c code */
13011 \newline
13012 clabel:\SpecialChar ~
13013 \SpecialChar ~
13014 /* inline assembler cannot reference this label */
13015 \newline
13016 \SpecialChar ~
13017 \SpecialChar ~
13018 \SpecialChar ~
13019 \SpecialChar ~
13020 _asm
13021 \newline
13022 \SpecialChar ~
13023 \SpecialChar ~
13024 \SpecialChar ~
13025 \SpecialChar ~
13026 $0003: ;label (can be referenced by inline assembler only)
13027 \newline
13028 \SpecialChar ~
13029 \SpecialChar ~
13030 \SpecialChar ~
13031 \SpecialChar ~
13032 _endasm
13033 \begin_inset LatexCommand \index{\_endasm}
13034
13035 \end_inset
13036
13037
13038 \begin_inset LatexCommand \index{\_\_endasm}
13039
13040 \end_inset
13041
13042  ;
13043 \newline
13044 \SpecialChar ~
13045 \SpecialChar ~
13046 \SpecialChar ~
13047 \SpecialChar ~
13048 /* some more c code */
13049 \newline
13050 }
13051 \layout Standard
13052
13053 In other words inline assembly code can access labels defined in inline
13054  assembly within the scope of the function.
13055  The same goes the other way, i.e.
13056  labels defines in inline assembly can not be accessed by C statements.
13057 \layout Section
13058
13059 Interfacing with Assembler Code
13060 \begin_inset LatexCommand \index{Assembler routines}
13061
13062 \end_inset
13063
13064
13065 \layout Subsection
13066
13067 Global Registers used for Parameter Passing
13068 \begin_inset LatexCommand \index{Parameter passing}
13069
13070 \end_inset
13071
13072
13073 \layout Standard
13074
13075 The compiler always uses the global registers
13076 \emph on
13077 DPL, DPH
13078 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13079
13080 \end_inset
13081
13082
13083 \begin_inset LatexCommand \index{DPTR}
13084
13085 \end_inset
13086
13087 , B
13088 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13089
13090 \end_inset
13091
13092
13093 \emph default
13094 and
13095 \emph on
13096  ACC
13097 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13098
13099 \end_inset
13100
13101
13102 \emph default
13103  to pass the first parameter to a routine.
13104  The second parameter onwards is either allocated on the stack (for reentrant
13105  routines or if -
13106 \begin_inset ERT
13107 status Collapsed
13108
13109 \layout Standard
13110
13111 \backslash
13112 /
13113 \end_inset
13114
13115 -stack-auto is used) or in data / xdata memory (depending on the memory
13116  model).
13117
13118 \layout Subsection
13119
13120 Assembler Routine (non-reentrant)
13121 \layout Standard
13122
13123 In the following example
13124 \begin_inset LatexCommand \index{reentrant}
13125
13126 \end_inset
13127
13128
13129 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13130
13131 \end_inset
13132
13133  the function c_func calls an assembler routine asm_func, which takes two
13134  parameters
13135 \begin_inset LatexCommand \index{function parameter}
13136
13137 \end_inset
13138
13139 .
13140 \layout Verse
13141
13142
13143 \family typewriter
13144 extern int asm_func(unsigned char, unsigned char);
13145 \newline
13146
13147 \newline
13148 int c_func (unsigned char i, unsigned char j)
13149 \newline
13150 {
13151 \newline
13152 \SpecialChar ~
13153 \SpecialChar ~
13154 \SpecialChar ~
13155 \SpecialChar ~
13156 return asm_func(i,j);
13157 \newline
13158 }
13159 \newline
13160
13161 \newline
13162 int main()
13163 \newline
13164 {
13165 \newline
13166 \SpecialChar ~
13167 \SpecialChar ~
13168 \SpecialChar ~
13169 \SpecialChar ~
13170 return c_func(10,9);
13171 \newline
13172 }
13173 \layout Standard
13174
13175 The corresponding assembler function is:
13176 \layout Verse
13177
13178
13179 \family typewriter
13180 .globl _asm_func_PARM_2
13181 \newline
13182 \SpecialChar ~
13183 \SpecialChar ~
13184 \SpecialChar ~
13185 \SpecialChar ~
13186 \SpecialChar ~
13187 \SpecialChar ~
13188 \SpecialChar ~
13189 \SpecialChar ~
13190 .globl _asm_func
13191 \newline
13192 \SpecialChar ~
13193 \SpecialChar ~
13194 \SpecialChar ~
13195 \SpecialChar ~
13196 \SpecialChar ~
13197 \SpecialChar ~
13198 \SpecialChar ~
13199 \SpecialChar ~
13200 .area OSEG
13201 \newline
13202 _asm_func_PARM_2:
13203 \newline
13204 \SpecialChar ~
13205 \SpecialChar ~
13206 \SpecialChar ~
13207 \SpecialChar ~
13208 \SpecialChar ~
13209 \SpecialChar ~
13210 \SpecialChar ~
13211 \SpecialChar ~
13212 .ds    1
13213 \newline
13214 \SpecialChar ~
13215 \SpecialChar ~
13216 \SpecialChar ~
13217 \SpecialChar ~
13218 \SpecialChar ~
13219 \SpecialChar ~
13220 \SpecialChar ~
13221 \SpecialChar ~
13222 .area CSEG
13223 \newline
13224 _asm_func:
13225 \newline
13226 \SpecialChar ~
13227 \SpecialChar ~
13228 \SpecialChar ~
13229 \SpecialChar ~
13230 \SpecialChar ~
13231 \SpecialChar ~
13232 \SpecialChar ~
13233 \SpecialChar ~
13234 mov\SpecialChar ~
13235 \SpecialChar ~
13236 \SpecialChar ~
13237 \SpecialChar ~
13238 a,dpl
13239 \newline
13240 \SpecialChar ~
13241 \SpecialChar ~
13242 \SpecialChar ~
13243 \SpecialChar ~
13244 \SpecialChar ~
13245 \SpecialChar ~
13246 \SpecialChar ~
13247 \SpecialChar ~
13248 add\SpecialChar ~
13249 \SpecialChar ~
13250 \SpecialChar ~
13251 \SpecialChar ~
13252 a,_asm_func_PARM_2
13253 \newline
13254 \SpecialChar ~
13255 \SpecialChar ~
13256 \SpecialChar ~
13257 \SpecialChar ~
13258 \SpecialChar ~
13259 \SpecialChar ~
13260 \SpecialChar ~
13261 \SpecialChar ~
13262 mov\SpecialChar ~
13263 \SpecialChar ~
13264 \SpecialChar ~
13265 \SpecialChar ~
13266 dpl,a
13267 \newline
13268 \SpecialChar ~
13269 \SpecialChar ~
13270 \SpecialChar ~
13271 \SpecialChar ~
13272 \SpecialChar ~
13273 \SpecialChar ~
13274 \SpecialChar ~
13275 \SpecialChar ~
13276 mov\SpecialChar ~
13277 \SpecialChar ~
13278 \SpecialChar ~
13279 \SpecialChar ~
13280 dph
13281 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13282
13283 \end_inset
13284
13285 ,#0x00
13286 \newline
13287 \SpecialChar ~
13288 \SpecialChar ~
13289 \SpecialChar ~
13290 \SpecialChar ~
13291 \SpecialChar ~
13292 \SpecialChar ~
13293 \SpecialChar ~
13294 \SpecialChar ~
13295 ret
13296 \layout Standard
13297
13298 Note here that the return values
13299 \begin_inset LatexCommand \index{return value}
13300
13301 \end_inset
13302
13303  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
13304  two byte values.
13305  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
13306 b' & 'acc' for four byte values.
13307 \layout Standard
13308
13309 The parameter naming convention is _<function_name>_PARM_<n>, where n is
13310  the parameter number starting from 1, and counting from the left.
13311  The first parameter is passed in
13312 \begin_inset Quotes eld
13313 \end_inset
13314
13315 dpl
13316 \begin_inset Quotes erd
13317 \end_inset
13318
13319  for a one byte parameter,
13320 \begin_inset Quotes eld
13321 \end_inset
13322
13323 dptr
13324 \begin_inset Quotes erd
13325 \end_inset
13326
13327  for two bytes,
13328 \begin_inset Quotes eld
13329 \end_inset
13330
13331 b,dptr
13332 \begin_inset Quotes erd
13333 \end_inset
13334
13335  for three bytes and
13336 \begin_inset Quotes eld
13337 \end_inset
13338
13339 acc,b,dptr
13340 \begin_inset Quotes erd
13341 \end_inset
13342
13343  for a four bytes parameter.
13344  The variable name for the second parameter will be _<function_name>_PARM_2.
13345 \newline
13346
13347 \newline
13348 Assemble the assembler routine with the following command:
13349 \newline
13350
13351 \newline
13352
13353 \family sans
13354 \series bold
13355 asx8051 -losg asmfunc.asm
13356 \newline
13357
13358 \newline
13359
13360 \family default
13361 \series default
13362 Then compile and link the assembler routine to the C source file with the
13363  following command:
13364 \newline
13365
13366 \newline
13367
13368 \family sans
13369 \series bold
13370 sdcc cfunc.c asmfunc.rel
13371 \layout Subsection
13372
13373 Assembler Routine (reentrant)
13374 \layout Standard
13375
13376 In this case
13377 \begin_inset LatexCommand \index{reentrant}
13378
13379 \end_inset
13380
13381
13382 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
13383
13384 \end_inset
13385
13386  the second parameter
13387 \begin_inset LatexCommand \index{function parameter}
13388
13389 \end_inset
13390
13391  onwards will be passed on the stack, the parameters are pushed from right
13392  to left i.e.
13393  after the call the leftmost parameter will be on the top of the stack.
13394  Here is an example:
13395 \layout Verse
13396
13397
13398 \family typewriter
13399 extern int asm_func(unsigned char, unsigned char);
13400 \newline
13401
13402 \newline
13403 int c_func (unsigned char i, unsigned char j) reentrant
13404 \newline
13405 {
13406 \newline
13407 \SpecialChar ~
13408 \SpecialChar ~
13409 \SpecialChar ~
13410 \SpecialChar ~
13411 return asm_func(i,j);
13412 \newline
13413 }
13414 \newline
13415
13416 \newline
13417 int main()
13418 \newline
13419 {
13420 \newline
13421 \SpecialChar ~
13422 \SpecialChar ~
13423 \SpecialChar ~
13424 \SpecialChar ~
13425 return c_func(10,9);
13426 \newline
13427 }
13428 \layout Standard
13429
13430 The corresponding assembler routine is:
13431 \layout Verse
13432
13433
13434 \family typewriter
13435 .globl _asm_func
13436 \newline
13437 _asm_func:
13438 \newline
13439 \SpecialChar ~
13440 \SpecialChar ~
13441 \SpecialChar ~
13442 \SpecialChar ~
13443 push  _bp
13444 \newline
13445 \SpecialChar ~
13446 \SpecialChar ~
13447 \SpecialChar ~
13448 \SpecialChar ~
13449 mov _bp,sp
13450 \newline
13451 \SpecialChar ~
13452 \SpecialChar ~
13453 \SpecialChar ~
13454 \SpecialChar ~
13455 mov r2,dpl
13456 \newline
13457 \SpecialChar ~
13458 \SpecialChar ~
13459 \SpecialChar ~
13460 \SpecialChar ~
13461 mov a,_bp
13462 \newline
13463 \SpecialChar ~
13464 \SpecialChar ~
13465 \SpecialChar ~
13466 \SpecialChar ~
13467 add a,#0xfd
13468 \newline
13469 \SpecialChar ~
13470 \SpecialChar ~
13471 \SpecialChar ~
13472 \SpecialChar ~
13473 mov r0,a
13474 \newline
13475 \SpecialChar ~
13476 \SpecialChar ~
13477 \SpecialChar ~
13478 \SpecialChar ~
13479 add  a,#0xfc ;?
13480 \newline
13481 \SpecialChar ~
13482 \SpecialChar ~
13483 \SpecialChar ~
13484 \SpecialChar ~
13485 mov  r1,a
13486 \newline
13487 \SpecialChar ~
13488 \SpecialChar ~
13489 \SpecialChar ~
13490 \SpecialChar ~
13491 mov  a,@r0
13492 \newline
13493 \SpecialChar ~
13494 \SpecialChar ~
13495 \SpecialChar ~
13496 \SpecialChar ~
13497 add  a,r2 ;?
13498 \newline
13499 \SpecialChar ~
13500 \SpecialChar ~
13501 \SpecialChar ~
13502 \SpecialChar ~
13503 mov  dpl,a
13504 \newline
13505 \SpecialChar ~
13506 \SpecialChar ~
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 mov  dph,#0x00
13510 \newline
13511 \SpecialChar ~
13512 \SpecialChar ~
13513 \SpecialChar ~
13514 \SpecialChar ~
13515 mov  sp,_bp
13516 \newline
13517 \SpecialChar ~
13518 \SpecialChar ~
13519 \SpecialChar ~
13520 \SpecialChar ~
13521 pop  _bp
13522 \newline
13523 \SpecialChar ~
13524 \SpecialChar ~
13525 \SpecialChar ~
13526 \SpecialChar ~
13527 ret
13528 \layout Standard
13529
13530 The compiling and linking procedure remains the same, however note the extra
13531  entry & exit linkage required for the assembler code, _bp is the stack
13532  frame pointer and is used to compute the offset into the stack for parameters
13533  and local variables.
13534 \layout Section
13535
13536 int (16 bit)
13537 \begin_inset LatexCommand \index{int (16 bit)}
13538
13539 \end_inset
13540
13541  and long (32 bit)
13542 \begin_inset LatexCommand \index{long (32 bit)}
13543
13544 \end_inset
13545
13546  Support
13547 \layout Standard
13548
13549 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
13550  multiplication and modulus operations are implemented by support routines.
13551  These support routines are all developed in ANSI-C to facilitate porting
13552  to other MCUs, although some model specific assembler optimizations are
13553  used.
13554  The following files contain the described routines, all of them can be
13555  found in <installdir>/share/sdcc/lib.
13556 \newline
13557
13558 \layout Standard
13559 \align center
13560
13561 \begin_inset  Tabular
13562 <lyxtabular version="3" rows="11" columns="2">
13563 <features>
13564 <column alignment="center" valignment="top" leftline="true" width="0">
13565 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13566 <row topline="true" bottomline="true">
13567 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13568 \begin_inset Text
13569
13570 \layout Standard
13571
13572
13573 \series bold
13574 Function
13575 \end_inset
13576 </cell>
13577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13578 \begin_inset Text
13579
13580 \layout Standard
13581
13582
13583 \series bold
13584 Description
13585 \end_inset
13586 </cell>
13587 </row>
13588 <row topline="true">
13589 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13590 \begin_inset Text
13591
13592 \layout Standard
13593
13594 _mulint.c
13595 \end_inset
13596 </cell>
13597 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13598 \begin_inset Text
13599
13600 \layout Standard
13601
13602 16 bit multiplication
13603 \end_inset
13604 </cell>
13605 </row>
13606 <row topline="true">
13607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13608 \begin_inset Text
13609
13610 \layout Standard
13611
13612 _divsint.c
13613 \end_inset
13614 </cell>
13615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13616 \begin_inset Text
13617
13618 \layout Standard
13619
13620  signed 16 bit division (calls _divuint)
13621 \end_inset
13622 </cell>
13623 </row>
13624 <row topline="true">
13625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13626 \begin_inset Text
13627
13628 \layout Standard
13629
13630 _divuint.c
13631 \end_inset
13632 </cell>
13633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13634 \begin_inset Text
13635
13636 \layout Standard
13637
13638  unsigned 16 bit division
13639 \end_inset
13640 </cell>
13641 </row>
13642 <row topline="true">
13643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13644 \begin_inset Text
13645
13646 \layout Standard
13647
13648 _modsint.c
13649 \end_inset
13650 </cell>
13651 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13652 \begin_inset Text
13653
13654 \layout Standard
13655
13656 signed 16 bit modulus (calls _moduint)
13657 \end_inset
13658 </cell>
13659 </row>
13660 <row topline="true">
13661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13662 \begin_inset Text
13663
13664 \layout Standard
13665
13666 _moduint.c
13667 \end_inset
13668 </cell>
13669 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13670 \begin_inset Text
13671
13672 \layout Standard
13673
13674 unsigned 16 bit modulus
13675 \end_inset
13676 </cell>
13677 </row>
13678 <row topline="true">
13679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13680 \begin_inset Text
13681
13682 \layout Standard
13683
13684 _mullong.c
13685 \end_inset
13686 </cell>
13687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13688 \begin_inset Text
13689
13690 \layout Standard
13691
13692 32 bit multiplication
13693 \end_inset
13694 </cell>
13695 </row>
13696 <row topline="true">
13697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13698 \begin_inset Text
13699
13700 \layout Standard
13701
13702 _divslong.c
13703 \end_inset
13704 </cell>
13705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13706 \begin_inset Text
13707
13708 \layout Standard
13709
13710  signed 32 division (calls _divulong)
13711 \end_inset
13712 </cell>
13713 </row>
13714 <row topline="true">
13715 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13716 \begin_inset Text
13717
13718 \layout Standard
13719
13720 _divulong.c
13721 \end_inset
13722 </cell>
13723 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13724 \begin_inset Text
13725
13726 \layout Standard
13727
13728 unsigned 32 division
13729 \end_inset
13730 </cell>
13731 </row>
13732 <row topline="true">
13733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13734 \begin_inset Text
13735
13736 \layout Standard
13737
13738 _modslong.c
13739 \end_inset
13740 </cell>
13741 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13742 \begin_inset Text
13743
13744 \layout Standard
13745
13746  signed 32 bit modulus (calls _modulong)
13747 \end_inset
13748 </cell>
13749 </row>
13750 <row topline="true" bottomline="true">
13751 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13752 \begin_inset Text
13753
13754 \layout Standard
13755
13756 _modulong.c
13757 \end_inset
13758 </cell>
13759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13760 \begin_inset Text
13761
13762 \layout Standard
13763
13764 unsigned 32 bit modulus
13765 \end_inset
13766 </cell>
13767 </row>
13768 </lyxtabular>
13769
13770 \end_inset
13771
13772
13773 \newline
13774
13775 \layout Standard
13776
13777 Since they are compiled as
13778 \emph on
13779 non-reentrant
13780 \emph default
13781
13782 \begin_inset LatexCommand \index{reentrant}
13783
13784 \end_inset
13785
13786 , interrupt
13787 \begin_inset LatexCommand \index{interrupt}
13788
13789 \end_inset
13790
13791  service routines should not do any of the above operations.
13792  If this is unavoidable then the above routines will need to be compiled
13793  with the
13794 \emph on
13795 -
13796 \begin_inset ERT
13797 status Collapsed
13798
13799 \layout Standard
13800
13801 \backslash
13802 /
13803 \end_inset
13804
13805 -stack-auto
13806 \begin_inset LatexCommand \index{-\/-stack-auto}
13807
13808 \end_inset
13809
13810
13811 \emph default
13812  option, after which the source program will have to be compiled with
13813 \emph on
13814 -
13815 \begin_inset ERT
13816 status Collapsed
13817
13818 \layout Standard
13819
13820 \backslash
13821 /
13822 \end_inset
13823
13824 -int-long-reent
13825 \begin_inset LatexCommand \index{-\/-int-long-reent}
13826
13827 \end_inset
13828
13829
13830 \emph default
13831  option.
13832  Notice that you don't have to call these routines directly.
13833  The compiler will use them automatically every time an integer operation
13834  is required.
13835 \layout Section
13836
13837 Floating Point Support
13838 \begin_inset LatexCommand \index{Floating point support}
13839
13840 \end_inset
13841
13842
13843 \layout Standard
13844
13845 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13846  floating point support routines are derived from gcc's floatlib.c and consist
13847  of the following routines:
13848 \newline
13849
13850 \layout Standard
13851 \align center
13852
13853 \size footnotesize
13854
13855 \begin_inset  Tabular
13856 <lyxtabular version="3" rows="17" columns="2">
13857 <features>
13858 <column alignment="center" valignment="top" leftline="true" width="0">
13859 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13860 <row topline="true" bottomline="true">
13861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13862 \begin_inset Text
13863
13864 \layout Standard
13865
13866
13867 \family roman
13868 \series medium
13869 \shape up
13870 \size normal
13871 \emph off
13872 \bar no
13873 \noun off
13874 \color none
13875 Function
13876 \end_inset
13877 </cell>
13878 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13879 \begin_inset Text
13880
13881 \layout Standard
13882
13883 Description
13884 \end_inset
13885 </cell>
13886 </row>
13887 <row topline="true">
13888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13889 \begin_inset Text
13890
13891 \layout Standard
13892
13893
13894 \family roman
13895 \series medium
13896 \shape up
13897 \size normal
13898 \emph off
13899 \bar no
13900 \noun off
13901 \color none
13902 _fsadd.c
13903 \end_inset
13904 </cell>
13905 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13906 \begin_inset Text
13907
13908 \layout Standard
13909
13910
13911 \family roman
13912 \series medium
13913 \shape up
13914 \size normal
13915 \emph off
13916 \bar no
13917 \noun off
13918 \color none
13919 add floating point numbers
13920 \end_inset
13921 </cell>
13922 </row>
13923 <row topline="true">
13924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13925 \begin_inset Text
13926
13927 \layout Standard
13928
13929
13930 \family roman
13931 \series medium
13932 \shape up
13933 \size normal
13934 \emph off
13935 \bar no
13936 \noun off
13937 \color none
13938 _fssub.c
13939 \end_inset
13940 </cell>
13941 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13942 \begin_inset Text
13943
13944 \layout Standard
13945
13946
13947 \family roman
13948 \series medium
13949 \shape up
13950 \size normal
13951 \emph off
13952 \bar no
13953 \noun off
13954 \color none
13955 subtract floating point numbers
13956 \end_inset
13957 </cell>
13958 </row>
13959 <row topline="true">
13960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13961 \begin_inset Text
13962
13963 \layout Standard
13964
13965
13966 \family roman
13967 \series medium
13968 \shape up
13969 \size normal
13970 \emph off
13971 \bar no
13972 \noun off
13973 \color none
13974 _fsdiv.c
13975 \end_inset
13976 </cell>
13977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13978 \begin_inset Text
13979
13980 \layout Standard
13981
13982
13983 \family roman
13984 \series medium
13985 \shape up
13986 \size normal
13987 \emph off
13988 \bar no
13989 \noun off
13990 \color none
13991 divide floating point numbers
13992 \end_inset
13993 </cell>
13994 </row>
13995 <row topline="true">
13996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13997 \begin_inset Text
13998
13999 \layout Standard
14000
14001
14002 \family roman
14003 \series medium
14004 \shape up
14005 \size normal
14006 \emph off
14007 \bar no
14008 \noun off
14009 \color none
14010 _fsmul.c
14011 \end_inset
14012 </cell>
14013 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14014 \begin_inset Text
14015
14016 \layout Standard
14017
14018
14019 \family roman
14020 \series medium
14021 \shape up
14022 \size normal
14023 \emph off
14024 \bar no
14025 \noun off
14026 \color none
14027 multiply floating point numbers
14028 \end_inset
14029 </cell>
14030 </row>
14031 <row topline="true">
14032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14033 \begin_inset Text
14034
14035 \layout Standard
14036
14037
14038 \family roman
14039 \series medium
14040 \shape up
14041 \size normal
14042 \emph off
14043 \bar no
14044 \noun off
14045 \color none
14046 _fs2uchar.c
14047 \end_inset
14048 </cell>
14049 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14050 \begin_inset Text
14051
14052 \layout Standard
14053
14054
14055 \family roman
14056 \series medium
14057 \shape up
14058 \size normal
14059 \emph off
14060 \bar no
14061 \noun off
14062 \color none
14063 convert floating point to unsigned char
14064 \end_inset
14065 </cell>
14066 </row>
14067 <row topline="true">
14068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14069 \begin_inset Text
14070
14071 \layout Standard
14072
14073
14074 \family roman
14075 \series medium
14076 \shape up
14077 \size normal
14078 \emph off
14079 \bar no
14080 \noun off
14081 \color none
14082 _fs2char.c
14083 \end_inset
14084 </cell>
14085 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14086 \begin_inset Text
14087
14088 \layout Standard
14089
14090
14091 \family roman
14092 \series medium
14093 \shape up
14094 \size normal
14095 \emph off
14096 \bar no
14097 \noun off
14098 \color none
14099 convert floating point to signed char
14100 \end_inset
14101 </cell>
14102 </row>
14103 <row topline="true">
14104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14105 \begin_inset Text
14106
14107 \layout Standard
14108
14109
14110 \family roman
14111 \series medium
14112 \shape up
14113 \size normal
14114 \emph off
14115 \bar no
14116 \noun off
14117 \color none
14118 _fs2uint.c
14119 \end_inset
14120 </cell>
14121 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14122 \begin_inset Text
14123
14124 \layout Standard
14125
14126
14127 \family roman
14128 \series medium
14129 \shape up
14130 \size normal
14131 \emph off
14132 \bar no
14133 \noun off
14134 \color none
14135 convert floating point to unsigned int
14136 \end_inset
14137 </cell>
14138 </row>
14139 <row topline="true">
14140 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14141 \begin_inset Text
14142
14143 \layout Standard
14144
14145
14146 \family roman
14147 \series medium
14148 \shape up
14149 \size normal
14150 \emph off
14151 \bar no
14152 \noun off
14153 \color none
14154 _fs2int.c
14155 \end_inset
14156 </cell>
14157 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14158 \begin_inset Text
14159
14160 \layout Standard
14161
14162
14163 \family roman
14164 \series medium
14165 \shape up
14166 \size normal
14167 \emph off
14168 \bar no
14169 \noun off
14170 \color none
14171 convert floating point to signed int
14172 \end_inset
14173 </cell>
14174 </row>
14175 <row topline="true">
14176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14177 \begin_inset Text
14178
14179 \layout Standard
14180
14181
14182 \family roman
14183 \series medium
14184 \shape up
14185 \size normal
14186 \emph off
14187 \bar no
14188 \noun off
14189 \color none
14190 _fs2ulong.
14191 \family default
14192 \series default
14193 \shape default
14194 \size default
14195 \emph default
14196 \bar default
14197 \noun default
14198 \color default
14199 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 unsigned long
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 _fs2long.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 signed long
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 _uchar2fs.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 unsigned char to floating point
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 _char2fs.c
14308 \end_inset
14309 </cell>
14310 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14311 \begin_inset Text
14312
14313 \layout Standard
14314
14315
14316 \family roman
14317 \series medium
14318 \shape up
14319 \size normal
14320 \emph off
14321 \bar no
14322 \noun off
14323 \color none
14324 convert char to floating point number
14325 \end_inset
14326 </cell>
14327 </row>
14328 <row topline="true">
14329 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14330 \begin_inset Text
14331
14332 \layout Standard
14333
14334
14335 \family roman
14336 \series medium
14337 \shape up
14338 \size normal
14339 \emph off
14340 \bar no
14341 \noun off
14342 \color none
14343 _uint2fs.c
14344 \end_inset
14345 </cell>
14346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14347 \begin_inset Text
14348
14349 \layout Standard
14350
14351
14352 \family roman
14353 \series medium
14354 \shape up
14355 \size normal
14356 \emph off
14357 \bar no
14358 \noun off
14359 \color none
14360 convert unsigned int to floating point
14361 \end_inset
14362 </cell>
14363 </row>
14364 <row topline="true">
14365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14366 \begin_inset Text
14367
14368 \layout Standard
14369
14370
14371 \family roman
14372 \series medium
14373 \shape up
14374 \size normal
14375 \emph off
14376 \bar no
14377 \noun off
14378 \color none
14379 _int2fs.c
14380 \end_inset
14381 </cell>
14382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14383 \begin_inset Text
14384
14385 \layout Standard
14386
14387
14388 \family roman
14389 \series medium
14390 \shape up
14391 \size normal
14392 \emph off
14393 \bar no
14394 \noun off
14395 \color none
14396 convert int to floating point numbers
14397 \end_inset
14398 </cell>
14399 </row>
14400 <row topline="true">
14401 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14402 \begin_inset Text
14403
14404 \layout Standard
14405
14406
14407 \family roman
14408 \series medium
14409 \shape up
14410 \size normal
14411 \emph off
14412 \bar no
14413 \noun off
14414 \color none
14415 _ulong2fs.c
14416 \end_inset
14417 </cell>
14418 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14419 \begin_inset Text
14420
14421 \layout Standard
14422
14423
14424 \family roman
14425 \series medium
14426 \shape up
14427 \size normal
14428 \emph off
14429 \bar no
14430 \noun off
14431 \color none
14432 convert unsigned long to floating point number
14433 \end_inset
14434 </cell>
14435 </row>
14436 <row topline="true" bottomline="true">
14437 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14438 \begin_inset Text
14439
14440 \layout Standard
14441
14442
14443 \family roman
14444 \series medium
14445 \shape up
14446 \size normal
14447 \emph off
14448 \bar no
14449 \noun off
14450 \color none
14451 _long2fs.c
14452 \end_inset
14453 </cell>
14454 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14455 \begin_inset Text
14456
14457 \layout Standard
14458
14459
14460 \family roman
14461 \series medium
14462 \shape up
14463 \size normal
14464 \emph off
14465 \bar no
14466 \noun off
14467 \color none
14468 convert long to floating point number
14469 \end_inset
14470 </cell>
14471 </row>
14472 </lyxtabular>
14473
14474 \end_inset
14475
14476
14477 \newline
14478
14479 \layout Standard
14480
14481 These support routines are developed in ANSI-C so there is room for space
14482  and speed improvement
14483 \begin_inset Foot
14484 collapsed false
14485
14486 \layout Standard
14487
14488 The floating point routines for the mcs51 are implemented in assembler
14489 \end_inset
14490
14491 .
14492  Note if all these routines are used simultaneously the data space might
14493  overflow.
14494  For serious floating point usage the large model might be needed.
14495  Also notice that you don't have to call this routines directly.
14496  The compiler will use them automatically every time a floating point operation
14497  is required.
14498 \layout Section
14499
14500 Library Routines
14501 \begin_inset LatexCommand \index{Libraries}
14502
14503 \end_inset
14504
14505
14506 \layout Standard
14507
14508
14509 \emph on
14510 <pending: this is messy and incomplete - a little more information is in
14511  sdcc/doc/libdoc.txt
14512 \emph default
14513  >
14514 \layout Subsection
14515
14516 Compiler support routines (_gptrget, _mulint etc.)
14517 \layout Subsection
14518
14519 Stdclib functions (puts, printf, strcat etc.)
14520 \layout Subsubsection
14521
14522 <stdio.h>
14523 \layout Standard
14524
14525
14526 \begin_inset LatexCommand \index{<stdio.h>}
14527
14528 \end_inset
14529
14530 As usual on embedded systems you have to provide your own
14531 \family typewriter
14532 getchar()
14533 \begin_inset LatexCommand \index{getchar()}
14534
14535 \end_inset
14536
14537
14538 \family default
14539 and
14540 \family typewriter
14541 putchar()
14542 \begin_inset LatexCommand \index{putchar()}
14543
14544 \end_inset
14545
14546
14547 \family default
14548  routines.
14549  SDCC does not know whether the system connects to a serial line with or
14550  without handshake, LCD, keyboard or other device.
14551  You'll find examples for serial routines f.e.
14552  in sdcc/device/lib.
14553 \layout Standard
14554
14555 The default
14556 \family typewriter
14557  printf()
14558 \begin_inset LatexCommand \index{printf()}
14559
14560 \end_inset
14561
14562
14563 \family default
14564 implementation in
14565 \family typewriter
14566  printf_large.c
14567 \family default
14568  does not support float (except on ds390).
14569  To enable this recompile it with the option
14570 \emph on
14571 -
14572 \begin_inset ERT
14573 status Collapsed
14574
14575 \layout Standard
14576
14577 \backslash
14578 /
14579 \end_inset
14580
14581 DUSE_FLOATS=1
14582 \begin_inset LatexCommand \index{USE\_FLOATS}
14583
14584 \end_inset
14585
14586
14587 \emph default
14588  on the command line.
14589  Use
14590 \emph on
14591 -
14592 \begin_inset ERT
14593 status Collapsed
14594
14595 \layout Standard
14596
14597 \backslash
14598 /
14599 \end_inset
14600
14601 -model-large
14602 \begin_inset LatexCommand \index{-\/-model-large}
14603
14604 \end_inset
14605
14606
14607 \emph default
14608  for the mcs51 port, since this uses a lot of memory.
14609 \layout Standard
14610
14611 If you're short on memory you might want to use
14612 \family typewriter
14613 printf_small()
14614 \begin_inset LatexCommand \index{printf\_small()}
14615
14616 \end_inset
14617
14618
14619 \family default
14620
14621 \emph on
14622 instead
14623 \emph default
14624  of
14625 \family typewriter
14626  printf().
14627
14628 \family default
14629  For the mcs51 there additionally are assembly versions
14630 \family typewriter
14631 printf_tiny()
14632 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
14633
14634 \end_inset
14635
14636
14637 \family default
14638  and
14639 \family typewriter
14640 printf_fast()
14641 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
14642
14643 \end_inset
14644
14645
14646 \family default
14647 and
14648 \family typewriter
14649  printf_fast_f()
14650 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
14651
14652 \end_inset
14653
14654
14655 \family default
14656  which should fit the requirements of many embedded systems (printf_fast()
14657  can be customized by unsetting #defines to
14658 \emph on
14659 not
14660 \emph default
14661  support long variables and field widths).
14662 \layout Subsection
14663
14664 Math functions (sin, pow, sqrt etc.)
14665 \layout Subsection
14666
14667 Other libraries
14668 \layout Standard
14669
14670 Libraries
14671 \begin_inset LatexCommand \index{Libraries}
14672
14673 \end_inset
14674
14675  included in SDCC should have a license at least as liberal as the GNU Lesser
14676  General Public License
14677 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14678
14679 \end_inset
14680
14681
14682 \emph on
14683 LGPL
14684 \emph default
14685 .
14686 \layout Comment
14687
14688 license statements for the libraries are missing.
14689  sdcc/device/lib/ser_ir.c
14690 \layout Comment
14691
14692 or _decdptr f.e.
14693  come with a GPL (as opposed to LGPL) License - this will not be liberal
14694  enough for many embedded programmers.
14695 \layout Standard
14696
14697 If you have ported some library or want to share experience about some code
14698  which f.e.
14699  falls into any of these categories Busses (I
14700 \begin_inset Formula $^{\textrm{2}}$
14701 \end_inset
14702
14703 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14704  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14705  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14706 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14707
14708 \end_inset
14709
14710 \SpecialChar ~
14711 would certainly like to hear about it.
14712  Programmers coding for embedded systems are not especially famous for being
14713  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14714 e these references are very valuable.
14715  Let's help to create a climate where information is shared.
14716 \layout Section
14717
14718 Memory Models
14719 \layout Subsection
14720
14721 MCS51 Memory Models
14722 \begin_inset LatexCommand \index{Memory model}
14723
14724 \end_inset
14725
14726
14727 \begin_inset LatexCommand \index{MCS51 memory model}
14728
14729 \end_inset
14730
14731
14732 \layout Subsubsection
14733
14734 Small and Large
14735 \layout Standard
14736
14737 SDCC allows two memory models for MCS51 code,
14738 \shape slanted
14739 small
14740 \shape default
14741  and
14742 \shape slanted
14743 large
14744 \shape default
14745 .
14746  Modules compiled with different memory models should
14747 \emph on
14748 never
14749 \emph default
14750  be combined together or the results would be unpredictable.
14751  The library routines supplied with the compiler are compiled as both small
14752  and large.
14753  The compiled library modules are contained in separate directories as small
14754  and large so that you can link to either set.
14755
14756 \layout Standard
14757
14758 When the large model is used all variables declared without a storage class
14759  will be allocated into the external ram, this includes all parameters and
14760  local variables (for non-reentrant
14761 \begin_inset LatexCommand \index{reentrant}
14762
14763 \end_inset
14764
14765  functions).
14766  When the small model is used variables without storage class are allocated
14767  in the internal ram.
14768 \layout Standard
14769
14770 Judicious usage of the processor specific storage classes
14771 \begin_inset LatexCommand \index{Storage class}
14772
14773 \end_inset
14774
14775  and the 'reentrant' function type will yield much more efficient code,
14776  than using the large model.
14777  Several optimizations are disabled when the program is compiled using the
14778  large model, it is therefore recommended that the small model be used unless
14779  absolutely required.
14780 \layout Subsubsection
14781
14782 External Stack
14783 \begin_inset LatexCommand \label{sub:External-Stack}
14784
14785 \end_inset
14786
14787
14788 \begin_inset LatexCommand \index{stack}
14789
14790 \end_inset
14791
14792
14793 \begin_inset LatexCommand \index{External stack (mcs51)}
14794
14795 \end_inset
14796
14797
14798 \layout Standard
14799
14800 The external stack (-
14801 \begin_inset ERT
14802 status Collapsed
14803
14804 \layout Standard
14805
14806 \backslash
14807 /
14808 \end_inset
14809
14810 -xstack option
14811 \begin_inset LatexCommand \index{-\/-xstack}
14812
14813 \end_inset
14814
14815 ) is located in pdata
14816 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14817
14818 \end_inset
14819
14820  memory (usually at the start of the external ram segment) and uses all
14821  unused space in pdata (max.
14822  256 bytes).
14823  When -
14824 \begin_inset ERT
14825 status Collapsed
14826
14827 \layout Standard
14828
14829 \backslash
14830 /
14831 \end_inset
14832
14833 -xstack option is used to compile the program, the parameters and local
14834  variables
14835 \begin_inset LatexCommand \index{local variables}
14836
14837 \end_inset
14838
14839  of all reentrant functions are allocated in this area.
14840  This option is provided for programs with large stack space requirements.
14841  When used with the -
14842 \begin_inset ERT
14843 status Collapsed
14844
14845 \layout Standard
14846
14847 \backslash
14848 /
14849 \end_inset
14850
14851 -stack-auto
14852 \begin_inset LatexCommand \index{-\/-stack-auto}
14853
14854 \end_inset
14855
14856  option, all parameters and local variables are allocated on the external
14857  stack (note: support libraries will need to be recompiled with the same
14858  options.
14859  There is a predefined target in the library makefile).
14860 \layout Standard
14861
14862 The compiler outputs the higher order address byte of the external ram segment
14863  into port P2
14864 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14865
14866 \end_inset
14867
14868  (see also section
14869 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14870
14871 \end_inset
14872
14873 ), therefore when using the External Stack option, this port
14874 \emph on
14875 may not
14876 \emph default
14877  be used by the application program.
14878 \layout Subsection
14879
14880 DS390 Memory Model
14881 \begin_inset LatexCommand \index{Memory model}
14882
14883 \end_inset
14884
14885
14886 \begin_inset LatexCommand \index{DS390 memory model}
14887
14888 \end_inset
14889
14890
14891 \layout Standard
14892
14893 The only model supported is Flat 24
14894 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
14895
14896 \end_inset
14897
14898 .
14899  This generates code for the 24 bit contiguous addressing mode of the Dallas
14900  DS80C390 part.
14901  In this mode, up to four meg of external RAM or code space can be directly
14902  addressed.
14903  See the data sheets at www.dalsemi.com for further information on this part.
14904 \newline
14905
14906 \newline
14907 Note that the compiler does not generate any code to place the processor
14908  into 24 bitmode (although
14909 \emph on
14910 tinibios
14911 \emph default
14912  in the ds390 libraries will do that for you).
14913  If you don't use
14914 \emph on
14915 tinibios
14916 \emph default
14917
14918 \begin_inset LatexCommand \index{Tinibios (DS390)}
14919
14920 \end_inset
14921
14922 , the boot loader or similar code must ensure that the processor is in 24
14923  bit contiguous addressing mode before calling the SDCC startup code.
14924 \newline
14925
14926 \newline
14927 Like the
14928 \emph on
14929 -
14930 \begin_inset ERT
14931 status Collapsed
14932
14933 \layout Standard
14934
14935 \backslash
14936 /
14937 \end_inset
14938
14939 -model-large
14940 \emph default
14941  option, variables will by default be placed into the XDATA segment.
14942
14943 \newline
14944
14945 \newline
14946 Segments may be placed anywhere in the 4 meg address space using the usual
14947  -
14948 \begin_inset ERT
14949 status Collapsed
14950
14951 \layout Standard
14952
14953 \backslash
14954 /
14955 \end_inset
14956
14957 -*-loc options.
14958  Note that if any segments are located above 64K, the -r flag must be passed
14959  to the linker to generate the proper segment relocations, and the Intel
14960  HEX output format must be used.
14961  The -r flag can be passed to the linker by using the option
14962 \emph on
14963 -Wl-r
14964 \emph default
14965  on the SDCC command line.
14966  However, currently the linker can not handle code segments > 64k.
14967 \layout Section
14968
14969 Pragmas
14970 \begin_inset LatexCommand \index{Pragmas}
14971
14972 \end_inset
14973
14974
14975 \layout Standard
14976
14977 SDCC supports the following #pragma directives:
14978 \layout Itemize
14979
14980 save
14981 \begin_inset LatexCommand \index{\#pragma save}
14982
14983 \end_inset
14984
14985  - this will save all current options to the save/restore stack.
14986  See #pragma\SpecialChar ~
14987 restore.
14988 \layout Itemize
14989
14990 restore
14991 \begin_inset LatexCommand \index{\#pragma restore}
14992
14993 \end_inset
14994
14995  - will restore saved options from the last save.
14996  saves & restores can be nested.
14997  SDCC uses a save/restore stack: save pushes current options to the stack,
14998  restore pulls current options from the stack.
14999  See #pragma\SpecialChar ~
15000 save.
15001 \newline
15002
15003 \layout Itemize
15004
15005 callee_saves
15006 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15007
15008 \end_inset
15009
15010
15011 \begin_inset LatexCommand \index{function prologue}
15012
15013 \end_inset
15014
15015  function1[,function2[,function3...]] - The compiler by default uses a caller
15016  saves convention for register saving across function calls, however this
15017  can cause unnecessary register pushing & popping
15018 \begin_inset LatexCommand \index{push/pop}
15019
15020 \end_inset
15021
15022  when calling small functions from larger functions.
15023  This option can be used to switch off the register saving convention for
15024  the function names specified.
15025  The compiler will not save registers when calling these functions, extra
15026  code need to be manually inserted at the entry & exit for these functions
15027  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15028  reduce code & improve run time performance of the generated code.
15029  In the future the compiler (with inter procedural analysis) may be able
15030  to determine the appropriate scheme to use for each function call.
15031  If -
15032 \begin_inset ERT
15033 status Collapsed
15034
15035 \layout Standard
15036
15037 \backslash
15038 /
15039 \end_inset
15040
15041 -callee-saves command line option is used, the function names specified
15042  in #pragma\SpecialChar ~
15043 callee_saves
15044 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15045
15046 \end_inset
15047
15048  is appended to the list of functions specified in the command line.
15049 \layout Itemize
15050
15051 exclude
15052 \begin_inset LatexCommand \index{\#pragma exclude}
15053
15054 \end_inset
15055
15056  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15057  of pairs of push/pop
15058 \begin_inset LatexCommand \index{push/pop}
15059
15060 \end_inset
15061
15062  instructions in
15063 \emph on
15064 I
15065 \emph default
15066 nterrupt
15067 \begin_inset LatexCommand \index{interrupt}
15068
15069 \end_inset
15070
15071
15072 \emph on
15073 S
15074 \emph default
15075 ervice
15076 \emph on
15077 R
15078 \emph default
15079 outines.
15080  The directive should be placed immediately before the ISR function definition
15081  and it affects ALL ISR functions following it.
15082  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15083 exclude\SpecialChar ~
15084 none
15085 \begin_inset LatexCommand \index{\#pragma exclude}
15086
15087 \end_inset
15088
15089 .
15090  See also the related keyword _naked
15091 \begin_inset LatexCommand \index{\_naked}
15092
15093 \end_inset
15094
15095
15096 \begin_inset LatexCommand \index{\_\_naked}
15097
15098 \end_inset
15099
15100 .
15101 \layout Itemize
15102
15103 less_pedantic
15104 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15105
15106 \end_inset
15107
15108  - the compiler will not warn you anymore for obvious mistakes, you'r on
15109  your own now ;-(
15110 \layout Itemize
15111
15112 disable_warning <nnnn>
15113 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15114
15115 \end_inset
15116
15117  - the compiler will not warn you anymore about warning number <nnnn>.
15118 \layout Itemize
15119
15120 nogcse
15121 \begin_inset LatexCommand \index{\#pragma nogcse}
15122
15123 \end_inset
15124
15125  - will stop global common subexpression elimination.
15126 \layout Itemize
15127
15128 noinduction
15129 \begin_inset LatexCommand \index{\#pragma noinduction}
15130
15131 \end_inset
15132
15133  - will stop loop induction optimizations.
15134 \layout Itemize
15135
15136 noinvariant
15137 \begin_inset LatexCommand \index{\#pragma noinvariant}
15138
15139 \end_inset
15140
15141  - will not do loop invariant optimizations.
15142  For more details see Loop Invariants in section
15143 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15144
15145 \end_inset
15146
15147 .
15148 \layout Itemize
15149
15150 noiv
15151 \begin_inset LatexCommand \index{\#pragma noiv}
15152
15153 \end_inset
15154
15155  - Do not generate interrupt
15156 \begin_inset LatexCommand \index{interrupt}
15157
15158 \end_inset
15159
15160  vector table entries for all ISR functions defined after the pragma.
15161  This is useful in cases where the interrupt vector table must be defined
15162  manually, or when there is a secondary, manually defined interrupt vector
15163  table (e.g.
15164  for the autovector feature of the Cypress EZ-USB FX2).
15165  More elegantly this can be achieved by obmitting the optional interrupt
15166  number after the interrupt keyword, see section
15167 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15168
15169 \end_inset
15170
15171 \SpecialChar ~
15172 about interrupts.
15173 \layout Itemize
15174
15175 nojtbound
15176 \begin_inset LatexCommand \index{\#pragma nojtbound}
15177
15178 \end_inset
15179
15180  - will not generate code for boundary value checking, when switch statements
15181  are turned into jump-tables (dangerous).
15182  For more details see section
15183 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15184
15185 \end_inset
15186
15187 .
15188 \layout Itemize
15189
15190 noloopreverse
15191 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15192
15193 \end_inset
15194
15195  - Will not do loop reversal optimization
15196 \layout Itemize
15197
15198 nooverlay
15199 \begin_inset LatexCommand \index{\#pragma nooverlay}
15200
15201 \end_inset
15202
15203  - the compiler will not overlay the parameters and local variables of a
15204  function.
15205 \layout Itemize
15206
15207 stackauto
15208 \begin_inset LatexCommand \index{\#pragma stackauto}
15209
15210 \end_inset
15211
15212 - See option -
15213 \begin_inset ERT
15214 status Collapsed
15215
15216 \layout Standard
15217
15218 \backslash
15219 /
15220 \end_inset
15221
15222 -stack-auto
15223 \begin_inset LatexCommand \index{-\/-stack-auto}
15224
15225 \end_inset
15226
15227  and section
15228 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
15229
15230 \end_inset
15231
15232  Parameters and Local Variables.
15233 \layout Itemize
15234
15235 opt_code_speed
15236 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
15237
15238 \end_inset
15239
15240 - The compiler will optimize code generation towards fast code, possibly
15241  at the expense of code size.
15242 \layout Itemize
15243
15244 opt_code_size
15245 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
15246
15247 \end_inset
15248
15249 - The compiler will optimize code generation towards compact code, possibly
15250  at the expense of code speed.
15251 \layout Itemize
15252
15253 opt_code_balanced
15254 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
15255
15256 \end_inset
15257
15258 - The compiler will attempt to generate code that is both compact and fast,
15259  as long as meeting one goal is not a detriment to the other (this is the
15260  default).
15261
15262 \layout Itemize
15263
15264 std_sdcc89
15265 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
15266
15267 \end_inset
15268
15269 - Generally follow the C89 standard, but allow SDCC features that conflict
15270  with the standard (default).
15271 \layout Itemize
15272
15273 std_c89
15274 \begin_inset LatexCommand \index{\#pragma std\_c89}
15275
15276 \end_inset
15277
15278 - Follow the C89 standard and disable SDCC features that conflict with the
15279  standard.
15280 \layout Itemize
15281
15282 std_sdcc99
15283 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
15284
15285 \end_inset
15286
15287 - Generally follow the C99 standard, but allow SDCC features that conflict
15288  with the standard (incomplete support).
15289 \layout Itemize
15290
15291 std_c99
15292 \begin_inset LatexCommand \index{\#pragma std\_c99}
15293
15294 \end_inset
15295
15296 - Follow the C99 standard and disable SDCC features that conflict with the
15297  standard (incomplete support).
15298 \layout Itemize
15299
15300 codeseg <name>
15301 \begin_inset LatexCommand \index{\#pragma codeseg}
15302
15303 \end_inset
15304
15305 - Use this name (max.
15306  8 characters) for the code segment.
15307 \layout Itemize
15308
15309 constseg <name>
15310 \begin_inset LatexCommand \index{\#pragma constseg}
15311
15312 \end_inset
15313
15314 - Use this name (max.
15315  8 characters) for the const segment.
15316 \layout Standard
15317
15318 SDCPP supports the following #pragma directives:
15319 \layout Itemize
15320
15321 preproc_asm
15322 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
15323
15324 \end_inset
15325
15326  (+ | -) - switch _asm _endasm block preprocessing on / off.
15327  Default is on.
15328 \layout Standard
15329
15330 The pragma's are intended to be used to turn-on or off certain optimizations
15331  which might cause the compiler to generate extra stack / data space to
15332  store compiler generated temporary variables.
15333  This usually happens in large functions.
15334  Pragma directives should be used as shown in the following example, they
15335  are used to control options & optimizations for a given function; pragmas
15336  should be placed before and/or after a function, placing pragma's inside
15337  a function body could have unpredictable results.
15338 \layout Verse
15339
15340
15341 \family typewriter
15342 #pragma save
15343 \begin_inset LatexCommand \index{\#pragma save}
15344
15345 \end_inset
15346
15347  \SpecialChar ~
15348 \SpecialChar ~
15349 \SpecialChar ~
15350 \SpecialChar ~
15351 \SpecialChar ~
15352 \SpecialChar ~
15353 \SpecialChar ~
15354 /* save the current settings */
15355 \newline
15356 #pragma nogcse
15357 \begin_inset LatexCommand \index{\#pragma nogcse}
15358
15359 \end_inset
15360
15361  \SpecialChar ~
15362 \SpecialChar ~
15363 \SpecialChar ~
15364 \SpecialChar ~
15365 \SpecialChar ~
15366 /* turnoff global subexpression elimination */
15367 \newline
15368 #pragma noinduction
15369 \begin_inset LatexCommand \index{\#pragma noinduction}
15370
15371 \end_inset
15372
15373  /* turn off induction optimizations */
15374 \newline
15375 int foo ()
15376 \newline
15377 {
15378 \newline
15379 \SpecialChar ~
15380  \SpecialChar ~
15381  ...
15382
15383 \newline
15384 \SpecialChar ~
15385  \SpecialChar ~
15386  /* large code */
15387 \newline
15388 \SpecialChar ~
15389  \SpecialChar ~
15390  ...
15391
15392 \newline
15393 }
15394 \newline
15395 #pragma restore
15396 \begin_inset LatexCommand \index{\#pragma restore}
15397
15398 \end_inset
15399
15400  /* turn the optimizations back on */
15401 \layout Standard
15402
15403 The compiler will generate a warning message when extra space is allocated.
15404  It is strongly recommended that the save and restore pragma's be used when
15405  changing options for a function.
15406 \layout Section
15407
15408 Defines Created by the Compiler
15409 \layout Standard
15410
15411 The compiler creates the following #defines
15412 \begin_inset LatexCommand \index{\#defines}
15413
15414 \end_inset
15415
15416
15417 \begin_inset LatexCommand \index{Defines created by the compiler}
15418
15419 \end_inset
15420
15421 :
15422 \newline
15423
15424 \layout Standard
15425
15426
15427 \begin_inset  Tabular
15428 <lyxtabular version="3" rows="10" columns="2">
15429 <features>
15430 <column alignment="center" valignment="top" leftline="true" width="0">
15431 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15432 <row topline="true" bottomline="true">
15433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15434 \begin_inset Text
15435
15436 \layout Standard
15437
15438
15439 \series bold
15440 #define
15441 \end_inset
15442 </cell>
15443 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15444 \begin_inset Text
15445
15446 \layout Standard
15447
15448
15449 \series bold
15450 Description
15451 \end_inset
15452 </cell>
15453 </row>
15454 <row topline="true">
15455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15456 \begin_inset Text
15457
15458 \layout Standard
15459
15460 SDCC
15461 \begin_inset LatexCommand \index{SDCC}
15462
15463 \end_inset
15464
15465
15466 \end_inset
15467 </cell>
15468 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15469 \begin_inset Text
15470
15471 \layout Standard
15472
15473 this Symbol is always defined
15474 \end_inset
15475 </cell>
15476 </row>
15477 <row topline="true">
15478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15479 \begin_inset Text
15480
15481 \layout Standard
15482
15483 SDCC_mcs51
15484 \begin_inset LatexCommand \index{SDCC\_mcs51}
15485
15486 \end_inset
15487
15488  or SDCC_ds390
15489 \begin_inset LatexCommand \index{SDCC\_ds390}
15490
15491 \end_inset
15492
15493  or SDCC_z80
15494 \begin_inset LatexCommand \index{SDCC\_z80}
15495
15496 \end_inset
15497
15498 , etc
15499 \end_inset
15500 </cell>
15501 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15502 \begin_inset Text
15503
15504 \layout Standard
15505
15506 depending on the model used (e.g.: -mds390
15507 \end_inset
15508 </cell>
15509 </row>
15510 <row topline="true">
15511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15512 \begin_inset Text
15513
15514 \layout Standard
15515
15516 __mcs51
15517 \begin_inset LatexCommand \index{\_\_mcs51}
15518
15519 \end_inset
15520
15521 , __ds390
15522 \begin_inset LatexCommand \index{\_\_ds390}
15523
15524 \end_inset
15525
15526 , __hc08
15527 \begin_inset LatexCommand \index{\_\_hc08}
15528
15529 \end_inset
15530
15531 , __z80
15532 \begin_inset LatexCommand \index{\_\_z80}
15533
15534 \end_inset
15535
15536 , etc
15537 \end_inset
15538 </cell>
15539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15540 \begin_inset Text
15541
15542 \layout Standard
15543
15544 depending on the model used (e.g.
15545  -mz80)
15546 \end_inset
15547 </cell>
15548 </row>
15549 <row topline="true">
15550 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15551 \begin_inset Text
15552
15553 \layout Standard
15554
15555 SDCC_STACK_AUTO
15556 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
15557
15558 \end_inset
15559
15560
15561 \end_inset
15562 </cell>
15563 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15564 \begin_inset Text
15565
15566 \layout Standard
15567
15568 when
15569 \emph on
15570 -
15571 \begin_inset ERT
15572 status Collapsed
15573
15574 \layout Standard
15575
15576 \backslash
15577 /
15578 \end_inset
15579
15580 -stack-auto
15581 \emph default
15582  option is used
15583 \end_inset
15584 </cell>
15585 </row>
15586 <row topline="true">
15587 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15588 \begin_inset Text
15589
15590 \layout Standard
15591
15592 SDCC_MODEL_SMALL
15593 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
15594
15595 \end_inset
15596
15597
15598 \end_inset
15599 </cell>
15600 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15601 \begin_inset Text
15602
15603 \layout Standard
15604
15605 when
15606 \emph on
15607 -
15608 \begin_inset ERT
15609 status Collapsed
15610
15611 \layout Standard
15612
15613 \backslash
15614 /
15615 \end_inset
15616
15617 -model-small
15618 \emph default
15619  is used
15620 \end_inset
15621 </cell>
15622 </row>
15623 <row topline="true">
15624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15625 \begin_inset Text
15626
15627 \layout Standard
15628
15629 SDCC_MODEL_LARGE
15630 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
15631
15632 \end_inset
15633
15634
15635 \end_inset
15636 </cell>
15637 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15638 \begin_inset Text
15639
15640 \layout Standard
15641
15642 when
15643 \emph on
15644 -
15645 \begin_inset ERT
15646 status Collapsed
15647
15648 \layout Standard
15649
15650 \backslash
15651 /
15652 \end_inset
15653
15654 -model-large
15655 \emph default
15656  is used
15657 \end_inset
15658 </cell>
15659 </row>
15660 <row topline="true">
15661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15662 \begin_inset Text
15663
15664 \layout Standard
15665
15666 SDCC_USE_XSTACK
15667 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15668
15669 \end_inset
15670
15671
15672 \end_inset
15673 </cell>
15674 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15675 \begin_inset Text
15676
15677 \layout Standard
15678
15679 when
15680 \emph on
15681 -
15682 \begin_inset ERT
15683 status Collapsed
15684
15685 \layout Standard
15686
15687 \backslash
15688 /
15689 \end_inset
15690
15691 -xstack
15692 \emph default
15693  option is used
15694 \end_inset
15695 </cell>
15696 </row>
15697 <row topline="true">
15698 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15699 \begin_inset Text
15700
15701 \layout Standard
15702
15703 SDCC_STACK_TENBIT
15704 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
15705
15706 \end_inset
15707
15708
15709 \end_inset
15710 </cell>
15711 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15712 \begin_inset Text
15713
15714 \layout Standard
15715
15716 when
15717 \emph on
15718 -mds390
15719 \emph default
15720  is used
15721 \end_inset
15722 </cell>
15723 </row>
15724 <row topline="true" bottomline="true">
15725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15726 \begin_inset Text
15727
15728 \layout Standard
15729
15730 SDCC_MODEL_FLAT24
15731 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
15732
15733 \end_inset
15734
15735
15736 \end_inset
15737 </cell>
15738 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15739 \begin_inset Text
15740
15741 \layout Standard
15742
15743 when
15744 \emph on
15745 -mds390
15746 \emph default
15747  is used
15748 \end_inset
15749 </cell>
15750 </row>
15751 </lyxtabular>
15752
15753 \end_inset
15754
15755
15756 \layout Chapter
15757
15758 Notes on supported Processors
15759 \layout Section
15760
15761 MCS51 variants
15762 \begin_inset LatexCommand \label{sub:MCS51-variants}
15763
15764 \end_inset
15765
15766
15767 \begin_inset LatexCommand \index{MCS51 variants}
15768
15769 \end_inset
15770
15771
15772 \layout Standard
15773
15774 MCS51 processors are available from many vendors and come in many different
15775  flavours.
15776  While they might differ considerably in respect to Special Function Registers
15777  the core MCS51 is usually not modified or is kept compatible.
15778
15779 \layout Subsection
15780
15781 pdata access by SFR
15782 \layout Standard
15783
15784 With the upcome of devices with internal xdata and flash memory devices
15785  using port P2
15786 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15787
15788 \end_inset
15789
15790  as dedicated I/O port is becoming more popular.
15791  Switching the high byte for pdata
15792 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15793
15794 \end_inset
15795
15796  access which was formerly done by port P2 is then achieved by a Special
15797  Function Register
15798 \begin_inset LatexCommand \index{sfr}
15799
15800 \end_inset
15801
15802 .
15803  In well-established MCS51 tradition the address of this
15804 \emph on
15805 sfr
15806 \emph default
15807  is where the chip designers decided to put it.
15808  Needless to say that they didn't agree on a common name either.
15809  So that the startup code can correctly initialize xdata variables, you
15810  should define an sfr with the name _XPAGE
15811 \family typewriter
15812
15813 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
15814
15815 \end_inset
15816
15817
15818 \family default
15819  at the appropriate location if the default, port P2, is not used for this.
15820  Some examples are:
15821 \layout Verse
15822
15823
15824 \family typewriter
15825 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
15826 \layout Verse
15827
15828
15829 \family typewriter
15830 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
15831 \layout Verse
15832
15833
15834 \family typewriter
15835 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
15836 \layout Standard
15837
15838 For more exotic implementations further customizations may be needed.
15839  See section
15840 \begin_inset LatexCommand \ref{sub:Startup-Code}
15841
15842 \end_inset
15843
15844  for other possibilities.
15845 \layout Subsection
15846
15847 Other Features available by SFR
15848 \layout Standard
15849
15850 Some MCS51 variants offer features like Double DPTR
15851 \begin_inset LatexCommand \index{DPTR}
15852
15853 \end_inset
15854
15855 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
15856  These are currently not used for the MCS51 port.
15857  If you absolutely need them you can fall back to inline assembly or submit
15858  a patch to SDCC.
15859 \layout Section
15860
15861 DS400 port
15862 \layout Standard
15863
15864 The DS80C400 microcontroller has a rich set of peripherals.
15865  In its built-in ROM library it includes functions to access some of the
15866  features, among them is a TCP stack with IP4 and IP6 support.
15867  Library headers (currently in beta status) and other files are provided
15868  at
15869 \size footnotesize
15870
15871 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
15872
15873 \end_inset
15874
15875 .
15876
15877 \layout Section
15878
15879 The Z80 and gbz80 port
15880 \layout Standard
15881
15882 SDCC can target both the Zilog
15883 \begin_inset LatexCommand \index{Z80}
15884
15885 \end_inset
15886
15887  and the Nintendo Gameboy's Z80-like gbz80
15888 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
15889
15890 \end_inset
15891
15892 .
15893  The Z80 port is passed through the same
15894 \emph on
15895 regressions tests
15896 \begin_inset LatexCommand \index{Regression test}
15897
15898 \end_inset
15899
15900
15901 \emph default
15902  as the MCS51 and DS390 ports, so floating point support, support for long
15903  variables and bitfield support is fine.
15904  See mailing lists and forums about interrupt routines.
15905 \layout Standard
15906
15907 As always, the code is the authoritative reference - see z80/ralloc.c and
15908  z80/gen.c.
15909  The stack
15910 \begin_inset LatexCommand \index{stack}
15911
15912 \end_inset
15913
15914  frame is similar to that generated by the IAR Z80 compiler.
15915  IX is used as the base pointer, HL and IY are used as a temporary registers,
15916  and BC and DE are available for holding variables.
15917  Return values
15918 \begin_inset LatexCommand \index{return value}
15919
15920 \end_inset
15921
15922  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
15923  bytes).
15924  The gbz80 port use the same set of registers for the return values, but
15925  in a different order of significance: E (one byte), DE (two bytes), or
15926  HLDE (four bytes).
15927 \layout Section
15928
15929 The HC08 port
15930 \layout Standard
15931
15932 The port to the Motorola HC08
15933 \begin_inset LatexCommand \index{HC08}
15934
15935 \end_inset
15936
15937  family has been added in October 2003, and is still undergoing some basic
15938  development.
15939  The code generator is complete, but the register allocation is still quite
15940  unoptimized.
15941  Some of the SDCC's standard C library functions have embedded non-HC08
15942  inline assembly and so are not yet usable.
15943 \newline
15944
15945 \newline
15946
15947 \layout Section
15948
15949 The PIC14 port
15950 \layout Standard
15951
15952 The 14bit PIC
15953 \begin_inset LatexCommand \index{PIC14}
15954
15955 \end_inset
15956
15957  port still requires a major effort from the development community.
15958  However it can work for very simple code.
15959 \layout Subsection
15960
15961 C code and 14bit PIC code page
15962 \begin_inset LatexCommand \index{code page (pic14)}
15963
15964 \end_inset
15965
15966  and RAM banks
15967 \begin_inset LatexCommand \index{RAM bank (pic14)}
15968
15969 \end_inset
15970
15971
15972 \layout Standard
15973
15974 The linker organizes allocation for the code page and RAM banks.
15975  It does not have intimate knowledge of the code flow.
15976  It will put all the code section of a single asm file into a single code
15977  page.
15978  In order to make use of multiple code pages, separate asm files must be
15979  used.
15980  The compiler treats all functions of a single C file as being in the same
15981  code page unless it is non static.
15982  The compiler treats all local variables of a single C file as being in
15983  the same RAM bank unless it is an extern.
15984 \newline
15985
15986 \newline
15987 To get the best follow these guide lines:
15988 \layout Enumerate
15989
15990 make local functions static, as non static functions require code page selection
15991  overhead.
15992 \layout Enumerate
15993
15994 Make local variables static as extern variables require RAM bank selection
15995  overhead.
15996 \layout Enumerate
15997
15998 For devices that have multiple code pages it is more efficient to use the
15999  same number of files as pages, i.e.
16000  for the 16F877 use 4 separate files and i.e.
16001  for the 16F874 use 2 separate files.
16002  This way the linker can put the code for each file into different code
16003  pages and the compiler can allocate reusable variables more efficiently
16004  and there's less page selection overhead.
16005  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
16006  instruction set) use 'unsigned char' whereever possible instead of 'int'.
16007 \layout Subsection
16008
16009 Creating a device include file
16010 \layout Standard
16011
16012 For generating a device include file use the support perl script inc2h.pl
16013  kept in directory support/script.
16014 \layout Subsection
16015
16016 Interrupt code
16017 \layout Standard
16018
16019 For the interrupt function, use the keyword 'interrupt'
16020 \begin_inset LatexCommand \index{interrupt}
16021
16022 \end_inset
16023
16024  with level number of 0 (PIC14 only has 1 interrupt so this number is only
16025  there to avoid a syntax error - it ought to be fixed).
16026  E.g.:
16027 \layout Verse
16028
16029
16030 \family typewriter
16031 void Intr(void) interrupt 0
16032 \newline
16033 {
16034 \newline
16035 \SpecialChar ~
16036 \SpecialChar ~
16037 T0IF = 0; /* Clear timer interrupt */
16038 \newline
16039 }
16040 \layout Subsection
16041
16042 Linking and assembling
16043 \layout Standard
16044
16045 For assembling you can use either GPUTILS'
16046 \begin_inset LatexCommand \index{gputils (pic tools)}
16047
16048 \end_inset
16049
16050  gpasm.exe or MPLAB's mpasmwin.exe.
16051  GPUTILS is available from
16052 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
16053
16054 \end_inset
16055
16056 .
16057  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
16058  If you use MPLAB and an interrupt function then the linker script file
16059  vectors section will need to be enlarged to link with mplink.
16060 \newline
16061
16062 \newline
16063 Here is a
16064 \family typewriter
16065 Makefile
16066 \family default
16067  using GPUTILS:
16068 \layout Verse
16069
16070
16071 \family typewriter
16072 .c.o:
16073 \newline
16074 \SpecialChar ~
16075 \SpecialChar ~
16076 \SpecialChar ~
16077 \SpecialChar ~
16078 \SpecialChar ~
16079 \SpecialChar ~
16080 \SpecialChar ~
16081 \SpecialChar ~
16082 sdcc -S -V -mpic14 -p16F877 $<
16083 \newline
16084 \SpecialChar ~
16085 \SpecialChar ~
16086 \SpecialChar ~
16087 \SpecialChar ~
16088 \SpecialChar ~
16089 \SpecialChar ~
16090 \SpecialChar ~
16091 \SpecialChar ~
16092 gpasm -c $*.asm
16093 \newline
16094
16095 \newline
16096 $(PRJ).hex: $(OBJS)
16097 \newline
16098 \SpecialChar ~
16099 \SpecialChar ~
16100 \SpecialChar ~
16101 \SpecialChar ~
16102 \SpecialChar ~
16103 \SpecialChar ~
16104 \SpecialChar ~
16105 \SpecialChar ~
16106 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
16107 \layout Standard
16108
16109 Here is a
16110 \family typewriter
16111 Makefile
16112 \family default
16113  using MPLAB:
16114 \layout Verse
16115
16116
16117 \family typewriter
16118 .c.o:
16119 \newline
16120 \SpecialChar ~
16121 \SpecialChar ~
16122 \SpecialChar ~
16123 \SpecialChar ~
16124 \SpecialChar ~
16125 \SpecialChar ~
16126 \SpecialChar ~
16127 \SpecialChar ~
16128 sdcc -S -V -mpic14 -p16F877 $<
16129 \newline
16130 \SpecialChar ~
16131 \SpecialChar ~
16132 \SpecialChar ~
16133 \SpecialChar ~
16134 \SpecialChar ~
16135 \SpecialChar ~
16136 \SpecialChar ~
16137 \SpecialChar ~
16138 mpasmwin /q /o $*.asm
16139 \newline
16140
16141 \newline
16142 $(PRJ).hex: $(OBJS)
16143 \newline
16144 \SpecialChar ~
16145 \SpecialChar ~
16146 \SpecialChar ~
16147 \SpecialChar ~
16148 \SpecialChar ~
16149 \SpecialChar ~
16150 \SpecialChar ~
16151 \SpecialChar ~
16152 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
16153 \layout Standard
16154
16155 Please note that indentations within a
16156 \family typewriter
16157  Makefile
16158 \family default
16159  have to be done with a tabulator character.
16160 \layout Section
16161
16162 The PIC16
16163 \begin_inset LatexCommand \index{PIC16}
16164
16165 \end_inset
16166
16167  port
16168 \layout Standard
16169
16170 The PIC16
16171 \begin_inset LatexCommand \index{PIC16}
16172
16173 \end_inset
16174
16175  port is the portion of SDCC that is responsible to produce code for the
16176  Microchip
16177 \begin_inset LatexCommand \index{Microchip}
16178
16179 \end_inset
16180
16181 (TM) microcontrollers with 16 bit core.
16182  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
16183  Currently supported devices are:
16184 \layout Standard
16185 \align center
16186
16187 \begin_inset  Tabular
16188 <lyxtabular version="3" rows="4" columns="6">
16189 <features>
16190 <column alignment="center" valignment="top" leftline="true" width="0">
16191 <column alignment="center" valignment="top" leftline="true" width="0">
16192 <column alignment="center" valignment="top" leftline="true" width="0">
16193 <column alignment="center" valignment="top" leftline="true" width="0">
16194 <column alignment="center" valignment="top" leftline="true" width="0">
16195 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16196 <row topline="true">
16197 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16198 \begin_inset Text
16199
16200 \layout Standard
16201
16202 18F242
16203 \end_inset
16204 </cell>
16205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16206 \begin_inset Text
16207
16208 \layout Standard
16209
16210 18F248
16211 \end_inset
16212 </cell>
16213 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16214 \begin_inset Text
16215
16216 \layout Standard
16217
16218 18F252
16219 \end_inset
16220 </cell>
16221 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16222 \begin_inset Text
16223
16224 \layout Standard
16225
16226 18F258
16227 \end_inset
16228 </cell>
16229 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16230 \begin_inset Text
16231
16232 \layout Standard
16233
16234 18F442
16235 \end_inset
16236 </cell>
16237 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16238 \begin_inset Text
16239
16240 \layout Standard
16241
16242 18F448
16243 \end_inset
16244 </cell>
16245 </row>
16246 <row topline="true">
16247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16248 \begin_inset Text
16249
16250 \layout Standard
16251
16252 18F452
16253 \end_inset
16254 </cell>
16255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16256 \begin_inset Text
16257
16258 \layout Standard
16259
16260 18F458
16261 \end_inset
16262 </cell>
16263 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16264 \begin_inset Text
16265
16266 \layout Standard
16267
16268 18F1220
16269 \end_inset
16270 </cell>
16271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16272 \begin_inset Text
16273
16274 \layout Standard
16275
16276 18F2220
16277 \end_inset
16278 </cell>
16279 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16280 \begin_inset Text
16281
16282 \layout Standard
16283
16284 18F2550
16285 \end_inset
16286 </cell>
16287 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16288 \begin_inset Text
16289
16290 \layout Standard
16291
16292 18F4331
16293 \end_inset
16294 </cell>
16295 </row>
16296 <row topline="true">
16297 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16298 \begin_inset Text
16299
16300 \layout Standard
16301
16302 18F4455
16303 \end_inset
16304 </cell>
16305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16306 \begin_inset Text
16307
16308 \layout Standard
16309
16310 18F6520
16311 \end_inset
16312 </cell>
16313 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16314 \begin_inset Text
16315
16316 \layout Standard
16317
16318 18F6620
16319 \end_inset
16320 </cell>
16321 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16322 \begin_inset Text
16323
16324 \layout Standard
16325
16326 18F6680
16327 \end_inset
16328 </cell>
16329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16330 \begin_inset Text
16331
16332 \layout Standard
16333
16334 18F6720
16335 \end_inset
16336 </cell>
16337 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16338 \begin_inset Text
16339
16340 \layout Standard
16341
16342 18F8520
16343 \end_inset
16344 </cell>
16345 </row>
16346 <row topline="true" bottomline="true">
16347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16348 \begin_inset Text
16349
16350 \layout Standard
16351
16352 18F8620
16353 \end_inset
16354 </cell>
16355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16356 \begin_inset Text
16357
16358 \layout Standard
16359
16360 18F8680
16361 \end_inset
16362 </cell>
16363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16364 \begin_inset Text
16365
16366 \layout Standard
16367
16368 18F8720
16369 \end_inset
16370 </cell>
16371 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16372 \begin_inset Text
16373
16374 \layout Standard
16375
16376 \end_inset
16377 </cell>
16378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16379 \begin_inset Text
16380
16381 \layout Standard
16382
16383 \end_inset
16384 </cell>
16385 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16386 \begin_inset Text
16387
16388 \layout Standard
16389
16390 \end_inset
16391 </cell>
16392 </row>
16393 </lyxtabular>
16394
16395 \end_inset
16396
16397
16398 \layout Subsection
16399
16400 Global Options
16401 \layout Standard
16402
16403 PIC16 port supports the standard command line arguments as supposed, with
16404  the exception of certain cases that will be mentioned in the following
16405  list:
16406 \layout List
16407 \labelwidthstring 00.00.0000
16408
16409 -
16410 \begin_inset ERT
16411 status Collapsed
16412
16413 \layout Standard
16414
16415 \backslash
16416 /
16417 \end_inset
16418
16419 -callee-saves See -
16420 \begin_inset ERT
16421 status Collapsed
16422
16423 \layout Standard
16424
16425 \backslash
16426 /
16427 \end_inset
16428
16429 -all-callee-saves
16430 \layout List
16431 \labelwidthstring 00.00.0000
16432
16433 -
16434 \begin_inset ERT
16435 status Collapsed
16436
16437 \layout Standard
16438
16439 \backslash
16440 /
16441 \end_inset
16442
16443 -all-callee-saves All function arguments are passed on stack by default.
16444
16445 \emph on
16446 There is no need to specify this in the command line.
16447 \layout List
16448 \labelwidthstring 00.00.0000
16449
16450 -
16451 \begin_inset ERT
16452 status Collapsed
16453
16454 \layout Standard
16455
16456 \backslash
16457 /
16458 \end_inset
16459
16460 -fommit-frame-pointer Frame pointer will be omitted when the function uses
16461  no local variables.
16462 \layout Subsection
16463
16464 Port Specific Options
16465 \begin_inset LatexCommand \index{Options PIC16}
16466
16467 \end_inset
16468
16469
16470 \layout Standard
16471
16472 The port specific options appear after the global options in the sdcc --help
16473  output.
16474 \layout Subsubsection
16475
16476 General Options
16477 \layout Standard
16478
16479 General options enable certain port features and optimizations.
16480 \layout List
16481 \labelwidthstring 00.00.0000
16482
16483 -
16484 \begin_inset ERT
16485 status Collapsed
16486
16487 \layout Standard
16488
16489 \backslash
16490 /
16491 \end_inset
16492
16493 -stack-model=[model] Used in conjuction with the command above.
16494  Defines the stack model to be used, valid stack models are :
16495 \begin_deeper
16496 \layout List
16497 \labelwidthstring 00.00.0000
16498
16499
16500 \emph on
16501 small
16502 \emph default
16503  Selects small stack model.
16504  8 bit stack and frame pointers.
16505  Supports 256 bytes stack size.
16506 \layout List
16507 \labelwidthstring 00.00.0000
16508
16509
16510 \emph on
16511 large
16512 \emph default
16513  Selects large stack model.
16514  16 bit stack and frame pointers.
16515  Supports 65536 bytes stack size.
16516 \end_deeper
16517 \layout List
16518 \labelwidthstring 00.00.0000
16519
16520 -
16521 \begin_inset ERT
16522 status Collapsed
16523
16524 \layout Standard
16525
16526 \backslash
16527 /
16528 \end_inset
16529
16530 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
16531  unitialized data variables with [kword].
16532  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
16533 \layout List
16534 \labelwidthstring 00.00.0000
16535
16536 -
16537 \begin_inset ERT
16538 status Collapsed
16539
16540 \layout Standard
16541
16542 \backslash
16543 /
16544 \end_inset
16545
16546 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
16547  Useful for bootloaders.
16548 \layout List
16549 \labelwidthstring 00.00.0000
16550
16551 -
16552 \begin_inset ERT
16553 status Collapsed
16554
16555 \layout Standard
16556
16557 \backslash
16558 /
16559 \end_inset
16560
16561 -asm= sets the full path and name of an external assembler to call.
16562 \layout List
16563 \labelwidthstring 00.00.0000
16564
16565 -
16566 \begin_inset ERT
16567 status Collapsed
16568
16569 \layout Standard
16570
16571 \backslash
16572 /
16573 \end_inset
16574
16575 -link= sets the full path and name of an external linker to call.
16576 \layout List
16577 \labelwidthstring 00.00.0000
16578
16579 -
16580 \begin_inset ERT
16581 status Collapsed
16582
16583 \layout Standard
16584
16585 \backslash
16586 /
16587 \end_inset
16588
16589 -mplab-comp MPLAB compatibility option.
16590  Currently only suppresses special gpasm directives.
16591 \layout Subsubsection
16592
16593 Optimization Options
16594 \layout List
16595 \labelwidthstring 00.00.0000
16596
16597 -
16598 \begin_inset ERT
16599 status Collapsed
16600
16601 \layout Standard
16602
16603 \backslash
16604 /
16605 \end_inset
16606
16607 -optimize-goto Try to use (conditional) BRA instead of GOTO
16608 \layout List
16609 \labelwidthstring 00.00.0000
16610
16611 -
16612 \begin_inset ERT
16613 status Collapsed
16614
16615 \layout Standard
16616
16617 \backslash
16618 /
16619 \end_inset
16620
16621 -optimize-cmp Try to optimize some compares.
16622 \layout List
16623 \labelwidthstring 00.00.0000
16624
16625 -
16626 \begin_inset ERT
16627 status Collapsed
16628
16629 \layout Standard
16630
16631 \backslash
16632 /
16633 \end_inset
16634
16635 -obanksel=nn Set optimization level for inserting BANKSELs.
16636 \newline
16637
16638 \begin_deeper
16639 \layout List
16640 \labelwidthstring 00.00.0000
16641
16642 0 no optimization
16643 \layout List
16644 \labelwidthstring 00.00.0000
16645
16646 1 checks previous used register and if it is the same then does not emit
16647  BANKSEL, accounts only for labels.
16648 \layout List
16649 \labelwidthstring 00.00.0000
16650
16651 2 tries to check the location of (even different) symbols and removes BANKSELs
16652  if they are in the same bank.
16653
16654 \newline
16655
16656 \emph on
16657 Important: There might be problems if the linker script has data sections
16658  across bank borders!
16659 \end_deeper
16660 \layout Subsubsection
16661
16662 Linking Options
16663 \layout List
16664 \labelwidthstring 00.00.0000
16665
16666 -
16667 \begin_inset ERT
16668 status Collapsed
16669
16670 \layout Standard
16671
16672 \backslash
16673 /
16674 \end_inset
16675
16676 -nodefaultlibs do not link default libraries when linking
16677 \layout List
16678 \labelwidthstring 00.00.0000
16679
16680 -
16681 \begin_inset ERT
16682 status Collapsed
16683
16684 \layout Standard
16685
16686 \backslash
16687 /
16688 \end_inset
16689
16690 -no-crt Don't link the default run-time modules
16691 \layout List
16692 \labelwidthstring 00.00.0000
16693
16694 -
16695 \begin_inset ERT
16696 status Collapsed
16697
16698 \layout Standard
16699
16700 \backslash
16701 /
16702 \end_inset
16703
16704 -use-crt= Use a custom run-time module instead of the defaults.
16705 \layout Subsubsection
16706
16707 Debugging Options
16708 \layout Standard
16709
16710 Debugging options enable extra debugging information in the output files.
16711 \layout List
16712 \labelwidthstring 00.00.0000
16713
16714 -
16715 \begin_inset ERT
16716 status Collapsed
16717
16718 \layout Standard
16719
16720 \backslash
16721 /
16722 \end_inset
16723
16724 -debug-xtra Similar to -
16725 \begin_inset ERT
16726 status Collapsed
16727
16728 \layout Standard
16729
16730 \backslash
16731 /
16732 \end_inset
16733
16734 -debug
16735 \begin_inset LatexCommand \index{-\/-debug}
16736
16737 \end_inset
16738
16739 , but dumps more information.
16740 \layout List
16741 \labelwidthstring 00.00.0000
16742
16743 -
16744 \begin_inset ERT
16745 status Collapsed
16746
16747 \layout Standard
16748
16749 \backslash
16750 /
16751 \end_inset
16752
16753 -debug-ralloc Force register allocator to dump <source>.d file with debugging
16754  information.
16755  <source> is the name of the file compiled.
16756 \layout List
16757 \labelwidthstring 00.00.0000
16758
16759 -
16760 \begin_inset ERT
16761 status Collapsed
16762
16763 \layout Standard
16764
16765 \backslash
16766 /
16767 \end_inset
16768
16769 -pcode-verbose Enable pcode debugging information in translation.
16770 \layout List
16771 \labelwidthstring 00.00.0000
16772
16773 -
16774 \begin_inset ERT
16775 status Collapsed
16776
16777 \layout Standard
16778
16779 \backslash
16780 /
16781 \end_inset
16782
16783 -denable-peeps Force the usage of peepholes.
16784  Use with care.
16785 \layout List
16786 \labelwidthstring 00.00.0000
16787
16788 -
16789 \begin_inset ERT
16790 status Collapsed
16791
16792 \layout Standard
16793
16794 \backslash
16795 /
16796 \end_inset
16797
16798 -gstack Trace push/pops for stack pointer overflow
16799 \layout List
16800 \labelwidthstring 00.00.0000
16801
16802 -
16803 \begin_inset ERT
16804 status Collapsed
16805
16806 \layout Standard
16807
16808 \backslash
16809 /
16810 \end_inset
16811
16812 -call-tree dump call tree in .calltree file
16813 \layout Subsection
16814
16815 Enviromental Variables
16816 \layout Standard
16817
16818 There is a number of enviromental variables that can be used when running
16819  SDCC to enable certain optimizations or force a specific program behaviour.
16820  these variables are primarily for debugging purposes so they can be enabled/dis
16821 abled at will.
16822 \layout Standard
16823
16824 Currently there is only two such variables available:
16825 \layout List
16826 \labelwidthstring 00.00.0000
16827
16828 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
16829  bitfields is optimized by directly loading FSR0 with the address of the
16830  bitfield structure.
16831  Normally SDCC will cast the bitfield structure to a bitfield pointer and
16832  then load FSR0.
16833  This step saves data ram and code space for functions that perform heavy
16834  use of bitfields.
16835  (ie.
16836  80 bytes of code space are saved when compiling malloc.c with this option).
16837
16838 \layout List
16839 \labelwidthstring 00.00.0000
16840
16841 NO_REG_OPT do not perform pCode registers optimization.
16842  This should be used for debugging purposes.
16843  In some where bugs in the pcode optimizer are found, users can benefit
16844  from temporarily disabling the optimizer until the bug is fixed.
16845 \layout Subsection
16846
16847 Preprocessor Macros
16848 \layout Standard
16849
16850 PIC16 port defines the following preprocessor macros while translating a
16851  source.
16852 \layout Standard
16853 \align center
16854
16855 \begin_inset  Tabular
16856 <lyxtabular version="3" rows="6" columns="2">
16857 <features>
16858 <column alignment="center" valignment="top" leftline="true" width="0">
16859 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16860 <row topline="true" bottomline="true">
16861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16862 \begin_inset Text
16863
16864 \layout Standard
16865
16866 Macro
16867 \end_inset
16868 </cell>
16869 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16870 \begin_inset Text
16871
16872 \layout Standard
16873
16874 Description
16875 \end_inset
16876 </cell>
16877 </row>
16878 <row topline="true">
16879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16880 \begin_inset Text
16881
16882 \layout Standard
16883
16884 SDCC_pic16
16885 \end_inset
16886 </cell>
16887 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16888 \begin_inset Text
16889
16890 \layout Standard
16891
16892 Port identification
16893 \end_inset
16894 </cell>
16895 </row>
16896 <row topline="true">
16897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16898 \begin_inset Text
16899
16900 \layout Standard
16901
16902 _
16903 \begin_inset ERT
16904 status Collapsed
16905
16906 \layout Standard
16907
16908 \backslash
16909 /
16910 \end_inset
16911
16912 _pic16
16913 \end_inset
16914 </cell>
16915 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16916 \begin_inset Text
16917
16918 \layout Standard
16919
16920 Port identification (same as above)
16921 \end_inset
16922 </cell>
16923 </row>
16924 <row topline="true">
16925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16926 \begin_inset Text
16927
16928 \layout Standard
16929
16930 pic18fxxxx
16931 \end_inset
16932 </cell>
16933 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16934 \begin_inset Text
16935
16936 \layout Standard
16937
16938 MCU Identification.
16939
16940 \emph on
16941 xxxx
16942 \emph default
16943  is the microcontrol identification number, i.e.
16944  452, 6620, etc
16945 \end_inset
16946 </cell>
16947 </row>
16948 <row topline="true">
16949 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16950 \begin_inset Text
16951
16952 \layout Standard
16953
16954 _
16955 \begin_inset ERT
16956 status Collapsed
16957
16958 \layout Standard
16959
16960 \backslash
16961 /
16962 \end_inset
16963
16964 _18Fxxxx
16965 \end_inset
16966 </cell>
16967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16968 \begin_inset Text
16969
16970 \layout Standard
16971
16972 MCU Identification (same as above)
16973 \end_inset
16974 </cell>
16975 </row>
16976 <row topline="true" bottomline="true">
16977 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16978 \begin_inset Text
16979
16980 \layout Standard
16981
16982 STACK_MODEL_nnn
16983 \end_inset
16984 </cell>
16985 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16986 \begin_inset Text
16987
16988 \layout Standard
16989
16990 nnn = SMALL or LARGE respectively according to the stack model used
16991 \end_inset
16992 </cell>
16993 </row>
16994 </lyxtabular>
16995
16996 \end_inset
16997
16998
16999 \layout Standard
17000
17001 In addition the following macros are defined when calling assembler:
17002 \layout Standard
17003 \align center
17004
17005 \begin_inset  Tabular
17006 <lyxtabular version="3" rows="4" columns="2">
17007 <features>
17008 <column alignment="center" valignment="top" leftline="true" width="0">
17009 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17010 <row topline="true" bottomline="true">
17011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17012 \begin_inset Text
17013
17014 \layout Standard
17015
17016 Macro
17017 \end_inset
17018 </cell>
17019 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17020 \begin_inset Text
17021
17022 \layout Standard
17023
17024 Description
17025 \end_inset
17026 </cell>
17027 </row>
17028 <row topline="true">
17029 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17030 \begin_inset Text
17031
17032 \layout Standard
17033
17034 __18Fxxxx
17035 \end_inset
17036 </cell>
17037 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17038 \begin_inset Text
17039
17040 \layout Standard
17041
17042 MCU Identification.
17043
17044 \emph on
17045 xxxx
17046 \emph default
17047  is the microcontrol identification number, i.e.
17048  452, 6620, etc
17049 \end_inset
17050 </cell>
17051 </row>
17052 <row topline="true">
17053 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17054 \begin_inset Text
17055
17056 \layout Standard
17057
17058 SDCC_MODEL_nnn
17059 \end_inset
17060 </cell>
17061 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17062 \begin_inset Text
17063
17064 \layout Standard
17065
17066 nnn = SMALL or LARGE respectively according to the memory model used for
17067  SDCC
17068 \end_inset
17069 </cell>
17070 </row>
17071 <row topline="true" bottomline="true">
17072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17073 \begin_inset Text
17074
17075 \layout Standard
17076
17077 STACK_MODEL_nnn
17078 \end_inset
17079 </cell>
17080 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17081 \begin_inset Text
17082
17083 \layout Standard
17084
17085 nnn = SMALL or LARGE respectively according to the stack model used
17086 \end_inset
17087 </cell>
17088 </row>
17089 </lyxtabular>
17090
17091 \end_inset
17092
17093
17094 \layout Subsection
17095
17096 Directories
17097 \layout Standard
17098
17099 PIC16
17100 \begin_inset LatexCommand \index{PIC16}
17101
17102 \end_inset
17103
17104  port uses the following directories for searching header files and libraries.
17105 \layout Standard
17106 \align center
17107
17108 \begin_inset  Tabular
17109 <lyxtabular version="3" rows="3" columns="4">
17110 <features>
17111 <column alignment="center" valignment="top" leftline="true" width="0">
17112 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17113 <column alignment="center" valignment="top" width="0">
17114 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17115 <row topline="true" bottomline="true">
17116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17117 \begin_inset Text
17118
17119 \layout Standard
17120
17121 Directory
17122 \end_inset
17123 </cell>
17124 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17125 \begin_inset Text
17126
17127 \layout Standard
17128
17129 Description
17130 \end_inset
17131 </cell>
17132 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17133 \begin_inset Text
17134
17135 \layout Standard
17136
17137 Target
17138 \end_inset
17139 </cell>
17140 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17141 \begin_inset Text
17142
17143 \layout Standard
17144
17145 Command prefix
17146 \end_inset
17147 </cell>
17148 </row>
17149 <row topline="true">
17150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17151 \begin_inset Text
17152
17153 \layout Standard
17154
17155 PREFIX/sdcc/include/pic16
17156 \end_inset
17157 </cell>
17158 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17159 \begin_inset Text
17160
17161 \layout Standard
17162
17163 PIC16 specific headers
17164 \end_inset
17165 </cell>
17166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17167 \begin_inset Text
17168
17169 \layout Standard
17170
17171 Compiler
17172 \end_inset
17173 </cell>
17174 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17175 \begin_inset Text
17176
17177 \layout Standard
17178
17179 -I
17180 \end_inset
17181 </cell>
17182 </row>
17183 <row topline="true" bottomline="true">
17184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17185 \begin_inset Text
17186
17187 \layout Standard
17188
17189 PREFIX/sdcc/lib/pic16
17190 \end_inset
17191 </cell>
17192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17193 \begin_inset Text
17194
17195 \layout Standard
17196
17197 PIC16 specific libraries
17198 \end_inset
17199 </cell>
17200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17201 \begin_inset Text
17202
17203 \layout Standard
17204
17205 Linker
17206 \end_inset
17207 </cell>
17208 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17209 \begin_inset Text
17210
17211 \layout Standard
17212
17213 -L
17214 \end_inset
17215 </cell>
17216 </row>
17217 </lyxtabular>
17218
17219 \end_inset
17220
17221
17222 \layout Subsection
17223
17224 Pragmas
17225 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
17226
17227 \end_inset
17228
17229
17230 \layout Standard
17231
17232 PIC16 port currently supports the following pragmas:
17233 \layout List
17234 \labelwidthstring 00.00.0000
17235
17236 stack pragma stack forces the code generator to initialize the stack & frame
17237  pointers at a specific address.
17238  This is an adhoc solution for cases where no STACK directive is available
17239  in the linker script or gplink is not instructed to create a stack section.
17240 \newline
17241 The stack pragma should be used only once in a project.
17242  Multiple pragmas may result in indeterminate behaviour of the program.
17243 \begin_inset Foot
17244 collapsed false
17245
17246 \layout Standard
17247
17248 The old format (ie.
17249  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
17250  cross page boundaries (or even exceed the available data RAM) and crash
17251  the program.
17252  Make sure that stack does not cross page boundaries when using the SMALL
17253  stack model.
17254 \end_inset
17255
17256
17257 \newline
17258 The format is as follows:
17259 \layout LyX-Code
17260
17261 #pragma stack bottom_address [stack_size]
17262 \layout Standard
17263
17264
17265 \emph on
17266 bottom_address
17267 \emph default
17268  is the lower bound of the stack section.
17269  The stack pointer initially will point at address (bottom_address+stack_size-1).
17270 \layout LyX-Code
17271
17272 Example:
17273 \layout LyX-Code
17274
17275 \layout LyX-Code
17276
17277 /* initializes stack of 100 bytes at RAM address 0x200 */
17278 \layout LyX-Code
17279
17280 #pragma stack 0x200 100
17281 \layout Standard
17282
17283 If the stack_size field is omitted then a stack is created with the default
17284  size of 64.
17285  This size might be enough for most programs, but its not enough for operations
17286  with deep function nesting or excessive stack usage.
17287 \layout List
17288 \labelwidthstring 00.00.0000
17289
17290 wparam
17291 \emph on
17292 This pragma is deprecated.
17293  Its use will cause a warning message to be issued.
17294 \emph default
17295
17296 \newline
17297
17298 \layout List
17299 \labelwidthstring 00.00.0000
17300
17301 code place a function symbol at static FLASH address
17302 \layout LyX-Code
17303
17304 Example:
17305 \layout LyX-Code
17306
17307 \layout LyX-Code
17308
17309 /* place function test_func at 0x4000 */
17310 \layout LyX-Code
17311
17312 #pragma code test_func 0x4000
17313 \layout LyX-Code
17314
17315 \layout List
17316 \labelwidthstring 00.00.0000
17317
17318 library instructs the linker to use a library module.
17319 \newline
17320 Usage:
17321 \layout LyX-Code
17322
17323 #pragma library module_name
17324 \layout Standard
17325
17326
17327 \emph on
17328 module_name
17329 \emph default
17330  can be any library or object file (including its path).
17331  Note that there are four reserved keywords which have special meaning.
17332  These are:
17333 \layout Standard
17334 \align center
17335
17336 \begin_inset  Tabular
17337 <lyxtabular version="3" rows="6" columns="3">
17338 <features>
17339 <column alignment="center" valignment="top" leftline="true" width="0">
17340 <column alignment="block" valignment="top" leftline="true" width="20page%">
17341 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
17342 <row topline="true" bottomline="true">
17343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17344 \begin_inset Text
17345
17346 \layout Standard
17347
17348 Keyword
17349 \end_inset
17350 </cell>
17351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17352 \begin_inset Text
17353
17354 \layout Standard
17355
17356 Description
17357 \end_inset
17358 </cell>
17359 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17360 \begin_inset Text
17361
17362 \layout Standard
17363
17364 Module to link
17365 \end_inset
17366 </cell>
17367 </row>
17368 <row topline="true">
17369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17370 \begin_inset Text
17371
17372 \layout Standard
17373
17374
17375 \series bold
17376 ignore
17377 \end_inset
17378 </cell>
17379 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17380 \begin_inset Text
17381
17382 \layout Standard
17383
17384 ignore all library pragmas
17385 \end_inset
17386 </cell>
17387 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17388 \begin_inset Text
17389
17390 \layout Standard
17391
17392
17393 \emph on
17394 (none)
17395 \end_inset
17396 </cell>
17397 </row>
17398 <row topline="true">
17399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17400 \begin_inset Text
17401
17402 \layout Standard
17403
17404
17405 \series bold
17406 c
17407 \end_inset
17408 </cell>
17409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17410 \begin_inset Text
17411
17412 \layout Standard
17413
17414 link the C library
17415 \end_inset
17416 </cell>
17417 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17418 \begin_inset Text
17419
17420 \layout Standard
17421
17422
17423 \emph on
17424 libc18f
17425 \emph default
17426 .lib
17427 \end_inset
17428 </cell>
17429 </row>
17430 <row topline="true">
17431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17432 \begin_inset Text
17433
17434 \layout Standard
17435
17436
17437 \series bold
17438 math
17439 \end_inset
17440 </cell>
17441 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17442 \begin_inset Text
17443
17444 \layout Standard
17445
17446 link the Math libarary
17447 \end_inset
17448 </cell>
17449 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17450 \begin_inset Text
17451
17452 \layout Standard
17453
17454
17455 \emph on
17456 libm18f
17457 \emph default
17458 .lib
17459 \end_inset
17460 </cell>
17461 </row>
17462 <row topline="true">
17463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17464 \begin_inset Text
17465
17466 \layout Standard
17467
17468
17469 \series bold
17470 io
17471 \end_inset
17472 </cell>
17473 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17474 \begin_inset Text
17475
17476 \layout Standard
17477
17478 link the I/O library
17479 \end_inset
17480 </cell>
17481 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17482 \begin_inset Text
17483
17484 \layout Standard
17485
17486
17487 \emph on
17488 libio18f*
17489 \emph default
17490 .lib
17491 \end_inset
17492 </cell>
17493 </row>
17494 <row topline="true" bottomline="true">
17495 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17496 \begin_inset Text
17497
17498 \layout Standard
17499
17500
17501 \series bold
17502 debug
17503 \end_inset
17504 </cell>
17505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17506 \begin_inset Text
17507
17508 \layout Standard
17509
17510 link the debug library
17511 \end_inset
17512 </cell>
17513 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17514 \begin_inset Text
17515
17516 \layout Standard
17517
17518
17519 \emph on
17520 libdebug
17521 \emph default
17522 .lib
17523 \end_inset
17524 </cell>
17525 </row>
17526 </lyxtabular>
17527
17528 \end_inset
17529
17530
17531 \newline
17532 * is the device number, i.e.
17533  452 for PIC18F452 MCU.
17534 \layout Standard
17535
17536 This feature allows for linking with specific libraries withoug having to
17537  explicit name them in the command line.
17538  Note that the
17539 \noun on
17540 ignore
17541 \noun default
17542  keyword will reject all modules specified by the library pragma.
17543 \layout List
17544 \labelwidthstring 00.00.0000
17545
17546 udata pragma udata instructs the compiler to emit code so that linker will
17547  place a variable at a specific memory bank
17548 \layout LyX-Code
17549
17550 Example:
17551 \layout LyX-Code
17552
17553 \layout LyX-Code
17554
17555 /* places variable foo at bank2 */
17556 \layout LyX-Code
17557
17558 #pragma udata bank2 foo
17559 \layout LyX-Code
17560
17561 char foo;
17562 \layout Standard
17563
17564 In order for this pragma to work extra SECTION directives should be added
17565  in the .lkr script.
17566  In the following example a sample .lkr file is shown:
17567 \layout LyX-Code
17568
17569 \layout LyX-Code
17570
17571 // Sample linker script for the PIC18F452 processor
17572 \layout LyX-Code
17573
17574 LIBPATH .
17575 \layout LyX-Code
17576
17577 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
17578 \layout LyX-Code
17579
17580 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
17581 \layout LyX-Code
17582
17583 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
17584 \layout LyX-Code
17585
17586 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
17587 \layout LyX-Code
17588
17589 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
17590 \layout LyX-Code
17591
17592 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
17593 \layout LyX-Code
17594
17595 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
17596 \layout LyX-Code
17597
17598 \layout LyX-Code
17599
17600 DATABANK   NAME=gpr0       START=0x80           END=0xFF
17601 \layout LyX-Code
17602
17603 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
17604 \layout LyX-Code
17605
17606 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
17607 \layout LyX-Code
17608
17609 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
17610 \layout LyX-Code
17611
17612 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
17613 \layout LyX-Code
17614
17615 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
17616 \layout LyX-Code
17617
17618 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
17619 \layout LyX-Code
17620
17621 \layout LyX-Code
17622
17623 SECTION    NAME=CONFIG     ROM=config
17624 \layout LyX-Code
17625
17626 \layout LyX-Code
17627
17628 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
17629 \layout LyX-Code
17630
17631 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
17632 \layout LyX-Code
17633
17634 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
17635 \layout LyX-Code
17636
17637 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
17638 \layout LyX-Code
17639
17640 SECTION    NAME=bank4      RAM=gpr4
17641 \layout LyX-Code
17642
17643 SECTION    NAME=bank5      RAM=gpr5
17644 \layout Standard
17645
17646 The linker will recognise the section name set in the pragma statement and
17647  will position the variable at the memory bank set with the RAM field at
17648  the SECTION line in the linker script file.
17649 \layout Subsection
17650
17651 Header Files
17652 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
17653
17654 \end_inset
17655
17656
17657 \layout Standard
17658
17659 There is one main header file that can be included to the source files using
17660  the pic16 port.
17661  That file is the
17662 \series bold
17663 pic18fregs.h
17664 \series default
17665 .
17666  This header file contains the definitions for the processor special registers,
17667  so it is necessary if the source accesses them.
17668  It can be included by adding the following line in the beginning of the
17669  file:
17670 \layout LyX-Code
17671
17672 #include <pic18fregs.h>
17673 \layout Standard
17674
17675 The specific microcontroller is selected within the pic18fregs.h automatically,
17676  so the same source can be used with a variety of devices.
17677 \layout Subsection
17678
17679 Libraries
17680 \layout Standard
17681
17682 The libraries that PIC16
17683 \begin_inset LatexCommand \index{PIC16}
17684
17685 \end_inset
17686
17687  port depends on are the microcontroller device libraries which contain
17688  the symbol definitions for the microcontroller special function registers.
17689  These libraries have the format pic18fxxxx.lib, where
17690 \emph on
17691 xxxx
17692 \emph default
17693  is the microcontroller identification number.
17694  The specific library is selected automatically by the compiler at link
17695  stage according to the selected device.
17696 \layout Standard
17697
17698 Libraries are created with gplib which is part of the gputils package
17699 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17700
17701 \end_inset
17702
17703 .
17704 \layout Subsubsection*
17705
17706 Building the libraries
17707 \layout Standard
17708
17709 Before using SDCC/pic16 there are some libraries that need to be compiled.
17710  This process is not done automatically by SDCC since not all users use
17711  SDCC for pic16 projects.
17712  So each user should compile the libraries separately.
17713 \layout Standard
17714
17715 The steps to compile the pic16 libraries under Linux are:
17716 \layout LyX-Code
17717
17718 cd device/lib/pic16
17719 \layout LyX-Code
17720
17721 ./configure
17722 \layout LyX-Code
17723
17724 make
17725 \layout LyX-Code
17726
17727 cd ..
17728 \layout LyX-Code
17729
17730 make model-pic16
17731 \layout LyX-Code
17732
17733 su -c 'make install'     # install the libraries, you need the root password
17734 \layout Standard
17735
17736 If you need to install the headers too, do:
17737 \layout LyX-Code
17738
17739 cd device/include
17740 \layout LyX-Code
17741
17742 su -c 'make install'     # install the headers, you need the root password
17743 \layout Standard
17744
17745 There exist a special target to build the I/O libraries.
17746  This target is not automatically build because it will build the I/O library
17747  for
17748 \emph on
17749 every
17750 \emph default
17751  supported device.
17752  This way building will take quite a lot of time.
17753  Users are advised to edit the
17754 \series bold
17755 device/lib/pic16/pics.build
17756 \series default
17757  file and then execute:
17758 \layout LyX-Code
17759
17760 make lib-io
17761 \layout Subsection
17762
17763 Memory Models
17764 \layout Standard
17765
17766 The following memory models are supported by the PIC16 port:
17767 \layout Itemize
17768
17769 small model
17770 \layout Itemize
17771
17772 large model
17773 \layout Standard
17774
17775 Memory model affects the default size of pointers within the source.
17776  The sizes are shown in the next table:
17777 \layout Standard
17778 \align center
17779
17780 \begin_inset  Tabular
17781 <lyxtabular version="3" rows="3" columns="3">
17782 <features>
17783 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17784 <column alignment="center" valignment="top" leftline="true" width="0">
17785 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
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 Pointer sizes according to memory model
17793 \end_inset
17794 </cell>
17795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17796 \begin_inset Text
17797
17798 \layout Standard
17799
17800 small model
17801 \end_inset
17802 </cell>
17803 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17804 \begin_inset Text
17805
17806 \layout Standard
17807
17808 large model
17809 \end_inset
17810 </cell>
17811 </row>
17812 <row topline="true" bottomline="true">
17813 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17814 \begin_inset Text
17815
17816 \layout Standard
17817
17818 code pointers
17819 \end_inset
17820 </cell>
17821 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17822 \begin_inset Text
17823
17824 \layout Standard
17825
17826 16-bits
17827 \end_inset
17828 </cell>
17829 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17830 \begin_inset Text
17831
17832 \layout Standard
17833
17834 24-bits
17835 \end_inset
17836 </cell>
17837 </row>
17838 <row topline="true" bottomline="true">
17839 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17840 \begin_inset Text
17841
17842 \layout Standard
17843
17844 data pointers
17845 \end_inset
17846 </cell>
17847 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
17848 \begin_inset Text
17849
17850 \layout Standard
17851
17852 16-bits
17853 \end_inset
17854 </cell>
17855 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17856 \begin_inset Text
17857
17858 \layout Standard
17859
17860 16-bits
17861 \end_inset
17862 </cell>
17863 </row>
17864 </lyxtabular>
17865
17866 \end_inset
17867
17868
17869 \layout Standard
17870
17871 It is advisable that all sources within a project are compiled with the
17872  same memory model.
17873  If one wants to override the default memory model, this can be done by
17874  declaring a pointer as
17875 \series bold
17876 far
17877 \series default
17878  or
17879 \series bold
17880 near
17881 \series default
17882 .
17883  Far selects large memory model's pointers, while near selects small memory
17884  model's pointers.
17885 \layout Standard
17886
17887 The standard device libraries (see
17888 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
17889
17890 \end_inset
17891
17892 ) contain no reference to pointers, so they can be used with both memory
17893  models.
17894 \layout Subsection
17895
17896 Stack
17897 \layout Standard
17898
17899 The stack implementation for the PIC16 port uses two indirect registers,
17900  FSR1 and FSR2.
17901 \layout List
17902 \labelwidthstring 00.00.0000
17903
17904 FSR1 is assigned as stack pointer
17905 \layout List
17906 \labelwidthstring 00.00.0000
17907
17908 FSR2 is assigned as frame pointer
17909 \layout Standard
17910
17911 The following stack models are supported by the PIC16 port
17912 \layout Itemize
17913
17914
17915 \noun on
17916 small
17917 \noun default
17918  model
17919 \layout Itemize
17920
17921
17922 \noun on
17923 large
17924 \noun default
17925  model
17926 \layout Standard
17927
17928
17929 \noun on
17930 Small
17931 \noun default
17932  model means that only the FSRxL byte is used to access stack and frame,
17933  while
17934 \emph on
17935 \noun on
17936 large
17937 \emph default
17938 \noun default
17939  uses both FSRxL and FSRxH registers.
17940  The following table shows the stack/frame pointers sizes according to stack
17941  model and the maximum space they can address:
17942 \layout Standard
17943 \align center
17944
17945 \begin_inset  Tabular
17946 <lyxtabular version="3" rows="3" columns="3">
17947 <features>
17948 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17949 <column alignment="center" valignment="top" leftline="true" width="0">
17950 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17951 <row topline="true" bottomline="true">
17952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17953 \begin_inset Text
17954
17955 \layout Standard
17956
17957 Stack & Frame pointer sizes according to stack model
17958 \end_inset
17959 </cell>
17960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17961 \begin_inset Text
17962
17963 \layout Standard
17964
17965 small
17966 \end_inset
17967 </cell>
17968 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17969 \begin_inset Text
17970
17971 \layout Standard
17972
17973 large
17974 \end_inset
17975 </cell>
17976 </row>
17977 <row topline="true">
17978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17979 \begin_inset Text
17980
17981 \layout Standard
17982
17983 Stack pointer FSR1
17984 \end_inset
17985 </cell>
17986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17987 \begin_inset Text
17988
17989 \layout Standard
17990
17991 8-bits
17992 \end_inset
17993 </cell>
17994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17995 \begin_inset Text
17996
17997 \layout Standard
17998
17999 16-bits
18000 \end_inset
18001 </cell>
18002 </row>
18003 <row topline="true" bottomline="true">
18004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18005 \begin_inset Text
18006
18007 \layout Standard
18008
18009 Frame pointer FSR2
18010 \end_inset
18011 </cell>
18012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18013 \begin_inset Text
18014
18015 \layout Standard
18016
18017 8-bits
18018 \end_inset
18019 </cell>
18020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18021 \begin_inset Text
18022
18023 \layout Standard
18024
18025 16-bits
18026 \end_inset
18027 </cell>
18028 </row>
18029 </lyxtabular>
18030
18031 \end_inset
18032
18033
18034 \layout Standard
18035
18036
18037 \noun on
18038 Large
18039 \noun default
18040 stack model is currently not working properly throughout the code generator.
18041  So its use is not advised.
18042  Also there are some other points that need special care:
18043 \newline
18044
18045 \layout Enumerate
18046
18047 Do not create stack sections with size more than one physical bank (that
18048  is 256 bytes)
18049 \layout Enumerate
18050
18051 Stack sections should no cross physical bank limits (i.e.
18052  #pragma stack 0x50 0x100)
18053 \layout Standard
18054
18055 These limitations are caused by the fact that only FSRxL is modified when
18056  using SMALL stack model, so no more than 256 bytes of stack can be used.
18057  This problem will disappear after LARGE model is fully implemented.
18058 \layout Subsection
18059
18060 Functions
18061 \layout Standard
18062
18063 In addition to the standard SDCC function keywords, PIC16 port makes available
18064  two more:
18065 \layout List
18066 \labelwidthstring 00.00.0000
18067
18068 wparam Use the WREG to pass one byte of the first function argument.
18069  This improves speed but you may not use this for functions with arguments
18070  that are called via function pointers, otherwise the first byte of the
18071  first parameter will get lost.
18072  Usage:
18073 \layout LyX-Code
18074
18075 void func_wparam(int a) wparam
18076 \layout LyX-Code
18077
18078 {
18079 \layout LyX-Code
18080
18081     /* WREG hold the lower part of a */
18082 \layout LyX-Code
18083
18084     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
18085  */
18086 \layout LyX-Code
18087
18088 ...
18089 \layout LyX-Code
18090
18091 }
18092 \layout Standard
18093
18094 This keyword replaces the deprecated wparam pragma.
18095 \layout List
18096 \labelwidthstring 00.00.0000
18097
18098 shadowregs When entering/exiting an ISR, it is possible to take advantage
18099  of the PIC18F hardware shadow registers which hold the values of WREG,
18100  STATUS and BSR registers.
18101  This can be done by adding the keyword
18102 \emph on
18103 shadowregs
18104 \emph default
18105  before the
18106 \emph on
18107 interrupt
18108 \emph default
18109  keyword in the function's header.
18110 \layout LyX-Code
18111
18112 void isr_shadow(void) shadowregs interrupt 1
18113 \layout LyX-Code
18114
18115 {
18116 \layout LyX-Code
18117
18118 ...
18119 \layout LyX-Code
18120
18121 }
18122 \layout Standard
18123
18124
18125 \emph on
18126 shadowregs
18127 \emph default
18128  instructs the code generator not to store/restore WREG, STATUS, BSR when
18129  entering/exiting the ISR.
18130 \layout Subsection
18131
18132 Function return values
18133 \layout Standard
18134
18135 Return values from functions are placed to the appropriate registers following
18136  a modified Microchip policy optimized for SDCC.
18137  The following table shows these registers:
18138 \layout Standard
18139 \align center
18140
18141 \begin_inset  Tabular
18142 <lyxtabular version="3" rows="6" columns="2">
18143 <features>
18144 <column alignment="center" valignment="top" leftline="true" width="0">
18145 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18146 <row topline="true" bottomline="true">
18147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18148 \begin_inset Text
18149
18150 \layout Standard
18151
18152 size
18153 \end_inset
18154 </cell>
18155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18156 \begin_inset Text
18157
18158 \layout Standard
18159
18160 destination register
18161 \end_inset
18162 </cell>
18163 </row>
18164 <row topline="true">
18165 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18166 \begin_inset Text
18167
18168 \layout Standard
18169
18170 8 bits
18171 \end_inset
18172 </cell>
18173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18174 \begin_inset Text
18175
18176 \layout Standard
18177
18178 WREG
18179 \end_inset
18180 </cell>
18181 </row>
18182 <row topline="true">
18183 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18184 \begin_inset Text
18185
18186 \layout Standard
18187
18188 16 bits
18189 \end_inset
18190 </cell>
18191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18192 \begin_inset Text
18193
18194 \layout Standard
18195
18196 PRODL:WREG
18197 \end_inset
18198 </cell>
18199 </row>
18200 <row topline="true">
18201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18202 \begin_inset Text
18203
18204 \layout Standard
18205
18206 24 bits
18207 \end_inset
18208 </cell>
18209 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18210 \begin_inset Text
18211
18212 \layout Standard
18213
18214 PRODH:PRODL:WREG
18215 \end_inset
18216 </cell>
18217 </row>
18218 <row topline="true">
18219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18220 \begin_inset Text
18221
18222 \layout Standard
18223
18224 32 bits
18225 \end_inset
18226 </cell>
18227 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18228 \begin_inset Text
18229
18230 \layout Standard
18231
18232 FSR0L:PRODH:PRODL:WREG
18233 \end_inset
18234 </cell>
18235 </row>
18236 <row topline="true" bottomline="true">
18237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18238 \begin_inset Text
18239
18240 \layout Standard
18241
18242 >32 bits
18243 \end_inset
18244 </cell>
18245 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18246 \begin_inset Text
18247
18248 \layout Standard
18249
18250 on stack, FSR0 points to the beginning
18251 \end_inset
18252 </cell>
18253 </row>
18254 </lyxtabular>
18255
18256 \end_inset
18257
18258
18259 \layout Subsection
18260
18261 Interrupts
18262 \layout Standard
18263
18264 An interrupt servive routine (ISR) is declared using the
18265 \emph on
18266 interrupt
18267 \emph default
18268  keyword.
18269 \layout LyX-Code
18270
18271 void isr(void) interrupt
18272 \emph on
18273 n
18274 \layout LyX-Code
18275
18276 {
18277 \layout LyX-Code
18278
18279 ...
18280 \layout LyX-Code
18281
18282 }
18283 \layout Standard
18284
18285
18286 \emph on
18287 n
18288 \emph default
18289  is the interrupt number, which for PIC18F devices can be:
18290 \layout Standard
18291 \align center
18292
18293 \begin_inset  Tabular
18294 <lyxtabular version="3" rows="4" columns="3">
18295 <features>
18296 <column alignment="center" valignment="top" leftline="true" width="0">
18297 <column alignment="center" valignment="top" leftline="true" width="0">
18298 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18299 <row topline="true" bottomline="true">
18300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18301 \begin_inset Text
18302
18303 \layout Standard
18304
18305
18306 \emph on
18307 n
18308 \end_inset
18309 </cell>
18310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18311 \begin_inset Text
18312
18313 \layout Standard
18314
18315 Interrupt Vector
18316 \end_inset
18317 </cell>
18318 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18319 \begin_inset Text
18320
18321 \layout Standard
18322
18323 Interrupt Vector Address
18324 \end_inset
18325 </cell>
18326 </row>
18327 <row topline="true">
18328 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18329 \begin_inset Text
18330
18331 \layout Standard
18332
18333 0
18334 \end_inset
18335 </cell>
18336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18337 \begin_inset Text
18338
18339 \layout Standard
18340
18341 RESET vector
18342 \end_inset
18343 </cell>
18344 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18345 \begin_inset Text
18346
18347 \layout Standard
18348
18349 0x000000
18350 \end_inset
18351 </cell>
18352 </row>
18353 <row topline="true">
18354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18355 \begin_inset Text
18356
18357 \layout Standard
18358
18359
18360 \family roman
18361 \series medium
18362 \shape up
18363 \size normal
18364 \emph off
18365 \bar no
18366 \noun off
18367 \color none
18368 1
18369 \end_inset
18370 </cell>
18371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18372 \begin_inset Text
18373
18374 \layout Standard
18375
18376
18377 \family roman
18378 \series medium
18379 \shape up
18380 \size normal
18381 \emph off
18382 \bar no
18383 \noun off
18384 \color none
18385 HIGH priority interrupts
18386 \end_inset
18387 </cell>
18388 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18389 \begin_inset Text
18390
18391 \layout Standard
18392
18393 0x000008
18394 \end_inset
18395 </cell>
18396 </row>
18397 <row topline="true" bottomline="true">
18398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18399 \begin_inset Text
18400
18401 \layout Standard
18402
18403 2
18404 \end_inset
18405 </cell>
18406 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18407 \begin_inset Text
18408
18409 \layout Standard
18410
18411 LOW priority interrupts
18412 \end_inset
18413 </cell>
18414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18415 \begin_inset Text
18416
18417 \layout Standard
18418
18419 0x000018
18420 \end_inset
18421 </cell>
18422 </row>
18423 </lyxtabular>
18424
18425 \end_inset
18426
18427
18428 \layout Standard
18429
18430 When generating assembly code for ISR the code generator places a
18431 \noun on
18432 goto
18433 \noun default
18434 instruction at the
18435 \emph on
18436 Interrupt Vector Address
18437 \emph default
18438  which points at the genetated ISR.
18439  This single GOTO instruction is part of an automatically generated
18440 \emph on
18441 interrupt entry point
18442 \emph default
18443  function.
18444  The actuall ISR code is placed as normally would in the code space.
18445  Upon interrupt request, the GOTO instruction is executed which jumps to
18446  the ISR code.
18447  When declaring interrupt functions as _naked this GOTO instruction is
18448 \series bold
18449 not
18450 \series default
18451  generated.
18452  The whole interrupt functions is therefore placed at the Interrupt Vector
18453  Address of the specific interrupt.
18454  This is not a problem for the LOW priority interrupts, but it is a problem
18455  for the RESET and the HIGH priority interrupts because code may be written
18456  at the next interrupt´s vector address and cause undeterminate program
18457  behaviour if that interrupt is raised.
18458 \begin_inset Foot
18459 collapsed false
18460
18461 \layout Standard
18462
18463 This is not a problem when
18464 \layout Enumerate
18465
18466 this is a HIGH interrupt ISR and LOW interrupts are
18467 \emph on
18468 disabled
18469 \emph default
18470  or not used.
18471 \layout Enumerate
18472
18473 when the ISR is small enough not to reach the next interrupt´s vector address.
18474 \end_inset
18475
18476
18477 \layout Standard
18478
18479
18480 \emph on
18481 n
18482 \emph default
18483  is possible to be omitted.
18484  This way a function is generated similar to an ISR, but it is not assigned
18485  to any interrupt.
18486 \layout Standard
18487
18488 When entering an interrupt, currently the PIC16
18489 \begin_inset LatexCommand \index{PIC16}
18490
18491 \end_inset
18492
18493  port automatically saves the following registers:
18494 \layout Itemize
18495
18496 WREG
18497 \layout Itemize
18498
18499 STATUS
18500 \layout Itemize
18501
18502 BSR
18503 \layout Itemize
18504
18505 PROD (PRODL and PRODH)
18506 \layout Itemize
18507
18508 FSR0 (FSR0L and FSR0H)
18509 \layout Standard
18510
18511 These registers are restored upon return from the interrupt routine.
18512 \begin_inset Foot
18513 collapsed false
18514
18515 \layout Standard
18516
18517 NOTE that when the _naked attribute is specified for an interrupt routine,
18518  then NO registers are stored or restored.
18519 \end_inset
18520
18521
18522 \layout Subsection
18523
18524 Generic Pointers
18525 \layout Standard
18526
18527 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
18528  There are 3 types of generic pointers currently implemented data, code
18529  and eeprom pointers.
18530  They are differentiated by the value of the 7th and 6th bits of the upper
18531  byte:
18532 \layout Standard
18533 \align center
18534
18535 \begin_inset  Tabular
18536 <lyxtabular version="3" rows="5" columns="5">
18537 <features>
18538 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18539 <column alignment="center" valignment="top" width="0">
18540 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18541 <column alignment="center" valignment="top" width="0">
18542 <column alignment="left" valignment="top" rightline="true" width="0">
18543 <row topline="true" bottomline="true">
18544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18545 \begin_inset Text
18546
18547 \layout Standard
18548
18549 pointer type
18550 \end_inset
18551 </cell>
18552 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18553 \begin_inset Text
18554
18555 \layout Standard
18556
18557 7th bit
18558 \end_inset
18559 </cell>
18560 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18561 \begin_inset Text
18562
18563 \layout Standard
18564
18565 6th bit
18566 \end_inset
18567 </cell>
18568 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18569 \begin_inset Text
18570
18571 \layout Standard
18572
18573 rest of the pointer
18574 \end_inset
18575 </cell>
18576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18577 \begin_inset Text
18578
18579 \layout Standard
18580
18581 descrption
18582 \end_inset
18583 </cell>
18584 </row>
18585 <row topline="true" bottomline="true">
18586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18587 \begin_inset Text
18588
18589 \layout Standard
18590
18591 data
18592 \end_inset
18593 </cell>
18594 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18595 \begin_inset Text
18596
18597 \layout Standard
18598
18599 1
18600 \end_inset
18601 </cell>
18602 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18603 \begin_inset Text
18604
18605 \layout Standard
18606
18607 0
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
18616 \family typewriter
18617 \shape slanted
18618 \emph on
18619 uuuuuu uuuuxxxx xxxxxxxx
18620 \end_inset
18621 </cell>
18622 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18623 \begin_inset Text
18624
18625 \layout Standard
18626
18627 a 12-bit data pointer in data RAM memory
18628 \end_inset
18629 </cell>
18630 </row>
18631 <row bottomline="true">
18632 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18633 \begin_inset Text
18634
18635 \layout Standard
18636
18637 code
18638 \end_inset
18639 </cell>
18640 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18641 \begin_inset Text
18642
18643 \layout Standard
18644
18645 0
18646 \end_inset
18647 </cell>
18648 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18649 \begin_inset Text
18650
18651 \layout Standard
18652
18653 0
18654 \end_inset
18655 </cell>
18656 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18657 \begin_inset Text
18658
18659 \layout Standard
18660
18661
18662 \family typewriter
18663 \shape slanted
18664 \emph on
18665 uxxxxx xxxxxxxx xxxxxxxx
18666 \end_inset
18667 </cell>
18668 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18669 \begin_inset Text
18670
18671 \layout Standard
18672
18673 a 21-bit code pointer in FLASH memory
18674 \end_inset
18675 </cell>
18676 </row>
18677 <row bottomline="true">
18678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18679 \begin_inset Text
18680
18681 \layout Standard
18682
18683 eeprom
18684 \end_inset
18685 </cell>
18686 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18687 \begin_inset Text
18688
18689 \layout Standard
18690
18691 0
18692 \end_inset
18693 </cell>
18694 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18695 \begin_inset Text
18696
18697 \layout Standard
18698
18699 1
18700 \end_inset
18701 </cell>
18702 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18703 \begin_inset Text
18704
18705 \layout Standard
18706
18707
18708 \family typewriter
18709 \shape slanted
18710 \emph on
18711 uuuuuu uuuuuuxx xxxxxxxx
18712 \end_inset
18713 </cell>
18714 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18715 \begin_inset Text
18716
18717 \layout Standard
18718
18719 a 10-bit eeprom pointer in EEPROM memory
18720 \end_inset
18721 </cell>
18722 </row>
18723 <row bottomline="true">
18724 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18725 \begin_inset Text
18726
18727 \layout Standard
18728
18729 (unimplemented)
18730 \end_inset
18731 </cell>
18732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18733 \begin_inset Text
18734
18735 \layout Standard
18736
18737 1
18738 \end_inset
18739 </cell>
18740 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18741 \begin_inset Text
18742
18743 \layout Standard
18744
18745 1
18746 \end_inset
18747 </cell>
18748 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18749 \begin_inset Text
18750
18751 \layout Standard
18752
18753
18754 \family typewriter
18755 \shape slanted
18756 \emph on
18757 xxxxxx xxxxxxxx xxxxxxxx
18758 \end_inset
18759 </cell>
18760 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18761 \begin_inset Text
18762
18763 \layout Standard
18764
18765 unimplemented pointer type
18766 \end_inset
18767 </cell>
18768 </row>
18769 </lyxtabular>
18770
18771 \end_inset
18772
18773
18774 \layout Standard
18775
18776 Generic pointer are read and written with a set of library functions which
18777  read/write 1, 2, 3, 4 bytes.
18778 \layout Subsection
18779
18780 PIC16 C Libraries
18781 \layout Subsubsection
18782
18783 Standard I/O Streams
18784 \layout Standard
18785
18786 In the
18787 \emph on
18788 stdio.h
18789 \emph default
18790  the type FILE is defined as:
18791 \layout LyX-Code
18792
18793 typedef char * FILE;
18794 \layout Standard
18795
18796 This type is the stream type implemented I/O in the PIC18F devices.
18797  Also the standard input and output streams are declared in stdio.h:
18798 \layout LyX-Code
18799
18800 extern FILE * stdin;
18801 \layout LyX-Code
18802
18803 extern FILE * stdout;
18804 \layout Standard
18805
18806 The FILE type is actually a generic pointer which defines one more type
18807  of generic pointers, the
18808 \emph on
18809 stream
18810 \emph default
18811 pointer.
18812  This new type has the format:
18813 \layout Standard
18814 \align center
18815
18816 \begin_inset  Tabular
18817 <lyxtabular version="3" rows="2" columns="7">
18818 <features>
18819 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18820 <column alignment="center" valignment="top" width="0">
18821 <column alignment="center" valignment="top" leftline="true" width="0">
18822 <column alignment="center" valignment="top" leftline="true" width="0">
18823 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18824 <column alignment="center" valignment="top" width="0">
18825 <column alignment="left" valignment="top" rightline="true" width="0">
18826 <row topline="true" bottomline="true">
18827 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18828 \begin_inset Text
18829
18830 \layout Standard
18831
18832 pointer type
18833 \end_inset
18834 </cell>
18835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18836 \begin_inset Text
18837
18838 \layout Standard
18839
18840 <7:6>
18841 \end_inset
18842 </cell>
18843 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18844 \begin_inset Text
18845
18846 \layout Standard
18847
18848 <5>
18849 \end_inset
18850 </cell>
18851 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18852 \begin_inset Text
18853
18854 \layout Standard
18855
18856 <4>
18857 \end_inset
18858 </cell>
18859 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18860 \begin_inset Text
18861
18862 \layout Standard
18863
18864 <3:0>
18865 \end_inset
18866 </cell>
18867 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18868 \begin_inset Text
18869
18870 \layout Standard
18871
18872 rest of the pointer
18873 \end_inset
18874 </cell>
18875 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18876 \begin_inset Text
18877
18878 \layout Standard
18879
18880 descrption
18881 \end_inset
18882 </cell>
18883 </row>
18884 <row topline="true" bottomline="true">
18885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18886 \begin_inset Text
18887
18888 \layout Standard
18889
18890 stream
18891 \end_inset
18892 </cell>
18893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18894 \begin_inset Text
18895
18896 \layout Standard
18897
18898 00
18899 \end_inset
18900 </cell>
18901 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18902 \begin_inset Text
18903
18904 \layout Standard
18905
18906 1
18907 \end_inset
18908 </cell>
18909 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18910 \begin_inset Text
18911
18912 \layout Standard
18913
18914 0
18915 \end_inset
18916 </cell>
18917 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18918 \begin_inset Text
18919
18920 \layout Standard
18921
18922 nnnn
18923 \end_inset
18924 </cell>
18925 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18926 \begin_inset Text
18927
18928 \layout Standard
18929
18930
18931 \family typewriter
18932 \shape slanted
18933 \emph on
18934 uuuuuuuu uuuuuuuu
18935 \end_inset
18936 </cell>
18937 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18938 \begin_inset Text
18939
18940 \layout Standard
18941
18942 upper byte high nubble is 0x2n, the rest are zeroes
18943 \end_inset
18944 </cell>
18945 </row>
18946 </lyxtabular>
18947
18948 \end_inset
18949
18950
18951 \layout Standard
18952
18953 Currently implemented there are 3 types of streams defined:
18954 \layout Standard
18955 \align center
18956
18957 \begin_inset  Tabular
18958 <lyxtabular version="3" rows="4" columns="4">
18959 <features>
18960 <column alignment="center" valignment="top" leftline="true" width="0">
18961 <column alignment="center" valignment="top" leftline="true" width="0">
18962 <column alignment="center" valignment="top" leftline="true" width="0">
18963 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18964 <row topline="true" bottomline="true">
18965 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18966 \begin_inset Text
18967
18968 \layout Standard
18969
18970 stream type
18971 \end_inset
18972 </cell>
18973 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18974 \begin_inset Text
18975
18976 \layout Standard
18977
18978 value
18979 \end_inset
18980 </cell>
18981 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18982 \begin_inset Text
18983
18984 \layout Standard
18985
18986 module
18987 \end_inset
18988 </cell>
18989 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18990 \begin_inset Text
18991
18992 \layout Standard
18993
18994 description
18995 \end_inset
18996 </cell>
18997 </row>
18998 <row topline="true">
18999 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19000 \begin_inset Text
19001
19002 \layout Standard
19003
19004 STREAM_USART
19005 \end_inset
19006 </cell>
19007 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19008 \begin_inset Text
19009
19010 \layout Standard
19011
19012
19013 \family typewriter
19014 0x200000UL
19015 \end_inset
19016 </cell>
19017 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19018 \begin_inset Text
19019
19020 \layout Standard
19021
19022 USART
19023 \end_inset
19024 </cell>
19025 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19026 \begin_inset Text
19027
19028 \layout Standard
19029
19030 Writes/Reads characters via the USART peripheral
19031 \end_inset
19032 </cell>
19033 </row>
19034 <row topline="true">
19035 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19036 \begin_inset Text
19037
19038 \layout Standard
19039
19040 STREAM_MSSP
19041 \end_inset
19042 </cell>
19043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19044 \begin_inset Text
19045
19046 \layout Standard
19047
19048
19049 \family typewriter
19050 0x210000UL
19051 \end_inset
19052 </cell>
19053 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19054 \begin_inset Text
19055
19056 \layout Standard
19057
19058 MSSP
19059 \end_inset
19060 </cell>
19061 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19062 \begin_inset Text
19063
19064 \layout Standard
19065
19066 Writes/Reads characters via the MSSP peripheral
19067 \end_inset
19068 </cell>
19069 </row>
19070 <row topline="true" bottomline="true">
19071 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19072 \begin_inset Text
19073
19074 \layout Standard
19075
19076 STREAM_USER
19077 \end_inset
19078 </cell>
19079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19080 \begin_inset Text
19081
19082 \layout Standard
19083
19084
19085 \family typewriter
19086 0x2f0000UL
19087 \end_inset
19088 </cell>
19089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19090 \begin_inset Text
19091
19092 \layout Standard
19093
19094 (none)
19095 \end_inset
19096 </cell>
19097 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19098 \begin_inset Text
19099
19100 \layout Standard
19101
19102 Writes/Reads characters via used defined functions
19103 \end_inset
19104 </cell>
19105 </row>
19106 </lyxtabular>
19107
19108 \end_inset
19109
19110
19111 \layout Standard
19112
19113 The stream identifiers are declared as macros in the stdio.h header.
19114 \layout Standard
19115
19116 In the libc library there exist the functions that are used to write to
19117  each of the above streams.
19118  These are
19119 \layout List
19120 \labelwidthstring 00.00.0000
19121
19122 _
19123 \begin_inset ERT
19124 status Collapsed
19125
19126 \layout Standard
19127
19128 \backslash
19129 /
19130 \end_inset
19131
19132 _stream_usart_putchar writes a character at the USART stream
19133 \layout List
19134 \labelwidthstring 00.00.0000
19135
19136 _
19137 \begin_inset ERT
19138 status Collapsed
19139
19140 \layout Standard
19141
19142 \backslash
19143 /
19144 \end_inset
19145
19146 _stream_mssp_putchar writes a character at the MSSP stream
19147 \layout List
19148 \labelwidthstring 00.00.0000
19149
19150 putchar dummy function.
19151  This writes a character to a user specified manner.
19152 \layout Standard
19153
19154 In order to increase performance
19155 \emph on
19156 putchar
19157 \emph default
19158 is declared in stdio.h as having its parameter in WREG (it has the wparam
19159  keyword).
19160  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
19161  in a user-friendly way.
19162
19163 \emph on
19164 arg
19165 \emph default
19166  is the name of the variable that holds the character to print.
19167  An example follows:
19168 \layout LyX-Code
19169
19170 #include <pic18fregs.h>
19171 \newline
19172 #include <stdio.h>
19173 \newline
19174
19175 \newline
19176 PUTCHAR( c )
19177 \layout LyX-Code
19178
19179 {
19180 \layout LyX-Code
19181
19182     PORTA = c;    /* dump character c to PORTA */
19183 \layout LyX-Code
19184
19185 }
19186 \newline
19187
19188 \newline
19189 void main(void)
19190 \layout LyX-Code
19191
19192 {
19193 \layout LyX-Code
19194
19195     stdout = STREAM_USER;    /* this is not necessery, since stdout points
19196 \layout LyX-Code
19197
19198                               * by default to STREAM_USER */
19199 \layout LyX-Code
19200
19201     printf (¨This is a printf test
19202 \backslash
19203 n¨);
19204 \layout LyX-Code
19205
19206 }
19207 \layout LyX-Code
19208
19209 \layout Subsubsection
19210
19211 Printing functions
19212 \layout Standard
19213
19214 PIC16 contains an implementation of the printf-family of functions.
19215  There exist the following functions:
19216 \layout LyX-Code
19217
19218 extern unsigned int sprintf(char *buf, char *fmt, ...);
19219 \layout LyX-Code
19220
19221 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
19222 \layout LyX-Code
19223
19224 \layout LyX-Code
19225
19226 extern unsigned int printf(char *fmt, ...);
19227 \layout LyX-Code
19228
19229 extern unsigned int vprintf(char *fmt, va_lista ap);
19230 \layout LyX-Code
19231
19232 \layout LyX-Code
19233
19234 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
19235 \layout LyX-Code
19236
19237 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
19238 \layout Standard
19239
19240 For sprintf and vsprintf
19241 \emph on
19242 buf
19243 \emph default
19244 should normally be a data pointer where the resulting string will be placed.
19245  No range checking is done so the user should allocate the necessery buffer.
19246  For fprintf and vfprintf
19247 \emph on
19248 fp
19249 \emph default
19250  should be a stream pointer (i.e.
19251  stdout, STREAM_MSSP, etc...).
19252 \layout Subsubsection
19253
19254 Signals
19255 \layout Standard
19256
19257 The PIC18F family of microcontrollers supports a number of interrupt sources.
19258  A list of these interrupts is shown in the following table:
19259 \layout Standard
19260 \align center
19261
19262 \begin_inset  Tabular
19263 <lyxtabular version="3" rows="11" columns="4">
19264 <features>
19265 <column alignment="left" valignment="top" leftline="true" width="0">
19266 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19267 <column alignment="left" valignment="top" leftline="true" width="0">
19268 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19269 <row topline="true" bottomline="true">
19270 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19271 \begin_inset Text
19272
19273 \layout Standard
19274
19275 signal name
19276 \end_inset
19277 </cell>
19278 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19279 \begin_inset Text
19280
19281 \layout Standard
19282
19283 description
19284 \end_inset
19285 </cell>
19286 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19287 \begin_inset Text
19288
19289 \layout Standard
19290
19291 signal name
19292 \end_inset
19293 </cell>
19294 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19295 \begin_inset Text
19296
19297 \layout Standard
19298
19299 descritpion
19300 \end_inset
19301 </cell>
19302 </row>
19303 <row topline="true">
19304 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19305 \begin_inset Text
19306
19307 \layout Standard
19308
19309 SIG_RB
19310 \end_inset
19311 </cell>
19312 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19313 \begin_inset Text
19314
19315 \layout Standard
19316
19317 PORTB change interrupt
19318 \end_inset
19319 </cell>
19320 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19321 \begin_inset Text
19322
19323 \layout Standard
19324
19325 SIG_EE
19326 \end_inset
19327 </cell>
19328 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19329 \begin_inset Text
19330
19331 \layout Standard
19332
19333 EEPROM/FLASH write complete interrupt
19334 \end_inset
19335 </cell>
19336 </row>
19337 <row topline="true">
19338 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19339 \begin_inset Text
19340
19341 \layout Standard
19342
19343 SIG_INT0
19344 \end_inset
19345 </cell>
19346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19347 \begin_inset Text
19348
19349 \layout Standard
19350
19351 INT0 external interrupt
19352 \end_inset
19353 </cell>
19354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19355 \begin_inset Text
19356
19357 \layout Standard
19358
19359 SIG_BCOL
19360 \end_inset
19361 </cell>
19362 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19363 \begin_inset Text
19364
19365 \layout Standard
19366
19367 Bus collision interrupt
19368 \end_inset
19369 </cell>
19370 </row>
19371 <row topline="true">
19372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19373 \begin_inset Text
19374
19375 \layout Standard
19376
19377 SIG_INT1
19378 \end_inset
19379 </cell>
19380 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19381 \begin_inset Text
19382
19383 \layout Standard
19384
19385 INT1 external interrupt
19386 \end_inset
19387 </cell>
19388 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19389 \begin_inset Text
19390
19391 \layout Standard
19392
19393 SIG_LVD
19394 \end_inset
19395 </cell>
19396 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19397 \begin_inset Text
19398
19399 \layout Standard
19400
19401 Low voltage detect interrupt
19402 \end_inset
19403 </cell>
19404 </row>
19405 <row topline="true">
19406 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19407 \begin_inset Text
19408
19409 \layout Standard
19410
19411 SIG_INT2
19412 \end_inset
19413 </cell>
19414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19415 \begin_inset Text
19416
19417 \layout Standard
19418
19419 INT2 external interrupt
19420 \end_inset
19421 </cell>
19422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19423 \begin_inset Text
19424
19425 \layout Standard
19426
19427 SIG_PSP
19428 \end_inset
19429 </cell>
19430 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19431 \begin_inset Text
19432
19433 \layout Standard
19434
19435 Parallel slave port interrupt
19436 \end_inset
19437 </cell>
19438 </row>
19439 <row topline="true">
19440 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19441 \begin_inset Text
19442
19443 \layout Standard
19444
19445 SIG_CCP1
19446 \end_inset
19447 </cell>
19448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19449 \begin_inset Text
19450
19451 \layout Standard
19452
19453 CCP1 module interrupt
19454 \end_inset
19455 </cell>
19456 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19457 \begin_inset Text
19458
19459 \layout Standard
19460
19461 SIG_AD
19462 \end_inset
19463 </cell>
19464 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19465 \begin_inset Text
19466
19467 \layout Standard
19468
19469 AD convertion complete interrupt
19470 \end_inset
19471 </cell>
19472 </row>
19473 <row topline="true">
19474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19475 \begin_inset Text
19476
19477 \layout Standard
19478
19479 SIG_CCP2
19480 \end_inset
19481 </cell>
19482 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19483 \begin_inset Text
19484
19485 \layout Standard
19486
19487 CCP2 module interrupt
19488 \end_inset
19489 </cell>
19490 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19491 \begin_inset Text
19492
19493 \layout Standard
19494
19495 SIG_RC
19496 \end_inset
19497 </cell>
19498 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19499 \begin_inset Text
19500
19501 \layout Standard
19502
19503 USART receive interrupt
19504 \end_inset
19505 </cell>
19506 </row>
19507 <row topline="true">
19508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19509 \begin_inset Text
19510
19511 \layout Standard
19512
19513 SIG_TMR0
19514 \end_inset
19515 </cell>
19516 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19517 \begin_inset Text
19518
19519 \layout Standard
19520
19521 TMR0 overflow interrupt
19522 \end_inset
19523 </cell>
19524 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19525 \begin_inset Text
19526
19527 \layout Standard
19528
19529 SIG_TX
19530 \end_inset
19531 </cell>
19532 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19533 \begin_inset Text
19534
19535 \layout Standard
19536
19537 USART transmit interrupt
19538 \end_inset
19539 </cell>
19540 </row>
19541 <row topline="true">
19542 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19543 \begin_inset Text
19544
19545 \layout Standard
19546
19547 SIG_TMR1
19548 \end_inset
19549 </cell>
19550 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19551 \begin_inset Text
19552
19553 \layout Standard
19554
19555 TMR1 overflow interrupt
19556 \end_inset
19557 </cell>
19558 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19559 \begin_inset Text
19560
19561 \layout Standard
19562
19563 SIG_MSSP
19564 \end_inset
19565 </cell>
19566 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19567 \begin_inset Text
19568
19569 \layout Standard
19570
19571 SSP receive/transmit interrupt
19572 \end_inset
19573 </cell>
19574 </row>
19575 <row topline="true">
19576 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19577 \begin_inset Text
19578
19579 \layout Standard
19580
19581 SIG_TMR2
19582 \end_inset
19583 </cell>
19584 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19585 \begin_inset Text
19586
19587 \layout Standard
19588
19589 TMR2 matches PR2 interrupt
19590 \end_inset
19591 </cell>
19592 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19593 \begin_inset Text
19594
19595 \layout Standard
19596
19597 \end_inset
19598 </cell>
19599 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19600 \begin_inset Text
19601
19602 \layout Standard
19603
19604 \end_inset
19605 </cell>
19606 </row>
19607 <row topline="true" bottomline="true">
19608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19609 \begin_inset Text
19610
19611 \layout Standard
19612
19613 SIG_TMR3
19614 \end_inset
19615 </cell>
19616 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19617 \begin_inset Text
19618
19619 \layout Standard
19620
19621 TMR3 overflow interrupt
19622 \end_inset
19623 </cell>
19624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19625 \begin_inset Text
19626
19627 \layout Standard
19628
19629 \end_inset
19630 </cell>
19631 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19632 \begin_inset Text
19633
19634 \layout Standard
19635
19636 \end_inset
19637 </cell>
19638 </row>
19639 </lyxtabular>
19640
19641 \end_inset
19642
19643
19644 \layout Standard
19645
19646 The prototypes for these names are defined in the header file
19647 \emph on
19648 signal.h
19649 \emph default
19650  .
19651 \layout Standard
19652
19653 In order to simplify signal handling, a number of macros is provided:
19654 \layout List
19655 \labelwidthstring 00.00.0000
19656
19657 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
19658  high priority interrupts.
19659
19660 \emph on
19661 name
19662 \emph default
19663  is the function name to use.
19664 \layout List
19665 \labelwidthstring 00.00.0000
19666
19667 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
19668  low priority interrupt.
19669
19670 \emph on
19671 name
19672 \emph default
19673  is the function name to use.
19674 \layout List
19675 \labelwidthstring 00.00.0000
19676
19677 DEF_HANDLER(sig,handler) define a handler for signal
19678 \emph on
19679 sig.
19680 \layout List
19681 \labelwidthstring 00.00.0000
19682
19683 END_DEF end the declaration of the dispatch table.
19684 \layout Standard
19685
19686 Additionally there are two more macros to simplify the declaration of the
19687  signal handler:
19688 \layout List
19689 \labelwidthstring 00.00.0000
19690
19691
19692 \series medium
19693 SIGHANDLER(handler)
19694 \series default
19695 this declares the function prototype for the
19696 \emph on
19697 handler
19698 \emph default
19699  function.
19700 \layout List
19701 \labelwidthstring 00.00.0000
19702
19703 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
19704 \layout Standard
19705
19706 An example of using the macros above is shown below:
19707 \layout LyX-Code
19708
19709 #include <pic18fregs.h>
19710 \layout LyX-Code
19711
19712 #include <signal.h>
19713 \newline
19714
19715 \newline
19716 DEF_INTHIGH(high_int)
19717 \layout LyX-Code
19718
19719 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
19720 \layout LyX-Code
19721
19722 DEF_HANDLER(SIG_BCOL, _bcol_handler)
19723 \layout LyX-Code
19724
19725 END_DEF
19726 \newline
19727
19728 \newline
19729 SIGHANDLER(_tmr0_handler)
19730 \layout LyX-Code
19731
19732 {
19733 \layout LyX-Code
19734
19735   /* action to be taken when timer 0 overflows */
19736 \layout LyX-Code
19737
19738 }
19739 \newline
19740
19741 \newline
19742 SIGHANDLERNAKED(_bcol_handler)
19743 \layout LyX-Code
19744
19745 {
19746 \layout LyX-Code
19747
19748   _asm
19749 \layout LyX-Code
19750
19751     /* action to be taken when bus collision occurs */
19752 \layout LyX-Code
19753
19754     retfie
19755 \layout LyX-Code
19756
19757  _endasm;
19758 \layout LyX-Code
19759
19760 }
19761 \layout Standard
19762
19763
19764 \series bold
19765 NOTES:
19766 \series default
19767  Special care should be taken when using the above scheme:
19768 \layout Itemize
19769
19770 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
19771 \layout Itemize
19772
19773 when declaring SIGHANDLERNAKED handler never forget to use
19774 \emph on
19775 retfie
19776 \emph default
19777  for proper returning.
19778 \layout Subsection
19779
19780 PIC16 Port -- Tips
19781 \layout Standard
19782
19783 Here you can find some general tips for compiling programs with SDCC/pic16.
19784 \layout Subsubsection
19785
19786 Stack size
19787 \layout Standard
19788
19789 The default stack size (that is 64 bytes) probably is enough for many programs.
19790  One must take care that when there are many levels of function nesting,
19791  or there is excessive usage of stack, its size should be extended.
19792  An example of such a case is the printf/sprintf family of functions.
19793  If you encounter problems like not being able to print integers, then you
19794  need to set the stack size around the maximum (256 for small stack model).
19795  The following diagram shows what happens when calling printf to print an
19796  integer:
19797 \layout LyX-Code
19798
19799 printf () --> ltoa () --> ultoa () --> divschar ()
19800 \layout Standard
19801
19802 It is should be understood that stack is easily consumed when calling complicate
19803 d functions.
19804  Using command line arguments like -
19805 \begin_inset ERT
19806 status Collapsed
19807
19808 \layout Standard
19809
19810 \backslash
19811 /
19812 \end_inset
19813
19814 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
19815  stack frames.
19816  Other ways to reduce stack usage may exist.
19817 \layout Chapter
19818
19819 Debugging with SDCDB
19820 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
19821
19822 \end_inset
19823
19824
19825 \begin_inset LatexCommand \index{sdcdb (debugger)}
19826
19827 \end_inset
19828
19829
19830 \layout Standard
19831
19832 SDCC is distributed with a source level debugger
19833 \begin_inset LatexCommand \index{Debugger}
19834
19835 \end_inset
19836
19837 .
19838  The debugger uses a command line interface, the command repertoire of the
19839  debugger has been kept as close to gdb
19840 \begin_inset LatexCommand \index{gdb}
19841
19842 \end_inset
19843
19844  (the GNU debugger) as possible.
19845  The configuration and build process is part of the standard compiler installati
19846 on, which also builds and installs the debugger in the target directory
19847  specified during configuration.
19848  The debugger allows you debug BOTH at the C source and at the ASM source
19849  level.
19850  Sdcdb is available on Unix platforms only.
19851 \layout Section
19852
19853 Compiling for Debugging
19854 \layout Standard
19855
19856 The -
19857 \begin_inset ERT
19858 status Collapsed
19859
19860 \layout Standard
19861
19862 \backslash
19863 /
19864 \end_inset
19865
19866 -debug
19867 \begin_inset LatexCommand \index{-\/-debug}
19868
19869 \end_inset
19870
19871  option must be specified for all files for which debug information is to
19872  be generated.
19873  The complier generates a .adb file for each of these files.
19874  The linker creates the .cdb
19875 \begin_inset LatexCommand \index{<file>.cdb}
19876
19877 \end_inset
19878
19879  file from the .adb
19880 \begin_inset LatexCommand \index{<file>.adb}
19881
19882 \end_inset
19883
19884  files and the address information.
19885  This .cdb is used by the debugger.
19886 \layout Section
19887
19888 How the Debugger Works
19889 \layout Standard
19890
19891 When the -
19892 \begin_inset ERT
19893 status Collapsed
19894
19895 \layout Standard
19896
19897 \backslash
19898 /
19899 \end_inset
19900
19901 -debug option is specified the compiler generates extra symbol information
19902  some of which are put into the assembler source and some are put into the
19903  .adb file.
19904   Then the linker creates the .cdb file from the individual .adb files with
19905  the address information for the symbols.
19906  The debugger reads the symbolic information generated by the compiler &
19907  the address information generated by the linker.
19908  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
19909  execution is controlled by the debugger.
19910  When a command is issued for the debugger, it translates it into appropriate
19911  commands for the simulator.
19912 \layout Section
19913
19914 Starting the Debugger
19915 \layout Standard
19916
19917 The debugger can be started using the following command line.
19918  (Assume the file you are debugging has the file name foo).
19919 \newline
19920
19921 \newline
19922
19923 \family sans
19924 \series bold
19925 sdcdb foo
19926 \newline
19927
19928 \family default
19929 \series default
19930
19931 \newline
19932 The debugger will look for the following files.
19933 \layout Itemize
19934
19935 foo.c - the source file.
19936 \layout Itemize
19937
19938 foo.cdb - the debugger symbol information file.
19939 \layout Itemize
19940
19941 foo.ihx - the Intel hex format
19942 \begin_inset LatexCommand \index{Intel hex format}
19943
19944 \end_inset
19945
19946  object file.
19947 \layout Section
19948
19949 Command Line Options
19950 \layout Itemize
19951
19952 -
19953 \begin_inset ERT
19954 status Collapsed
19955
19956 \layout Standard
19957
19958 \backslash
19959 /
19960 \end_inset
19961
19962 -directory=<source file directory> this option can used to specify the directory
19963  search list.
19964  The debugger will look into the directory list specified for source, cdb
19965  & ihx files.
19966  The items in the directory list must be separated by ':', e.g.
19967  if the source files can be in the directories /home/src1 and /home/src2,
19968  the -
19969 \begin_inset ERT
19970 status Collapsed
19971
19972 \layout Standard
19973
19974 \backslash
19975 /
19976 \end_inset
19977
19978 -directory option should be -
19979 \begin_inset ERT
19980 status Collapsed
19981
19982 \layout Standard
19983
19984 \backslash
19985 /
19986 \end_inset
19987
19988 -directory=/home/src1:/home/src2.
19989  Note there can be no spaces in the option.
19990
19991 \layout Itemize
19992
19993 -cd <directory> - change to the <directory>.
19994 \layout Itemize
19995
19996 -fullname - used by GUI front ends.
19997 \layout Itemize
19998
19999 -cpu <cpu-type> - this argument is passed to the simulator please see the
20000  simulator docs for details.
20001 \layout Itemize
20002
20003 -X <Clock frequency > this options is passed to the simulator please see
20004  the simulator docs for details.
20005 \layout Itemize
20006
20007 -s <serial port file> passed to simulator see the simulator docs for details.
20008 \layout Itemize
20009
20010 -S <serial in,out> passed to simulator see the simulator docs for details.
20011 \layout Itemize
20012
20013 -k <port number> passed to simulator see the simulator docs for details.
20014 \layout Section
20015
20016 Debugger Commands
20017 \layout Standard
20018
20019 As mentioned earlier the command interface for the debugger has been deliberatel
20020 y kept as close the GNU debugger gdb, as possible.
20021  This will help the integration with existing graphical user interfaces
20022  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
20023  If you use a graphical user interface for the debugger you can skip this
20024  section.
20025 \layout Subsubsection*
20026
20027 break [line | file:line | function | file:function]
20028 \layout Standard
20029
20030 Set breakpoint at specified line or function:
20031 \newline
20032
20033 \newline
20034
20035 \family sans
20036 \series bold
20037 sdcdb>break 100
20038 \newline
20039 sdcdb>break foo.c:100
20040 \newline
20041 sdcdb>break funcfoo
20042 \newline
20043 sdcdb>break foo.c:funcfoo
20044 \layout Subsubsection*
20045
20046 clear [line | file:line | function | file:function ]
20047 \layout Standard
20048
20049 Clear breakpoint at specified line or function:
20050 \newline
20051
20052 \newline
20053
20054 \family sans
20055 \series bold
20056 sdcdb>clear 100
20057 \newline
20058 sdcdb>clear foo.c:100
20059 \newline
20060 sdcdb>clear funcfoo
20061 \newline
20062 sdcdb>clear foo.c:funcfoo
20063 \layout Subsubsection*
20064
20065 continue
20066 \layout Standard
20067
20068 Continue program being debugged, after breakpoint.
20069 \layout Subsubsection*
20070
20071 finish
20072 \layout Standard
20073
20074 Execute till the end of the current function.
20075 \layout Subsubsection*
20076
20077 delete [n]
20078 \layout Standard
20079
20080 Delete breakpoint number 'n'.
20081  If used without any option clear ALL user defined break points.
20082 \layout Subsubsection*
20083
20084 info [break | stack | frame | registers ]
20085 \layout Itemize
20086
20087 info break - list all breakpoints
20088 \layout Itemize
20089
20090 info stack - show the function call stack.
20091 \layout Itemize
20092
20093 info frame - show information about the current execution frame.
20094 \layout Itemize
20095
20096 info registers - show content of all registers.
20097 \layout Subsubsection*
20098
20099 step
20100 \layout Standard
20101
20102 Step program until it reaches a different source line.
20103  Note: pressing <return> repeats the last command.
20104 \layout Subsubsection*
20105
20106 next
20107 \layout Standard
20108
20109 Step program, proceeding through subroutine calls.
20110 \layout Subsubsection*
20111
20112 run
20113 \layout Standard
20114
20115 Start debugged program.
20116 \layout Subsubsection*
20117
20118 ptype variable
20119 \layout Standard
20120
20121 Print type information of the variable.
20122 \layout Subsubsection*
20123
20124 print variable
20125 \layout Standard
20126
20127 print value of variable.
20128 \layout Subsubsection*
20129
20130 file filename
20131 \layout Standard
20132
20133 load the given file name.
20134  Note this is an alternate method of loading file for debugging.
20135 \layout Subsubsection*
20136
20137 frame
20138 \layout Standard
20139
20140 print information about current frame.
20141 \layout Subsubsection*
20142
20143 set srcmode
20144 \layout Standard
20145
20146 Toggle between C source & assembly source.
20147 \layout Subsubsection*
20148
20149 ! simulator command
20150 \layout Standard
20151
20152 Send the string following '!' to the simulator, the simulator response is
20153  displayed.
20154  Note the debugger does not interpret the command being sent to the simulator,
20155  so if a command like 'go' is sent the debugger can loose its execution
20156  context and may display incorrect values.
20157 \layout Subsubsection*
20158
20159 quit
20160 \layout Standard
20161
20162 "Watch me now.
20163  Iam going Down.
20164  My name is Bobby Brown"
20165 \layout Section
20166
20167 Interfacing with DDD
20168 \layout Comment
20169
20170 The screenshot was converted from png to eps with:
20171 \begin_inset Quotes sld
20172 \end_inset
20173
20174 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
20175 \begin_inset Quotes srd
20176 \end_inset
20177
20178  which produces a pretty compact eps file which is free from compression
20179  artifacts.
20180 \layout Comment
20181
20182 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
20183  as this broke the build system on Sourceforge (pdf-file was broken).
20184 \layout Standard
20185
20186 The .eps File
20187 \size footnotesize
20188
20189 \begin_inset LatexCommand \url{http://cvs.sourceforge.net/viewcvs.py/*checkout*/sdcc/sdcc/doc/figures/ddd_example.eps}
20190
20191 \end_inset
20192
20193
20194 \size default
20195  shows a screenshot of a debugging session with DDD
20196 \begin_inset LatexCommand \index{DDD (debugger)}
20197
20198 \end_inset
20199
20200  (Unix only) on a simulated 8032.
20201  The debugging session might not run as smoothly as the screenshot suggests.
20202  The debugger allows setting of breakpoints, displaying and changing variables,
20203  single stepping through C and assembler code.
20204
20205 \newline
20206 The source was compiled with
20207 \family sans
20208 \series bold
20209
20210 \newline
20211
20212 \newline
20213 sdcc -
20214 \family default
20215 \series default
20216
20217 \begin_inset ERT
20218 status Collapsed
20219
20220 \layout Standard
20221
20222 \backslash
20223 /
20224 \end_inset
20225
20226
20227 \family sans
20228 \series bold
20229 -debug ddd_example.c
20230 \family default
20231 \series default
20232
20233 \family sans
20234 \series bold
20235
20236 \newline
20237
20238 \family default
20239 \series default
20240
20241 \newline
20242 and DDD was invoked with
20243 \family sans
20244 \series bold
20245
20246 \newline
20247
20248 \newline
20249 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
20250 \layout Section
20251
20252 Interfacing with XEmacs
20253 \begin_inset LatexCommand \index{XEmacs}
20254
20255 \end_inset
20256
20257
20258 \begin_inset LatexCommand \index{Emacs}
20259
20260 \end_inset
20261
20262
20263 \layout Standard
20264
20265 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
20266  sdcdb.el and sdcdbsrc.el.
20267  These two files can be found in the $(prefix)/bin directory after the installat
20268 ion is complete.
20269  These files need to be loaded into XEmacs for the interface to work.
20270  This can be done at XEmacs startup time by inserting the following into
20271  your '.xemacs' file (which can be found in your HOME directory):
20272 \newline
20273
20274 \newline
20275
20276 \family typewriter
20277 (load-file sdcdbsrc.el)
20278 \family default
20279
20280 \newline
20281
20282 \newline
20283 .xemacs is a lisp file so the () around the command is REQUIRED.
20284  The files can also be loaded dynamically while XEmacs is running, set the
20285  environment variable 'EMACSLOADPATH' to the installation bin directory
20286  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
20287  To start the interface enter the following command:
20288 \newline
20289
20290 \newline
20291
20292 \family sans
20293 \series bold
20294 ESC-x sdcdbsrc
20295 \family default
20296 \series default
20297
20298 \newline
20299
20300 \newline
20301 You will prompted to enter the file name to be debugged.
20302
20303 \newline
20304
20305 \newline
20306 The command line options that are passed to the simulator directly are bound
20307  to default values in the file sdcdbsrc.el.
20308  The variables are listed below, these values maybe changed as required.
20309 \layout Itemize
20310
20311 sdcdbsrc-cpu-type '51
20312 \layout Itemize
20313
20314 sdcdbsrc-frequency '11059200
20315 \layout Itemize
20316
20317 sdcdbsrc-serial nil
20318 \layout Standard
20319
20320 The following is a list of key mapping for the debugger interface.
20321 \layout Standard
20322
20323 \SpecialChar ~
20324
20325 \family typewriter
20326
20327 \newline
20328 ;;\SpecialChar ~
20329 Current Listing ::
20330 \newline
20331 ;;key\SpecialChar ~
20332 \SpecialChar ~
20333 \SpecialChar ~
20334 \SpecialChar ~
20335 \SpecialChar ~
20336 \SpecialChar ~
20337 \SpecialChar ~
20338 \SpecialChar ~
20339 \SpecialChar ~
20340 \SpecialChar ~
20341 \SpecialChar ~
20342 \SpecialChar ~
20343 \SpecialChar ~
20344 \SpecialChar ~
20345 binding\SpecialChar ~
20346 \SpecialChar ~
20347 \SpecialChar ~
20348 \SpecialChar ~
20349 \SpecialChar ~
20350 \SpecialChar ~
20351 \SpecialChar ~
20352 \SpecialChar ~
20353 \SpecialChar ~
20354 \SpecialChar ~
20355 \SpecialChar ~
20356 \SpecialChar ~
20357 \SpecialChar ~
20358 \SpecialChar ~
20359 \SpecialChar ~
20360 \SpecialChar ~
20361 \SpecialChar ~
20362 \SpecialChar ~
20363 \SpecialChar ~
20364 \SpecialChar ~
20365 \SpecialChar ~
20366 \SpecialChar ~
20367 Comment
20368 \newline
20369 ;;---\SpecialChar ~
20370 \SpecialChar ~
20371 \SpecialChar ~
20372 \SpecialChar ~
20373 \SpecialChar ~
20374 \SpecialChar ~
20375 \SpecialChar ~
20376 \SpecialChar ~
20377 \SpecialChar ~
20378 \SpecialChar ~
20379 \SpecialChar ~
20380 \SpecialChar ~
20381 \SpecialChar ~
20382 \SpecialChar ~
20383 -------\SpecialChar ~
20384 \SpecialChar ~
20385 \SpecialChar ~
20386 \SpecialChar ~
20387 \SpecialChar ~
20388 \SpecialChar ~
20389 \SpecialChar ~
20390 \SpecialChar ~
20391 \SpecialChar ~
20392 \SpecialChar ~
20393 \SpecialChar ~
20394 \SpecialChar ~
20395 \SpecialChar ~
20396 \SpecialChar ~
20397 \SpecialChar ~
20398 \SpecialChar ~
20399 \SpecialChar ~
20400 \SpecialChar ~
20401 \SpecialChar ~
20402 \SpecialChar ~
20403 \SpecialChar ~
20404 \SpecialChar ~
20405 -------
20406 \newline
20407 ;;
20408 \newline
20409 ;;\SpecialChar ~
20410 n\SpecialChar ~
20411 \SpecialChar ~
20412 \SpecialChar ~
20413 \SpecialChar ~
20414 \SpecialChar ~
20415 \SpecialChar ~
20416 \SpecialChar ~
20417 \SpecialChar ~
20418 \SpecialChar ~
20419 \SpecialChar ~
20420 \SpecialChar ~
20421 \SpecialChar ~
20422 \SpecialChar ~
20423 \SpecialChar ~
20424 \SpecialChar ~
20425 sdcdb-next-from-src\SpecialChar ~
20426 \SpecialChar ~
20427 \SpecialChar ~
20428 \SpecialChar ~
20429 \SpecialChar ~
20430 \SpecialChar ~
20431 \SpecialChar ~
20432 \SpecialChar ~
20433 \SpecialChar ~
20434 \SpecialChar ~
20435 SDCDB next command
20436 \newline
20437 ;;\SpecialChar ~
20438 b\SpecialChar ~
20439 \SpecialChar ~
20440 \SpecialChar ~
20441 \SpecialChar ~
20442 \SpecialChar ~
20443 \SpecialChar ~
20444 \SpecialChar ~
20445 \SpecialChar ~
20446 \SpecialChar ~
20447 \SpecialChar ~
20448 \SpecialChar ~
20449 \SpecialChar ~
20450 \SpecialChar ~
20451 \SpecialChar ~
20452 \SpecialChar ~
20453 sdcdb-back-from-src\SpecialChar ~
20454 \SpecialChar ~
20455 \SpecialChar ~
20456 \SpecialChar ~
20457 \SpecialChar ~
20458 \SpecialChar ~
20459 \SpecialChar ~
20460 \SpecialChar ~
20461 \SpecialChar ~
20462 \SpecialChar ~
20463 SDCDB back command
20464 \newline
20465 ;;\SpecialChar ~
20466 c\SpecialChar ~
20467 \SpecialChar ~
20468 \SpecialChar ~
20469 \SpecialChar ~
20470 \SpecialChar ~
20471 \SpecialChar ~
20472 \SpecialChar ~
20473 \SpecialChar ~
20474 \SpecialChar ~
20475 \SpecialChar ~
20476 \SpecialChar ~
20477 \SpecialChar ~
20478 \SpecialChar ~
20479 \SpecialChar ~
20480 \SpecialChar ~
20481 sdcdb-cont-from-src\SpecialChar ~
20482 \SpecialChar ~
20483 \SpecialChar ~
20484 \SpecialChar ~
20485 \SpecialChar ~
20486 \SpecialChar ~
20487 \SpecialChar ~
20488 \SpecialChar ~
20489 \SpecialChar ~
20490 \SpecialChar ~
20491 SDCDB continue command
20492 \newline
20493 ;;\SpecialChar ~
20494 s\SpecialChar ~
20495 \SpecialChar ~
20496 \SpecialChar ~
20497 \SpecialChar ~
20498 \SpecialChar ~
20499 \SpecialChar ~
20500 \SpecialChar ~
20501 \SpecialChar ~
20502 \SpecialChar ~
20503 \SpecialChar ~
20504 \SpecialChar ~
20505 \SpecialChar ~
20506 \SpecialChar ~
20507 \SpecialChar ~
20508 \SpecialChar ~
20509 sdcdb-step-from-src\SpecialChar ~
20510 \SpecialChar ~
20511 \SpecialChar ~
20512 \SpecialChar ~
20513 \SpecialChar ~
20514 \SpecialChar ~
20515 \SpecialChar ~
20516 \SpecialChar ~
20517 \SpecialChar ~
20518 \SpecialChar ~
20519 SDCDB step command
20520 \newline
20521 ;;\SpecialChar ~
20522 ?\SpecialChar ~
20523 \SpecialChar ~
20524 \SpecialChar ~
20525 \SpecialChar ~
20526 \SpecialChar ~
20527 \SpecialChar ~
20528 \SpecialChar ~
20529 \SpecialChar ~
20530 \SpecialChar ~
20531 \SpecialChar ~
20532 \SpecialChar ~
20533 \SpecialChar ~
20534 \SpecialChar ~
20535 \SpecialChar ~
20536 \SpecialChar ~
20537 sdcdb-whatis-c-sexp\SpecialChar ~
20538 \SpecialChar ~
20539 \SpecialChar ~
20540 \SpecialChar ~
20541 \SpecialChar ~
20542 \SpecialChar ~
20543 \SpecialChar ~
20544 \SpecialChar ~
20545 \SpecialChar ~
20546 \SpecialChar ~
20547 SDCDB ptypecommand for data at
20548 \newline
20549 ;;\SpecialChar ~
20550 \SpecialChar ~
20551 \SpecialChar ~
20552 \SpecialChar ~
20553 \SpecialChar ~
20554 \SpecialChar ~
20555 \SpecialChar ~
20556 \SpecialChar ~
20557 \SpecialChar ~
20558 \SpecialChar ~
20559 \SpecialChar ~
20560 \SpecialChar ~
20561 \SpecialChar ~
20562 \SpecialChar ~
20563 \SpecialChar ~
20564 \SpecialChar ~
20565 \SpecialChar ~
20566 \SpecialChar ~
20567 \SpecialChar ~
20568 \SpecialChar ~
20569 \SpecialChar ~
20570 \SpecialChar ~
20571 \SpecialChar ~
20572 \SpecialChar ~
20573 \SpecialChar ~
20574 \SpecialChar ~
20575 \SpecialChar ~
20576 \SpecialChar ~
20577 \SpecialChar ~
20578 \SpecialChar ~
20579 \SpecialChar ~
20580 \SpecialChar ~
20581 \SpecialChar ~
20582 \SpecialChar ~
20583 \SpecialChar ~
20584 \SpecialChar ~
20585 \SpecialChar ~
20586 \SpecialChar ~
20587 \SpecialChar ~
20588 \SpecialChar ~
20589 \SpecialChar ~
20590 \SpecialChar ~
20591 \SpecialChar ~
20592 \SpecialChar ~
20593 \SpecialChar ~
20594 \SpecialChar ~
20595 \SpecialChar ~
20596 buffer point
20597 \newline
20598 ;;\SpecialChar ~
20599 x\SpecialChar ~
20600 \SpecialChar ~
20601 \SpecialChar ~
20602 \SpecialChar ~
20603 \SpecialChar ~
20604 \SpecialChar ~
20605 \SpecialChar ~
20606 \SpecialChar ~
20607 \SpecialChar ~
20608 \SpecialChar ~
20609 \SpecialChar ~
20610 \SpecialChar ~
20611 \SpecialChar ~
20612 \SpecialChar ~
20613 \SpecialChar ~
20614 sdcdbsrc-delete\SpecialChar ~
20615 \SpecialChar ~
20616 \SpecialChar ~
20617 \SpecialChar ~
20618 \SpecialChar ~
20619 \SpecialChar ~
20620 \SpecialChar ~
20621 \SpecialChar ~
20622 \SpecialChar ~
20623 \SpecialChar ~
20624 \SpecialChar ~
20625 \SpecialChar ~
20626 \SpecialChar ~
20627 \SpecialChar ~
20628 SDCDB Delete all breakpoints if no arg
20629 \newline
20630 ;;\SpecialChar ~
20631 \SpecialChar ~
20632 \SpecialChar ~
20633 \SpecialChar ~
20634 \SpecialChar ~
20635 \SpecialChar ~
20636 \SpecialChar ~
20637 \SpecialChar ~
20638 \SpecialChar ~
20639 \SpecialChar ~
20640 \SpecialChar ~
20641 \SpecialChar ~
20642 \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 \SpecialChar ~
20660 \SpecialChar ~
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 given or delete arg (C-u arg x)
20678 \newline
20679 ;;\SpecialChar ~
20680 m\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 sdcdbsrc-frame\SpecialChar ~
20696 \SpecialChar ~
20697 \SpecialChar ~
20698 \SpecialChar ~
20699 \SpecialChar ~
20700 \SpecialChar ~
20701 \SpecialChar ~
20702 \SpecialChar ~
20703 \SpecialChar ~
20704 \SpecialChar ~
20705 \SpecialChar ~
20706 \SpecialChar ~
20707 \SpecialChar ~
20708 \SpecialChar ~
20709 \SpecialChar ~
20710 SDCDB Display current frame if no arg,
20711 \newline
20712 ;;\SpecialChar ~
20713 \SpecialChar ~
20714 \SpecialChar ~
20715 \SpecialChar ~
20716 \SpecialChar ~
20717 \SpecialChar ~
20718 \SpecialChar ~
20719 \SpecialChar ~
20720 \SpecialChar ~
20721 \SpecialChar ~
20722 \SpecialChar ~
20723 \SpecialChar ~
20724 \SpecialChar ~
20725 \SpecialChar ~
20726 \SpecialChar ~
20727 \SpecialChar ~
20728 \SpecialChar ~
20729 \SpecialChar ~
20730 \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 \SpecialChar ~
20746 \SpecialChar ~
20747 \SpecialChar ~
20748 \SpecialChar ~
20749 \SpecialChar ~
20750 \SpecialChar ~
20751 \SpecialChar ~
20752 \SpecialChar ~
20753 \SpecialChar ~
20754 \SpecialChar ~
20755 \SpecialChar ~
20756 \SpecialChar ~
20757 \SpecialChar ~
20758 \SpecialChar ~
20759 given or display frame arg
20760 \newline
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 \SpecialChar ~
20774 \SpecialChar ~
20775 \SpecialChar ~
20776 \SpecialChar ~
20777 \SpecialChar ~
20778 \SpecialChar ~
20779 \SpecialChar ~
20780 \SpecialChar ~
20781 \SpecialChar ~
20782 \SpecialChar ~
20783 \SpecialChar ~
20784 \SpecialChar ~
20785 \SpecialChar ~
20786 \SpecialChar ~
20787 \SpecialChar ~
20788 \SpecialChar ~
20789 \SpecialChar ~
20790 \SpecialChar ~
20791 \SpecialChar ~
20792 \SpecialChar ~
20793 \SpecialChar ~
20794 \SpecialChar ~
20795 \SpecialChar ~
20796 \SpecialChar ~
20797 \SpecialChar ~
20798 \SpecialChar ~
20799 \SpecialChar ~
20800 \SpecialChar ~
20801 \SpecialChar ~
20802 \SpecialChar ~
20803 \SpecialChar ~
20804 \SpecialChar ~
20805 \SpecialChar ~
20806 \SpecialChar ~
20807 \SpecialChar ~
20808 buffer point
20809 \newline
20810 ;;\SpecialChar ~
20811 !\SpecialChar ~
20812 \SpecialChar ~
20813 \SpecialChar ~
20814 \SpecialChar ~
20815 \SpecialChar ~
20816 \SpecialChar ~
20817 \SpecialChar ~
20818 \SpecialChar ~
20819 \SpecialChar ~
20820 \SpecialChar ~
20821 \SpecialChar ~
20822 \SpecialChar ~
20823 \SpecialChar ~
20824 \SpecialChar ~
20825 \SpecialChar ~
20826 sdcdbsrc-goto-sdcdb\SpecialChar ~
20827 \SpecialChar ~
20828 \SpecialChar ~
20829 \SpecialChar ~
20830 \SpecialChar ~
20831 \SpecialChar ~
20832 \SpecialChar ~
20833 \SpecialChar ~
20834 \SpecialChar ~
20835 \SpecialChar ~
20836 Goto the SDCDB output buffer
20837 \newline
20838 ;;\SpecialChar ~
20839 p\SpecialChar ~
20840 \SpecialChar ~
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 sdcdb-print-c-sexp\SpecialChar ~
20855 \SpecialChar ~
20856 \SpecialChar ~
20857 \SpecialChar ~
20858 \SpecialChar ~
20859 \SpecialChar ~
20860 \SpecialChar ~
20861 \SpecialChar ~
20862 \SpecialChar ~
20863 \SpecialChar ~
20864 \SpecialChar ~
20865 SDCDB print command for data at
20866 \newline
20867 ;;\SpecialChar ~
20868 \SpecialChar ~
20869 \SpecialChar ~
20870 \SpecialChar ~
20871 \SpecialChar ~
20872 \SpecialChar ~
20873 \SpecialChar ~
20874 \SpecialChar ~
20875 \SpecialChar ~
20876 \SpecialChar ~
20877 \SpecialChar ~
20878 \SpecialChar ~
20879 \SpecialChar ~
20880 \SpecialChar ~
20881 \SpecialChar ~
20882 \SpecialChar ~
20883 \SpecialChar ~
20884 \SpecialChar ~
20885 \SpecialChar ~
20886 \SpecialChar ~
20887 \SpecialChar ~
20888 \SpecialChar ~
20889 \SpecialChar ~
20890 \SpecialChar ~
20891 \SpecialChar ~
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895 \SpecialChar ~
20896 \SpecialChar ~
20897 \SpecialChar ~
20898 \SpecialChar ~
20899 \SpecialChar ~
20900 \SpecialChar ~
20901 \SpecialChar ~
20902 \SpecialChar ~
20903 \SpecialChar ~
20904 \SpecialChar ~
20905 \SpecialChar ~
20906 \SpecialChar ~
20907 \SpecialChar ~
20908 \SpecialChar ~
20909 \SpecialChar ~
20910 \SpecialChar ~
20911 \SpecialChar ~
20912 \SpecialChar ~
20913 \SpecialChar ~
20914 buffer point
20915 \newline
20916 ;;\SpecialChar ~
20917 g\SpecialChar ~
20918 \SpecialChar ~
20919 \SpecialChar ~
20920 \SpecialChar ~
20921 \SpecialChar ~
20922 \SpecialChar ~
20923 \SpecialChar ~
20924 \SpecialChar ~
20925 \SpecialChar ~
20926 \SpecialChar ~
20927 \SpecialChar ~
20928 \SpecialChar ~
20929 \SpecialChar ~
20930 \SpecialChar ~
20931 \SpecialChar ~
20932 sdcdbsrc-goto-sdcdb\SpecialChar ~
20933 \SpecialChar ~
20934 \SpecialChar ~
20935 \SpecialChar ~
20936 \SpecialChar ~
20937 \SpecialChar ~
20938 \SpecialChar ~
20939 \SpecialChar ~
20940 \SpecialChar ~
20941 \SpecialChar ~
20942 Goto the SDCDB output buffer
20943 \newline
20944 ;;\SpecialChar ~
20945 t\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 sdcdbsrc-mode\SpecialChar ~
20961 \SpecialChar ~
20962 \SpecialChar ~
20963 \SpecialChar ~
20964 \SpecialChar ~
20965 \SpecialChar ~
20966 \SpecialChar ~
20967 \SpecialChar ~
20968 \SpecialChar ~
20969 \SpecialChar ~
20970 \SpecialChar ~
20971 \SpecialChar ~
20972 \SpecialChar ~
20973 \SpecialChar ~
20974 \SpecialChar ~
20975 \SpecialChar ~
20976 Toggles Sdcdbsrc mode (turns it off)
20977 \newline
20978 ;;
20979 \newline
20980 ;;\SpecialChar ~
20981 C-c\SpecialChar ~
20982 C-f\SpecialChar ~
20983 \SpecialChar ~
20984 \SpecialChar ~
20985 \SpecialChar ~
20986 \SpecialChar ~
20987 \SpecialChar ~
20988 \SpecialChar ~
20989 \SpecialChar ~
20990 \SpecialChar ~
20991 sdcdb-finish-from-src\SpecialChar ~
20992 \SpecialChar ~
20993 \SpecialChar ~
20994 \SpecialChar ~
20995 \SpecialChar ~
20996 \SpecialChar ~
20997 \SpecialChar ~
20998 \SpecialChar ~
20999 SDCDB finish command
21000 \newline
21001 ;;
21002 \newline
21003 ;;\SpecialChar ~
21004 C-x\SpecialChar ~
21005 SPC\SpecialChar ~
21006 \SpecialChar ~
21007 \SpecialChar ~
21008 \SpecialChar ~
21009 \SpecialChar ~
21010 \SpecialChar ~
21011 \SpecialChar ~
21012 \SpecialChar ~
21013 \SpecialChar ~
21014 sdcdb-break\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 Set break for line with point
21033 \newline
21034 ;;\SpecialChar ~
21035 ESC\SpecialChar ~
21036 t\SpecialChar ~
21037 \SpecialChar ~
21038 \SpecialChar ~
21039 \SpecialChar ~
21040 \SpecialChar ~
21041 \SpecialChar ~
21042 \SpecialChar ~
21043 \SpecialChar ~
21044 \SpecialChar ~
21045 \SpecialChar ~
21046 \SpecialChar ~
21047 sdcdbsrc-mode\SpecialChar ~
21048 \SpecialChar ~
21049 \SpecialChar ~
21050 \SpecialChar ~
21051 \SpecialChar ~
21052 \SpecialChar ~
21053 \SpecialChar ~
21054 \SpecialChar ~
21055 \SpecialChar ~
21056 \SpecialChar ~
21057 \SpecialChar ~
21058 \SpecialChar ~
21059 \SpecialChar ~
21060 \SpecialChar ~
21061 \SpecialChar ~
21062 \SpecialChar ~
21063 Toggle Sdcdbsrc mode
21064 \newline
21065 ;;\SpecialChar ~
21066 ESC\SpecialChar ~
21067 m\SpecialChar ~
21068 \SpecialChar ~
21069 \SpecialChar ~
21070 \SpecialChar ~
21071 \SpecialChar ~
21072 \SpecialChar ~
21073 \SpecialChar ~
21074 \SpecialChar ~
21075 \SpecialChar ~
21076 \SpecialChar ~
21077 \SpecialChar ~
21078 sdcdbsrc-srcmode\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 Toggle list mode
21092 \newline
21093 ;;
21094 \newline
21095
21096 \layout Chapter
21097 \pagebreak_top
21098 TIPS
21099 \layout Standard
21100
21101 Here are a few guidelines that will help the compiler generate more efficient
21102  code, some of the tips are specific to this compiler others are generally
21103  good programming practice.
21104 \layout Itemize
21105
21106 Use the smallest data type to represent your data-value.
21107  If it is known in advance that the value is going to be less than 256 then
21108  use an 'unsigned char' instead of a 'short' or 'int'.
21109  Please note, that ANSI C requires both signed and unsigned chars to be
21110  promoted to 'signed int' before doing any operation.
21111  This promotion
21112 \begin_inset LatexCommand \index{type promotion}
21113
21114 \end_inset
21115
21116  can be omitted, if the result is the same.
21117  The effect of the promotion rules together with the sign-extension is often
21118  surprising:
21119 \begin_deeper
21120 \layout Verse
21121
21122
21123 \family typewriter
21124 unsigned char uc = 0xfe;
21125 \newline
21126 if (uc * uc < 0) /* this is true! */
21127 \newline
21128 {
21129 \newline
21130 \SpecialChar ~
21131 \SpecialChar ~
21132 \SpecialChar ~
21133 \SpecialChar ~
21134 ....
21135 \newline
21136 }
21137 \layout Standard
21138
21139
21140 \family typewriter
21141 uc * uc
21142 \family default
21143  is evaluated as
21144 \family typewriter
21145 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
21146 \family default
21147 .
21148
21149 \newline
21150 Another one:
21151 \layout Verse
21152
21153
21154 \family typewriter
21155 (unsigned char) -12 / (signed char) -3 = ...
21156 \layout Standard
21157
21158 No, the result is not 4:
21159 \layout Verse
21160
21161
21162 \family typewriter
21163 (int) (unsigned char) -12 / (int) (signed char) -3 =
21164 \newline
21165 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
21166 \newline
21167 (int) 0x00f4 / (int) 0xfffd =
21168 \newline
21169 (int) 0x00f4 / (int) 0xfffd =
21170 \newline
21171 (int) 244 / (int) -3 =
21172 \newline
21173 (int) -81 = (int) 0xffaf;
21174 \layout Standard
21175
21176 Don't complain, that gcc gives you a different result.
21177  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
21178  Therefore the results are different.
21179 \newline
21180 From
21181 \begin_inset Quotes sld
21182 \end_inset
21183
21184 comp.lang.c FAQ
21185 \begin_inset Quotes srd
21186 \end_inset
21187
21188 :
21189 \layout Quote
21190
21191 If well-defined overflow characteristics are important and negative values
21192  are not, or if you want to steer clear of sign-extension problems when
21193  manipulating bits or bytes, use one of the corresponding unsigned types.
21194  (Beware when mixing signed and unsigned values in expressions, though.)
21195 \newline
21196 Although character types (especially unsigned char) can be used as "tiny"
21197  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
21198 ble sign extension and increased code size.
21199 \end_deeper
21200 \layout Itemize
21201
21202 Use unsigned when it is known in advance that the value is not going to
21203  be negative.
21204  This helps especially if you are doing division or multiplication, bit-shifting
21205  or are using an array index.
21206 \layout Itemize
21207
21208 NEVER jump into a LOOP.
21209 \layout Itemize
21210
21211 Declare the variables to be local
21212 \begin_inset LatexCommand \index{local variables}
21213
21214 \end_inset
21215
21216  whenever possible, especially loop control variables (induction).
21217 \layout Itemize
21218
21219 Since the compiler does not always do implicit integral promotion, the programme
21220 r should do an explicit cast when integral promotion is required.
21221 \layout Itemize
21222
21223 Reducing the size of division, multiplication & modulus operations can reduce
21224  code size substantially.
21225  Take the following code for example.
21226 \begin_deeper
21227 \layout Verse
21228
21229
21230 \family typewriter
21231 foobar(unsigned int p1, unsigned char ch)
21232 \newline
21233 {
21234 \newline
21235 \SpecialChar ~
21236 \SpecialChar ~
21237 \SpecialChar ~
21238 \SpecialChar ~
21239 unsigned char ch1 = p1 % ch ;
21240 \newline
21241 \SpecialChar ~
21242 \SpecialChar ~
21243 \SpecialChar ~
21244 \SpecialChar ~
21245 ....
21246 \newline
21247 }
21248 \layout Standard
21249
21250 For the modulus operation the variable ch will be promoted to unsigned int
21251  first then the modulus operation will be performed (this will lead to a
21252  call to support routine _moduint()), and the result will be casted to a
21253  char.
21254  If the code is changed to
21255 \layout Verse
21256
21257
21258 \family typewriter
21259 foobar(unsigned int p1, unsigned char ch)
21260 \newline
21261 {
21262 \newline
21263 \SpecialChar ~
21264 \SpecialChar ~
21265 \SpecialChar ~
21266 \SpecialChar ~
21267 unsigned char ch1 = (unsigned char)p1 % ch ;
21268 \newline
21269 \SpecialChar ~
21270 \SpecialChar ~
21271 \SpecialChar ~
21272 \SpecialChar ~
21273 ....
21274 \newline
21275 }
21276 \layout Standard
21277
21278 It would substantially reduce the code generated (future versions of the
21279  compiler will be smart enough to detect such optimization opportunities).
21280 \end_deeper
21281 \layout Itemize
21282
21283 Have a look at the assembly listing to get a
21284 \begin_inset Quotes sld
21285 \end_inset
21286
21287 feeling
21288 \begin_inset Quotes srd
21289 \end_inset
21290
21291  for the code generation.
21292 \layout Section
21293
21294 Tools
21295 \begin_inset LatexCommand \index{Tools}
21296
21297 \end_inset
21298
21299  included in the distribution
21300 \layout Standard
21301 \align center
21302
21303 \begin_inset  Tabular
21304 <lyxtabular version="3" rows="12" columns="3">
21305 <features>
21306 <column alignment="center" valignment="top" leftline="true" width="0pt">
21307 <column alignment="center" valignment="top" leftline="true" width="0pt">
21308 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21309 <row topline="true" bottomline="true">
21310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21311 \begin_inset Text
21312
21313 \layout Standard
21314
21315 Name
21316 \end_inset
21317 </cell>
21318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21319 \begin_inset Text
21320
21321 \layout Standard
21322
21323 Purpose
21324 \end_inset
21325 </cell>
21326 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21327 \begin_inset Text
21328
21329 \layout Standard
21330
21331 Directory
21332 \end_inset
21333 </cell>
21334 </row>
21335 <row topline="true">
21336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21337 \begin_inset Text
21338
21339 \layout Standard
21340
21341 uCsim
21342 \end_inset
21343 </cell>
21344 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21345 \begin_inset Text
21346
21347 \layout Standard
21348
21349 Simulator for various architectures
21350 \end_inset
21351 </cell>
21352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21353 \begin_inset Text
21354
21355 \layout Standard
21356
21357 sdcc/sim/ucsim
21358 \end_inset
21359 </cell>
21360 </row>
21361 <row topline="true">
21362 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21363 \begin_inset Text
21364
21365 \layout Standard
21366
21367 keil2sdcc.pl
21368 \end_inset
21369 </cell>
21370 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21371 \begin_inset Text
21372
21373 \layout Standard
21374
21375 header file conversion
21376 \end_inset
21377 </cell>
21378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21379 \begin_inset Text
21380
21381 \layout Standard
21382
21383 sdcc/support/scripts
21384 \end_inset
21385 </cell>
21386 </row>
21387 <row topline="true">
21388 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21389 \begin_inset Text
21390
21391 \layout Standard
21392
21393 mh2h.c
21394 \end_inset
21395 </cell>
21396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21397 \begin_inset Text
21398
21399 \layout Standard
21400
21401 header file conversion
21402 \end_inset
21403 </cell>
21404 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21405 \begin_inset Text
21406
21407 \layout Standard
21408
21409 sdcc/support/scripts
21410 \end_inset
21411 </cell>
21412 </row>
21413 <row topline="true">
21414 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21415 \begin_inset Text
21416
21417 \layout Standard
21418
21419 as-gbz80
21420 \end_inset
21421 </cell>
21422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21423 \begin_inset Text
21424
21425 \layout Standard
21426
21427 Assembler
21428 \end_inset
21429 </cell>
21430 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21431 \begin_inset Text
21432
21433 \layout Standard
21434
21435
21436 \family roman
21437 \series medium
21438 \shape up
21439 \size normal
21440 \emph off
21441 \bar no
21442 \noun off
21443 \color none
21444 sdcc/bin
21445 \end_inset
21446 </cell>
21447 </row>
21448 <row topline="true">
21449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21450 \begin_inset Text
21451
21452 \layout Standard
21453
21454 as-z80
21455 \end_inset
21456 </cell>
21457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21458 \begin_inset Text
21459
21460 \layout Standard
21461
21462 Assembler
21463 \end_inset
21464 </cell>
21465 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21466 \begin_inset Text
21467
21468 \layout Standard
21469
21470
21471 \family roman
21472 \series medium
21473 \shape up
21474 \size normal
21475 \emph off
21476 \bar no
21477 \noun off
21478 \color none
21479 sdcc/bin
21480 \end_inset
21481 </cell>
21482 </row>
21483 <row topline="true">
21484 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21485 \begin_inset Text
21486
21487 \layout Standard
21488
21489 asx8051
21490 \end_inset
21491 </cell>
21492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21493 \begin_inset Text
21494
21495 \layout Standard
21496
21497 Assembler
21498 \end_inset
21499 </cell>
21500 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21501 \begin_inset Text
21502
21503 \layout Standard
21504
21505
21506 \family roman
21507 \series medium
21508 \shape up
21509 \size normal
21510 \emph off
21511 \bar no
21512 \noun off
21513 \color none
21514 sdcc/bin
21515 \end_inset
21516 </cell>
21517 </row>
21518 <row topline="true">
21519 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21520 \begin_inset Text
21521
21522 \layout Standard
21523
21524 sdcdb
21525 \end_inset
21526 </cell>
21527 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21528 \begin_inset Text
21529
21530 \layout Standard
21531
21532 Simulator
21533 \end_inset
21534 </cell>
21535 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21536 \begin_inset Text
21537
21538 \layout Standard
21539
21540
21541 \family roman
21542 \series medium
21543 \shape up
21544 \size normal
21545 \emph off
21546 \bar no
21547 \noun off
21548 \color none
21549 sdcc/bin
21550 \end_inset
21551 </cell>
21552 </row>
21553 <row topline="true">
21554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21555 \begin_inset Text
21556
21557 \layout Standard
21558
21559 aslink
21560 \end_inset
21561 </cell>
21562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21563 \begin_inset Text
21564
21565 \layout Standard
21566
21567 Linker
21568 \end_inset
21569 </cell>
21570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21571 \begin_inset Text
21572
21573 \layout Standard
21574
21575
21576 \family roman
21577 \series medium
21578 \shape up
21579 \size normal
21580 \emph off
21581 \bar no
21582 \noun off
21583 \color none
21584 sdcc/bin
21585 \end_inset
21586 </cell>
21587 </row>
21588 <row topline="true">
21589 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21590 \begin_inset Text
21591
21592 \layout Standard
21593
21594 link-z80
21595 \end_inset
21596 </cell>
21597 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21598 \begin_inset Text
21599
21600 \layout Standard
21601
21602 Linker
21603 \end_inset
21604 </cell>
21605 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21606 \begin_inset Text
21607
21608 \layout Standard
21609
21610
21611 \family roman
21612 \series medium
21613 \shape up
21614 \size normal
21615 \emph off
21616 \bar no
21617 \noun off
21618 \color none
21619 sdcc/bin
21620 \end_inset
21621 </cell>
21622 </row>
21623 <row topline="true">
21624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21625 \begin_inset Text
21626
21627 \layout Standard
21628
21629 link-gbz80
21630 \end_inset
21631 </cell>
21632 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21633 \begin_inset Text
21634
21635 \layout Standard
21636
21637 Linker
21638 \end_inset
21639 </cell>
21640 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21641 \begin_inset Text
21642
21643 \layout Standard
21644
21645
21646 \family roman
21647 \series medium
21648 \shape up
21649 \size normal
21650 \emph off
21651 \bar no
21652 \noun off
21653 \color none
21654 sdcc/bin
21655 \end_inset
21656 </cell>
21657 </row>
21658 <row topline="true" bottomline="true">
21659 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21660 \begin_inset Text
21661
21662 \layout Standard
21663
21664 packihx
21665 \end_inset
21666 </cell>
21667 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21668 \begin_inset Text
21669
21670 \layout Standard
21671
21672 ihx packer
21673 \end_inset
21674 </cell>
21675 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21676 \begin_inset Text
21677
21678 \layout Standard
21679
21680
21681 \family roman
21682 \series medium
21683 \shape up
21684 \size normal
21685 \emph off
21686 \bar no
21687 \noun off
21688 \color none
21689 sdcc/bin
21690 \end_inset
21691 </cell>
21692 </row>
21693 </lyxtabular>
21694
21695 \end_inset
21696
21697
21698 \newline
21699
21700 \layout Section
21701
21702 Documentation
21703 \begin_inset LatexCommand \index{Documentation}
21704
21705 \end_inset
21706
21707  included in the distribution
21708 \layout Standard
21709 \align center
21710
21711 \begin_inset  Tabular
21712 <lyxtabular version="3" rows="10" columns="2">
21713 <features>
21714 <column alignment="left" valignment="top" leftline="true" width="0">
21715 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21716 <row topline="true" bottomline="true">
21717 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21718 \begin_inset Text
21719
21720 \layout Standard
21721
21722 Subject / Title
21723 \end_inset
21724 </cell>
21725 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21726 \begin_inset Text
21727
21728 \layout Standard
21729
21730 Where to get / filename
21731 \end_inset
21732 </cell>
21733 </row>
21734 <row topline="true">
21735 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21736 \begin_inset Text
21737
21738 \layout Standard
21739
21740 SDCC Compiler User Guide
21741 \end_inset
21742 </cell>
21743 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21744 \begin_inset Text
21745
21746 \layout Standard
21747
21748 You're reading it right now
21749 \end_inset
21750 </cell>
21751 </row>
21752 <row topline="true">
21753 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21754 \begin_inset Text
21755
21756 \layout Standard
21757
21758 Changelog of SDCC
21759 \end_inset
21760 </cell>
21761 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21762 \begin_inset Text
21763
21764 \layout Standard
21765
21766 sdcc/Changelog
21767 \end_inset
21768 </cell>
21769 </row>
21770 <row topline="true">
21771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21772 \begin_inset Text
21773
21774 \layout Standard
21775
21776 ASXXXX
21777 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
21778
21779 \end_inset
21780
21781
21782 \begin_inset LatexCommand \index{Assembler documentation}
21783
21784 \end_inset
21785
21786  Assemblers and ASLINK
21787 \begin_inset LatexCommand \index{aslink}
21788
21789 \end_inset
21790
21791
21792 \begin_inset LatexCommand \index{Linker documentation}
21793
21794 \end_inset
21795
21796  Relocating Linker
21797 \end_inset
21798 </cell>
21799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21800 \begin_inset Text
21801
21802 \layout Standard
21803
21804 sdcc/as/doc/asxhtm.html
21805 \end_inset
21806 </cell>
21807 </row>
21808 <row topline="true">
21809 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21810 \begin_inset Text
21811
21812 \layout Standard
21813
21814 SDCC regression test
21815 \begin_inset LatexCommand \index{Regression test}
21816
21817 \end_inset
21818
21819
21820 \end_inset
21821 </cell>
21822 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21823 \begin_inset Text
21824
21825 \layout Standard
21826
21827 sdcc/doc/test_suite_spec.pdf
21828 \end_inset
21829 </cell>
21830 </row>
21831 <row topline="true">
21832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21833 \begin_inset Text
21834
21835 \layout Standard
21836
21837 Various notes
21838 \end_inset
21839 </cell>
21840 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21841 \begin_inset Text
21842
21843 \layout Standard
21844
21845 sdcc/doc/*
21846 \end_inset
21847 </cell>
21848 </row>
21849 <row topline="true">
21850 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21851 \begin_inset Text
21852
21853 \layout Standard
21854
21855 Notes on debugging with sdcdb
21856 \begin_inset LatexCommand \index{sdcdb (debugger)}
21857
21858 \end_inset
21859
21860
21861 \end_inset
21862 </cell>
21863 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21864 \begin_inset Text
21865
21866 \layout Standard
21867
21868 sdcc/debugger/README
21869 \end_inset
21870 </cell>
21871 </row>
21872 <row topline="true">
21873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21874 \begin_inset Text
21875
21876 \layout Standard
21877
21878 Software simulator for microcontrollers
21879 \end_inset
21880 </cell>
21881 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21882 \begin_inset Text
21883
21884 \layout Standard
21885
21886
21887 \family roman
21888 \series medium
21889 \shape up
21890 \size normal
21891 \emph off
21892 \bar no
21893 \noun off
21894 \color none
21895 sdcc/sim/ucsim/doc
21896 \family default
21897 \series default
21898 \shape default
21899 \size default
21900 \emph default
21901 \bar default
21902 \noun default
21903 \color default
21904 /index.html
21905 \end_inset
21906 </cell>
21907 </row>
21908 <row topline="true">
21909 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21910 \begin_inset Text
21911
21912 \layout Standard
21913
21914 Temporary notes on the pic16
21915 \begin_inset LatexCommand \index{PIC16}
21916
21917 \end_inset
21918
21919  port
21920 \end_inset
21921 </cell>
21922 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21923 \begin_inset Text
21924
21925 \layout Standard
21926
21927 sdcc/src/pic16/NOTES
21928 \end_inset
21929 </cell>
21930 </row>
21931 <row topline="true" bottomline="true">
21932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21933 \begin_inset Text
21934
21935 \layout Standard
21936
21937 SDCC internal documentation (debugging file format)
21938 \end_inset
21939 </cell>
21940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21941 \begin_inset Text
21942
21943 \layout Standard
21944
21945 sdcc/doc/
21946 \family roman
21947 \series medium
21948 \shape up
21949 \size normal
21950 \emph off
21951 \bar no
21952 \noun off
21953 \color none
21954 cdbfileformat.pd
21955 \family default
21956 \series default
21957 \shape default
21958 \size default
21959 \emph default
21960 \bar default
21961 \noun default
21962 \color default
21963 f
21964 \end_inset
21965 </cell>
21966 </row>
21967 </lyxtabular>
21968
21969 \end_inset
21970
21971
21972 \newline
21973
21974 \layout Section
21975
21976 Related open source tools
21977 \begin_inset LatexCommand \index{Related tools}
21978
21979 \end_inset
21980
21981
21982 \layout Standard
21983 \align center
21984
21985 \begin_inset  Tabular
21986 <lyxtabular version="3" rows="11" columns="3">
21987 <features>
21988 <column alignment="center" valignment="top" leftline="true" width="0pt">
21989 <column alignment="block" valignment="top" leftline="true" width="30line%">
21990 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21991 <row topline="true" bottomline="true">
21992 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21993 \begin_inset Text
21994
21995 \layout Standard
21996
21997 Name
21998 \end_inset
21999 </cell>
22000 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22001 \begin_inset Text
22002
22003 \layout Standard
22004
22005 Purpose
22006 \end_inset
22007 </cell>
22008 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22009 \begin_inset Text
22010
22011 \layout Standard
22012
22013 Where to get
22014 \end_inset
22015 </cell>
22016 </row>
22017 <row topline="true">
22018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22019 \begin_inset Text
22020
22021 \layout Standard
22022
22023 gpsim
22024 \begin_inset LatexCommand \index{gpsim (pic simulator)}
22025
22026 \end_inset
22027
22028
22029 \end_inset
22030 </cell>
22031 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22032 \begin_inset Text
22033
22034 \layout Standard
22035
22036 PIC simulator
22037 \end_inset
22038 </cell>
22039 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22040 \begin_inset Text
22041
22042 \layout Standard
22043
22044
22045 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
22046
22047 \end_inset
22048
22049
22050 \end_inset
22051 </cell>
22052 </row>
22053 <row topline="true">
22054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22055 \begin_inset Text
22056
22057 \layout Standard
22058
22059 gputils
22060 \begin_inset LatexCommand \index{gputils (pic tools)}
22061
22062 \end_inset
22063
22064
22065 \end_inset
22066 </cell>
22067 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22068 \begin_inset Text
22069
22070 \layout Standard
22071
22072 GNU PIC utilities
22073 \end_inset
22074 </cell>
22075 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22076 \begin_inset Text
22077
22078 \layout Standard
22079
22080
22081 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
22082
22083 \end_inset
22084
22085
22086 \end_inset
22087 </cell>
22088 </row>
22089 <row topline="true">
22090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22091 \begin_inset Text
22092
22093 \layout Standard
22094
22095 flP5
22096 \end_inset
22097 </cell>
22098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22099 \begin_inset Text
22100
22101 \layout Standard
22102
22103 PIC programmer
22104 \end_inset
22105 </cell>
22106 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22107 \begin_inset Text
22108
22109 \layout Standard
22110
22111
22112 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
22113
22114 \end_inset
22115
22116
22117 \end_inset
22118 </cell>
22119 </row>
22120 <row topline="true">
22121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22122 \begin_inset Text
22123
22124 \layout Standard
22125
22126 indent
22127 \begin_inset LatexCommand \index{indent (source formatting tool)}
22128
22129 \end_inset
22130
22131
22132 \end_inset
22133 </cell>
22134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22135 \begin_inset Text
22136
22137 \layout Standard
22138
22139 Formats C source - Master of the white spaces
22140 \end_inset
22141 </cell>
22142 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22143 \begin_inset Text
22144
22145 \layout Standard
22146
22147
22148 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
22149
22150 \end_inset
22151
22152
22153 \end_inset
22154 </cell>
22155 </row>
22156 <row topline="true">
22157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22158 \begin_inset Text
22159
22160 \layout Standard
22161
22162 srecord
22163 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
22164
22165 \end_inset
22166
22167
22168 \end_inset
22169 </cell>
22170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22171 \begin_inset Text
22172
22173 \layout Standard
22174
22175 Object file conversion, checksumming, ...
22176 \end_inset
22177 </cell>
22178 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22179 \begin_inset Text
22180
22181 \layout Standard
22182
22183
22184 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
22185
22186 \end_inset
22187
22188
22189 \end_inset
22190 </cell>
22191 </row>
22192 <row topline="true">
22193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22194 \begin_inset Text
22195
22196 \layout Standard
22197
22198 objdump
22199 \begin_inset LatexCommand \index{objdump (tool)}
22200
22201 \end_inset
22202
22203
22204 \end_inset
22205 </cell>
22206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22207 \begin_inset Text
22208
22209 \layout Standard
22210
22211 Object file conversion, ...
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 Part of binutils (should be there anyway)
22220 \end_inset
22221 </cell>
22222 </row>
22223 <row topline="true">
22224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22225 \begin_inset Text
22226
22227 \layout Standard
22228
22229 doxygen
22230 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
22231
22232 \end_inset
22233
22234
22235 \end_inset
22236 </cell>
22237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22238 \begin_inset Text
22239
22240 \layout Standard
22241
22242 Source code documentation system
22243 \end_inset
22244 </cell>
22245 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22246 \begin_inset Text
22247
22248 \layout Standard
22249
22250
22251 \begin_inset LatexCommand \url{http://www.doxygen.org}
22252
22253 \end_inset
22254
22255
22256 \end_inset
22257 </cell>
22258 </row>
22259 <row topline="true">
22260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22261 \begin_inset Text
22262
22263 \layout Standard
22264
22265 kdevelop
22266 \end_inset
22267 </cell>
22268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22269 \begin_inset Text
22270
22271 \layout Standard
22272
22273 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
22274 \end_inset
22275 </cell>
22276 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22277 \begin_inset Text
22278
22279 \layout Standard
22280
22281
22282 \begin_inset LatexCommand \url{http://www.kdevelop.org}
22283
22284 \end_inset
22285
22286
22287 \end_inset
22288 </cell>
22289 </row>
22290 <row topline="true">
22291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22292 \begin_inset Text
22293
22294 \layout Standard
22295
22296 splint
22297 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22298
22299 \end_inset
22300
22301
22302 \end_inset
22303 </cell>
22304 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22305 \begin_inset Text
22306
22307 \layout Standard
22308
22309 Statically checks c sources (see
22310 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22311
22312 \end_inset
22313
22314 )
22315 \end_inset
22316 </cell>
22317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22318 \begin_inset Text
22319
22320 \layout Standard
22321
22322
22323 \begin_inset LatexCommand \url{http://www.splint.org}
22324
22325 \end_inset
22326
22327
22328 \end_inset
22329 </cell>
22330 </row>
22331 <row topline="true" bottomline="true">
22332 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22333 \begin_inset Text
22334
22335 \layout Standard
22336
22337 ddd
22338 \begin_inset LatexCommand \index{ddd (debugger)}
22339
22340 \end_inset
22341
22342
22343 \end_inset
22344 </cell>
22345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22346 \begin_inset Text
22347
22348 \layout Standard
22349
22350 Debugger, serves nicely as GUI to sdcdb
22351 \begin_inset LatexCommand \index{sdcdb (debugger)}
22352
22353 \end_inset
22354
22355  (Unix only)
22356 \end_inset
22357 </cell>
22358 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22359 \begin_inset Text
22360
22361 \layout Standard
22362
22363
22364 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
22365
22366 \end_inset
22367
22368
22369 \end_inset
22370 </cell>
22371 </row>
22372 </lyxtabular>
22373
22374 \end_inset
22375
22376
22377 \newline
22378
22379 \layout Section
22380
22381 Related documentation / recommended reading
22382 \layout Standard
22383 \align center
22384
22385 \begin_inset  Tabular
22386 <lyxtabular version="3" rows="6" columns="3">
22387 <features>
22388 <column alignment="center" valignment="top" leftline="true" width="0pt">
22389 <column alignment="block" valignment="top" leftline="true" width="30line%">
22390 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
22391 <row topline="true" bottomline="true">
22392 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22393 \begin_inset Text
22394
22395 \layout Standard
22396
22397 Name
22398 \end_inset
22399 </cell>
22400 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22401 \begin_inset Text
22402
22403 \layout Standard
22404
22405 Subject / Title
22406 \end_inset
22407 </cell>
22408 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22409 \begin_inset Text
22410
22411 \layout Standard
22412
22413 Where to get
22414 \end_inset
22415 </cell>
22416 </row>
22417 <row topline="true">
22418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22419 \begin_inset Text
22420
22421 \layout Standard
22422
22423
22424 \family roman
22425 \series medium
22426 \shape up
22427 \size normal
22428 \emph off
22429 \bar no
22430 \noun off
22431 \color none
22432 c-refcard.pdf
22433 \end_inset
22434 </cell>
22435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22436 \begin_inset Text
22437
22438 \layout Standard
22439
22440 C Reference Card
22441 \begin_inset LatexCommand \index{C Reference card}
22442
22443 \end_inset
22444
22445 , 2 pages
22446 \end_inset
22447 </cell>
22448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22449 \begin_inset Text
22450
22451 \layout Standard
22452
22453
22454 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
22455
22456 \end_inset
22457
22458
22459 \end_inset
22460 </cell>
22461 </row>
22462 <row topline="true">
22463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22464 \begin_inset Text
22465
22466 \layout Standard
22467
22468 c-faq
22469 \end_inset
22470 </cell>
22471 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22472 \begin_inset Text
22473
22474 \layout Standard
22475
22476 C-FAQ-list
22477 \end_inset
22478 </cell>
22479 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22480 \begin_inset Text
22481
22482 \layout Standard
22483
22484
22485 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
22486
22487 \end_inset
22488
22489
22490 \end_inset
22491 </cell>
22492 </row>
22493 <row topline="true">
22494 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22495 \begin_inset Text
22496
22497 \layout Standard
22498
22499 \end_inset
22500 </cell>
22501 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22502 \begin_inset Text
22503
22504 \layout Standard
22505
22506 Latest datasheet of the target CPU
22507 \end_inset
22508 </cell>
22509 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22510 \begin_inset Text
22511
22512 \layout Standard
22513
22514 vendor
22515 \end_inset
22516 </cell>
22517 </row>
22518 <row topline="true">
22519 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22520 \begin_inset Text
22521
22522 \layout Standard
22523
22524 \end_inset
22525 </cell>
22526 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22527 \begin_inset Text
22528
22529 \layout Standard
22530
22531 Revision history of datasheet
22532 \end_inset
22533 </cell>
22534 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22535 \begin_inset Text
22536
22537 \layout Standard
22538
22539 vendor
22540 \end_inset
22541 </cell>
22542 </row>
22543 <row topline="true" bottomline="true">
22544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22545 \begin_inset Text
22546
22547 \layout Standard
22548
22549 S.
22550  S.
22551  Muchnick
22552 \end_inset
22553 </cell>
22554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22555 \begin_inset Text
22556
22557 \layout Standard
22558
22559 Advanced Compiler Design and Implementation
22560 \end_inset
22561 </cell>
22562 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22563 \begin_inset Text
22564
22565 \layout Standard
22566
22567 bookstore (very dedicated, probably read other books first)
22568 \end_inset
22569 </cell>
22570 </row>
22571 </lyxtabular>
22572
22573 \end_inset
22574
22575
22576 \newline
22577
22578 \layout Section
22579
22580 Some Questions
22581 \layout Standard
22582
22583 Some questions answered, some pointers given - it might be time to in turn
22584  ask
22585 \emph on
22586 you
22587 \emph default
22588  some questions:
22589 \layout Itemize
22590
22591 can you solve your project with the selected microcontroller? Would you
22592  find out early or rather late that your target is too small/slow/whatever?
22593  Can you switch to a slightly better device if it doesn't fit?
22594 \layout Itemize
22595
22596 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
22597  and/or another programming language be more adequate? Would an operating
22598  system on the target device help?
22599 \layout Itemize
22600
22601 if you solved the problem, will the marketing department be happy?
22602 \layout Itemize
22603
22604 if the marketing department is happy, will customers be happy?
22605 \layout Itemize
22606
22607 if you're the project manager, marketing department and maybe even the customer
22608  in one person, have you tried to see the project from the outside?
22609 \layout Itemize
22610
22611 is the project done if you think it is done? Or is just that other interface/pro
22612 tocol/feature/configuration/option missing? How about website, manual(s),
22613  internationali(z|s)ation, packaging, labels, 2nd source for components,
22614  electromagnetic compatability/interference, documentation for production,
22615  production test software, update mechanism, patent issues?
22616 \layout Itemize
22617
22618 is your project adequately positioned in that magic triangle: fame, fortune,
22619  fun?
22620 \layout Standard
22621
22622 Maybe not all answers to these questions are known and some answers may
22623  even be
22624 \emph on
22625 no
22626 \emph default
22627 , nevertheless knowing these questions may help you to avoid burnout
22628 \begin_inset Foot
22629 collapsed false
22630
22631 \layout Standard
22632
22633 burnout is bad for electronic devices, programmers and motorcycle tyres
22634 \end_inset
22635
22636 .
22637  Chances are you didn't want to hear some of them...
22638 \layout Chapter
22639
22640 Support
22641 \begin_inset LatexCommand \index{Support}
22642
22643 \end_inset
22644
22645
22646 \layout Standard
22647
22648 SDCC has grown to be a large project.
22649  The compiler alone (without the preprocessor, assembler and linker) is
22650  well over 100,000 lines of code (blank stripped).
22651  The open source nature of this project is a key to its continued growth
22652  and support.
22653  You gain the benefit and support of many active software developers and
22654  end users.
22655  Is SDCC perfect? No, that's why we need your help.
22656  The developers take pride in fixing reported bugs.
22657  You can help by reporting the bugs and helping other SDCC users.
22658  There are lots of ways to contribute, and we encourage you to take part
22659  in making SDCC a great software package.
22660
22661 \layout Standard
22662
22663 The SDCC project is hosted on the SDCC sourceforge site at
22664 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
22665
22666 \end_inset
22667
22668 .
22669  You'll find the complete set of mailing lists
22670 \begin_inset LatexCommand \index{Mailing list(s)}
22671
22672 \end_inset
22673
22674 , forums, bug reporting system, patch submission
22675 \begin_inset LatexCommand \index{Patch submission}
22676
22677 \end_inset
22678
22679  system, download
22680 \begin_inset LatexCommand \index{download}
22681
22682 \end_inset
22683
22684  area and cvs code repository
22685 \begin_inset LatexCommand \index{cvs code repository}
22686
22687 \end_inset
22688
22689  there.
22690 \layout Section
22691
22692 Reporting Bugs
22693 \begin_inset LatexCommand \index{Bug reporting}
22694
22695 \end_inset
22696
22697
22698 \begin_inset LatexCommand \index{Reporting bugs}
22699
22700 \end_inset
22701
22702
22703 \layout Standard
22704
22705 The recommended way of reporting bugs is using the infrastructure of the
22706  sourceforge site.
22707  You can follow the status of bug reports there and have an overview about
22708  the known bugs.
22709 \layout Standard
22710
22711 Bug reports are automatically forwarded to the developer mailing list and
22712  will be fixed ASAP.
22713  When reporting a bug, it is very useful to include a small test program
22714  (the smaller the better) which reproduces the problem.
22715  If you can isolate the problem by looking at the generated assembly code,
22716  this can be very helpful.
22717  Compiling your program with the -
22718 \begin_inset ERT
22719 status Collapsed
22720
22721 \layout Standard
22722
22723 \backslash
22724 /
22725 \end_inset
22726
22727 -dumpall
22728 \begin_inset LatexCommand \index{-\/-dumpall}
22729
22730 \end_inset
22731
22732  option can sometimes be useful in locating optimization problems.
22733  When reporting a bug please maker sure you:
22734 \layout Enumerate
22735
22736 Attach the code you are compiling with SDCC.
22737
22738 \layout Enumerate
22739
22740 Specify the exact command you use to run SDCC, or attach your Makefile.
22741
22742 \layout Enumerate
22743
22744 Specify the SDCC version (type "
22745 \family sans
22746 \series bold
22747 sdcc -v
22748 \family default
22749 \series default
22750 "), your platform, and operating system.
22751
22752 \layout Enumerate
22753
22754 Provide an exact copy of any error message or incorrect output.
22755
22756 \layout Enumerate
22757
22758 Put something meaningful in the subject of your message.
22759 \layout Standard
22760
22761 Please attempt to include these 5 important parts, as applicable, in all
22762  requests for support or when reporting any problems or bugs with SDCC.
22763  Though this will make your message lengthy, it will greatly improve your
22764  chance that SDCC users and developers will be able to help you.
22765  Some SDCC developers are frustrated by bug reports without code provided
22766  that they can use to reproduce and ultimately fix the problem, so please
22767  be sure to provide sample code if you are reporting a bug!
22768 \layout Standard
22769
22770 Please have a short check that you are using a recent version of SDCC and
22771  the bug is not yet known.
22772  This is the link for reporting bugs:
22773 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
22774
22775 \end_inset
22776
22777 .
22778 \layout Section
22779
22780 Requesting Features
22781 \begin_inset LatexCommand \label{sub:Requesting-Features}
22782
22783 \end_inset
22784
22785
22786 \begin_inset LatexCommand \index{Feature request}
22787
22788 \end_inset
22789
22790
22791 \begin_inset LatexCommand \index{Requesting features}
22792
22793 \end_inset
22794
22795
22796 \layout Standard
22797
22798 Like bug reports feature requests are forwarded to the developer mailing
22799  list.
22800  This is the link for requesting features:
22801 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
22802
22803 \end_inset
22804
22805 .
22806 \layout Section
22807
22808 Submitting patches
22809 \layout Standard
22810
22811 Like bug reports contributed patches are forwarded to the developer mailing
22812  list.
22813  This is the link for submitting patches
22814 \begin_inset LatexCommand \index{Patch submission}
22815
22816 \end_inset
22817
22818 :
22819 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
22820
22821 \end_inset
22822
22823 .
22824 \layout Standard
22825
22826 You need to specify some parameters to the
22827 \family typewriter
22828 diff
22829 \family default
22830  command for the patches to be useful.
22831  If you modified more than one file a patch created f.e.
22832  with
22833 \family sans
22834 \series bold
22835
22836 \begin_inset Quotes sld
22837 \end_inset
22838
22839 diff -Naur unmodified_directory modified_directory >my_changes.patch
22840 \begin_inset Quotes srd
22841 \end_inset
22842
22843
22844 \family default
22845 \series default
22846  will be fine, otherwise
22847 \family sans
22848 \series bold
22849
22850 \begin_inset Quotes sld
22851 \end_inset
22852
22853 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
22854 \begin_inset Quotes srd
22855 \end_inset
22856
22857
22858 \series default
22859
22860 \family default
22861 will do.
22862 \layout Section
22863
22864 Getting Help
22865 \layout Standard
22866
22867 These links should take you directly to the
22868 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
22869
22870 \end_inset
22871
22872
22873 \begin_inset Foot
22874 collapsed false
22875
22876 \layout Standard
22877
22878 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
22879  automated messages (mid 2003)
22880 \end_inset
22881
22882  and the
22883 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
22884
22885 \end_inset
22886
22887 , lists
22888 \begin_inset LatexCommand \index{Mailing list(s)}
22889
22890 \end_inset
22891
22892  and forums are archived and searchable so if you are lucky someone already
22893  had a similar problem.
22894  While mails to the lists themselves are delivered promptly their web front
22895  end on sourceforge sometimes shows a severe time lag (up to several weeks),
22896  if you're seriously using SDCC please consider subscribing to the lists.
22897 \layout Section
22898
22899 ChangeLog
22900 \layout Standard
22901
22902 You can follow the status of the cvs version
22903 \begin_inset LatexCommand \index{version}
22904
22905 \end_inset
22906
22907  of SDCC by watching the Changelog
22908 \begin_inset LatexCommand \index{Changelog}
22909
22910 \end_inset
22911
22912  in the cvs-repository
22913 \newline
22914
22915 \size footnotesize
22916
22917 \begin_inset LatexCommand \htmlurl{http://cvs.sf.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
22918
22919 \end_inset
22920
22921 .
22922 \layout Section
22923
22924 Release policy
22925 \begin_inset LatexCommand \index{Release policy}
22926
22927 \end_inset
22928
22929
22930 \layout Standard
22931
22932 Historically there often were long delays between official releases and
22933  the sourceforge download area tends to get not updated at all.
22934  Excuses in the past might have referred to problems with live range analysis,
22935  but as this was fixed a while ago, the current problem is that another
22936  excuse has to be found.
22937  Kidding aside, we have to get better there! On the other hand there are
22938  daily snapshots available at
22939 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
22940
22941 \end_inset
22942
22943 , and you can always build the very last version (hopefully with many bugs
22944  fixed, and features added) from the source code available at
22945 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
22946
22947 \end_inset
22948
22949 .
22950 \layout Section
22951
22952 Examples
22953 \begin_inset LatexCommand \index{Examples}
22954
22955 \end_inset
22956
22957
22958 \layout Standard
22959
22960 You'll find some small examples in the directory
22961 \emph on
22962 sdcc/device/examples/.
22963
22964 \emph default
22965 More examples and libraries are available at
22966 \emph on
22967  The SDCC Open Knowledge Resource
22968 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
22969
22970 \end_inset
22971
22972
22973 \emph default
22974 web site or at
22975 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
22976
22977 \end_inset
22978
22979 .
22980 \layout Comment
22981
22982 I did insert a reference to Paul's web site here although it seems rather
22983  dedicated to a specific 8032 board (I think it's okay because it f.e.
22984  shows LCD/Harddisc interface and has a free 8051 monitor.
22985  Independent 8032 board vendors face hard competition of heavily subsidized
22986  development boards anyway).
22987 \layout Comment
22988
22989 Maybe we should include some links to real world applications.
22990  Preferably pointer to pointers (one for each architecture) so this stays
22991  manageable here?
22992 \layout Section
22993
22994 Quality control
22995 \begin_inset LatexCommand \index{Quality control}
22996
22997 \end_inset
22998
22999
23000 \layout Standard
23001
23002 The compiler is passed through nightly compile and build checks.
23003  The so called
23004 \shape italic
23005 regression tests
23006 \shape default
23007
23008 \begin_inset LatexCommand \index{Regression test}
23009
23010 \end_inset
23011
23012  check that SDCC itself compiles flawlessly on several platforms and checks
23013  the quality of the code generated by SDCC by running the code through simulator
23014 s.
23015  There is a separate document
23016 \shape italic
23017 test_suite.pdf
23018 \begin_inset LatexCommand \index{Test suite}
23019
23020 \end_inset
23021
23022
23023 \shape default
23024  about this.
23025 \layout Standard
23026
23027 You'll find the test code in the directory
23028 \shape italic
23029 sdcc/support/regression
23030 \shape default
23031 .
23032  You can run these tests manually by running
23033 \family sans
23034 make
23035 \family default
23036  in this directory (or f.e.
23037
23038 \family sans
23039 \series bold
23040
23041 \begin_inset Quotes sld
23042 \end_inset
23043
23044 make test-mcs51
23045 \begin_inset Quotes srd
23046 \end_inset
23047
23048
23049 \family default
23050 \series default
23051  if you don't want to run the complete tests).
23052  The test code might also be interesting if you want to look for examples
23053 \begin_inset LatexCommand \index{Examples}
23054
23055 \end_inset
23056
23057  checking corner cases of SDCC or if you plan to submit patches
23058 \begin_inset LatexCommand \index{Patch submission}
23059
23060 \end_inset
23061
23062 .
23063 \layout Standard
23064
23065 The pic port uses a different set of regression tests, you'll find them
23066  in the directory
23067 \shape italic
23068 sdcc/src/regression
23069 \shape default
23070 .
23071 \layout Chapter
23072 \pagebreak_top
23073 SDCC Technical Data
23074 \layout Section
23075
23076 Optimizations
23077 \begin_inset LatexCommand \index{Optimizations}
23078
23079 \end_inset
23080
23081
23082 \layout Standard
23083
23084 SDCC performs a host of standard optimizations in addition to some MCU specific
23085  optimizations.
23086
23087 \layout Subsection
23088
23089 Sub-expression Elimination
23090 \begin_inset LatexCommand \index{Subexpression elimination}
23091
23092 \end_inset
23093
23094
23095 \layout Standard
23096
23097 The compiler does local and
23098 \emph on
23099 g
23100 \emph default
23101 lobal
23102 \emph on
23103 c
23104 \emph default
23105 ommon
23106 \emph on
23107 s
23108 \emph default
23109 ubexpression
23110 \emph on
23111 e
23112 \emph default
23113 limination, e.g.:
23114 \layout Verse
23115
23116
23117 \family typewriter
23118 i = x + y + 1;
23119 \newline
23120 j = x + y;
23121 \layout Standard
23122
23123 will be translated to
23124 \layout Verse
23125
23126
23127 \family typewriter
23128 iTemp = x + y;
23129 \newline
23130 i = iTemp + 1;
23131 \newline
23132 j = iTemp;
23133 \layout Standard
23134
23135 Some subexpressions are not as obvious as the above example, e.g.:
23136 \layout Verse
23137
23138
23139 \family typewriter
23140 a->b[i].c = 10;
23141 \newline
23142 a->b[i].d = 11;
23143 \layout Standard
23144
23145 In this case the address arithmetic a->b[i] will be computed only once;
23146  the equivalent code in C would be.
23147 \layout Verse
23148
23149
23150 \family typewriter
23151 iTemp = a->b[i];
23152 \newline
23153 iTemp.c = 10;
23154 \newline
23155 iTemp.d = 11;
23156 \layout Standard
23157
23158 The compiler will try to keep these temporary variables in registers.
23159 \layout Subsection
23160
23161 Dead-Code Elimination
23162 \begin_inset LatexCommand \index{Dead-code elimination}
23163
23164 \end_inset
23165
23166
23167 \layout Verse
23168
23169
23170 \family typewriter
23171 int global;
23172 \newline
23173
23174 \newline
23175 void f () {
23176 \newline
23177 \SpecialChar ~
23178 \SpecialChar ~
23179 int i;
23180 \newline
23181 \SpecialChar ~
23182 \SpecialChar ~
23183 i = 1; \SpecialChar ~
23184 \SpecialChar ~
23185 \SpecialChar ~
23186 \SpecialChar ~
23187 \SpecialChar ~
23188 /* dead store */
23189 \newline
23190 \SpecialChar ~
23191 \SpecialChar ~
23192 global = 1;\SpecialChar ~
23193 /* dead store */
23194 \newline
23195 \SpecialChar ~
23196 \SpecialChar ~
23197 global = 2;
23198 \newline
23199 \SpecialChar ~
23200 \SpecialChar ~
23201 return;
23202 \newline
23203 \SpecialChar ~
23204 \SpecialChar ~
23205 global = 3;\SpecialChar ~
23206 /* unreachable */
23207 \newline
23208 }
23209 \layout Standard
23210
23211 will be changed to
23212 \layout Verse
23213
23214
23215 \family typewriter
23216 int global;
23217 \newline
23218
23219 \newline
23220 void f () {
23221 \newline
23222 \SpecialChar ~
23223 \SpecialChar ~
23224 global = 2;
23225 \newline
23226 }
23227 \layout Subsection
23228
23229 Copy-Propagation
23230 \begin_inset LatexCommand \index{Copy propagation}
23231
23232 \end_inset
23233
23234
23235 \layout Verse
23236
23237
23238 \family typewriter
23239 int f() {
23240 \newline
23241 \SpecialChar ~
23242 \SpecialChar ~
23243 int i, j;
23244 \newline
23245 \SpecialChar ~
23246 \SpecialChar ~
23247 i = 10;
23248 \newline
23249 \SpecialChar ~
23250 \SpecialChar ~
23251 j = i;
23252 \newline
23253 \SpecialChar ~
23254 \SpecialChar ~
23255 return j;
23256 \newline
23257 }
23258 \layout Standard
23259
23260 will be changed to
23261 \layout Verse
23262
23263
23264 \family typewriter
23265 int f() {
23266 \newline
23267 \SpecialChar ~
23268 \SpecialChar ~
23269 int i, j;
23270 \newline
23271 \SpecialChar ~
23272 \SpecialChar ~
23273 i = 10;
23274 \newline
23275 \SpecialChar ~
23276 \SpecialChar ~
23277 j = 10;
23278 \newline
23279 \SpecialChar ~
23280 \SpecialChar ~
23281 return 10;
23282 \newline
23283 }
23284 \layout Standard
23285
23286 Note: the dead stores created by this copy propagation will be eliminated
23287  by dead-code elimination.
23288 \layout Subsection
23289
23290 Loop Optimizations
23291 \begin_inset LatexCommand \index{Loop optimization}
23292
23293 \end_inset
23294
23295
23296 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
23297
23298 \end_inset
23299
23300
23301 \layout Standard
23302
23303 Two types of loop optimizations are done by SDCC
23304 \emph on
23305 loop invariant
23306 \emph default
23307  lifting and
23308 \emph on
23309  strength reduction
23310 \emph default
23311  of loop induction variables.
23312  In addition to the strength reduction the optimizer marks the induction
23313  variables and the register allocator tries to keep the induction variables
23314  in registers for the duration of the loop.
23315  Because of this preference of the register allocator
23316 \begin_inset LatexCommand \index{Register allocation}
23317
23318 \end_inset
23319
23320 , loop induction optimization causes an increase in register pressure, which
23321  may cause unwanted spilling of other temporary variables into the stack
23322 \begin_inset LatexCommand \index{stack}
23323
23324 \end_inset
23325
23326  / data space.
23327  The compiler will generate a warning message when it is forced to allocate
23328  extra space either on the stack or data space.
23329  If this extra space allocation is undesirable then induction optimization
23330  can be eliminated either for the entire source file (with -
23331 \begin_inset ERT
23332 status Collapsed
23333
23334 \layout Standard
23335
23336 \backslash
23337 /
23338 \end_inset
23339
23340 -noinduction option) or for a given function only using #pragma\SpecialChar ~
23341 noinduction
23342 \begin_inset LatexCommand \index{\#pragma noinduction}
23343
23344 \end_inset
23345
23346 .
23347 \newline
23348
23349 \newline
23350 Loop Invariant:
23351 \layout Verse
23352
23353
23354 \family typewriter
23355 for (i = 0 ; i < 100 ; i ++)
23356 \newline
23357 \SpecialChar ~
23358 \SpecialChar ~
23359 \SpecialChar ~
23360 \SpecialChar ~
23361 f += k + l;
23362 \layout Standard
23363
23364 changed to
23365 \layout Verse
23366
23367
23368 \family typewriter
23369 itemp = k + l;
23370 \newline
23371 for (i = 0; i < 100; i++)
23372 \newline
23373 \SpecialChar ~
23374 \SpecialChar ~
23375 \SpecialChar ~
23376 \SpecialChar ~
23377 f += itemp;
23378 \layout Standard
23379
23380 As mentioned previously some loop invariants are not as apparent, all static
23381  address computations are also moved out of the loop.
23382 \newline
23383
23384 \newline
23385 Strength Reduction
23386 \begin_inset LatexCommand \index{Strength reduction}
23387
23388 \end_inset
23389
23390 , this optimization substitutes an expression by a cheaper expression:
23391 \layout Verse
23392
23393
23394 \family typewriter
23395 for (i=0;i < 100; i++)
23396 \newline
23397 \SpecialChar ~
23398 \SpecialChar ~
23399 \SpecialChar ~
23400 \SpecialChar ~
23401 ar[i*5] = i*3;
23402 \layout Standard
23403
23404 changed to
23405 \layout Verse
23406
23407
23408 \family typewriter
23409 itemp1 = 0;
23410 \newline
23411 itemp2 = 0;
23412 \newline
23413 for (i=0;i< 100;i++) {
23414 \newline
23415 \SpecialChar ~
23416 \SpecialChar ~
23417 \SpecialChar ~
23418 \SpecialChar ~
23419 ar[itemp1] = itemp2;
23420 \newline
23421 \SpecialChar ~
23422 \SpecialChar ~
23423 \SpecialChar ~
23424 \SpecialChar ~
23425 itemp1 += 5;
23426 \newline
23427 \SpecialChar ~
23428 \SpecialChar ~
23429 \SpecialChar ~
23430 \SpecialChar ~
23431 itemp2 += 3;
23432 \newline
23433 }
23434 \layout Standard
23435
23436 The more expensive multiplication
23437 \begin_inset LatexCommand \index{Multiplication}
23438
23439 \end_inset
23440
23441  is changed to a less expensive addition.
23442 \layout Subsection
23443
23444 Loop Reversing
23445 \begin_inset LatexCommand \index{Loop reversing}
23446
23447 \end_inset
23448
23449
23450 \layout Standard
23451
23452 This optimization is done to reduce the overhead of checking loop boundaries
23453  for every iteration.
23454  Some simple loops can be reversed and implemented using a
23455 \begin_inset Quotes eld
23456 \end_inset
23457
23458 decrement and jump if not zero
23459 \begin_inset Quotes erd
23460 \end_inset
23461
23462  instruction.
23463  SDCC checks for the following criterion to determine if a loop is reversible
23464  (note: more sophisticated compilers use data-dependency analysis to make
23465  this determination, SDCC uses a more simple minded analysis).
23466 \layout Itemize
23467
23468 The 'for' loop is of the form
23469 \newline
23470
23471 \newline
23472
23473 \family typewriter
23474 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
23475  += 1])
23476 \newline
23477 \SpecialChar ~
23478 \SpecialChar ~
23479 \SpecialChar ~
23480 \SpecialChar ~
23481 <for body>
23482 \layout Itemize
23483
23484 The <for body> does not contain
23485 \begin_inset Quotes eld
23486 \end_inset
23487
23488 continue
23489 \begin_inset Quotes erd
23490 \end_inset
23491
23492  or 'break
23493 \begin_inset Quotes erd
23494 \end_inset
23495
23496 .
23497 \layout Itemize
23498
23499 All goto's are contained within the loop.
23500 \layout Itemize
23501
23502 No function calls within the loop.
23503 \layout Itemize
23504
23505 The loop control variable <sym> is not assigned any value within the loop
23506 \layout Itemize
23507
23508 The loop control variable does NOT participate in any arithmetic operation
23509  within the loop.
23510 \layout Itemize
23511
23512 There are NO switch statements in the loop.
23513 \layout Subsection
23514
23515 Algebraic Simplifications
23516 \layout Standard
23517
23518 SDCC does numerous algebraic simplifications, the following is a small sub-set
23519  of these optimizations.
23520 \layout Verse
23521
23522
23523 \family typewriter
23524 i = j + 0;\SpecialChar ~
23525 \SpecialChar ~
23526 \SpecialChar ~
23527 \SpecialChar ~
23528  /* changed to: */\SpecialChar ~
23529 \SpecialChar ~
23530 \SpecialChar ~
23531 \SpecialChar ~
23532  i = j;
23533 \newline
23534 i /= 2;\SpecialChar ~
23535 \SpecialChar ~
23536 \SpecialChar ~
23537 \SpecialChar ~
23538 \SpecialChar ~
23539 \SpecialChar ~
23540 \SpecialChar ~
23541  /* changed to: */\SpecialChar ~
23542 \SpecialChar ~
23543 \SpecialChar ~
23544 \SpecialChar ~
23545  i >>= 1;
23546 \newline
23547 i = j - j;\SpecialChar ~
23548 \SpecialChar ~
23549 \SpecialChar ~
23550 \SpecialChar ~
23551  /* changed to: */\SpecialChar ~
23552 \SpecialChar ~
23553 \SpecialChar ~
23554 \SpecialChar ~
23555  i = 0;
23556 \newline
23557 i = j / 1;\SpecialChar ~
23558 \SpecialChar ~
23559 \SpecialChar ~
23560 \SpecialChar ~
23561  /* changed to: */\SpecialChar ~
23562 \SpecialChar ~
23563 \SpecialChar ~
23564 \SpecialChar ~
23565  i = j;
23566 \layout Standard
23567
23568 Note the subexpressions
23569 \begin_inset LatexCommand \index{Subexpression}
23570
23571 \end_inset
23572
23573  given above are generally introduced by macro expansions or as a result
23574  of copy/constant propagation.
23575 \layout Subsection
23576
23577 'switch' Statements
23578 \begin_inset LatexCommand \label{sub:'switch'-Statements}
23579
23580 \end_inset
23581
23582
23583 \begin_inset LatexCommand \index{switch statement}
23584
23585 \end_inset
23586
23587
23588 \layout Standard
23589
23590 SDCC can optimize switch statements to jump tables
23591 \begin_inset LatexCommand \index{jump tables}
23592
23593 \end_inset
23594
23595 .
23596  It makes the decision based on an estimate of the generated code size.
23597  SDCC is quite liberal in the requirements for jump table generation:
23598 \layout Itemize
23599
23600 The labels need not be in order, and the starting number need not be one
23601  or zero, the case labels are in numerical sequence or not too many case
23602  labels are missing.
23603 \begin_deeper
23604 \layout Verse
23605
23606
23607 \family typewriter
23608 switch(i) {\SpecialChar ~
23609 \SpecialChar ~
23610 \SpecialChar ~
23611 \SpecialChar ~
23612 \SpecialChar ~
23613 \SpecialChar ~
23614 \SpecialChar ~
23615 \SpecialChar ~
23616 \SpecialChar ~
23617 \SpecialChar ~
23618 \SpecialChar ~
23619 \SpecialChar ~
23620 \SpecialChar ~
23621 \SpecialChar ~
23622 \SpecialChar ~
23623 \SpecialChar ~
23624 \SpecialChar ~
23625 \SpecialChar ~
23626 \SpecialChar ~
23627 \SpecialChar ~
23628 \SpecialChar ~
23629 \SpecialChar ~
23630 \SpecialChar ~
23631 \SpecialChar ~
23632 \SpecialChar ~
23633 \SpecialChar ~
23634 switch (i) {
23635 \newline
23636 \SpecialChar ~
23637 \SpecialChar ~
23638 \SpecialChar ~
23639 case 4: ...\SpecialChar ~
23640 \SpecialChar ~
23641 \SpecialChar ~
23642 \SpecialChar ~
23643 \SpecialChar ~
23644 \SpecialChar ~
23645 \SpecialChar ~
23646 \SpecialChar ~
23647 \SpecialChar ~
23648 \SpecialChar ~
23649 \SpecialChar ~
23650 \SpecialChar ~
23651 \SpecialChar ~
23652 \SpecialChar ~
23653 \SpecialChar ~
23654 \SpecialChar ~
23655 \SpecialChar ~
23656 \SpecialChar ~
23657 \SpecialChar ~
23658 \SpecialChar ~
23659 \SpecialChar ~
23660 \SpecialChar ~
23661 \SpecialChar ~
23662 \SpecialChar ~
23663 \SpecialChar ~
23664 \SpecialChar ~
23665 case 0: ...
23666
23667 \newline
23668 \SpecialChar ~
23669 \SpecialChar ~
23670 \SpecialChar ~
23671 case 5: ...\SpecialChar ~
23672 \SpecialChar ~
23673 \SpecialChar ~
23674 \SpecialChar ~
23675 \SpecialChar ~
23676 \SpecialChar ~
23677 \SpecialChar ~
23678 \SpecialChar ~
23679 \SpecialChar ~
23680 \SpecialChar ~
23681 \SpecialChar ~
23682 \SpecialChar ~
23683 \SpecialChar ~
23684 \SpecialChar ~
23685 \SpecialChar ~
23686 \SpecialChar ~
23687 \SpecialChar ~
23688 \SpecialChar ~
23689 \SpecialChar ~
23690 \SpecialChar ~
23691 \SpecialChar ~
23692 \SpecialChar ~
23693 \SpecialChar ~
23694 \SpecialChar ~
23695 \SpecialChar ~
23696 \SpecialChar ~
23697 case 1: ...
23698
23699 \newline
23700 \SpecialChar ~
23701 \SpecialChar ~
23702 \SpecialChar ~
23703 case 3: ...\SpecialChar ~
23704 \SpecialChar ~
23705 \SpecialChar ~
23706 \SpecialChar ~
23707 \SpecialChar ~
23708 \SpecialChar ~
23709 \SpecialChar ~
23710 \SpecialChar ~
23711 \SpecialChar ~
23712 \SpecialChar ~
23713 \SpecialChar ~
23714 \SpecialChar ~
23715 \SpecialChar ~
23716 \SpecialChar ~
23717 \SpecialChar ~
23718 \SpecialChar ~
23719 \SpecialChar ~
23720 \SpecialChar ~
23721 \SpecialChar ~
23722 \SpecialChar ~
23723 \SpecialChar ~
23724 \SpecialChar ~
23725 \SpecialChar ~
23726 \SpecialChar ~
23727 \SpecialChar ~
23728 \SpecialChar ~
23729
23730 \newline
23731 \SpecialChar ~
23732 \SpecialChar ~
23733 \SpecialChar ~
23734 case 6: ...\SpecialChar ~
23735 \SpecialChar ~
23736 \SpecialChar ~
23737 \SpecialChar ~
23738 \SpecialChar ~
23739 \SpecialChar ~
23740 \SpecialChar ~
23741 \SpecialChar ~
23742 \SpecialChar ~
23743 \SpecialChar ~
23744 \SpecialChar ~
23745 \SpecialChar ~
23746 \SpecialChar ~
23747 \SpecialChar ~
23748 \SpecialChar ~
23749 \SpecialChar ~
23750 \SpecialChar ~
23751 \SpecialChar ~
23752 \SpecialChar ~
23753 \SpecialChar ~
23754 \SpecialChar ~
23755 \SpecialChar ~
23756 \SpecialChar ~
23757 \SpecialChar ~
23758 \SpecialChar ~
23759 \SpecialChar ~
23760 case 3: ...
23761
23762 \newline
23763 \SpecialChar ~
23764 \SpecialChar ~
23765 \SpecialChar ~
23766 case 7: ...\SpecialChar ~
23767 \SpecialChar ~
23768 \SpecialChar ~
23769 \SpecialChar ~
23770 \SpecialChar ~
23771 \SpecialChar ~
23772 \SpecialChar ~
23773 \SpecialChar ~
23774 \SpecialChar ~
23775 \SpecialChar ~
23776 \SpecialChar ~
23777 \SpecialChar ~
23778 \SpecialChar ~
23779 \SpecialChar ~
23780 \SpecialChar ~
23781 \SpecialChar ~
23782 \SpecialChar ~
23783 \SpecialChar ~
23784 \SpecialChar ~
23785 \SpecialChar ~
23786 \SpecialChar ~
23787 \SpecialChar ~
23788 \SpecialChar ~
23789 \SpecialChar ~
23790 \SpecialChar ~
23791 \SpecialChar ~
23792 case 4: ...
23793
23794 \newline
23795 \SpecialChar ~
23796 \SpecialChar ~
23797 \SpecialChar ~
23798 case 8: ...\SpecialChar ~
23799 \SpecialChar ~
23800 \SpecialChar ~
23801 \SpecialChar ~
23802 \SpecialChar ~
23803 \SpecialChar ~
23804 \SpecialChar ~
23805 \SpecialChar ~
23806 \SpecialChar ~
23807 \SpecialChar ~
23808 \SpecialChar ~
23809 \SpecialChar ~
23810 \SpecialChar ~
23811 \SpecialChar ~
23812 \SpecialChar ~
23813 \SpecialChar ~
23814 \SpecialChar ~
23815 \SpecialChar ~
23816 \SpecialChar ~
23817 \SpecialChar ~
23818 \SpecialChar ~
23819 \SpecialChar ~
23820 \SpecialChar ~
23821 \SpecialChar ~
23822 \SpecialChar ~
23823 \SpecialChar ~
23824 case 5: ...
23825
23826 \newline
23827 \SpecialChar ~
23828 \SpecialChar ~
23829 \SpecialChar ~
23830 case 9: ...\SpecialChar ~
23831 \SpecialChar ~
23832 \SpecialChar ~
23833 \SpecialChar ~
23834 \SpecialChar ~
23835 \SpecialChar ~
23836 \SpecialChar ~
23837 \SpecialChar ~
23838 \SpecialChar ~
23839 \SpecialChar ~
23840 \SpecialChar ~
23841 \SpecialChar ~
23842 \SpecialChar ~
23843 \SpecialChar ~
23844 \SpecialChar ~
23845 \SpecialChar ~
23846 \SpecialChar ~
23847 \SpecialChar ~
23848 \SpecialChar ~
23849 \SpecialChar ~
23850 \SpecialChar ~
23851 \SpecialChar ~
23852 \SpecialChar ~
23853 \SpecialChar ~
23854 \SpecialChar ~
23855 \SpecialChar ~
23856 case 6: ...
23857
23858 \newline
23859 \SpecialChar ~
23860 \SpecialChar ~
23861 \SpecialChar ~
23862 case 10: ...\SpecialChar ~
23863 \SpecialChar ~
23864 \SpecialChar ~
23865 \SpecialChar ~
23866 \SpecialChar ~
23867 \SpecialChar ~
23868 \SpecialChar ~
23869 \SpecialChar ~
23870 \SpecialChar ~
23871 \SpecialChar ~
23872 \SpecialChar ~
23873 \SpecialChar ~
23874 \SpecialChar ~
23875 \SpecialChar ~
23876 \SpecialChar ~
23877 \SpecialChar ~
23878 \SpecialChar ~
23879 \SpecialChar ~
23880 \SpecialChar ~
23881 \SpecialChar ~
23882 \SpecialChar ~
23883 \SpecialChar ~
23884 \SpecialChar ~
23885 \SpecialChar ~
23886 \SpecialChar ~
23887 case 7: ...
23888
23889 \newline
23890 \SpecialChar ~
23891 \SpecialChar ~
23892 \SpecialChar ~
23893 case 11: ...\SpecialChar ~
23894 \SpecialChar ~
23895 \SpecialChar ~
23896 \SpecialChar ~
23897 \SpecialChar ~
23898 \SpecialChar ~
23899 \SpecialChar ~
23900 \SpecialChar ~
23901 \SpecialChar ~
23902 \SpecialChar ~
23903 \SpecialChar ~
23904 \SpecialChar ~
23905 \SpecialChar ~
23906 \SpecialChar ~
23907 \SpecialChar ~
23908 \SpecialChar ~
23909 \SpecialChar ~
23910 \SpecialChar ~
23911 \SpecialChar ~
23912 \SpecialChar ~
23913 \SpecialChar ~
23914 \SpecialChar ~
23915 \SpecialChar ~
23916 \SpecialChar ~
23917 \SpecialChar ~
23918 case 8: ...
23919
23920 \newline
23921 }\SpecialChar ~
23922 \SpecialChar ~
23923 \SpecialChar ~
23924 \SpecialChar ~
23925 \SpecialChar ~
23926 \SpecialChar ~
23927 \SpecialChar ~
23928 \SpecialChar ~
23929 \SpecialChar ~
23930 \SpecialChar ~
23931 \SpecialChar ~
23932 \SpecialChar ~
23933 \SpecialChar ~
23934 \SpecialChar ~
23935 \SpecialChar ~
23936 \SpecialChar ~
23937 \SpecialChar ~
23938 \SpecialChar ~
23939 \SpecialChar ~
23940 \SpecialChar ~
23941 \SpecialChar ~
23942 \SpecialChar ~
23943 \SpecialChar ~
23944 \SpecialChar ~
23945 \SpecialChar ~
23946 \SpecialChar ~
23947 \SpecialChar ~
23948 \SpecialChar ~
23949 \SpecialChar ~
23950 \SpecialChar ~
23951 \SpecialChar ~
23952 \SpecialChar ~
23953 \SpecialChar ~
23954 \SpecialChar ~
23955 \SpecialChar ~
23956 \SpecialChar ~
23957 }
23958 \layout Standard
23959
23960 Both the above switch statements will be implemented using a jump-table.
23961  The example to the right side is slightly more efficient as the check for
23962  the lower boundary of the jump-table is not needed.
23963 \end_deeper
23964 \layout Itemize
23965
23966 The number of case labels is not larger than supported by the target architectur
23967 e.
23968 \layout Itemize
23969
23970 If the case labels are not in numerical sequence ('gaps' between cases)
23971  SDCC checks whether a jump table with additionally inserted dummy cases
23972  is still attractive.
23973
23974 \layout Itemize
23975
23976 If the starting number is not zero and a check for the lower boundary of
23977  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
23978  ...
23979  .
23980 \layout Standard
23981
23982 Switch statements which have large gaps in the numeric sequence or those
23983  that have too many case labels can be split into more than one switch statement
23984  for efficient code generation, e.g.:
23985 \layout Verse
23986
23987
23988 \family typewriter
23989 switch (i) {
23990 \newline
23991 \SpecialChar ~
23992 \SpecialChar ~
23993 case 1: ...
23994
23995 \newline
23996 \SpecialChar ~
23997 \SpecialChar ~
23998 case 2: ...
23999
24000 \newline
24001 \SpecialChar ~
24002 \SpecialChar ~
24003 case 3: ...
24004
24005 \newline
24006 \SpecialChar ~
24007 \SpecialChar ~
24008 case 4: ...
24009
24010 \newline
24011 \SpecialChar ~
24012 \SpecialChar ~
24013 case 5: ...
24014
24015 \newline
24016 \SpecialChar ~
24017 \SpecialChar ~
24018 case 6: ...
24019
24020 \newline
24021 \SpecialChar ~
24022 \SpecialChar ~
24023 case 7: ...
24024
24025 \newline
24026 \SpecialChar ~
24027 \SpecialChar ~
24028 case 101: ...
24029
24030 \newline
24031 \SpecialChar ~
24032 \SpecialChar ~
24033 case 102: ...
24034
24035 \newline
24036 \SpecialChar ~
24037 \SpecialChar ~
24038 case 103: ...
24039
24040 \newline
24041 \SpecialChar ~
24042 \SpecialChar ~
24043 case 104: ...
24044
24045 \newline
24046 \SpecialChar ~
24047 \SpecialChar ~
24048 case 105: ...
24049
24050 \newline
24051 \SpecialChar ~
24052 \SpecialChar ~
24053 case 106: ...
24054
24055 \newline
24056 \SpecialChar ~
24057 \SpecialChar ~
24058 case 107: ...
24059
24060 \newline
24061 }
24062 \layout Standard
24063
24064 If the above switch statement is broken down into two switch statements
24065 \layout Verse
24066
24067
24068 \family typewriter
24069 switch (i) {
24070 \newline
24071 \SpecialChar ~
24072 \SpecialChar ~
24073 case 1: ...
24074
24075 \newline
24076 \SpecialChar ~
24077 \SpecialChar ~
24078 case 2: ...
24079
24080 \newline
24081 \SpecialChar ~
24082 \SpecialChar ~
24083 case 3: ...
24084
24085 \newline
24086 \SpecialChar ~
24087 \SpecialChar ~
24088 case 4: ...
24089
24090 \newline
24091 \SpecialChar ~
24092 \SpecialChar ~
24093 case 5: ...
24094
24095 \newline
24096 \SpecialChar ~
24097 \SpecialChar ~
24098 case 6: ...
24099
24100 \newline
24101 \SpecialChar ~
24102 \SpecialChar ~
24103 case 7: ...
24104
24105 \newline
24106 }
24107 \layout Standard
24108
24109 and
24110 \layout Verse
24111
24112
24113 \family typewriter
24114 switch (i) {
24115 \newline
24116 \SpecialChar ~
24117 \SpecialChar ~
24118 case 101: ...
24119
24120 \newline
24121 \SpecialChar ~
24122 \SpecialChar ~
24123 case 102: ...
24124
24125 \newline
24126 \SpecialChar ~
24127 \SpecialChar ~
24128 case 103: ...
24129
24130 \newline
24131 \SpecialChar ~
24132 \SpecialChar ~
24133 case 104: ...
24134
24135 \newline
24136 \SpecialChar ~
24137 \SpecialChar ~
24138 case 105: ...
24139
24140 \newline
24141 \SpecialChar ~
24142 \SpecialChar ~
24143 case 106: ...
24144
24145 \newline
24146 \SpecialChar ~
24147 \SpecialChar ~
24148 case 107: ...
24149
24150 \newline
24151 }
24152 \layout Standard
24153
24154 then both the switch statements will be implemented using jump-tables whereas
24155  the unmodified switch statement will not be.
24156 \layout Comment
24157
24158 There might be reasons which SDCC cannot know about to either favour or
24159  not favour jump tables.
24160  If the target system has to be as quick for the last switch case as for
24161  the first (pro jump table), or if the switch argument is known to be zero
24162  in the majority of the cases (contra jump table).
24163 \layout Standard
24164
24165 The pragma nojtbound
24166 \begin_inset LatexCommand \index{\#pragma nojtbound}
24167
24168 \end_inset
24169
24170  can be used to turn off checking the
24171 \emph on
24172 j
24173 \emph default
24174 ump
24175 \emph on
24176 t
24177 \emph default
24178 able
24179 \emph on
24180 bound
24181 \emph default
24182 aries.
24183  It has no effect if a default label is supplied.
24184  Use of this pragma is dangerous: if the switch
24185 \begin_inset LatexCommand \index{switch statement}
24186
24187 \end_inset
24188
24189  argument is not matched by a case statement the processor will happily
24190  jump into Nirvana.
24191 \layout Subsection
24192
24193 Bit-shifting Operations
24194 \begin_inset LatexCommand \index{Bit shifting}
24195
24196 \end_inset
24197
24198 .
24199 \layout Standard
24200
24201 Bit shifting is one of the most frequently used operation in embedded programmin
24202 g.
24203  SDCC tries to implement bit-shift operations in the most efficient way
24204  possible, e.g.:
24205 \layout Verse
24206
24207
24208 \family typewriter
24209 unsigned char i;
24210 \newline
24211 ...
24212
24213 \newline
24214 i >>= 4;
24215 \newline
24216 ...
24217 \layout Standard
24218
24219 generates the following code:
24220 \layout Verse
24221
24222
24223 \family typewriter
24224 mov\SpecialChar ~
24225  a,_i
24226 \newline
24227 swap a
24228 \newline
24229 anl\SpecialChar ~
24230  a,#0x0f
24231 \newline
24232 mov\SpecialChar ~
24233  _i,a
24234 \layout Standard
24235
24236 In general SDCC will never setup a loop if the shift count is known.
24237  Another example:
24238 \layout Verse
24239
24240
24241 \family typewriter
24242 unsigned int i;
24243 \newline
24244 ...
24245
24246 \newline
24247 i >>= 9;
24248 \newline
24249 ...
24250 \layout Standard
24251
24252 will generate:
24253 \layout Verse
24254
24255
24256 \family typewriter
24257 mov\SpecialChar ~
24258 \SpecialChar ~
24259 a,(_i + 1)
24260 \newline
24261 mov\SpecialChar ~
24262 \SpecialChar ~
24263 (_i + 1),#0x00
24264 \newline
24265 clr\SpecialChar ~
24266 \SpecialChar ~
24267 c
24268 \newline
24269 rrc\SpecialChar ~
24270 \SpecialChar ~
24271 a
24272 \newline
24273 mov\SpecialChar ~
24274 \SpecialChar ~
24275 _i,a
24276 \layout Subsection
24277
24278 Bit-rotation
24279 \begin_inset LatexCommand \index{Bit rotation}
24280
24281 \end_inset
24282
24283
24284 \layout Standard
24285
24286 A special case of the bit-shift operation is bit rotation
24287 \begin_inset LatexCommand \index{rotating bits}
24288
24289 \end_inset
24290
24291 , SDCC recognizes the following expression to be a left bit-rotation:
24292 \layout Verse
24293
24294
24295 \family typewriter
24296 \series bold
24297 unsigned
24298 \series default
24299 \SpecialChar ~
24300 \SpecialChar ~
24301 char i;\SpecialChar ~
24302 \SpecialChar ~
24303 \SpecialChar ~
24304 \SpecialChar ~
24305 \SpecialChar ~
24306 \SpecialChar ~
24307 \SpecialChar ~
24308 \SpecialChar ~
24309 \SpecialChar ~
24310 \SpecialChar ~
24311 \SpecialChar ~
24312 /* unsigned is needed for rotation */
24313 \newline
24314 ...
24315
24316 \newline
24317 i = ((i << 1) | (i >> 7));
24318 \family default
24319
24320 \newline
24321
24322 \family typewriter
24323 ...
24324 \layout Standard
24325
24326 will generate the following code:
24327 \layout Verse
24328
24329
24330 \family typewriter
24331 mov\SpecialChar ~
24332 \SpecialChar ~
24333 a,_i
24334 \newline
24335 rl\SpecialChar ~
24336 \SpecialChar ~
24337 \SpecialChar ~
24338 a
24339 \newline
24340 mov\SpecialChar ~
24341 \SpecialChar ~
24342 _i,a
24343 \layout Standard
24344
24345 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
24346 ns of this case will also be recognized as bit-rotation, i.e.:
24347 \layout Verse
24348
24349
24350 \family typewriter
24351 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
24352 \layout Subsection
24353
24354 Nibble and Byte Swapping
24355 \layout Standard
24356
24357 Other special cases of the bit-shift operations are nibble or byte swapping
24358 \begin_inset LatexCommand \index{swapping nibbles/bytes}
24359
24360 \end_inset
24361
24362 , SDCC recognizes the following expressions:
24363 \layout Verse
24364
24365
24366 \family typewriter
24367 \series bold
24368 unsigned
24369 \series default
24370 \SpecialChar ~
24371 \SpecialChar ~
24372 char i;
24373 \newline
24374
24375 \series bold
24376 unsigned
24377 \series default
24378 \SpecialChar ~
24379 \SpecialChar ~
24380 int j;
24381 \newline
24382 ...
24383
24384 \newline
24385 i = ((i << 4) | (i >> 4));
24386 \family default
24387
24388 \newline
24389
24390 \family typewriter
24391 j = ((j << 8) | (j >> 8));
24392 \layout Standard
24393
24394 and generates a swap instruction for the nibble swapping
24395 \begin_inset LatexCommand \index{Nibble swapping}
24396
24397 \end_inset
24398
24399  or move instructions for the byte swapping
24400 \begin_inset LatexCommand \index{Byte swapping}
24401
24402 \end_inset
24403
24404 .
24405  The
24406 \begin_inset Quotes sld
24407 \end_inset
24408
24409 j
24410 \begin_inset Quotes srd
24411 \end_inset
24412
24413  example can be used to convert from little to big-endian or vice versa.
24414  If you want to change the endianness of a
24415 \emph on
24416 signed
24417 \emph default
24418  integer you have to cast to
24419 \family typewriter
24420 (unsigned int)
24421 \family default
24422  first.
24423 \layout Standard
24424
24425 Note that SDCC stores numbers in little-endian
24426 \begin_inset Foot
24427 collapsed false
24428
24429 \layout Standard
24430
24431 Usually 8-bit processors don't care much about endianness.
24432  This is not the case for the standard 8051 which only has an instruction
24433  to increment its
24434 \emph on
24435 dptr
24436 \emph default
24437
24438 \begin_inset LatexCommand \index{DPTR}
24439
24440 \end_inset
24441
24442 -datapointer
24443 \emph on
24444
24445 \emph default
24446 so little-endian is the more efficient byte order.
24447 \end_inset
24448
24449
24450 \begin_inset LatexCommand \index{little-endian}
24451
24452 \end_inset
24453
24454
24455 \begin_inset LatexCommand \index{Endianness}
24456
24457 \end_inset
24458
24459  format (i.e.
24460  lowest order first).
24461 \layout Subsection
24462
24463 Highest Order Bit
24464 \begin_inset LatexCommand \index{Highest Order Bit}
24465
24466 \end_inset
24467
24468
24469 \layout Standard
24470
24471 It is frequently required to obtain the highest order bit of an integral
24472  type (long, int, short or char types).
24473  SDCC recognizes the following expression to yield the highest order bit
24474  and generates optimized code for it, e.g.:
24475 \layout Verse
24476
24477
24478 \family typewriter
24479 unsigned int gint;
24480 \newline
24481
24482 \newline
24483 foo () {
24484 \newline
24485 \SpecialChar ~
24486 \SpecialChar ~
24487 unsigned char hob;
24488 \newline
24489 \SpecialChar ~
24490 \SpecialChar ~
24491 ...
24492
24493 \newline
24494 \SpecialChar ~
24495 \SpecialChar ~
24496 hob = (gint >> 15) & 1;
24497 \newline
24498 \SpecialChar ~
24499 \SpecialChar ~
24500 ..
24501
24502 \newline
24503 }
24504 \layout Standard
24505
24506 will generate the following code:
24507 \layout Verse
24508
24509
24510 \family typewriter
24511 \SpecialChar ~
24512 \SpecialChar ~
24513 \SpecialChar ~
24514 \SpecialChar ~
24515 \SpecialChar ~
24516 \SpecialChar ~
24517 \SpecialChar ~
24518 \SpecialChar ~
24519 \SpecialChar ~
24520 \SpecialChar ~
24521 \SpecialChar ~
24522 \SpecialChar ~
24523 \SpecialChar ~
24524 \SpecialChar ~
24525 \SpecialChar ~
24526 \SpecialChar ~
24527 \SpecialChar ~
24528 \SpecialChar ~
24529 \SpecialChar ~
24530 \SpecialChar ~
24531 \SpecialChar ~
24532 \SpecialChar ~
24533 \SpecialChar ~
24534 \SpecialChar ~
24535 \SpecialChar ~
24536  61 ;\SpecialChar ~
24537  hob.c 7
24538 \newline
24539 000A E5*01\SpecialChar ~
24540 \SpecialChar ~
24541 \SpecialChar ~
24542 \SpecialChar ~
24543 \SpecialChar ~
24544 \SpecialChar ~
24545 \SpecialChar ~
24546 \SpecialChar ~
24547 \SpecialChar ~
24548 \SpecialChar ~
24549 \SpecialChar ~
24550 \SpecialChar ~
24551 \SpecialChar ~
24552 \SpecialChar ~
24553 \SpecialChar ~
24554  62\SpecialChar ~
24555 \SpecialChar ~
24556 \SpecialChar ~
24557 \SpecialChar ~
24558 \SpecialChar ~
24559 \SpecialChar ~
24560 \SpecialChar ~
24561 \SpecialChar ~
24562  mov\SpecialChar ~
24563 \SpecialChar ~
24564  a,(_gint + 1)
24565 \newline
24566 000C 23\SpecialChar ~
24567 \SpecialChar ~
24568 \SpecialChar ~
24569 \SpecialChar ~
24570 \SpecialChar ~
24571 \SpecialChar ~
24572 \SpecialChar ~
24573 \SpecialChar ~
24574 \SpecialChar ~
24575 \SpecialChar ~
24576 \SpecialChar ~
24577 \SpecialChar ~
24578 \SpecialChar ~
24579 \SpecialChar ~
24580 \SpecialChar ~
24581 \SpecialChar ~
24582 \SpecialChar ~
24583 \SpecialChar ~
24584  63\SpecialChar ~
24585 \SpecialChar ~
24586 \SpecialChar ~
24587 \SpecialChar ~
24588 \SpecialChar ~
24589 \SpecialChar ~
24590 \SpecialChar ~
24591 \SpecialChar ~
24592  rl\SpecialChar ~
24593 \SpecialChar ~
24594 \SpecialChar ~
24595  a
24596 \newline
24597 000D 54 01\SpecialChar ~
24598 \SpecialChar ~
24599 \SpecialChar ~
24600 \SpecialChar ~
24601 \SpecialChar ~
24602 \SpecialChar ~
24603 \SpecialChar ~
24604 \SpecialChar ~
24605 \SpecialChar ~
24606 \SpecialChar ~
24607 \SpecialChar ~
24608 \SpecialChar ~
24609 \SpecialChar ~
24610 \SpecialChar ~
24611 \SpecialChar ~
24612  64\SpecialChar ~
24613 \SpecialChar ~
24614 \SpecialChar ~
24615 \SpecialChar ~
24616 \SpecialChar ~
24617 \SpecialChar ~
24618 \SpecialChar ~
24619 \SpecialChar ~
24620  anl\SpecialChar ~
24621 \SpecialChar ~
24622  a,#0x01
24623 \newline
24624 000F F5*02\SpecialChar ~
24625 \SpecialChar ~
24626 \SpecialChar ~
24627 \SpecialChar ~
24628 \SpecialChar ~
24629 \SpecialChar ~
24630 \SpecialChar ~
24631 \SpecialChar ~
24632 \SpecialChar ~
24633 \SpecialChar ~
24634 \SpecialChar ~
24635 \SpecialChar ~
24636 \SpecialChar ~
24637 \SpecialChar ~
24638 \SpecialChar ~
24639  65\SpecialChar ~
24640 \SpecialChar ~
24641 \SpecialChar ~
24642 \SpecialChar ~
24643 \SpecialChar ~
24644 \SpecialChar ~
24645 \SpecialChar ~
24646 \SpecialChar ~
24647  mov\SpecialChar ~
24648 \SpecialChar ~
24649  _foo_hob_1_1,a
24650 \layout Standard
24651
24652 Variations of this case however will
24653 \emph on
24654 not
24655 \emph default
24656  be recognized.
24657  It is a standard C expression, so I heartily recommend this be the only
24658  way to get the highest order bit, (it is portable).
24659  Of course it will be recognized even if it is embedded in other expressions,
24660  e.g.:
24661 \layout Verse
24662
24663
24664 \family typewriter
24665 xyz = gint + ((gint >> 15) & 1);
24666 \layout Standard
24667
24668 will still be recognized.
24669 \layout Subsection
24670
24671 Peephole Optimizer
24672 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
24673
24674 \end_inset
24675
24676
24677 \begin_inset LatexCommand \index{Peephole optimizer}
24678
24679 \end_inset
24680
24681
24682 \layout Standard
24683
24684 The compiler uses a rule based, pattern matching and re-writing mechanism
24685  for peep-hole optimization.
24686  It is inspired by
24687 \emph on
24688 copt
24689 \emph default
24690  a peep-hole optimizer by Christopher W.
24691  Fraser (cwfraser\SpecialChar ~
24692 @\SpecialChar ~
24693 microsoft.com).
24694  A default set of rules are compiled into the compiler, additional rules
24695  may be added with the
24696 \emph on
24697 -
24698 \begin_inset ERT
24699 status Collapsed
24700
24701 \layout Standard
24702
24703 \backslash
24704 /
24705 \end_inset
24706
24707 -peep-file
24708 \begin_inset LatexCommand \index{-\/-peep-file}
24709
24710 \end_inset
24711
24712  <filename>
24713 \emph default
24714  option.
24715  The rule language is best illustrated with examples.
24716 \layout Verse
24717
24718
24719 \family typewriter
24720 replace {
24721 \newline
24722 \SpecialChar ~
24723 \SpecialChar ~
24724 mov %1,a
24725 \newline
24726 \SpecialChar ~
24727 \SpecialChar ~
24728 mov a,%1
24729 \newline
24730 } by {
24731 \newline
24732 \SpecialChar ~
24733 \SpecialChar ~
24734 mov %1,a
24735 \newline
24736 }
24737 \layout Standard
24738
24739 The above rule will change the following assembly
24740 \begin_inset LatexCommand \index{Assembler routines}
24741
24742 \end_inset
24743
24744  sequence:
24745 \layout Verse
24746
24747
24748 \family typewriter
24749 mov r1,a
24750 \newline
24751 mov a,r1
24752 \layout Standard
24753
24754 to
24755 \layout Verse
24756
24757
24758 \family typewriter
24759 mov r1,a
24760 \layout Standard
24761
24762 Note: All occurrences of a
24763 \emph on
24764 %n
24765 \emph default
24766  (pattern variable) must denote the same string.
24767  With the above rule, the assembly sequence:
24768 \layout Verse
24769
24770
24771 \family typewriter
24772 mov r1,a
24773 \newline
24774 mov a,r2
24775 \layout Standard
24776
24777 will remain unmodified.
24778 \newline
24779
24780 \newline
24781 Other special case optimizations may be added by the user (via
24782 \emph on
24783 -
24784 \begin_inset ERT
24785 status Collapsed
24786
24787 \layout Standard
24788
24789 \backslash
24790 /
24791 \end_inset
24792
24793 -peep-file option
24794 \emph default
24795 ).
24796  E.g.
24797  some variants of the 8051 MCU
24798 \begin_inset LatexCommand \index{MCS51 variants}
24799
24800 \end_inset
24801
24802  allow only
24803 \family typewriter
24804 ajmp
24805 \family default
24806  and
24807 \family typewriter
24808 acall
24809 \family default
24810 .
24811  The following two rules will change all
24812 \family typewriter
24813 ljmp
24814 \family default
24815  and
24816 \family typewriter
24817 lcall
24818 \family default
24819  to
24820 \family typewriter
24821 ajmp
24822 \family default
24823  and
24824 \family typewriter
24825 acall
24826 \layout Verse
24827
24828
24829 \family typewriter
24830 replace { lcall %1 } by { acall %1 }
24831 \newline
24832 replace { ljmp %1 } by { ajmp %1 }
24833 \layout Standard
24834
24835 The
24836 \emph on
24837 inline-assembler code
24838 \emph default
24839  is also passed through the peep hole optimizer, thus the peephole optimizer
24840  can also be used as an assembly level macro expander.
24841  The rules themselves are MCU dependent whereas the rule language infra-structur
24842 e is MCU independent.
24843  Peephole optimization rules for other MCU can be easily programmed using
24844  the rule language.
24845 \newline
24846
24847 \newline
24848 The syntax for a rule is as follows:
24849 \layout Verse
24850
24851
24852 \family typewriter
24853 rule := replace [ restart ] '{' <assembly sequence> '
24854 \backslash
24855 n'
24856 \newline
24857 \SpecialChar ~
24858  \SpecialChar ~
24859  \SpecialChar ~
24860  \SpecialChar ~
24861  \SpecialChar ~
24862  \SpecialChar ~
24863  \SpecialChar ~
24864  \SpecialChar ~
24865  \SpecialChar ~
24866  \SpecialChar ~
24867  \SpecialChar ~
24868  \SpecialChar ~
24869  \SpecialChar ~
24870  \SpecialChar ~
24871  '}' by '{' '
24872 \backslash
24873 n'
24874 \newline
24875 \SpecialChar ~
24876  \SpecialChar ~
24877  \SpecialChar ~
24878  \SpecialChar ~
24879  \SpecialChar ~
24880  \SpecialChar ~
24881  \SpecialChar ~
24882  \SpecialChar ~
24883  \SpecialChar ~
24884  \SpecialChar ~
24885  \SpecialChar ~
24886  \SpecialChar ~
24887  \SpecialChar ~
24888  \SpecialChar ~
24889  \SpecialChar ~
24890  \SpecialChar ~
24891  <assembly sequence> '
24892 \backslash
24893 n'
24894 \newline
24895 \SpecialChar ~
24896  \SpecialChar ~
24897  \SpecialChar ~
24898  \SpecialChar ~
24899  \SpecialChar ~
24900  \SpecialChar ~
24901  \SpecialChar ~
24902  \SpecialChar ~
24903  \SpecialChar ~
24904  \SpecialChar ~
24905  \SpecialChar ~
24906  \SpecialChar ~
24907  \SpecialChar ~
24908  \SpecialChar ~
24909  '}' [if <functionName> ] '
24910 \backslash
24911 n'
24912 \layout Standard
24913
24914 <assembly sequence> := assembly instruction (each instruction including
24915  labels must be on a separate line).
24916 \newline
24917
24918 \newline
24919 The optimizer will apply to the rules one by one from the top in the sequence
24920  of their appearance, it will terminate when all rules are exhausted.
24921  If the 'restart' option is specified, then the optimizer will start matching
24922  the rules again from the top, this option for a rule is expensive (performance)
24923 , it is intended to be used in situations where a transformation will trigger
24924  the same rule again.
24925  An example of this (not a good one, it has side effects) is the following
24926  rule:
24927 \layout Verse
24928
24929
24930 \family typewriter
24931 replace restart {
24932 \newline
24933 \SpecialChar ~
24934 \SpecialChar ~
24935 pop %1
24936 \newline
24937 \SpecialChar ~
24938 \SpecialChar ~
24939 push %1 } by {
24940 \newline
24941 \SpecialChar ~
24942 \SpecialChar ~
24943 ; nop
24944 \newline
24945 }
24946 \layout Standard
24947
24948 Note that the replace pattern cannot be a blank, but can be a comment line.
24949  Without the 'restart' option only the innermost 'pop' 'push' pair would
24950  be eliminated, i.e.:
24951 \layout Verse
24952
24953
24954 \family typewriter
24955 pop ar1
24956 \newline
24957 pop ar2
24958 \newline
24959 push ar2
24960 \newline
24961 push ar1
24962 \layout Standard
24963
24964 would result in:
24965 \layout Verse
24966
24967
24968 \family typewriter
24969 pop ar1
24970 \newline
24971 ; nop
24972 \newline
24973 push ar1
24974 \layout Standard
24975
24976
24977 \emph on
24978 with
24979 \emph default
24980  the restart option the rule will be applied again to the resulting code
24981  and then all the pop-push pairs will be eliminated to yield:
24982 \layout Verse
24983
24984
24985 \family typewriter
24986 ; nop
24987 \newline
24988 ; nop
24989 \layout Standard
24990
24991 A conditional function can be attached to a rule.
24992  Attaching rules are somewhat more involved, let me illustrate this with
24993  an example.
24994 \layout Verse
24995
24996
24997 \family typewriter
24998 replace {
24999 \newline
25000 \SpecialChar ~
25001  \SpecialChar ~
25002  \SpecialChar ~
25003 ljmp %5
25004 \newline
25005 %2:
25006 \newline
25007 } by {
25008 \newline
25009 \SpecialChar ~
25010  \SpecialChar ~
25011  \SpecialChar ~
25012 sjmp %5
25013 \newline
25014 %2:
25015 \newline
25016 } if labelInRange
25017 \layout Standard
25018
25019 The optimizer does a look-up of a function name table defined in function
25020
25021 \emph on
25022 callFuncByName
25023 \emph default
25024  in the source file SDCCpeeph.c, with the name
25025 \emph on
25026 labelInRange
25027 \emph default
25028 .
25029  If it finds a corresponding entry the function is called.
25030  Note there can be no parameters specified for these functions, in this
25031  case the use of
25032 \emph on
25033 %5
25034 \emph default
25035  is crucial, since the function
25036 \emph on
25037 labelInRange
25038 \emph default
25039  expects to find the label in that particular variable (the hash table containin
25040 g the variable bindings is passed as a parameter).
25041  If you want to code more such functions, take a close look at the function
25042  labelInRange and the calling mechanism in source file SDCCpeeph.c.
25043  Currently implemented are
25044 \emph on
25045 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
25046  24bitMode, portIsDS390, 24bitModeAndPortDS390
25047 \emph default
25048 and
25049 \emph on
25050  notVolatile
25051 \emph default
25052 .
25053 \layout Standard
25054
25055 I know this whole thing is a little kludgey, but maybe some day we will
25056  have some better means.
25057  If you are looking at this file, you will see the default rules that are
25058  compiled into the compiler, you can add your own rules in the default set
25059  there if you get tired of specifying the -
25060 \begin_inset ERT
25061 status Collapsed
25062
25063 \layout Standard
25064
25065 \backslash
25066 /
25067 \end_inset
25068
25069 -peep-file option.
25070 \layout Section
25071
25072 ANSI-Compliance
25073 \begin_inset LatexCommand \index{ANSI-compliance}
25074
25075 \end_inset
25076
25077
25078 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
25079
25080 \end_inset
25081
25082
25083 \layout Standard
25084
25085 Deviations from the compliance:
25086 \layout Itemize
25087
25088 functions are not reentrant
25089 \begin_inset LatexCommand \index{reentrant}
25090
25091 \end_inset
25092
25093  unless explicitly declared as such or the
25094 \series bold
25095 -
25096 \begin_inset ERT
25097 status Collapsed
25098
25099 \layout Standard
25100
25101 \backslash
25102 /
25103 \end_inset
25104
25105 -stack-auto
25106 \begin_inset LatexCommand \index{-\/-stack-auto}
25107
25108 \end_inset
25109
25110
25111 \series default
25112  command line option is specified.
25113 \layout Itemize
25114
25115 structures and unions cannot be assigned values directly, cannot be passed
25116  as function parameters or assigned to each other and cannot be a return
25117  value from a function, e.g.:
25118 \begin_deeper
25119 \layout Verse
25120
25121
25122 \family typewriter
25123 struct s { ...
25124  };
25125 \newline
25126 struct s s1, s2;
25127 \newline
25128 foo()
25129 \newline
25130 {
25131 \newline
25132 \SpecialChar ~
25133 \SpecialChar ~
25134 \SpecialChar ~
25135 \SpecialChar ~
25136 ...
25137
25138 \newline
25139 \SpecialChar ~
25140 \SpecialChar ~
25141 \SpecialChar ~
25142 \SpecialChar ~
25143 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
25144 \newline
25145 \SpecialChar ~
25146 \SpecialChar ~
25147 \SpecialChar ~
25148 \SpecialChar ~
25149 ...
25150
25151 \newline
25152 }
25153 \newline
25154 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
25155  */
25156 \newline
25157 {
25158 \newline
25159 \SpecialChar ~
25160 \SpecialChar ~
25161 \SpecialChar ~
25162 \SpecialChar ~
25163 struct s rets;
25164 \newline
25165 \SpecialChar ~
25166 \SpecialChar ~
25167 \SpecialChar ~
25168 \SpecialChar ~
25169 ...
25170
25171 \newline
25172 \SpecialChar ~
25173 \SpecialChar ~
25174 \SpecialChar ~
25175 \SpecialChar ~
25176 return rets;/* is invalid in SDCC although allowed in ANSI */
25177 \newline
25178 }
25179 \end_deeper
25180 \layout Itemize
25181
25182 'long long
25183 \begin_inset LatexCommand \index{long long (not supported)}
25184
25185 \end_inset
25186
25187 ' (64 bit integers
25188 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
25189
25190 \end_inset
25191
25192 ) not supported.
25193 \layout Itemize
25194
25195 'double
25196 \begin_inset LatexCommand \index{double (not supported)}
25197
25198 \end_inset
25199
25200 ' precision floating point
25201 \begin_inset LatexCommand \index{Floating point support}
25202
25203 \end_inset
25204
25205 not supported.
25206 \layout Itemize
25207
25208 No support for setjmp
25209 \begin_inset LatexCommand \index{setjmp (not supported)}
25210
25211 \end_inset
25212
25213  and longjmp
25214 \begin_inset LatexCommand \index{longjmp (not supported)}
25215
25216 \end_inset
25217
25218  (for now).
25219 \layout Itemize
25220
25221 Old K&R style
25222 \begin_inset LatexCommand \index{K\&R style}
25223
25224 \end_inset
25225
25226  function declarations are NOT allowed.
25227 \begin_deeper
25228 \layout Verse
25229
25230
25231 \family typewriter
25232 foo(i,j) /* this old style of function declarations */
25233 \newline
25234 int i,j; /* are valid in ANSI but not valid in SDCC */
25235 \newline
25236 {
25237 \newline
25238 \SpecialChar ~
25239 \SpecialChar ~
25240 \SpecialChar ~
25241 \SpecialChar ~
25242 ...
25243
25244 \newline
25245 }
25246 \end_deeper
25247 \layout Itemize
25248
25249 Certain words that are valid identifiers in the standard may be reserved
25250  words in SDCC unless the
25251 \series bold
25252 -
25253 \begin_inset ERT
25254 status Collapsed
25255
25256 \layout Standard
25257
25258 \backslash
25259 /
25260 \end_inset
25261
25262 -std-c89
25263 \begin_inset LatexCommand \index{-\/-std-c89}
25264
25265 \end_inset
25266
25267  or -
25268 \begin_inset ERT
25269 status Collapsed
25270
25271 \layout Standard
25272
25273 \backslash
25274 /
25275 \end_inset
25276
25277 -std-c99
25278 \begin_inset LatexCommand \index{-\/-std-c99}
25279
25280 \end_inset
25281
25282
25283 \series default
25284  command line options are used.
25285  These may include (depending on the selected processor): 'at', 'banked',
25286  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
25287 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
25288  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
25289  '_naked'.
25290  Compliant equivalents of these keywords are always available in a form
25291  that begin with two underscores
25292 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
25293
25294 \end_inset
25295
25296 , f.e.
25297  '__data' instead of 'data'.
25298 \layout Section
25299
25300 Cyclomatic Complexity
25301 \begin_inset LatexCommand \index{Cyclomatic complexity}
25302
25303 \end_inset
25304
25305
25306 \layout Standard
25307
25308 Cyclomatic complexity of a function is defined as the number of independent
25309  paths the program can take during execution of the function.
25310  This is an important number since it defines the number test cases you
25311  have to generate to validate the function.
25312  The accepted industry standard for complexity number is 10, if the cyclomatic
25313  complexity reported by SDCC exceeds 10 you should think about simplification
25314  of the function logic.
25315  Note that the complexity level is not related to the number of lines of
25316  code in a function.
25317  Large functions can have low complexity, and small functions can have large
25318  complexity levels.
25319
25320 \newline
25321
25322 \newline
25323 SDCC uses the following formula to compute the complexity:
25324 \newline
25325
25326 \layout Standard
25327
25328 complexity = (number of edges in control flow graph) - (number of nodes
25329  in control flow graph) + 2;
25330 \newline
25331
25332 \newline
25333 Having said that the industry standard is 10, you should be aware that in
25334  some cases it be may unavoidable to have a complexity level of less than
25335  10.
25336  For example if you have switch statement with more than 10 case labels,
25337  each case label adds one to the complexity level.
25338  The complexity level is by no means an absolute measure of the algorithmic
25339  complexity of the function, it does however provide a good starting point
25340  for which functions you might look at for further optimization.
25341 \layout Section
25342
25343 Retargetting for other Processors
25344 \layout Standard
25345
25346 The issues for retargetting the compiler are far too numerous to be covered
25347  by this document.
25348  What follows is a brief description of each of the seven phases of the
25349  compiler and its MCU dependency.
25350 \layout Itemize
25351
25352 Parsing the source and building the annotated parse tree.
25353  This phase is largely MCU independent (except for the language extensions).
25354  Syntax & semantic checks are also done in this phase, along with some initial
25355  optimizations like back patching labels and the pattern matching optimizations
25356  like bit-rotation etc.
25357 \layout Itemize
25358
25359 The second phase involves generating an intermediate code which can be easy
25360  manipulated during the later phases.
25361  This phase is entirely MCU independent.
25362  The intermediate code generation assumes the target machine has unlimited
25363  number of registers, and designates them with the name iTemp.
25364  The compiler can be made to dump a human readable form of the code generated
25365  by using the -
25366 \begin_inset ERT
25367 status Collapsed
25368
25369 \layout Standard
25370
25371 \backslash
25372 /
25373 \end_inset
25374
25375 -dumpraw option.
25376 \layout Itemize
25377
25378 This phase does the bulk of the standard optimizations and is also MCU independe
25379 nt.
25380  This phase can be broken down into several sub-phases:
25381 \newline
25382
25383 \newline
25384 Break down intermediate code (iCode) into basic blocks.
25385 \newline
25386 Do control flow & data flow analysis on the basic blocks.
25387 \newline
25388 Do local common subexpression elimination, then global subexpression elimination
25389 \newline
25390 Dead code elimination
25391 \newline
25392 Loop optimizations
25393 \newline
25394 If loop optimizations caused any changes then do 'global subexpression eliminati
25395 on' and 'dead code elimination' again.
25396 \layout Itemize
25397
25398 This phase determines the live-ranges; by live range I mean those iTemp
25399  variables defined by the compiler that still survive after all the optimization
25400 s.
25401  Live range analysis
25402 \begin_inset LatexCommand \index{Live range analysis}
25403
25404 \end_inset
25405
25406  is essential for register allocation, since these computation determines
25407  which of these iTemps will be assigned to registers, and for how long.
25408 \layout Itemize
25409
25410 Phase five is register allocation.
25411  There are two parts to this process.
25412 \newline
25413
25414 \newline
25415 The first part I call 'register packing' (for lack of a better term).
25416  In this case several MCU specific expression folding is done to reduce
25417  register pressure.
25418 \newline
25419
25420 \newline
25421 The second part is more MCU independent and deals with allocating registers
25422  to the remaining live ranges.
25423  A lot of MCU specific code does creep into this phase because of the limited
25424  number of index registers available in the 8051.
25425 \layout Itemize
25426
25427 The Code generation phase is (unhappily), entirely MCU dependent and very
25428  little (if any at all) of this code can be reused for other MCU.
25429  However the scheme for allocating a homogenized assembler operand for each
25430  iCode operand may be reused.
25431 \layout Itemize
25432
25433 As mentioned in the optimization section the peep-hole optimizer is rule
25434  based system, which can reprogrammed for other MCUs.
25435 \layout Chapter
25436
25437 Compiler internals
25438 \begin_inset LatexCommand \index{Compiler internals}
25439
25440 \end_inset
25441
25442
25443 \layout Section
25444
25445 The anatomy of the compiler
25446 \begin_inset LatexCommand \label{sub:The-anatomy-of}
25447
25448 \end_inset
25449
25450
25451 \layout Standard
25452
25453
25454 \shape italic
25455 This is an excerpt from an article published in Circuit Cellar Magazine
25456  in
25457 \series bold
25458 August 2000
25459 \series default
25460 .
25461  It's a little outdated (the compiler is much more efficient now and user/develo
25462 per friendly), but pretty well exposes the guts of it all.
25463 \shape default
25464
25465 \newline
25466
25467 \newline
25468 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
25469  It is fairly easy to retarget for other 8-bit MCU.
25470  Here we take a look at some of the internals of the compiler.
25471
25472 \layout Paragraph*
25473
25474 Parsing
25475 \begin_inset LatexCommand \index{Parsing}
25476
25477 \end_inset
25478
25479
25480 \layout Standard
25481
25482 Parsing the input source file and creating an AST (Annotated Syntax Tree
25483 \begin_inset LatexCommand \index{Annotated syntax tree}
25484
25485 \end_inset
25486
25487 ).
25488  This phase also involves propagating types (annotating each node of the
25489  parse tree with type information) and semantic analysis.
25490  There are some MCU specific parsing rules.
25491  For example the storage classes, the extended storage classes are MCU specific
25492  while there may be a xdata storage class for 8051 there is no such storage
25493  class for z80 or Atmel AVR.
25494  SDCC allows MCU specific storage class extensions, i.e.
25495  xdata will be treated as a storage class specifier when parsing 8051 C
25496  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
25497  C code.
25498 \layout Paragraph*
25499
25500 Generating iCode
25501 \begin_inset LatexCommand \index{iCode}
25502
25503 \end_inset
25504
25505
25506 \layout Standard
25507
25508 Intermediate code generation.
25509  In this phase the AST is broken down into three-operand form (iCode).
25510  These three operand forms are represented as doubly linked lists.
25511  ICode is the term given to the intermediate form generated by the compiler.
25512  ICode example section shows some examples of iCode generated for some simple
25513  C source functions.
25514 \layout Paragraph*
25515
25516 Optimizations
25517 \begin_inset LatexCommand \index{Optimizations}
25518
25519 \end_inset
25520
25521 .
25522 \layout Standard
25523
25524 Bulk of the target independent optimizations is performed in this phase.
25525  The optimizations include constant propagation, common sub-expression eliminati
25526 on, loop invariant code movement, strength reduction of loop induction variables
25527  and dead-code elimination.
25528 \layout Paragraph*
25529
25530 Live range analysis
25531 \begin_inset LatexCommand \index{Live range analysis}
25532
25533 \end_inset
25534
25535
25536 \layout Standard
25537
25538 During intermediate code generation phase, the compiler assumes the target
25539  machine has infinite number of registers and generates a lot of temporary
25540  variables.
25541  The live range computation determines the lifetime of each of these compiler-ge
25542 nerated temporaries.
25543  A picture speaks a thousand words.
25544  ICode example sections show the live range annotations for each of the
25545  operand.
25546  It is important to note here, each iCode is assigned a number in the order
25547  of its execution in the function.
25548  The live ranges are computed in terms of these numbers.
25549  The from number is the number of the iCode which first defines the operand
25550  and the to number signifies the iCode which uses this operand last.
25551 \layout Paragraph*
25552
25553 Register Allocation
25554 \begin_inset LatexCommand \index{Register allocation}
25555
25556 \end_inset
25557
25558
25559 \layout Standard
25560
25561 The register allocation determines the type and number of registers needed
25562  by each operand.
25563  In most MCUs only a few registers can be used for indirect addressing.
25564  In case of 8051 for example the registers R0 & R1 can be used to indirectly
25565  address the internal ram and DPTR to indirectly address the external ram.
25566  The compiler will try to allocate the appropriate register to pointer variables
25567  if it can.
25568  ICode example section shows the operands annotated with the registers assigned
25569  to them.
25570  The compiler will try to keep operands in registers as much as possible;
25571  there are several schemes the compiler uses to do achieve this.
25572  When the compiler runs out of registers the compiler will check to see
25573  if there are any live operands which is not used or defined in the current
25574  basic block being processed, if there are any found then it will push that
25575  operand and use the registers in this block, the operand will then be popped
25576  at the end of the basic block.
25577
25578 \layout Standard
25579
25580 There are other MCU specific considerations in this phase.
25581  Some MCUs have an accumulator; very short-lived operands could be assigned
25582  to the accumulator instead of a general-purpose register.
25583 \layout Paragraph*
25584
25585 Code generation
25586 \layout Standard
25587
25588 Figure II gives a table of iCode operations supported by the compiler.
25589  The code generation involves translating these operations into corresponding
25590  assembly code for the processor.
25591  This sounds overly simple but that is the essence of code generation.
25592  Some of the iCode operations are generated on a MCU specific manner for
25593  example, the z80 port does not use registers to pass parameters so the
25594  SEND and RECV iCode operations will not be generated, and it also does
25595  not support JUMPTABLES.
25596
25597 \newline
25598
25599 \series bold
25600 \shape italic
25601 \color red
25602 <Where is Figure II?>
25603 \layout Comment
25604
25605 In the original article Figure II was announced to be downloadable on
25606 \shape italic
25607 Circuit Cellar
25608 \shape default
25609 's web site.
25610  Unfortunately it never seemed to have shown up there, so: where is Figure
25611  II?
25612 \layout Paragraph*
25613
25614 ICode Example
25615 \begin_inset LatexCommand \index{iCode}
25616
25617 \end_inset
25618
25619
25620 \layout Standard
25621
25622 This section shows some details of iCode.
25623  The example C code does not do anything useful; it is used as an example
25624  to illustrate the intermediate code generated by the compiler.
25625 \layout Verse
25626
25627
25628 \family typewriter
25629 1.\SpecialChar ~
25630 xdata int * p;
25631 \newline
25632 2.\SpecialChar ~
25633 int gint;
25634 \newline
25635 3.\SpecialChar ~
25636 /* This function does nothing useful.
25637  It is used
25638 \newline
25639 4.\SpecialChar ~
25640 \SpecialChar ~
25641 \SpecialChar ~
25642 \SpecialChar ~
25643 for the purpose of explaining iCode */
25644 \newline
25645 5.\SpecialChar ~
25646 short function (data int *x)
25647 \newline
25648 6.\SpecialChar ~
25649 {
25650 \newline
25651 7.\SpecialChar ~
25652 \SpecialChar ~
25653 \SpecialChar ~
25654 short i=10; \SpecialChar ~
25655 \SpecialChar ~
25656 /* dead initialization eliminated */
25657 \newline
25658 8.\SpecialChar ~
25659 \SpecialChar ~
25660 \SpecialChar ~
25661 short sum=10; /* dead initialization eliminated */
25662 \newline
25663 9.\SpecialChar ~
25664 \SpecialChar ~
25665 \SpecialChar ~
25666 short mul;
25667 \newline
25668 10.\SpecialChar ~
25669 \SpecialChar ~
25670 int j ;
25671 \newline
25672 11.\SpecialChar ~
25673 \SpecialChar ~
25674 while (*x) *x++ = *p++;
25675 \newline
25676 12.\SpecialChar ~
25677 \SpecialChar ~
25678 \SpecialChar ~
25679 \SpecialChar ~
25680 sum = 0 ;
25681 \newline
25682 13.\SpecialChar ~
25683 \SpecialChar ~
25684 mul = 0;
25685 \newline
25686 14.\SpecialChar ~
25687 \SpecialChar ~
25688 /* compiler detects i,j to be induction variables */
25689 \newline
25690 15.\SpecialChar ~
25691 \SpecialChar ~
25692 for (i = 0, j = 10 ; i < 10 ; i++, j
25693 \family default
25694 -
25695 \begin_inset ERT
25696 status Collapsed
25697
25698 \layout Standard
25699
25700 \backslash
25701 /
25702 \end_inset
25703
25704 -
25705 \family typewriter
25706 ) {
25707 \newline
25708 16.\SpecialChar ~
25709 \SpecialChar ~
25710 \SpecialChar ~
25711 \SpecialChar ~
25712 sum += i;
25713 \newline
25714 17.\SpecialChar ~
25715 \SpecialChar ~
25716 \SpecialChar ~
25717 \SpecialChar ~
25718 mul += i * 3; \SpecialChar ~
25719 \SpecialChar ~
25720 /* this multiplication remains */
25721 \newline
25722 18.\SpecialChar ~
25723 \SpecialChar ~
25724 \SpecialChar ~
25725 \SpecialChar ~
25726 gint += j * 3;\SpecialChar ~
25727 \SpecialChar ~
25728 /* this multiplication changed to addition */
25729 \newline
25730 19.\SpecialChar ~
25731 \SpecialChar ~
25732 }
25733 \newline
25734 20.\SpecialChar ~
25735 \SpecialChar ~
25736 return sum+mul;
25737 \newline
25738 21.\SpecialChar ~
25739 }
25740 \layout Standard
25741
25742 In addition to the operands each iCode contains information about the filename
25743  and line it corresponds to in the source file.
25744  The first field in the listing should be interpreted as follows:
25745 \newline
25746
25747 \shape italic
25748 \size footnotesize
25749 Filename(linenumber: iCode Execution sequence number : ICode hash table
25750  key : loop depth of the iCode).
25751 \shape default
25752 \size default
25753
25754 \newline
25755 Then follows the human readable form of the ICode operation.
25756  Each operand of this triplet form can be of three basic types a) compiler
25757  generated temporary b) user defined variable c) a constant value.
25758  Note that local variables and parameters are replaced by compiler generated
25759  temporaries.
25760  Live ranges
25761 \begin_inset LatexCommand \index{Live range analysis}
25762
25763 \end_inset
25764
25765  are computed only for temporaries (i.e.
25766  live ranges are not computed for global variables).
25767  Registers
25768 \begin_inset LatexCommand \index{Register allocation}
25769
25770 \end_inset
25771
25772  are allocated for temporaries only.
25773  Operands are formatted in the following manner:
25774 \newline
25775
25776 \shape italic
25777 \size footnotesize
25778 Operand Name [lr live-from : live-to ] { type information } [ registers
25779  allocated ].
25780 \shape default
25781 \size default
25782
25783 \newline
25784 As mentioned earlier the live ranges are computed in terms of the execution
25785  sequence number of the iCodes, for example
25786 \newline
25787 the iTemp0 is live from (i.e.
25788  first defined in iCode with execution sequence number 3, and is last used
25789  in the iCode with sequence number 5).
25790  For induction variables such as iTemp21 the live range computation extends
25791  the lifetime from the start to the end of the loop.
25792 \newline
25793 The register allocator used the live range information to allocate registers,
25794  the same registers may be used for different temporaries if their live
25795  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
25796  iTemp17 since their live ranges do not overlap.
25797  In addition the allocator also takes into consideration the type and usage
25798  of a temporary, for example itemp6 is a pointer to near space and is used
25799  as to fetch data from (i.e.
25800  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
25801  Some short lived temporaries are allocated to special registers which have
25802  meaning to the code generator e.g.
25803  iTemp13 is allocated to a pseudo register CC which tells the back end that
25804  the temporary is used only for a conditional jump the code generation makes
25805  use of this information to optimize a compare and jump ICode.
25806 \newline
25807 There are several loop optimizations
25808 \begin_inset LatexCommand \index{Loop optimization}
25809
25810 \end_inset
25811
25812  performed by the compiler.
25813  It can detect induction variables iTemp21(i) and iTemp23(j).
25814  Also note the compiler does selective strength reduction
25815 \begin_inset LatexCommand \index{Strength reduction}
25816
25817 \end_inset
25818
25819 , i.e.
25820  the multiplication of an induction variable in line 18 (gint = j * 3) is
25821  changed to addition, a new temporary iTemp17 is allocated and assigned
25822  a initial value, a constant 3 is then added for each iteration of the loop.
25823  The compiler does not change the multiplication
25824 \begin_inset LatexCommand \index{Multiplication}
25825
25826 \end_inset
25827
25828  in line 17 however since the processor does support an 8 * 8 bit multiplication.
25829 \newline
25830 Note the dead code elimination
25831 \begin_inset LatexCommand \index{Dead-code elimination}
25832
25833 \end_inset
25834
25835  optimization eliminated the dead assignments in line 7 & 8 to I and sum
25836  respectively.
25837 \newline
25838
25839 \layout Standard
25840
25841
25842 \size footnotesize
25843 Sample.c (5:1:0:0) _entry($9) :
25844 \layout Standard
25845
25846
25847 \size footnotesize
25848 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
25849 \layout Standard
25850
25851
25852 \size footnotesize
25853 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
25854 \layout Standard
25855
25856
25857 \size footnotesize
25858 Sample.c(11:4:53:0) preHeaderLbl0($11) :
25859 \layout Standard
25860
25861
25862 \size footnotesize
25863 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
25864  * int}[r2]
25865 \layout Standard
25866
25867
25868 \size footnotesize
25869 Sample.c(11:6:5:1) _whilecontinue_0($1) :
25870 \layout Standard
25871
25872
25873 \size footnotesize
25874 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
25875  int}[r0]]
25876 \layout Standard
25877
25878
25879 \size footnotesize
25880 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
25881 \layout Standard
25882
25883
25884 \size footnotesize
25885 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
25886  * int}
25887 \layout Standard
25888
25889
25890 \size footnotesize
25891 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
25892  {short}
25893 \layout Standard
25894
25895
25896 \size footnotesize
25897 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
25898  * int}[DPTR]]
25899 \layout Standard
25900
25901
25902 \size footnotesize
25903 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
25904 }[r2 r3]
25905 \layout Standard
25906
25907
25908 \size footnotesize
25909 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
25910  * int}[r0] + 0x2 {short}
25911 \layout Standard
25912
25913
25914 \size footnotesize
25915 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
25916 \layout Standard
25917
25918
25919 \size footnotesize
25920 Sample.c(11:17:21:0)_whilebreak_0($3) :
25921 \layout Standard
25922
25923
25924 \size footnotesize
25925 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
25926 \layout Standard
25927
25928
25929 \size footnotesize
25930 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
25931 \layout Standard
25932
25933
25934 \size footnotesize
25935 Sample.c(15:20:54:0)preHeaderLbl1($13) :
25936 \layout Standard
25937
25938
25939 \size footnotesize
25940 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
25941 \layout Standard
25942
25943
25944 \size footnotesize
25945 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
25946 \layout Standard
25947
25948
25949 \size footnotesize
25950 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
25951 \layout Standard
25952
25953
25954 \size footnotesize
25955 Sample.c(15:24:26:1)_forcond_0($4) :
25956 \layout Standard
25957
25958
25959 \size footnotesize
25960 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
25961  < 0xa {short}
25962 \layout Standard
25963
25964
25965 \size footnotesize
25966 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
25967 \layout Standard
25968
25969
25970 \size footnotesize
25971 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
25972  + ITemp21 [lr21:38]{short}[r4]
25973 \layout Standard
25974
25975
25976 \size footnotesize
25977 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
25978  * 0x3 {short}
25979 \layout Standard
25980
25981
25982 \size footnotesize
25983 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
25984  + iTemp15 [lr29:30]{short}[r1]
25985 \layout Standard
25986
25987
25988 \size footnotesize
25989 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
25990  r0]- 0x3 {short}
25991 \layout Standard
25992
25993
25994 \size footnotesize
25995 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
25996 int}[r7 r0]
25997 \layout Standard
25998
25999
26000 \size footnotesize
26001 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
26002  + 0x1 {short}
26003 \layout Standard
26004
26005
26006 \size footnotesize
26007 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
26008  r6]- 0x1 {short}
26009 \layout Standard
26010
26011
26012 \size footnotesize
26013 Sample.c(19:38:47:1) goto _forcond_0($4)
26014 \layout Standard
26015
26016
26017 \size footnotesize
26018 Sample.c(19:39:48:0)_forbreak_0($7) :
26019 \layout Standard
26020
26021
26022 \size footnotesize
26023 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
26024  + ITemp11 [lr19:40]{short}[r3]
26025 \layout Standard
26026
26027
26028 \size footnotesize
26029 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
26030 \layout Standard
26031
26032
26033 \size footnotesize
26034 Sample.c(20:42:51:0)_return($8) :
26035 \layout Standard
26036
26037
26038 \size footnotesize
26039 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
26040 \size default
26041
26042 \newline
26043
26044 \newline
26045 Finally the code generated for this function:
26046 \newline
26047
26048 \layout Standard
26049
26050
26051 \size footnotesize
26052 .area DSEG (DATA)
26053 \layout Standard
26054
26055
26056 \size footnotesize
26057 _p::
26058 \layout Standard
26059
26060
26061 \size footnotesize
26062 \SpecialChar ~
26063 \SpecialChar ~
26064 .ds 2
26065 \layout Standard
26066
26067
26068 \size footnotesize
26069 _gint::
26070 \layout Standard
26071
26072
26073 \size footnotesize
26074 \SpecialChar ~
26075 \SpecialChar ~
26076 .ds 2
26077 \layout Standard
26078
26079
26080 \size footnotesize
26081 ; sample.c 5
26082 \layout Standard
26083
26084
26085 \size footnotesize
26086 ; ----------------------------------------------
26087 \layout Standard
26088
26089
26090 \size footnotesize
26091 ; function function
26092 \layout Standard
26093
26094
26095 \size footnotesize
26096 ; ----------------------------------------------
26097 \layout Standard
26098
26099
26100 \size footnotesize
26101 _function:
26102 \layout Standard
26103
26104
26105 \size footnotesize
26106 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
26107 \layout Standard
26108
26109
26110 \size footnotesize
26111 \SpecialChar ~
26112 \SpecialChar ~
26113 mov r2,dpl
26114 \layout Standard
26115
26116
26117 \size footnotesize
26118 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
26119 \layout Standard
26120
26121
26122 \size footnotesize
26123 \SpecialChar ~
26124 \SpecialChar ~
26125 mov ar0,r2
26126 \layout Standard
26127
26128
26129 \size footnotesize
26130 ;_whilecontinue_0($1) :
26131 \layout Standard
26132
26133
26134 \size footnotesize
26135 00101$:
26136 \layout Standard
26137
26138
26139 \size footnotesize
26140 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
26141 \layout Standard
26142
26143
26144 \size footnotesize
26145 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
26146 \layout Standard
26147
26148
26149 \size footnotesize
26150 \SpecialChar ~
26151 \SpecialChar ~
26152 mov ar2,@r0
26153 \layout Standard
26154
26155
26156 \size footnotesize
26157 \SpecialChar ~
26158 \SpecialChar ~
26159 inc r0
26160 \layout Standard
26161
26162
26163 \size footnotesize
26164 \SpecialChar ~
26165 \SpecialChar ~
26166 mov ar3,@r0
26167 \layout Standard
26168
26169
26170 \size footnotesize
26171 \SpecialChar ~
26172 \SpecialChar ~
26173 dec r0
26174 \layout Standard
26175
26176
26177 \size footnotesize
26178 \SpecialChar ~
26179 \SpecialChar ~
26180 mov a,r2
26181 \layout Standard
26182
26183
26184 \size footnotesize
26185 \SpecialChar ~
26186 \SpecialChar ~
26187 orl a,r3
26188 \layout Standard
26189
26190
26191 \size footnotesize
26192 \SpecialChar ~
26193 \SpecialChar ~
26194 jz 00103$
26195 \layout Standard
26196
26197
26198 \size footnotesize
26199 00114$:
26200 \layout Standard
26201
26202
26203 \size footnotesize
26204 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
26205 \layout Standard
26206
26207
26208 \size footnotesize
26209 \SpecialChar ~
26210 \SpecialChar ~
26211 mov dpl,_p
26212 \layout Standard
26213
26214
26215 \size footnotesize
26216 \SpecialChar ~
26217 \SpecialChar ~
26218 mov dph,(_p + 1)
26219 \layout Standard
26220
26221
26222 \size footnotesize
26223 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
26224 \layout Standard
26225
26226
26227 \size footnotesize
26228 \SpecialChar ~
26229 \SpecialChar ~
26230 mov a,#0x02
26231 \layout Standard
26232
26233
26234 \size footnotesize
26235 \SpecialChar ~
26236 \SpecialChar ~
26237 add a,_p
26238 \layout Standard
26239
26240
26241 \size footnotesize
26242 \SpecialChar ~
26243 \SpecialChar ~
26244 mov _p,a
26245 \layout Standard
26246
26247
26248 \size footnotesize
26249 \SpecialChar ~
26250 \SpecialChar ~
26251 clr a
26252 \layout Standard
26253
26254
26255 \size footnotesize
26256 \SpecialChar ~
26257 \SpecialChar ~
26258 addc a,(_p + 1)
26259 \layout Standard
26260
26261
26262 \size footnotesize
26263 \SpecialChar ~
26264 \SpecialChar ~
26265 mov (_p + 1),a
26266 \layout Standard
26267
26268
26269 \size footnotesize
26270 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
26271 \layout Standard
26272
26273
26274 \size footnotesize
26275 \SpecialChar ~
26276 \SpecialChar ~
26277 movx a,@dptr
26278 \layout Standard
26279
26280
26281 \size footnotesize
26282 \SpecialChar ~
26283 \SpecialChar ~
26284 mov r2,a
26285 \layout Standard
26286
26287
26288 \size footnotesize
26289 \SpecialChar ~
26290 \SpecialChar ~
26291 inc dptr
26292 \layout Standard
26293
26294
26295 \size footnotesize
26296 \SpecialChar ~
26297 \SpecialChar ~
26298 movx a,@dptr
26299 \layout Standard
26300
26301
26302 \size footnotesize
26303 \SpecialChar ~
26304 \SpecialChar ~
26305 mov r3,a
26306 \layout Standard
26307
26308
26309 \size footnotesize
26310 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
26311 \layout Standard
26312
26313
26314 \size footnotesize
26315 \SpecialChar ~
26316 \SpecialChar ~
26317 mov @r0,ar2
26318 \layout Standard
26319
26320
26321 \size footnotesize
26322 \SpecialChar ~
26323 \SpecialChar ~
26324 inc r0
26325 \layout Standard
26326
26327
26328 \size footnotesize
26329 \SpecialChar ~
26330 \SpecialChar ~
26331 mov @r0,ar3
26332 \layout Standard
26333
26334
26335 \size footnotesize
26336 ; iTemp6 [lr5:16]{_near * int}[r0] =
26337 \layout Standard
26338
26339
26340 \size footnotesize
26341 ; iTemp6 [lr5:16]{_near * int}[r0] +
26342 \layout Standard
26343
26344
26345 \size footnotesize
26346 ; 0x2 {short}
26347 \layout Standard
26348
26349
26350 \size footnotesize
26351 \SpecialChar ~
26352 \SpecialChar ~
26353 inc r0
26354 \layout Standard
26355
26356
26357 \size footnotesize
26358 ; goto _whilecontinue_0($1)
26359 \layout Standard
26360
26361
26362 \size footnotesize
26363 \SpecialChar ~
26364 \SpecialChar ~
26365 sjmp 00101$
26366 \layout Standard
26367
26368
26369 \size footnotesize
26370 ; _whilebreak_0($3) :
26371 \layout Standard
26372
26373
26374 \size footnotesize
26375 00103$:
26376 \layout Standard
26377
26378
26379 \size footnotesize
26380 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
26381 \layout Standard
26382
26383
26384 \size footnotesize
26385 \SpecialChar ~
26386 \SpecialChar ~
26387 mov r2,#0x00
26388 \layout Standard
26389
26390
26391 \size footnotesize
26392 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
26393 \layout Standard
26394
26395
26396 \size footnotesize
26397 \SpecialChar ~
26398 \SpecialChar ~
26399 mov r3,#0x00
26400 \layout Standard
26401
26402
26403 \size footnotesize
26404 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
26405 \layout Standard
26406
26407
26408 \size footnotesize
26409 \SpecialChar ~
26410 \SpecialChar ~
26411 mov r4,#0x00
26412 \layout Standard
26413
26414
26415 \size footnotesize
26416 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
26417 \layout Standard
26418
26419
26420 \size footnotesize
26421 \SpecialChar ~
26422 \SpecialChar ~
26423 mov r5,#0x0A
26424 \layout Standard
26425
26426
26427 \size footnotesize
26428 \SpecialChar ~
26429 \SpecialChar ~
26430 mov r6,#0x00
26431 \layout Standard
26432
26433
26434 \size footnotesize
26435 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
26436 \layout Standard
26437
26438
26439 \size footnotesize
26440 \SpecialChar ~
26441 \SpecialChar ~
26442 mov r7,#0x1E
26443 \layout Standard
26444
26445
26446 \size footnotesize
26447 \SpecialChar ~
26448 \SpecialChar ~
26449 mov r0,#0x00
26450 \layout Standard
26451
26452
26453 \size footnotesize
26454 ; _forcond_0($4) :
26455 \layout Standard
26456
26457
26458 \size footnotesize
26459 00104$:
26460 \layout Standard
26461
26462
26463 \size footnotesize
26464 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
26465 \layout Standard
26466
26467
26468 \size footnotesize
26469 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
26470 \layout Standard
26471
26472
26473 \size footnotesize
26474 \SpecialChar ~
26475 \SpecialChar ~
26476 clr c
26477 \layout Standard
26478
26479
26480 \size footnotesize
26481 \SpecialChar ~
26482 \SpecialChar ~
26483 mov a,r4
26484 \layout Standard
26485
26486
26487 \size footnotesize
26488 \SpecialChar ~
26489 \SpecialChar ~
26490 xrl a,#0x80
26491 \layout Standard
26492
26493
26494 \size footnotesize
26495 \SpecialChar ~
26496 \SpecialChar ~
26497 subb a,#0x8a
26498 \layout Standard
26499
26500
26501 \size footnotesize
26502 \SpecialChar ~
26503 \SpecialChar ~
26504 jnc 00107$
26505 \layout Standard
26506
26507
26508 \size footnotesize
26509 00115$:
26510 \layout Standard
26511
26512
26513 \size footnotesize
26514 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
26515 \layout Standard
26516
26517
26518 \size footnotesize
26519 ; iTemp21 [lr21:38]{short}[r4]
26520 \layout Standard
26521
26522
26523 \size footnotesize
26524 \SpecialChar ~
26525 \SpecialChar ~
26526 mov a,r4
26527 \layout Standard
26528
26529
26530 \size footnotesize
26531 \SpecialChar ~
26532 \SpecialChar ~
26533 add a,r2
26534 \layout Standard
26535
26536
26537 \size footnotesize
26538 \SpecialChar ~
26539 \SpecialChar ~
26540 mov r2,a
26541 \layout Standard
26542
26543
26544 \size footnotesize
26545 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
26546 \layout Standard
26547
26548
26549 \size footnotesize
26550 \SpecialChar ~
26551 \SpecialChar ~
26552 mov b,#0x03
26553 \layout Standard
26554
26555
26556 \size footnotesize
26557 \SpecialChar ~
26558 \SpecialChar ~
26559 mov a,r4
26560 \layout Standard
26561
26562
26563 \size footnotesize
26564 \SpecialChar ~
26565 \SpecialChar ~
26566 mul ab
26567 \layout Standard
26568
26569
26570 \size footnotesize
26571 \SpecialChar ~
26572 \SpecialChar ~
26573 mov r1,a
26574 \layout Standard
26575
26576
26577 \size footnotesize
26578 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
26579 \layout Standard
26580
26581
26582 \size footnotesize
26583 ; iTemp15 [lr29:30]{short}[r1]
26584 \layout Standard
26585
26586
26587 \size footnotesize
26588 \SpecialChar ~
26589 \SpecialChar ~
26590 add a,r3
26591 \layout Standard
26592
26593
26594 \size footnotesize
26595 \SpecialChar ~
26596 \SpecialChar ~
26597 mov r3,a
26598 \layout Standard
26599
26600
26601 \size footnotesize
26602 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
26603 \layout Standard
26604
26605
26606 \size footnotesize
26607 \SpecialChar ~
26608 \SpecialChar ~
26609 mov a,r7
26610 \layout Standard
26611
26612
26613 \size footnotesize
26614 \SpecialChar ~
26615 \SpecialChar ~
26616 add a,#0xfd
26617 \layout Standard
26618
26619
26620 \size footnotesize
26621 \SpecialChar ~
26622 \SpecialChar ~
26623 mov r7,a
26624 \layout Standard
26625
26626
26627 \size footnotesize
26628 \SpecialChar ~
26629 \SpecialChar ~
26630 mov a,r0
26631 \layout Standard
26632
26633
26634 \size footnotesize
26635 \SpecialChar ~
26636 \SpecialChar ~
26637 addc a,#0xff
26638 \layout Standard
26639
26640
26641 \size footnotesize
26642 \SpecialChar ~
26643 \SpecialChar ~
26644 mov r0,a
26645 \layout Standard
26646
26647
26648 \size footnotesize
26649 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
26650 \layout Standard
26651
26652
26653 \size footnotesize
26654 \SpecialChar ~
26655 \SpecialChar ~
26656 mov a,r7
26657 \layout Standard
26658
26659
26660 \size footnotesize
26661 \SpecialChar ~
26662 \SpecialChar ~
26663 add a,_gint
26664 \layout Standard
26665
26666
26667 \size footnotesize
26668 \SpecialChar ~
26669 \SpecialChar ~
26670 mov _gint,a
26671 \layout Standard
26672
26673
26674 \size footnotesize
26675 \SpecialChar ~
26676 \SpecialChar ~
26677 mov a,r0
26678 \layout Standard
26679
26680
26681 \size footnotesize
26682 \SpecialChar ~
26683 \SpecialChar ~
26684 addc a,(_gint + 1)
26685 \layout Standard
26686
26687
26688 \size footnotesize
26689 \SpecialChar ~
26690 \SpecialChar ~
26691 mov (_gint + 1),a
26692 \layout Standard
26693
26694
26695 \size footnotesize
26696 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
26697 \layout Standard
26698
26699
26700 \size footnotesize
26701 \SpecialChar ~
26702 \SpecialChar ~
26703 inc r4
26704 \layout Standard
26705
26706
26707 \size footnotesize
26708 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
26709 \layout Standard
26710
26711
26712 \size footnotesize
26713 \SpecialChar ~
26714 \SpecialChar ~
26715 dec r5
26716 \layout Standard
26717
26718
26719 \size footnotesize
26720 \SpecialChar ~
26721 \SpecialChar ~
26722 cjne r5,#0xff,00104$
26723 \layout Standard
26724
26725
26726 \size footnotesize
26727 \SpecialChar ~
26728 \SpecialChar ~
26729 dec r6
26730 \layout Standard
26731
26732
26733 \size footnotesize
26734 ; goto _forcond_0($4)
26735 \layout Standard
26736
26737
26738 \size footnotesize
26739 \SpecialChar ~
26740 \SpecialChar ~
26741 sjmp 00104$
26742 \layout Standard
26743
26744
26745 \size footnotesize
26746 ; _forbreak_0($7) :
26747 \layout Standard
26748
26749
26750 \size footnotesize
26751 00107$:
26752 \layout Standard
26753
26754
26755 \size footnotesize
26756 ; ret iTemp24 [lr40:41]{short}
26757 \layout Standard
26758
26759
26760 \size footnotesize
26761 \SpecialChar ~
26762 \SpecialChar ~
26763 mov a,r3
26764 \layout Standard
26765
26766
26767 \size footnotesize
26768 \SpecialChar ~
26769 \SpecialChar ~
26770 add a,r2
26771 \layout Standard
26772
26773
26774 \size footnotesize
26775 \SpecialChar ~
26776 \SpecialChar ~
26777 mov dpl,a
26778 \layout Standard
26779
26780
26781 \size footnotesize
26782 ; _return($8) :
26783 \layout Standard
26784
26785
26786 \size footnotesize
26787 00108$:
26788 \layout Standard
26789
26790
26791 \size footnotesize
26792 \SpecialChar ~
26793 \SpecialChar ~
26794 ret
26795 \newline
26796
26797 \layout Section
26798
26799 A few words about basic block successors, predecessors and dominators
26800 \layout Standard
26801
26802 Successors are basic blocks
26803 \begin_inset LatexCommand \index{Basic blocks}
26804
26805 \end_inset
26806
26807  that might execute after this basic block.
26808 \newline
26809 Predecessors are basic blocks that might execute before reaching this basic
26810  block.
26811 \newline
26812 Dominators are basic blocks that WILL execute before reaching this basic
26813  block.
26814 \newline
26815
26816 \layout Standard
26817
26818 [basic block 1]
26819 \layout Standard
26820
26821 if (something)
26822 \layout Standard
26823
26824 \SpecialChar ~
26825 \SpecialChar ~
26826 \SpecialChar ~
26827 \SpecialChar ~
26828 [basic block 2]
26829 \layout Standard
26830
26831 else
26832 \layout Standard
26833
26834 \SpecialChar ~
26835 \SpecialChar ~
26836 \SpecialChar ~
26837 \SpecialChar ~
26838 [basic block 3]
26839 \layout Standard
26840
26841 [basic block 4]
26842 \newline
26843
26844 \layout Standard
26845
26846 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
26847 \layout Standard
26848
26849 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
26850 \layout Standard
26851
26852 c) domVect of [BB4] = BB1 ...
26853  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
26854  was executed.
26855 \layout Chapter
26856
26857 Acknowledgments
26858 \layout Standard
26859
26860
26861 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
26862
26863 \end_inset
26864
26865
26866 \newline
26867
26868 \newline
26869
26870 \emph on
26871 Thanks to all the other volunteer developers who have helped with coding,
26872  testing, web-page creation, distribution sets, etc.
26873  You know who you are :-)
26874 \emph default
26875
26876 \newline
26877
26878 \layout Standard
26879
26880 This document was initially written by Sandeep Dutta
26881 \layout Standard
26882
26883 All product names mentioned herein may be trademarks
26884 \begin_inset LatexCommand \index{Trademarks}
26885
26886 \end_inset
26887
26888  of their respective companies.
26889
26890 \layout Section*
26891
26892 Alphabetical index
26893 \layout Standard
26894
26895 To avoid confusion, the installation and building options for SDCC itself
26896  (chapter 2) are not part of the index.
26897 \layout Standard
26898
26899
26900 \begin_inset LatexCommand \printindex{}
26901
26902 \end_inset
26903
26904
26905 \the_end