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.2
  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 code banking
 561 \begin_inset LatexCommand \index{code banking (not supported)}
 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  If you are getting a message such as "This makefile was not generated by
3272  Developer Studio etc.
3273  etc.
3274 \begin_inset Quotes srd
3275 \end_inset
3276
3277  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3278  need to convert the Unix style line endings to DOS style line endings.
3279  To do so you can use the
3280 \begin_inset Quotes sld
3281 \end_inset
3282
3283 unix2dos
3284 \begin_inset Quotes srd
3285 \end_inset
3286
3287  utility freely available on the internet.
3288  Doug Hawkins reported in the sdcc-user list that this works:
3289 \newline
3290
3291 \newline
3292 C:
3293 \backslash
3294 Programming
3295 \backslash
3296 SDCC> unix2dos sdcc.dsw
3297 \newline
3298 C:
3299 \backslash
3300 Programming
3301 \backslash
3302 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3303 \newline
3304
3305 \newline
3306 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3307  flex.exe, and gawk.exe.
3308  One good place to get them is
3309 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3310
3311 \end_inset
3312
3313
3314 \newline
3315
3316 \newline
3317 Download the file UnxUtils
3318 \begin_inset LatexCommand \index{UnxUtils}
3319
3320 \end_inset
3321
3322 .zip.
3323  Now you have to install the utilities and setup MSVC so it can locate the
3324  required programs.
3325  Here there are two alternatives (choose one!):
3326 \layout Enumerate
3327
3328 The easy way:
3329 \newline
3330
3331 \newline
3332 a) Extract UnxUtils.zip to your C:
3333 \backslash
3334  hard disk PRESERVING the original paths, otherwise bison won't work.
3335  (If you are using WinZip make certain that 'Use folder names' is selected)
3336 \newline
3337
3338 \newline
3339 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3340  in 'Show directories for:' select 'Executable files', and in the directories
3341  window add a new path: 'C:
3342 \backslash
3343 user
3344 \backslash
3345 local
3346 \backslash
3347 wbin', click ok.
3348 \newline
3349
3350 \newline
3351 (As a side effect, you get a bunch of Unix utilities that could be useful,
3352  such as diff and patch.)
3353 \layout Enumerate
3354
3355 A more compact way:
3356 \newline
3357
3358 \newline
3359 This one avoids extracting a bunch of files you may not use, but requires
3360  some extra work:
3361 \newline
3362
3363 \newline
3364 a) Create a directory were to put the tools needed, or use a directory already
3365  present.
3366  Say for example 'C:
3367 \backslash
3368 util'.
3369 \newline
3370
3371 \newline
3372 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3373  to such directory WITHOUT preserving the original paths.
3374  (If you are using WinZip make certain that 'Use folder names' is not selected)
3375 \newline
3376
3377 \newline
3378 c) Rename bison.exe to '_bison.exe'.
3379 \newline
3380
3381 \newline
3382 d) Create a batch file 'bison.bat' in 'C:
3383 \backslash
3384 util
3385 \backslash
3386 ' and add these lines:
3387 \newline
3388 \SpecialChar ~
3389 \SpecialChar ~
3390 set BISON_SIMPLE=C:
3391 \backslash
3392 util
3393 \backslash
3394 bison.simple
3395 \newline
3396 \SpecialChar ~
3397 \SpecialChar ~
3398 set BISON_HAIRY=C:
3399 \backslash
3400 util
3401 \backslash
3402 bison.hairy
3403 \newline
3404 \SpecialChar ~
3405 \SpecialChar ~
3406 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3407 \newline
3408
3409 \newline
3410 Steps 'c' and 'd' are needed because bison requires by default that the
3411  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3412  '/usr/local/share/' I think.
3413  So it is necessary to tell bison where those files are located if they
3414  are not in such directory.
3415  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3416 \newline
3417
3418 \newline
3419 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3420  in 'Show directories for:' select 'Executable files', and in the directories
3421  window add a new path: 'c:
3422 \backslash
3423 util', click ok.
3424  Note that you can use any other path instead of 'c:
3425 \backslash
3426 util', even the path where the Visual C++ tools are, probably: 'C:
3427 \backslash
3428 Program Files
3429 \backslash
3430 Microsoft Visual Studio
3431 \backslash
3432 Common
3433 \backslash
3434 Tools'.
3435  So you don't have to execute step 'e' :)
3436 \layout Standard
3437
3438 That is it.
3439  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3440  the executables from sdcc
3441 \backslash
3442 bin_vc to sdcc
3443 \backslash
3444 bin, and you can compile using SDCC.
3445 \layout Subsection
3446
3447 Building SDCC Using Borland
3448 \layout Enumerate
3449
3450 From the sdcc directory, run the command "make -f Makefile.bcc".
3451  This should regenerate all the .exe files in the bin directory except for
3452  sdcdb.exe (which currently doesn't build under Borland C++).
3453 \layout Enumerate
3454
3455 If you modify any source files and need to rebuild, be aware that the dependenci
3456 es may not be correctly calculated.
3457  The safest option is to delete all .obj files and run the build again.
3458  From a Cygwin BASH prompt, this can easily be done with the command (be
3459  sure you are in the sdcc directory):
3460 \newline
3461
3462 \newline
3463
3464 \family sans
3465 \series bold
3466 find .
3467
3468 \backslash
3469 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3470 \backslash
3471 ) -print -exec rm {}
3472 \backslash
3473 ;
3474 \family default
3475 \series default
3476
3477 \newline
3478
3479 \newline
3480 or on Windows NT/2000/XP from the command prompt with the command:
3481 \newline
3482
3483 \family sans
3484 \series bold
3485
3486 \newline
3487 del /s *.obj *.lib *.rul
3488 \family default
3489 \series default
3490  from the sdcc directory.
3491 \layout Subsection
3492
3493 Windows Install Using a ZIP Package
3494 \layout Enumerate
3495
3496 Download the binary zip package from
3497 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3498
3499 \end_inset
3500
3501  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3502  This should unpack to a group of sub-directories.
3503  An example directory structure after unpacking the mingw32 package is:
3504  c:
3505 \backslash
3506 sdcc
3507 \backslash
3508 bin for the executables, c:
3509 \backslash
3510 sdcc
3511 \backslash
3512 include and c:
3513 \backslash
3514 sdcc
3515 \backslash
3516 lib for the include and libraries.
3517 \layout Enumerate
3518
3519 Adjust your environment variable PATH to include the location of the bin
3520  directory or start sdcc using the full path.
3521 \layout Subsection
3522
3523 Windows Install Using the Setup Program
3524 \begin_inset LatexCommand \label{sub:Windows-Install}
3525
3526 \end_inset
3527
3528
3529 \layout Standard
3530
3531 Download the setup program
3532 \emph on
3533 sdcc-x.y.z-setup.exe
3534 \emph default
3535  for an official release from
3536 \newline
3537
3538 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3539
3540 \end_inset
3541
3542  or a setup program for one of the snapshots
3543 \emph on
3544 sdcc_yyyymmdd_setup.exe
3545 \emph default
3546  from
3547 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3548
3549 \end_inset
3550
3551  and execute it.
3552  A windows typical installer will guide you through the installation process.
3553 \layout Section
3554
3555 Building the Documentation
3556 \layout Standard
3557
3558 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3559  as changing into the doc directory and typing
3560 \family sans
3561 \series bold
3562
3563 \begin_inset Quotes srd
3564 \end_inset
3565
3566 make
3567 \begin_inset Quotes srd
3568 \end_inset
3569
3570
3571 \family default
3572 \series default
3573  there.
3574  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3575 x).
3576  Using LyX
3577 \begin_inset LatexCommand \url{http://www.lyx.org}
3578
3579 \end_inset
3580
3581  as editor this is straightforward.
3582  Prebuilt documentation in html and pdf format is available from
3583 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3584
3585 \end_inset
3586
3587 .
3588 \layout Section
3589
3590 Reading the Documentation
3591 \layout Standard
3592
3593 Currently reading the document in pdf format is recommended, as for unknown
3594  reason the hyperlinks are working there whereas in the html version they
3595  are not
3596 \begin_inset Foot
3597 collapsed false
3598
3599 \layout Standard
3600
3601 If you should know why please drop us a note
3602 \end_inset
3603
3604 .
3605
3606 \newline
3607 You'll find the pdf version
3608 \begin_inset LatexCommand \index{PDF version of this document}
3609
3610 \end_inset
3611
3612  at
3613 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
3614
3615 \end_inset
3616
3617 .
3618
3619 \newline
3620 A html version
3621 \begin_inset LatexCommand \index{HTML version of this document}
3622
3623 \end_inset
3624
3625  should be online at
3626 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
3627
3628 \end_inset
3629
3630 .
3631 \newline
3632 This documentation is in some aspects different from a commercial documentation:
3633
3634 \layout Itemize
3635
3636 It tries to document SDCC for several processor architectures in one document
3637  (commercially these probably would be separate documents/products).
3638  This document
3639 \begin_inset LatexCommand \index{Status of documentation}
3640
3641 \end_inset
3642
3643  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3644 on about f.e.
3645  Z80, PIC14, PIC16 and HC08.
3646 \layout Itemize
3647
3648 There are many references pointing away from this documentation.
3649  Don't let this distract you.
3650  If there f.e.
3651  was a reference like
3652 \begin_inset LatexCommand \url{http://www.opencores.org}
3653
3654 \end_inset
3655
3656  together with a statement
3657 \begin_inset Quotes sld
3658 \end_inset
3659
3660 some processors which are targetted by SDCC can be implemented in a
3661 \emph on
3662 f
3663 \emph default
3664 ield
3665 \emph on
3666 p
3667 \emph default
3668 rogrammable
3669 \emph on
3670 g
3671 \emph default
3672 ate
3673 \emph on
3674 a
3675 \emph default
3676 rray
3677 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3678
3679 \end_inset
3680
3681
3682 \begin_inset Quotes srd
3683 \end_inset
3684
3685  we expect you to have a quick look there and come back.
3686  If you read this you are on the right track.
3687 \layout Itemize
3688
3689 Some sections attribute more space to problems, restrictions and warnings
3690  than to the solution.
3691 \layout Itemize
3692
3693 The installation section and the section about the debugger is intimidating.
3694 \layout Itemize
3695
3696 There are still lots of typos and there are more different writing styles
3697  than pictures.
3698 \layout Section
3699
3700 Testing the SDCC Compiler
3701 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3702
3703 \end_inset
3704
3705
3706 \layout Standard
3707
3708 The first thing you should do after installing your SDCC compiler is to
3709  see if it runs.
3710  Type
3711 \family sans
3712 \series bold
3713 "sdcc -
3714 \begin_inset ERT
3715 status Collapsed
3716
3717 \layout Standard
3718
3719 \backslash
3720 /
3721 \end_inset
3722
3723 -version"
3724 \begin_inset LatexCommand \index{version}
3725
3726 \end_inset
3727
3728
3729 \family default
3730 \series default
3731  at the prompt, and the program should run and tell you the version.
3732  If it doesn't run, or gives a message about not finding sdcc program, then
3733  you need to check over your installation.
3734  Make sure that the sdcc bin directory is in your executable search path
3735  defined by the PATH environment setting (
3736 \series medium
3737 see
3738 \series default
3739 section
3740 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3741
3742 \end_inset
3743
3744 \SpecialChar ~
3745
3746 \series medium
3747 Install trouble-shooting for suggestions
3748 \series default
3749 ).
3750  Make sure that the sdcc program is in the bin folder, if not perhaps something
3751  did not install correctly.
3752 \newline
3753
3754 \newline
3755
3756 \series medium
3757 SDCC
3758 \series default
3759 is commonly installed as described in section
3760 \begin_inset Quotes sld
3761 \end_inset
3762
3763 Install and search paths
3764 \begin_inset Quotes srd
3765 \end_inset
3766
3767 .
3768 \newline
3769
3770 \newline
3771
3772 \series medium
3773 Make sure the compiler works on a very simple example.
3774  Type in the following test.c program using your favorite
3775 \series default
3776 ASCII
3777 \series medium
3778 editor:
3779 \layout Verse
3780
3781
3782 \family typewriter
3783 char test;
3784 \newline
3785
3786 \newline
3787 void main(void) {
3788 \newline
3789 \SpecialChar ~
3790 \SpecialChar ~
3791 \SpecialChar ~
3792 \SpecialChar ~
3793 test=0;
3794 \newline
3795 }
3796 \layout Standard
3797
3798
3799 \series medium
3800 Compile this using the following command:
3801 \family sans
3802 \series bold
3803 "sdcc -c test.c".
3804
3805 \family default
3806 \series default
3807
3808 \series medium
3809 If all goes well, the compiler will generate a test.asm and test.rel file.
3810  Congratulations, you've just compiled your first program with SDCC.
3811  We used the -c option to tell SDCC not to link the generated code, just
3812  to keep things simple for this step.
3813 \series default
3814
3815 \newline
3816
3817 \newline
3818
3819 \series medium
3820 The next step is to try it with the linker.
3821  Type in
3822 \family sans
3823 \series bold
3824 "sdcc test.c
3825 \family default
3826 \series default
3827 "
3828 \series medium
3829 .
3830  If all goes well the compiler will link with the libraries and produce
3831  a test.ihx output file.
3832  If this step fails
3833 \series default
3834
3835 \series medium
3836 (no test.ihx, and the linker generates warnings), then the problem is most
3837  likely that
3838 \series default
3839 SDCC
3840 \series medium
3841  cannot find the
3842 \series default
3843 /
3844 \series medium
3845 usr/local/share/sdcc/lib directory
3846 \series default
3847
3848 \series medium
3849 (see
3850 \series default
3851 section
3852 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3853
3854 \end_inset
3855
3856 \SpecialChar ~
3857
3858 \series medium
3859 Install trouble-shooting for suggestions).
3860 \series default
3861
3862 \newline
3863
3864 \newline
3865
3866 \series medium
3867 The final test is to ensure
3868 \series default
3869 SDCC
3870 \series medium
3871  can use the
3872 \series default
3873 standard
3874 \series medium
3875  header files and libraries.
3876  Edit test.c and change it to the following:
3877 \layout Verse
3878
3879
3880 \family typewriter
3881 #include <string.h>
3882 \newline
3883
3884 \newline
3885 char str1[10];
3886 \newline
3887
3888 \newline
3889 void main(void) {
3890 \newline
3891 \SpecialChar ~
3892 \SpecialChar ~
3893 strcpy(str1, "testing");
3894 \newline
3895 }
3896 \layout Standard
3897
3898
3899 \series medium
3900 Compile this by typing
3901 \family sans
3902 \series bold
3903 "sdcc test.c"
3904 \family default
3905 \series medium
3906 .
3907  This should generate a test.ihx output file, and it should give no warnings
3908  such as not finding the string.h file.
3909  If it cannot find the string.h file, then the problem is that
3910 \series default
3911 SDCC
3912 \series medium
3913  cannot find the /usr/local/share/sdcc/include directory
3914 \series default
3915
3916 \series medium
3917 (see the
3918 \series default
3919 section
3920 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3921
3922 \end_inset
3923
3924 \SpecialChar ~
3925
3926 \series medium
3927 Install trouble-shooting section for suggestions).
3928
3929 \series default
3930  Use option
3931 \series bold
3932 -
3933 \begin_inset ERT
3934 status Collapsed
3935
3936 \layout Standard
3937
3938 \backslash
3939 /
3940 \end_inset
3941
3942 -print-search-dirs
3943 \series default
3944
3945 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3946
3947 \end_inset
3948
3949  to find exactly where SDCC is looking for the include and lib files.
3950 \layout Section
3951
3952 Install Trouble-shooting
3953 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3954
3955 \end_inset
3956
3957
3958 \begin_inset LatexCommand \index{Install trouble-shooting}
3959
3960 \end_inset
3961
3962
3963 \layout Subsection
3964
3965 If SDCC does not build correctly
3966 \layout Standard
3967
3968 A thing to try is starting from scratch by unpacking the .tgz source package
3969  again in an empty directory.
3970  Configure it like:
3971 \newline
3972
3973 \newline
3974
3975 \family sans
3976 \series bold
3977 ./configure 2>&1 | tee configure.log
3978 \family default
3979 \series default
3980
3981 \newline
3982
3983 \newline
3984 and build it like:
3985 \newline
3986
3987 \newline
3988
3989 \family sans
3990 \series bold
3991 make 2>&1 | tee make.log
3992 \family default
3993 \series default
3994
3995 \newline
3996
3997 \newline
3998 If anything goes wrong, you can review the log files to locate the problem.
3999  Or a relevant part of this can be attached to an email that could be helpful
4000  when requesting help from the mailing list.
4001 \layout Subsection
4002
4003 What the
4004 \begin_inset Quotes sld
4005 \end_inset
4006
4007 ./configure
4008 \begin_inset Quotes srd
4009 \end_inset
4010
4011  does
4012 \layout Standard
4013
4014 The
4015 \begin_inset Quotes sld
4016 \end_inset
4017
4018 ./configure
4019 \begin_inset Quotes srd
4020 \end_inset
4021
4022  command is a script that analyzes your system and performs some configuration
4023  to ensure the source package compiles on your system.
4024  It will take a few minutes to run, and will compile a few tests to determine
4025  what compiler features are installed.
4026 \layout Subsection
4027
4028 What the
4029 \begin_inset Quotes sld
4030 \end_inset
4031
4032 make
4033 \begin_inset Quotes srd
4034 \end_inset
4035
4036  does
4037 \layout Standard
4038
4039 This runs the GNU make tool, which automatically compiles all the source
4040  packages into the final installed binary executables.
4041 \layout Subsection
4042
4043 What the
4044 \begin_inset Quotes sld
4045 \end_inset
4046
4047 make install
4048 \begin_inset Quotes erd
4049 \end_inset
4050
4051  command does.
4052 \layout Standard
4053
4054 This will install the compiler, other executables libraries and include
4055  files into the appropriate directories.
4056  See sections
4057 \begin_inset LatexCommand \ref{sub:Install-paths}
4058
4059 \end_inset
4060
4061 ,\SpecialChar ~
4062
4063 \begin_inset LatexCommand \ref{sub:Search-Paths}
4064
4065 \end_inset
4066
4067 \SpecialChar ~
4068 about install and search paths.
4069 \newline
4070 On most systems you will need super-user privileges to do this.
4071 \layout Section
4072
4073 Components of SDCC
4074 \layout Standard
4075
4076 SDCC is not just a compiler, but a collection of tools by various developers.
4077  These include linkers, assemblers, simulators and other components.
4078  Here is a summary of some of the components.
4079  Note that the included simulator and assembler have separate documentation
4080  which you can find in the source package in their respective directories.
4081  As SDCC grows to include support for other processors, other packages from
4082  various developers are included and may have their own sets of documentation.
4083 \newline
4084
4085 \newline
4086 You might want to look at the files which are installed in <installdir>.
4087  At the time of this writing, we find the following programs for gcc-builds:
4088 \newline
4089
4090 \newline
4091 In <installdir>/bin:
4092 \layout Itemize
4093
4094 sdcc - The compiler.
4095 \layout Itemize
4096
4097 sdcpp - The C preprocessor.
4098 \layout Itemize
4099
4100 asx8051 - The assembler for 8051 type processors.
4101 \layout Itemize
4102
4103 as-z80
4104 \series bold
4105 ,
4106 \series default
4107 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4108 \layout Itemize
4109
4110 aslink -The linker for 8051 type processors.
4111 \layout Itemize
4112
4113 link-z80
4114 \series bold
4115 ,
4116 \series default
4117 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4118 \layout Itemize
4119
4120 s51 - The ucSim 8051 simulator.
4121 \layout Itemize
4122
4123 sdcdb - The source debugger.
4124 \layout Itemize
4125
4126 packihx - A tool to pack (compress) Intel hex files.
4127 \layout Standard
4128
4129 In <installdir>/share/sdcc/include
4130 \layout Itemize
4131
4132 the include files
4133 \layout Standard
4134
4135 In <installdir>/share/sdcc/lib
4136 \layout Itemize
4137
4138 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4139  relocatables.
4140 \layout Standard
4141
4142 In <installdir>/share/sdcc/doc
4143 \layout Itemize
4144
4145 the documentation
4146 \layout Standard
4147
4148 As development for other processors proceeds, this list will expand to include
4149  executables to support processors like AVR, PIC, etc.
4150 \layout Subsection
4151
4152 sdcc - The Compiler
4153 \layout Standard
4154
4155 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4156  the assembler and linkage editor.
4157 \layout Subsection
4158
4159 sdcpp - The C-Preprocessor
4160 \layout Standard
4161
4162 The preprocessor
4163 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4164
4165 \end_inset
4166
4167  is a modified version of the GNU preprocessor.
4168  The C preprocessor is used to pull in #include sources, process #ifdef
4169  statements, #defines and so on.
4170 \layout Subsection
4171
4172 as
4173 \emph on
4174 xxxx
4175 \emph default
4176 , aslink, link-
4177 \emph on
4178 xxx
4179 \emph default
4180  - The Assemblers and Linkage Editors
4181 \layout Standard
4182
4183 This is retargettable assembler & linkage editor, it was developed by Alan
4184  Baldwin.
4185  John Hartman created the version for 8051, and I (Sandeep) have made some
4186  enhancements and bug fixes for it to work properly with SDCC.
4187 \layout Subsection
4188
4189 s51 - The Simulator
4190 \layout Standard
4191
4192 S51
4193 \begin_inset LatexCommand \index{s51}
4194
4195 \end_inset
4196
4197  is a freeware, opensource simulator developed by Daniel Drotos.
4198  The simulator is built as part of the build process.
4199  For more information visit Daniel's web site at:
4200 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4201
4202 \end_inset
4203
4204 .
4205  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4206  XA51 family.
4207 \layout Subsection
4208
4209 sdcdb - Source Level Debugger
4210 \layout Standard
4211
4212 Sdcdb
4213 \begin_inset LatexCommand \index{sdcdb (debugger)}
4214
4215 \end_inset
4216
4217  is the companion source level debugger.
4218  More about sdcdb in section
4219 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4220
4221 \end_inset
4222
4223 .
4224  The current version of the debugger uses Daniel's Simulator S51
4225 \begin_inset LatexCommand \index{s51}
4226
4227 \end_inset
4228
4229 , but can be easily changed to use other simulators.
4230
4231 \layout Chapter
4232
4233 Using SDCC
4234 \layout Section
4235
4236 Compiling
4237 \layout Subsection
4238
4239 Single Source File Projects
4240 \layout Standard
4241
4242 For single source file 8051 projects the process is very simple.
4243  Compile your programs with the following command
4244 \family sans
4245 \series bold
4246 "sdcc sourcefile.c".
4247
4248 \family default
4249 \series default
4250  This will compile, assemble and link your source file.
4251  Output files are as follows:
4252 \layout Itemize
4253
4254 sourcefile.asm
4255 \begin_inset LatexCommand \index{<file>.asm}
4256
4257 \end_inset
4258
4259  - Assembler source
4260 \begin_inset LatexCommand \index{Assembler source}
4261
4262 \end_inset
4263
4264  file created by the compiler
4265 \layout Itemize
4266
4267 sourcefile.lst
4268 \begin_inset LatexCommand \index{<file>.lst}
4269
4270 \end_inset
4271
4272  - Assembler listing
4273 \begin_inset LatexCommand \index{Assembler listing}
4274
4275 \end_inset
4276
4277  file created by the Assembler
4278 \layout Itemize
4279
4280 sourcefile.rst
4281 \begin_inset LatexCommand \index{<file>.rst}
4282
4283 \end_inset
4284
4285  - Assembler listing
4286 \begin_inset LatexCommand \index{Assembler listing}
4287
4288 \end_inset
4289
4290  file updated with linkedit information, created by linkage editor
4291 \layout Itemize
4292
4293 sourcefile.sym
4294 \begin_inset LatexCommand \index{<file>.sym}
4295
4296 \end_inset
4297
4298  - symbol listing
4299 \begin_inset LatexCommand \index{Symbol listing}
4300
4301 \end_inset
4302
4303  for the sourcefile, created by the assembler
4304 \layout Itemize
4305
4306 sourcefile.rel
4307 \begin_inset LatexCommand \index{<file>.rel}
4308
4309 \end_inset
4310
4311  or sourcefile.o
4312 \begin_inset LatexCommand \index{<file>.o}
4313
4314 \end_inset
4315
4316  - Object file
4317 \begin_inset LatexCommand \index{Object file}
4318
4319 \end_inset
4320
4321  created by the assembler, input to Linkage editor
4322 \layout Itemize
4323
4324 sourcefile.map
4325 \begin_inset LatexCommand \index{<file>.map}
4326
4327 \end_inset
4328
4329  - The memory map
4330 \begin_inset LatexCommand \index{Memory map}
4331
4332 \end_inset
4333
4334  for the load module, created by the Linker
4335 \layout Itemize
4336
4337 sourcefile.mem
4338 \begin_inset LatexCommand \index{<file>.mem}
4339
4340 \end_inset
4341
4342  - A file with a summary of the memory usage
4343 \layout Itemize
4344
4345 sourcefile.ihx
4346 \begin_inset LatexCommand \index{<file>.ihx}
4347
4348 \end_inset
4349
4350  - The load module in Intel hex format
4351 \begin_inset LatexCommand \index{Intel hex format}
4352
4353 \end_inset
4354
4355  (you can select the Motorola S19 format
4356 \begin_inset LatexCommand \index{Motorola S19 format}
4357
4358 \end_inset
4359
4360  with -
4361 \begin_inset ERT
4362 status Collapsed
4363
4364 \layout Standard
4365
4366 \backslash
4367 /
4368 \end_inset
4369
4370 -out-fmt-s19
4371 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4372
4373 \end_inset
4374
4375 .
4376  If you need another format you might want to use
4377 \family sans
4378 \shape italic
4379 objdump
4380 \family default
4381 \shape default
4382
4383 \begin_inset LatexCommand \index{objdump (tool)}
4384
4385 \end_inset
4386
4387  or
4388 \family sans
4389 \shape italic
4390  srecord
4391 \family default
4392 \shape default
4393
4394 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4395
4396 \end_inset
4397
4398 ).
4399  Both formats are documented in the documentation of srecord
4400 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4401
4402 \end_inset
4403
4404
4405 \layout Itemize
4406
4407 sourcefile.adb
4408 \begin_inset LatexCommand \index{<file>.adb}
4409
4410 \end_inset
4411
4412  - An intermediate file containing debug information needed to create the
4413  .cdb file (with -
4414 \begin_inset ERT
4415 status Open
4416
4417 \layout Standard
4418
4419 \backslash
4420 /
4421 \end_inset
4422
4423 -debug
4424 \begin_inset LatexCommand \index{-\/-debug}
4425
4426 \end_inset
4427
4428 )
4429 \layout Itemize
4430
4431 sourcefile.cdb
4432 \begin_inset LatexCommand \index{<file>.cdb}
4433
4434 \end_inset
4435
4436  - An optional file (with -
4437 \begin_inset ERT
4438 status Collapsed
4439
4440 \layout Standard
4441
4442 \backslash
4443 /
4444 \end_inset
4445
4446 -debug) containing debug information.
4447  The format is documented in cdbfileformat.pdf
4448 \layout Itemize
4449
4450 sourcefile.
4451  - (no extension)
4452 \begin_inset LatexCommand \index{<file> (no extension)}
4453
4454 \end_inset
4455
4456  An optional AOMF or AOMF51
4457 \begin_inset LatexCommand \index{AOMF, AOMF51}
4458
4459 \end_inset
4460
4461  file containing debug information (generated with option -
4462 \begin_inset ERT
4463 status Collapsed
4464
4465 \layout Standard
4466
4467 \backslash
4468 /
4469 \end_inset
4470
4471 -debug).
4472  The (Intel)
4473 \emph on
4474  a
4475 \emph default
4476 bsolute
4477 \emph on
4478 o
4479 \emph default
4480 bject
4481 \emph on
4482 m
4483 \emph default
4484 odule
4485 \emph on
4486 f
4487 \emph default
4488 ormat is commonly used by third party tools (debuggers
4489 \begin_inset LatexCommand \index{Debugger}
4490
4491 \end_inset
4492
4493 , simulators, emulators)
4494 \layout Itemize
4495
4496 sourcefile.dump*
4497 \begin_inset LatexCommand \index{<file>.dump*}
4498
4499 \end_inset
4500
4501  - Dump file to debug the compiler it self (generated with option -
4502 \begin_inset ERT
4503 status Collapsed
4504
4505 \layout Standard
4506
4507 \backslash
4508 /
4509 \end_inset
4510
4511 -dumpall) (see section
4512 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4513
4514 \end_inset
4515
4516 \SpecialChar ~
4517  and section
4518 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4519
4520 \end_inset
4521
4522 \SpecialChar ~
4523
4524 \begin_inset Quotes sld
4525 \end_inset
4526
4527 Anatomy of the compiler
4528 \begin_inset Quotes srd
4529 \end_inset
4530
4531 ).
4532 \layout Subsection
4533
4534 Projects with Multiple Source Files
4535 \layout Standard
4536
4537 SDCC can compile only ONE file at a time.
4538  Let us for example assume that you have a project containing the following
4539  files:
4540 \newline
4541
4542 \newline
4543 foo1.c (contains some functions)
4544 \newline
4545 foo2.c (contains some more functions)
4546 \newline
4547 foomain.c (contains more functions and the function main)
4548 \newline
4549
4550 \size footnotesize
4551
4552 \newline
4553
4554 \size default
4555 The first two files will need to be compiled separately with the commands:
4556 \size footnotesize
4557
4558 \size default
4559
4560 \newline
4561
4562 \newline
4563
4564 \family sans
4565 \series bold
4566 sdcc\SpecialChar ~
4567 -c\SpecialChar ~
4568 foo1.c
4569 \family default
4570 \series default
4571 \size footnotesize
4572
4573 \newline
4574
4575 \family sans
4576 \series bold
4577 \size default
4578 sdcc\SpecialChar ~
4579 -c\SpecialChar ~
4580 foo2.c
4581 \family default
4582 \series default
4583
4584 \newline
4585
4586 \newline
4587 Then compile the source file containing the
4588 \emph on
4589 main()
4590 \emph default
4591  function and link
4592 \begin_inset LatexCommand \index{Linker}
4593
4594 \end_inset
4595
4596  the files together with the following command:
4597 \newline
4598
4599 \newline
4600
4601 \family sans
4602 \series bold
4603 sdcc\SpecialChar ~
4604 foomain.c\SpecialChar ~
4605 foo1.rel\SpecialChar ~
4606 foo2.rel
4607 \family default
4608 \series default
4609
4610 \begin_inset LatexCommand \index{<file>.rel}
4611
4612 \end_inset
4613
4614
4615 \newline
4616
4617 \newline
4618 Alternatively,
4619 \emph on
4620 foomain.c
4621 \emph default
4622 can be separately compiled as well:
4623 \family sans
4624 \series bold
4625
4626 \newline
4627
4628 \newline
4629 sdcc\SpecialChar ~
4630 -c\SpecialChar ~
4631 foomain.c
4632 \newline
4633 sdcc foomain.rel foo1.rel foo2.rel
4634 \newline
4635
4636 \newline
4637
4638 \family default
4639 \series default
4640 The file containing the
4641 \emph on
4642 main()
4643 \emph default
4644  function
4645 \emph on
4646
4647 \emph default
4648 \noun on
4649 must
4650 \noun default
4651  be the
4652 \noun on
4653 first
4654 \noun default
4655  file specified in the command line, since the linkage editor processes
4656  file in the order they are presented to it.
4657  The linker is invoked from SDCC using a script file with extension .lnk
4658 \begin_inset LatexCommand \index{<file>.lnk}
4659
4660 \end_inset
4661
4662 .
4663  You can view this file to troubleshoot linking problems such as those arising
4664  from missing libraries.
4665 \layout Subsection
4666
4667 Projects with Additional Libraries
4668 \begin_inset LatexCommand \index{Libraries}
4669
4670 \end_inset
4671
4672
4673 \layout Standard
4674
4675 Some reusable routines may be compiled into a library, see the documentation
4676  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4677  for how to create a
4678 \emph on
4679 .lib
4680 \begin_inset LatexCommand \index{<file>.lib}
4681
4682 \end_inset
4683
4684
4685 \emph default
4686  library file.
4687  Libraries created in this manner can be included in the command line.
4688  Make sure you include the -L <library-path> option to tell the linker where
4689  to look for these files if they are not in the current directory.
4690  Here is an example, assuming you have the source file
4691 \emph on
4692 foomain.c
4693 \emph default
4694  and a library
4695 \emph on
4696  foolib.lib
4697 \emph default
4698  in the directory
4699 \emph on
4700 mylib
4701 \emph default
4702  (if that is not the same as your current project):
4703 \newline
4704
4705 \newline
4706
4707 \family sans
4708 \series bold
4709 sdcc foomain.c foolib.lib -L mylib
4710 \newline
4711
4712 \newline
4713
4714 \family default
4715 \series default
4716 Note here that
4717 \emph on
4718  mylib
4719 \emph default
4720  must be an absolute path name.
4721 \newline
4722
4723 \newline
4724 The most efficient way to use libraries is to keep separate modules in separate
4725  source files.
4726  The lib file now should name all the modules.rel
4727 \begin_inset LatexCommand \index{<file>.rel}
4728
4729 \end_inset
4730
4731  files.
4732  For an example see the standard library file
4733 \emph on
4734 libsdcc.lib
4735 \emph default
4736  in the directory <installdir>/share/lib/small.
4737 \layout Subsection
4738
4739 Using sdcclib to Create and Manage Libraries
4740 \begin_inset LatexCommand \index{sdcclib}
4741
4742 \end_inset
4743
4744
4745 \layout Standard
4746
4747 Alternatively, instead of having a .rel file for each entry on the library
4748  file as described in the preceding section, sdcclib can be used to embed
4749  all the modules belonging to such library in the library file itself.
4750  This results in a larger library file, but it greatly reduces the number
4751  of disk files accessed by the linker.
4752   Additionally, the packed library file contains an index of all include
4753  modules and symbols that significantly speeds up the linking process.
4754  To display a list of options supported by sdcclib type:
4755 \newline
4756
4757 \layout Standard
4758
4759
4760 \family sans
4761 \series bold
4762 sdcclib -?
4763 \begin_inset LatexCommand \index{sdcclib}
4764
4765 \end_inset
4766
4767
4768 \newline
4769
4770 \newline
4771
4772 \family default
4773 \series default
4774 To create a new library file, start by compiling all the required modules.
4775  For example:
4776 \newline
4777
4778 \layout Standard
4779
4780
4781 \family sans
4782 \series bold
4783 sdcc -c _divsint.c
4784 \layout Standard
4785
4786
4787 \family sans
4788 \series bold
4789 sdcc -c _divuint.c
4790 \layout Standard
4791
4792
4793 \family sans
4794 \series bold
4795 sdcc -c _modsint.c
4796 \layout Standard
4797
4798
4799 \family sans
4800 \series bold
4801 sdcc -c _moduint.c
4802 \layout Standard
4803
4804
4805 \family sans
4806 \series bold
4807 sdcc -c _mulint.c
4808 \newline
4809
4810 \layout Standard
4811
4812 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4813  and _mulint.rel.
4814  The next step is to add the .rel files to the library file:
4815 \newline
4816
4817 \layout Standard
4818
4819
4820 \family sans
4821 \series bold
4822 sdcclib libint.lib _divsint.rel
4823 \family default
4824
4825 \begin_inset LatexCommand \index{sdcclib}
4826
4827 \end_inset
4828
4829
4830 \layout Standard
4831
4832
4833 \family sans
4834 \series bold
4835 sdcclib libint.lib _divuint.rel
4836 \layout Standard
4837
4838
4839 \family sans
4840 \series bold
4841 sdcclib libint.lib _modsint.rel
4842 \layout Standard
4843
4844
4845 \family sans
4846 \series bold
4847 sdcclib libint.lib _moduint.rel
4848 \layout Standard
4849
4850
4851 \family sans
4852 \series bold
4853 sdcclib libint.lib _mulint.rel
4854 \series default
4855
4856 \newline
4857
4858 \layout Standard
4859
4860 If the file already exists in the library, it will be replaced.
4861  To see what modules and symbols are included in the library, options -s
4862  and -m are available.
4863  For example:
4864 \newline
4865
4866 \newline
4867
4868 \family sans
4869 \series bold
4870 sdcclib -s libint.lib
4871 \family default
4872
4873 \begin_inset LatexCommand \index{sdcclib}
4874
4875 \end_inset
4876
4877
4878 \newline
4879
4880 \family typewriter
4881 \series default
4882 _divsint.rel:
4883 \layout Standard
4884
4885
4886 \family typewriter
4887 __divsint_a_1_1
4888 \layout Standard
4889
4890
4891 \family typewriter
4892 __divsint_PARM_2
4893 \layout Standard
4894
4895
4896 \family typewriter
4897 __divsint
4898 \newline
4899 _divuint.rel:
4900 \layout Standard
4901
4902
4903 \family typewriter
4904 __divuint_a_1_1
4905 \layout Standard
4906
4907
4908 \family typewriter
4909 __divuint_PARM_2
4910 \layout Standard
4911
4912
4913 \family typewriter
4914 __divuint_reste_1_1
4915 \layout Standard
4916
4917
4918 \family typewriter
4919 __divuint_count_1_1
4920 \layout Standard
4921
4922
4923 \family typewriter
4924 __divuint
4925 \newline
4926 _modsint.rel:
4927 \layout Standard
4928
4929
4930 \family typewriter
4931 __modsint_a_1_1
4932 \layout Standard
4933
4934
4935 \family typewriter
4936 __modsint_PARM_2
4937 \layout Standard
4938
4939
4940 \family typewriter
4941 __modsint
4942 \newline
4943 _moduint.rel:
4944 \layout Standard
4945
4946
4947 \family typewriter
4948 __moduint_a_1_1
4949 \layout Standard
4950
4951
4952 \family typewriter
4953 __moduint_PARM_2
4954 \layout Standard
4955
4956
4957 \family typewriter
4958 __moduint_count_1_1
4959 \layout Standard
4960
4961
4962 \family typewriter
4963 __moduint
4964 \newline
4965 _mulint.rel:
4966 \layout Standard
4967
4968
4969 \family typewriter
4970 __mulint_PARM_2
4971 \layout Standard
4972
4973
4974 \family typewriter
4975 __mulint
4976 \family default
4977 \series bold
4978
4979 \newline
4980
4981 \layout Standard
4982
4983 If the source files are compiled using -
4984 \begin_inset ERT
4985 status Open
4986
4987 \layout Standard
4988
4989 \backslash
4990 /
4991 \end_inset
4992
4993 -debug
4994 \begin_inset LatexCommand \index{-\/-debug}
4995
4996 \end_inset
4997
4998 , the corresponding debug information file .adb will be include in the library
4999  file as well.
5000  The library files created with sdcclib are plain text files, so they can
5001  be viewed with a text editor.
5002  It is not recomended to modify a library file created with sdcclib using
5003  a text editor, as there are file indexes numbers located accross the file
5004  used by the linker to quickly locate the required module to link.
5005  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5006  it can be safely deleted, since all the information required for linking
5007  is embedded in the library file itself.
5008  Library files created using sdcclib are used as described in the preceding
5009  sections.
5010 \layout Section
5011
5012 Command Line Options
5013 \begin_inset LatexCommand \index{Command Line Options}
5014
5015 \end_inset
5016
5017
5018 \layout Subsection
5019
5020 Processor Selection Options
5021 \begin_inset LatexCommand \index{Options processor selection}
5022
5023 \end_inset
5024
5025
5026 \begin_inset LatexCommand \index{Processor selection options}
5027
5028 \end_inset
5029
5030
5031 \layout List
5032 \labelwidthstring 00.00.0000
5033
5034
5035 \series bold
5036 -mmcs51
5037 \begin_inset LatexCommand \index{-mmcs51}
5038
5039 \end_inset
5040
5041
5042 \series default
5043  Generate code for the Intel MCS51
5044 \begin_inset LatexCommand \index{MCS51}
5045
5046 \end_inset
5047
5048  family of processors.
5049  This is the default processor target.
5050 \layout List
5051 \labelwidthstring 00.00.0000
5052
5053
5054 \series bold
5055 -mds390
5056 \begin_inset LatexCommand \index{-mds390}
5057
5058 \end_inset
5059
5060
5061 \series default
5062  Generate code for the Dallas DS80C390
5063 \begin_inset LatexCommand \index{DS80C390}
5064
5065 \end_inset
5066
5067  processor.
5068 \layout List
5069 \labelwidthstring 00.00.0000
5070
5071
5072 \series bold
5073 -mds400
5074 \begin_inset LatexCommand \index{-mds400}
5075
5076 \end_inset
5077
5078
5079 \series default
5080  Generate code for the Dallas DS80C400
5081 \begin_inset LatexCommand \index{DS80C400}
5082
5083 \end_inset
5084
5085  processor.
5086 \layout List
5087 \labelwidthstring 00.00.0000
5088
5089
5090 \series bold
5091 -mhc08
5092 \begin_inset LatexCommand \index{-mhc08}
5093
5094 \end_inset
5095
5096
5097 \series default
5098  Generate code for the Freescale/Motorola HC08
5099 \begin_inset LatexCommand \index{HC08}
5100
5101 \end_inset
5102
5103  family of processors.
5104 \layout List
5105 \labelwidthstring 00.00.0000
5106
5107
5108 \series bold
5109 -mz80
5110 \begin_inset LatexCommand \index{-mz80}
5111
5112 \end_inset
5113
5114
5115 \series default
5116  Generate code for the Zilog Z80
5117 \begin_inset LatexCommand \index{Z80}
5118
5119 \end_inset
5120
5121  family of processors.
5122 \layout List
5123 \labelwidthstring 00.00.0000
5124
5125
5126 \series bold
5127 -mgbz80
5128 \begin_inset LatexCommand \index{-mgbz80}
5129
5130 \end_inset
5131
5132
5133 \series default
5134  Generate code for the GameBoy Z80
5135 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5136
5137 \end_inset
5138
5139  processor (Not actively maintained).
5140 \layout List
5141 \labelwidthstring 00.00.0000
5142
5143
5144 \series bold
5145 -mavr
5146 \begin_inset LatexCommand \index{-mavr}
5147
5148 \end_inset
5149
5150
5151 \series default
5152  Generate code for the Atmel AVR
5153 \begin_inset LatexCommand \index{AVR}
5154
5155 \end_inset
5156
5157  processor (In development, not complete).
5158  AVR users should probably have a look at winavr
5159 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5160
5161 \end_inset
5162
5163  or
5164 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5165
5166 \end_inset
5167
5168 .
5169 \layout Comment
5170
5171 I think it is fair to direct users there for now.
5172  Open source is also about avoiding unnecessary work .
5173  But I didn't find the 'official' link.
5174 \layout List
5175 \labelwidthstring 00.00.0000
5176
5177
5178 \series bold
5179 -mpic14
5180 \begin_inset LatexCommand \index{-mpic14}
5181
5182 \end_inset
5183
5184
5185 \series default
5186  Generate code for the Microchip PIC 14
5187 \begin_inset LatexCommand \index{PIC14}
5188
5189 \end_inset
5190
5191 -bit processors (p16f84 and variants.
5192  In development, not complete).
5193 \layout Comment
5194
5195 p16f627 p16f628 p16f84 p16f873 p16f877?
5196 \layout List
5197 \labelwidthstring 00.00.0000
5198
5199
5200 \series bold
5201 -mpic16
5202 \begin_inset LatexCommand \index{-mpic16}
5203
5204 \end_inset
5205
5206
5207 \series default
5208  Generate code for the Microchip PIC 16
5209 \begin_inset LatexCommand \index{PIC16}
5210
5211 \end_inset
5212
5213 -bit processors (p18f452 and variants.
5214  In development, not complete).
5215 \layout List
5216 \labelwidthstring 00.00.0000
5217
5218
5219 \series bold
5220 -mtlcs900h
5221 \series default
5222  Generate code for the Toshiba TLCS-900H
5223 \begin_inset LatexCommand \index{TLCS-900H}
5224
5225 \end_inset
5226
5227  processor (Not maintained, not complete).
5228 \layout List
5229 \labelwidthstring 00.00.0000
5230
5231
5232 \series bold
5233 -mxa51
5234 \begin_inset LatexCommand \index{-mxa51}
5235
5236 \end_inset
5237
5238
5239 \series default
5240  Generate code for the Phillips XA51
5241 \begin_inset LatexCommand \index{XA51}
5242
5243 \end_inset
5244
5245  processor (Not maintained, not complete).
5246 \layout Subsection
5247
5248 Preprocessor Options
5249 \begin_inset LatexCommand \index{Options preprocessor}
5250
5251 \end_inset
5252
5253
5254 \begin_inset LatexCommand \index{Preprocessor options}
5255
5256 \end_inset
5257
5258
5259 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5260
5261 \end_inset
5262
5263
5264 \layout List
5265 \labelwidthstring 00.00.0000
5266
5267
5268 \series bold
5269 -I<path>
5270 \begin_inset LatexCommand \index{-I<path>}
5271
5272 \end_inset
5273
5274
5275 \series default
5276  The additional location where the pre processor will look for <..h> or
5277 \begin_inset Quotes eld
5278 \end_inset
5279
5280 ..h
5281 \begin_inset Quotes erd
5282 \end_inset
5283
5284  files.
5285 \layout List
5286 \labelwidthstring 00.00.0000
5287
5288
5289 \series bold
5290 -D<macro[=value]>
5291 \begin_inset LatexCommand \index{-D<macro[=value]>}
5292
5293 \end_inset
5294
5295
5296 \series default
5297  Command line definition of macros.
5298  Passed to the preprocessor.
5299 \layout List
5300 \labelwidthstring 00.00.0000
5301
5302
5303 \series bold
5304 -M
5305 \begin_inset LatexCommand \index{-M}
5306
5307 \end_inset
5308
5309
5310 \series default
5311  Tell the preprocessor to output a rule suitable for make describing the
5312  dependencies of each object file.
5313  For each source file, the preprocessor outputs one make-rule whose target
5314  is the object file name for that source file and whose dependencies are
5315  all the files `#include'd in it.
5316  This rule may be a single line or may be continued with `
5317 \backslash
5318 '-newline if it is long.
5319  The list of rules is printed on standard output instead of the preprocessed
5320  C program.
5321  `-M' implies `-E
5322 \begin_inset LatexCommand \index{-E}
5323
5324 \end_inset
5325
5326 '.
5327 \layout List
5328 \labelwidthstring 00.00.0000
5329
5330
5331 \series bold
5332 -C
5333 \begin_inset LatexCommand \index{-C}
5334
5335 \end_inset
5336
5337
5338 \series default
5339  Tell the preprocessor not to discard comments.
5340  Used with the `-E' option.
5341 \layout List
5342 \labelwidthstring 00.00.0000
5343
5344
5345 \series bold
5346 -MM
5347 \begin_inset LatexCommand \index{-MM}
5348
5349 \end_inset
5350
5351
5352 \size large
5353 \bar under
5354
5355 \series default
5356 \size default
5357 \bar default
5358 Like `-M' but the output mentions only the user header files included with
5359  `#include
5360 \begin_inset Quotes eld
5361 \end_inset
5362
5363 file"'.
5364  System header files included with `#include <file>' are omitted.
5365 \layout List
5366 \labelwidthstring 00.00.0000
5367
5368
5369 \series bold
5370 -Aquestion(answer)
5371 \begin_inset LatexCommand \index{-Aquestion(answer)}
5372
5373 \end_inset
5374
5375
5376 \series default
5377  Assert the answer answer for question, in case it is tested with a preprocessor
5378  conditional such as `#if #question(answer)'.
5379  `-A-' disables the standard assertions that normally describe the target
5380  machine.
5381 \layout List
5382 \labelwidthstring 00.00.0000
5383
5384
5385 \series bold
5386 -Umacro
5387 \begin_inset LatexCommand \index{-Umacro}
5388
5389 \end_inset
5390
5391
5392 \series default
5393  Undefine macro macro.
5394  `-U' options are evaluated after all `-D' options, but before any `-include'
5395  and `-imacros' options.
5396 \layout List
5397 \labelwidthstring 00.00.0000
5398
5399
5400 \series bold
5401 -dM
5402 \begin_inset LatexCommand \index{-dM}
5403
5404 \end_inset
5405
5406
5407 \series default
5408  Tell the preprocessor to output only a list of the macro definitions that
5409  are in effect at the end of preprocessing.
5410  Used with the `-E' option.
5411 \layout List
5412 \labelwidthstring 00.00.0000
5413
5414
5415 \series bold
5416 -dD
5417 \begin_inset LatexCommand \index{-dD}
5418
5419 \end_inset
5420
5421
5422 \series default
5423  Tell the preprocessor to pass all macro definitions into the output, in
5424  their proper sequence in the rest of the output.
5425 \layout List
5426 \labelwidthstring 00.00.0000
5427
5428
5429 \series bold
5430 -dN
5431 \begin_inset LatexCommand \index{-dN}
5432
5433 \end_inset
5434
5435
5436 \size large
5437 \bar under
5438
5439 \series default
5440 \size default
5441 \bar default
5442 Like `-dD' except that the macro arguments and contents are omitted.
5443  Only `#define name' is included in the output.
5444 \layout List
5445 \labelwidthstring 00.00.0000
5446
5447
5448 \series bold
5449 -Wp\SpecialChar ~
5450 preprocessorOption[,preprocessorOption]
5451 \series default
5452
5453 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5454
5455 \end_inset
5456
5457 ...
5458  Pass the preprocessorOption to the preprocessor
5459 \family typewriter
5460 sdcpp
5461 \family default
5462
5463 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5464
5465 \end_inset
5466
5467 .
5468  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5469  Collection (gcc), if you need more dedicated options please refer to the
5470  documentation at
5471 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5472
5473 \end_inset
5474
5475 .
5476 \layout Subsection
5477
5478 Linker Options
5479 \begin_inset LatexCommand \index{Options linker}
5480
5481 \end_inset
5482
5483
5484 \begin_inset LatexCommand \index{Linker options}
5485
5486 \end_inset
5487
5488
5489 \layout List
5490 \labelwidthstring 00.00.0000
5491
5492
5493 \series bold
5494 -L\SpecialChar ~
5495 -
5496 \series default
5497
5498 \begin_inset ERT
5499 status Collapsed
5500
5501 \layout Standard
5502
5503 \backslash
5504 /
5505 \end_inset
5506
5507
5508 \series bold
5509 -lib-path
5510 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5511
5512 \end_inset
5513
5514
5515 \begin_inset LatexCommand \index{-L -\/-lib-path}
5516
5517 \end_inset
5518
5519
5520 \series default
5521 \SpecialChar ~
5522 <absolute path to additional libraries> This option is passed to the linkage
5523  editor's additional libraries
5524 \begin_inset LatexCommand \index{Libraries}
5525
5526 \end_inset
5527
5528  search path.
5529  The path name must be absolute.
5530  Additional library files may be specified in the command line.
5531  See section Compiling programs for more details.
5532 \layout List
5533 \labelwidthstring 00.00.0000
5534
5535
5536 \series bold
5537 -
5538 \begin_inset ERT
5539 status Collapsed
5540
5541 \layout Standard
5542
5543 \backslash
5544 /
5545 \end_inset
5546
5547 -xram-loc
5548 \series default
5549
5550 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5551
5552 \end_inset
5553
5554 \SpecialChar ~
5555 <Value> The start location of the external ram
5556 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5557
5558 \end_inset
5559
5560 , default value is 0.
5561  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5562 \begin_inset ERT
5563 status Collapsed
5564
5565 \layout Standard
5566
5567 \backslash
5568 /
5569 \end_inset
5570
5571 -xram-loc 0x8000 or -
5572 \begin_inset ERT
5573 status Collapsed
5574
5575 \layout Standard
5576
5577 \backslash
5578 /
5579 \end_inset
5580
5581 -xram-loc 32768.
5582 \layout List
5583 \labelwidthstring 00.00.0000
5584
5585
5586 \series bold
5587 -
5588 \begin_inset ERT
5589 status Collapsed
5590
5591 \layout Standard
5592
5593 \backslash
5594 /
5595 \end_inset
5596
5597 -code-loc
5598 \series default
5599
5600 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5601
5602 \end_inset
5603
5604 \SpecialChar ~
5605 <Value> The start location of the code
5606 \begin_inset LatexCommand \index{code}
5607
5608 \end_inset
5609
5610  segment, default value 0.
5611  Note when this option is used the interrupt vector table is also relocated
5612  to the given address.
5613  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5614 \begin_inset ERT
5615 status Collapsed
5616
5617 \layout Standard
5618
5619 \backslash
5620 /
5621 \end_inset
5622
5623 -code-loc 0x8000 or -
5624 \begin_inset ERT
5625 status Collapsed
5626
5627 \layout Standard
5628
5629 \backslash
5630 /
5631 \end_inset
5632
5633 -code-loc 32768.
5634 \layout List
5635 \labelwidthstring 00.00.0000
5636
5637
5638 \series bold
5639 -
5640 \begin_inset ERT
5641 status Collapsed
5642
5643 \layout Standard
5644
5645 \backslash
5646 /
5647 \end_inset
5648
5649 -stack-loc
5650 \series default
5651
5652 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5653
5654 \end_inset
5655
5656 \SpecialChar ~
5657 <Value> By default the stack
5658 \begin_inset LatexCommand \index{stack}
5659
5660 \end_inset
5661
5662  is placed after the data segment.
5663  Using this option the stack can be placed anywhere in the internal memory
5664  space of the 8051.
5665  The value entered can be in Hexadecimal or Decimal format, e.g.
5666  -
5667 \begin_inset ERT
5668 status Collapsed
5669
5670 \layout Standard
5671
5672 \backslash
5673 /
5674 \end_inset
5675
5676 -stack-loc 0x20 or -
5677 \begin_inset ERT
5678 status Collapsed
5679
5680 \layout Standard
5681
5682 \backslash
5683 /
5684 \end_inset
5685
5686 -stack-loc 32.
5687  Since the sp register is incremented before a push or call, the initial
5688  sp will be set to one byte prior the provided value.
5689  The provided value should not overlap any other memory areas such as used
5690  register banks or the data segment and with enough space for the current
5691  application.
5692  The
5693 \series bold
5694 -
5695 \begin_inset ERT
5696 status Collapsed
5697
5698 \layout Standard
5699
5700 \backslash
5701 /
5702 \end_inset
5703
5704 -pack-iram
5705 \series default
5706 \SpecialChar ~
5707
5708 \begin_inset LatexCommand \index{-\/-pack-iram}
5709
5710 \end_inset
5711
5712  option (which is now a default setting) will override this setting, so
5713  you should also specify the
5714 \series bold
5715 -
5716 \begin_inset ERT
5717 status Collapsed
5718
5719 \layout Standard
5720
5721 \backslash
5722 /
5723 \end_inset
5724
5725 -no-pack-iram
5726 \series default
5727 \SpecialChar ~
5728
5729 \begin_inset LatexCommand \index{-\/-no-pack-iram}
5730
5731 \end_inset
5732
5733  option if you need to manually place the stack.
5734 \layout List
5735 \labelwidthstring 00.00.0000
5736
5737
5738 \series bold
5739 -
5740 \begin_inset ERT
5741 status Collapsed
5742
5743 \layout Standard
5744
5745 \backslash
5746 /
5747 \end_inset
5748
5749 -data-loc
5750 \series default
5751
5752 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5753
5754 \end_inset
5755
5756 \SpecialChar ~
5757 <Value> The start location of the internal ram data
5758 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5759
5760 \end_inset
5761
5762  segment.
5763  The value entered can be in Hexadecimal or Decimal format, eg.
5764  -
5765 \begin_inset ERT
5766 status Collapsed
5767
5768 \layout Standard
5769
5770 \backslash
5771 /
5772 \end_inset
5773
5774 -data-loc 0x20 or -
5775 \begin_inset ERT
5776 status Collapsed
5777
5778 \layout Standard
5779
5780 \backslash
5781 /
5782 \end_inset
5783
5784 -data-loc 32.
5785  (By default, the start location of the internal ram data segment  is set
5786  as low as possible in memory, taking into account the used register banks
5787  and the bit segment at address 0x20.
5788  For example if register banks 0 and 1 are used without bit variables, the
5789  data segment will be set, if -
5790 \begin_inset ERT
5791 status Collapsed
5792
5793 \layout Standard
5794
5795 \backslash
5796 /
5797 \end_inset
5798
5799 -data-loc is not used, to location 0x10.)
5800 \layout List
5801 \labelwidthstring 00.00.0000
5802
5803
5804 \series bold
5805 -
5806 \begin_inset ERT
5807 status Collapsed
5808
5809 \layout Standard
5810
5811 \backslash
5812 /
5813 \end_inset
5814
5815 -idata-loc
5816 \series default
5817
5818 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5819
5820 \end_inset
5821
5822 \SpecialChar ~
5823 <Value> The start location of the indirectly addressable internal ram
5824 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5825
5826 \end_inset
5827
5828  of the 8051, default value is 0x80.
5829  The value entered can be in Hexadecimal or Decimal format, eg.
5830  -
5831 \begin_inset ERT
5832 status Collapsed
5833
5834 \layout Standard
5835
5836 \backslash
5837 /
5838 \end_inset
5839
5840 -idata-loc 0x88 or -
5841 \begin_inset ERT
5842 status Collapsed
5843
5844 \layout Standard
5845
5846 \backslash
5847 /
5848 \end_inset
5849
5850 -idata-loc 136.
5851 \layout List
5852 \labelwidthstring 00.00.0000
5853
5854
5855 \series bold
5856 -
5857 \begin_inset ERT
5858 status Collapsed
5859
5860 \layout Standard
5861
5862 \backslash
5863 /
5864 \end_inset
5865
5866 -bit-loc
5867 \series default
5868 \SpecialChar ~
5869 <Value> The start location of the bit
5870 \begin_inset LatexCommand \index{bit}
5871
5872 \end_inset
5873
5874  addressable internal ram of the 8051.
5875  This is
5876 \emph on
5877 not
5878 \emph default
5879  implemented yet.
5880  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5881 -bBSEG=<Value>.
5882 \layout List
5883 \labelwidthstring 00.00.0000
5884
5885
5886 \series bold
5887 -
5888 \begin_inset ERT
5889 status Collapsed
5890
5891 \layout Standard
5892
5893 \backslash
5894 /
5895 \end_inset
5896
5897 -out-fmt-ihx
5898 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5899
5900 \end_inset
5901
5902
5903 \bar under
5904
5905 \series default
5906 \bar default
5907 The linker output (final object code) is in Intel Hex format.
5908 \begin_inset LatexCommand \index{Intel hex format}
5909
5910 \end_inset
5911
5912  This is the default option.
5913  The format itself is documented in the documentation of srecord
5914 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5915
5916 \end_inset
5917
5918 .
5919 \layout List
5920 \labelwidthstring 00.00.0000
5921
5922
5923 \series bold
5924 -
5925 \begin_inset ERT
5926 status Collapsed
5927
5928 \layout Standard
5929
5930 \backslash
5931 /
5932 \end_inset
5933
5934 -out-fmt-s19
5935 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5936
5937 \end_inset
5938
5939
5940 \bar under
5941
5942 \series default
5943 \bar default
5944 The linker output (final object code) is in Motorola S19 format
5945 \begin_inset LatexCommand \index{Motorola S19 format}
5946
5947 \end_inset
5948
5949 .
5950  The format itself is documented in the documentation of srecord.
5951 \layout List
5952 \labelwidthstring 00.00.0000
5953
5954
5955 \series bold
5956 -
5957 \begin_inset ERT
5958 status Collapsed
5959
5960 \layout Standard
5961
5962 \backslash
5963 /
5964 \end_inset
5965
5966 -out-fmt-elf
5967 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5968
5969 \end_inset
5970
5971
5972 \bar under
5973
5974 \series default
5975 \bar default
5976 The linker output (final object code) is in ELF format
5977 \begin_inset LatexCommand \index{ELF format}
5978
5979 \end_inset
5980
5981 .
5982  (Currently only supported for the HC08 processors)
5983 \layout List
5984 \labelwidthstring 00.00.0000
5985
5986
5987 \series bold
5988 -Wl\SpecialChar ~
5989 linkOption[,linkOption]
5990 \series default
5991
5992 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5993
5994 \end_inset
5995
5996 ...
5997  Pass the linkOption to the linker.
5998  See file sdcc/as/doc/asxhtm.html for more on linker options.
5999 \layout Subsection
6000
6001 MCS51 Options
6002 \begin_inset LatexCommand \index{Options MCS51}
6003
6004 \end_inset
6005
6006
6007 \begin_inset LatexCommand \index{MCS51 options}
6008
6009 \end_inset
6010
6011
6012 \layout List
6013 \labelwidthstring 00.00.0000
6014
6015
6016 \series bold
6017 -
6018 \begin_inset ERT
6019 status Collapsed
6020
6021 \layout Standard
6022
6023 \backslash
6024 /
6025 \end_inset
6026
6027 -model-small
6028 \begin_inset LatexCommand \index{-\/-model-small}
6029
6030 \end_inset
6031
6032
6033 \series default
6034 \size large
6035 \emph on
6036
6037 \size default
6038 \emph default
6039 Generate code for Small Model programs, see section Memory Models for more
6040  details.
6041  This is the default model.
6042 \layout List
6043 \labelwidthstring 00.00.0000
6044
6045
6046 \series bold
6047 -
6048 \begin_inset ERT
6049 status Collapsed
6050
6051 \layout Standard
6052
6053 \backslash
6054 /
6055 \end_inset
6056
6057 -model-large
6058 \begin_inset LatexCommand \index{-\/-model-large}
6059
6060 \end_inset
6061
6062
6063 \series default
6064  Generate code for Large model programs, see section Memory Models for more
6065  details.
6066  If this option is used all source files in the project have to be compiled
6067  with this option.
6068 \layout List
6069 \labelwidthstring 00.00.0000
6070
6071
6072 \series bold
6073 -
6074 \begin_inset ERT
6075 status Collapsed
6076
6077 \layout Standard
6078
6079 \backslash
6080 /
6081 \end_inset
6082
6083 -xstack
6084 \begin_inset LatexCommand \index{-\/-xstack}
6085
6086 \end_inset
6087
6088
6089 \series default
6090  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6091  variables and passing parameters.
6092  See section
6093 \begin_inset LatexCommand \ref{sub:External-Stack}
6094
6095 \end_inset
6096
6097 \SpecialChar ~
6098  External Stack for more details.
6099 \layout List
6100 \labelwidthstring 00.00.0000
6101
6102
6103 \series bold
6104 -
6105 \begin_inset ERT
6106 status Collapsed
6107
6108 \layout Standard
6109
6110 \backslash
6111 /
6112 \end_inset
6113
6114 -iram-size
6115 \series default
6116 \SpecialChar ~
6117 <Value>
6118 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6119
6120 \end_inset
6121
6122  Causes the linker to check if the internal ram usage is within limits of
6123  the given value.
6124 \layout List
6125 \labelwidthstring 00.00.0000
6126
6127
6128 \series bold
6129 -
6130 \begin_inset ERT
6131 status Collapsed
6132
6133 \layout Standard
6134
6135 \backslash
6136 /
6137 \end_inset
6138
6139 -xram-size
6140 \series default
6141 \SpecialChar ~
6142 <Value>
6143 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6144
6145 \end_inset
6146
6147  Causes the linker to check if the external ram usage is within limits of
6148  the given value.
6149 \layout List
6150 \labelwidthstring 00.00.0000
6151
6152
6153 \series bold
6154 -
6155 \begin_inset ERT
6156 status Collapsed
6157
6158 \layout Standard
6159
6160 \backslash
6161 /
6162 \end_inset
6163
6164 -code-size
6165 \series default
6166 \SpecialChar ~
6167 <Value>
6168 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6169
6170 \end_inset
6171
6172  Causes the linker to check if the code memory usage is within limits of
6173  the given value.
6174 \layout List
6175 \labelwidthstring 00.00.0000
6176
6177
6178 \series bold
6179 -
6180 \begin_inset ERT
6181 status Collapsed
6182
6183 \layout Standard
6184
6185 \backslash
6186 /
6187 \end_inset
6188
6189 -stack-size
6190 \series default
6191 \SpecialChar ~
6192 <Value>
6193 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6194
6195 \end_inset
6196
6197  Causes the linker to check if there is at minimum <Value> bytes for stack.
6198 \layout List
6199 \labelwidthstring 00.00.0000
6200
6201
6202 \series bold
6203 -
6204 \begin_inset ERT
6205 status Collapsed
6206
6207 \layout Standard
6208
6209 \backslash
6210 /
6211 \end_inset
6212
6213 -pack-iram
6214 \series default
6215 \SpecialChar ~
6216
6217 \begin_inset LatexCommand \index{-\/-pack-iram}
6218
6219 \end_inset
6220
6221  Causes the linker to use unused register banks for data variables and pack
6222  data, idata and stack together.
6223  This is the default now.
6224 \layout List
6225 \labelwidthstring 00.00.0000
6226
6227
6228 \series bold
6229 -
6230 \begin_inset ERT
6231 status Collapsed
6232
6233 \layout Standard
6234
6235 \backslash
6236 /
6237 \end_inset
6238
6239 -no-pack-iram
6240 \series default
6241 \SpecialChar ~
6242
6243 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6244
6245 \end_inset
6246
6247  Causes the linker to use old style for allocating memory areas.
6248 \layout Subsection
6249
6250 DS390 / DS400 Options
6251 \begin_inset LatexCommand \index{Options DS390}
6252
6253 \end_inset
6254
6255
6256 \begin_inset LatexCommand \index{DS390 options}
6257
6258 \end_inset
6259
6260
6261 \layout List
6262 \labelwidthstring 00.00.0000
6263
6264
6265 \series bold
6266 -
6267 \begin_inset ERT
6268 status Collapsed
6269
6270 \layout Standard
6271
6272 \backslash
6273 /
6274 \end_inset
6275
6276 -model-flat24
6277 \series default
6278
6279 \begin_inset LatexCommand \index{-\/-model-flat24}
6280
6281 \end_inset
6282
6283
6284 \size large
6285 \emph on
6286
6287 \size default
6288 \emph default
6289 Generate 24-bit flat mode code.
6290  This is the one and only that the ds390 code generator supports right now
6291  and is default when using
6292 \emph on
6293 -mds390
6294 \emph default
6295 .
6296  See section Memory Models for more details.
6297 \layout List
6298 \labelwidthstring 00.00.0000
6299
6300
6301 \series bold
6302 -
6303 \begin_inset ERT
6304 status Collapsed
6305
6306 \layout Standard
6307
6308 \backslash
6309 /
6310 \end_inset
6311
6312 -protect-sp-update
6313 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6314
6315 \end_inset
6316
6317
6318 \series default
6319  disable interrupts during ESP:SP updates.
6320 \layout List
6321 \labelwidthstring 00.00.0000
6322
6323
6324 \series bold
6325 -
6326 \begin_inset ERT
6327 status Collapsed
6328
6329 \layout Standard
6330
6331 \backslash
6332 /
6333 \end_inset
6334
6335 -stack-10bit
6336 \series default
6337
6338 \begin_inset LatexCommand \index{-\/-stack-10bit}
6339
6340 \end_inset
6341
6342  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6343  This is the one and only that the ds390 code generator supports right now
6344  and is default when using
6345 \emph on
6346 -mds390
6347 \emph default
6348 .
6349  In this mode, the stack is located in the lower 1K of the internal RAM,
6350  which is mapped to 0x400000.
6351  Note that the support is incomplete, since it still uses a single byte
6352  as the stack pointer.
6353  This means that only the lower 256 bytes of the potential 1K stack space
6354  will actually be used.
6355  However, this does allow you to reclaim the precious 256 bytes of low RAM
6356  for use for the DATA and IDATA segments.
6357  The compiler will not generate any code to put the processor into 10 bit
6358  stack mode.
6359  It is important to ensure that the processor is in this mode before calling
6360  any re-entrant functions compiled with this option.
6361  In principle, this should work with the
6362 \emph on
6363 -
6364 \begin_inset ERT
6365 status Collapsed
6366
6367 \layout Standard
6368
6369 \backslash
6370 /
6371 \end_inset
6372
6373 -stack-auto
6374 \begin_inset LatexCommand \index{-\/-stack-auto}
6375
6376 \end_inset
6377
6378
6379 \emph default
6380  option, but that has not been tested.
6381  It is incompatible with the
6382 \emph on
6383 -
6384 \begin_inset ERT
6385 status Collapsed
6386
6387 \layout Standard
6388
6389 \backslash
6390 /
6391 \end_inset
6392
6393 -xstack
6394 \begin_inset LatexCommand \index{-\/-xstack}
6395
6396 \end_inset
6397
6398
6399 \emph default
6400  option.
6401  It also only makes sense if the processor is in 24 bit contiguous addressing
6402  mode (see the
6403 \emph on
6404 -
6405 \begin_inset ERT
6406 status Collapsed
6407
6408 \layout Standard
6409
6410 \backslash
6411 /
6412 \end_inset
6413
6414 -model-flat24 option
6415 \emph default
6416 ).
6417 \layout List
6418 \labelwidthstring 00.00.0000
6419
6420
6421 \series bold
6422 -
6423 \begin_inset ERT
6424 status Collapsed
6425
6426 \layout Standard
6427
6428 \backslash
6429 /
6430 \end_inset
6431
6432 -stack-probe
6433 \begin_inset LatexCommand \index{-\/-stack-probe}
6434
6435 \end_inset
6436
6437
6438 \series default
6439  insert call to function __stack_probe at each function prologue.
6440 \layout List
6441 \labelwidthstring 00.00.0000
6442
6443
6444 \series bold
6445 -
6446 \begin_inset ERT
6447 status Collapsed
6448
6449 \layout Standard
6450
6451 \backslash
6452 /
6453 \end_inset
6454
6455 -tini-libid
6456 \begin_inset LatexCommand \index{-\/-tini-libid}
6457
6458 \end_inset
6459
6460
6461 \series default
6462  <nnnn> LibraryID used in -mTININative.
6463
6464 \layout List
6465 \labelwidthstring 00.00.0000
6466
6467
6468 \series bold
6469 -
6470 \begin_inset ERT
6471 status Collapsed
6472
6473 \layout Standard
6474
6475 \backslash
6476 /
6477 \end_inset
6478
6479 -use-accelerator
6480 \begin_inset LatexCommand \index{-\/-use-accelerator}
6481
6482 \end_inset
6483
6484
6485 \series default
6486  generate code for DS390 Arithmetic Accelerator.
6487
6488 \layout Subsection
6489
6490 Z80 Options
6491 \begin_inset LatexCommand \index{Options Z80}
6492
6493 \end_inset
6494
6495
6496 \begin_inset LatexCommand \index{Z80 options}
6497
6498 \end_inset
6499
6500
6501 \layout List
6502 \labelwidthstring 00.00.0000
6503
6504
6505 \series bold
6506 -
6507 \begin_inset ERT
6508 status Collapsed
6509
6510 \layout Standard
6511
6512 \backslash
6513 /
6514 \end_inset
6515
6516 -callee-saves-bc
6517 \series default
6518
6519 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6520
6521 \end_inset
6522
6523
6524 \size large
6525 \emph on
6526
6527 \size default
6528 \emph default
6529 Force a called function to always save BC.
6530 \layout List
6531 \labelwidthstring 00.00.0000
6532
6533
6534 \series bold
6535 -
6536 \begin_inset ERT
6537 status Collapsed
6538
6539 \layout Standard
6540
6541 \backslash
6542 /
6543 \end_inset
6544
6545 -no-std-crt0
6546 \series default
6547
6548 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6549
6550 \end_inset
6551
6552  When linking, skip the standard crt0.o object file.
6553  You must provide your own crt0.o for your system when linking.
6554
6555 \layout Subsection
6556
6557 Optimization Options
6558 \begin_inset LatexCommand \index{Options optimization}
6559
6560 \end_inset
6561
6562
6563 \begin_inset LatexCommand \index{Optimization options}
6564
6565 \end_inset
6566
6567
6568 \layout List
6569 \labelwidthstring 00.00.0000
6570
6571
6572 \series bold
6573 -
6574 \begin_inset ERT
6575 status Collapsed
6576
6577 \layout Standard
6578
6579 \backslash
6580 /
6581 \end_inset
6582
6583 -nogcse
6584 \begin_inset LatexCommand \index{-\/-nogcse}
6585
6586 \end_inset
6587
6588
6589 \series default
6590  Will not do global subexpression elimination, this option may be used when
6591  the compiler creates undesirably large stack/data spaces to store compiler
6592  temporaries (
6593 \emph on
6594 s
6595 \emph default
6596 pill
6597 \emph on
6598 loc
6599 \emph default
6600 ations, sloc
6601 \begin_inset LatexCommand \index{sloc (spill location)}
6602
6603 \end_inset
6604
6605 ).
6606  A warning message will be generated when this happens and the compiler
6607  will indicate the number of extra bytes it allocated.
6608  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6609 nogcse
6610 \begin_inset LatexCommand \index{\#pragma nogcse}
6611
6612 \end_inset
6613
6614  can be used to turn off global subexpression elimination
6615 \begin_inset LatexCommand \index{Subexpression elimination}
6616
6617 \end_inset
6618
6619  for a given function only.
6620 \layout List
6621 \labelwidthstring 00.00.0000
6622
6623
6624 \series bold
6625 -
6626 \begin_inset ERT
6627 status Collapsed
6628
6629 \layout Standard
6630
6631 \backslash
6632 /
6633 \end_inset
6634
6635 -noinvariant
6636 \begin_inset LatexCommand \index{-\/-noinvariant}
6637
6638 \end_inset
6639
6640
6641 \series default
6642  Will not do loop invariant optimizations, this may be turned off for reasons
6643  explained for the previous option.
6644  For more details of loop optimizations performed see Loop Invariants in
6645  section
6646 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6647
6648 \end_inset
6649
6650 .
6651  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6652 noinvariant
6653 \begin_inset LatexCommand \index{\#pragma noinvariant}
6654
6655 \end_inset
6656
6657  can be used to turn off invariant optimizations for a given function only.
6658 \layout List
6659 \labelwidthstring 00.00.0000
6660
6661
6662 \series bold
6663 -
6664 \begin_inset ERT
6665 status Collapsed
6666
6667 \layout Standard
6668
6669 \backslash
6670 /
6671 \end_inset
6672
6673 -noinduction
6674 \begin_inset LatexCommand \index{-\/-noinduction}
6675
6676 \end_inset
6677
6678
6679 \series default
6680  Will not do loop induction optimizations, see section strength reduction
6681  for more details.
6682  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6683 noinduction
6684 \begin_inset LatexCommand \index{\#pragma noinduction}
6685
6686 \end_inset
6687
6688  can be used to turn off induction optimizations for a given function only.
6689 \layout List
6690 \labelwidthstring 00.00.0000
6691
6692
6693 \series bold
6694 -
6695 \begin_inset ERT
6696 status Collapsed
6697
6698 \layout Standard
6699
6700 \backslash
6701 /
6702 \end_inset
6703
6704 -nojtbound
6705 \begin_inset LatexCommand \index{-\/-nojtbound}
6706
6707 \end_inset
6708
6709
6710 \size large
6711 \bar under
6712
6713 \series default
6714 \size default
6715 \bar default
6716  Will not generate boundary condition check when switch statements
6717 \begin_inset LatexCommand \index{switch statement}
6718
6719 \end_inset
6720
6721  are implemented using jump-tables.
6722  See section
6723 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6724
6725 \end_inset
6726
6727 \SpecialChar ~
6728 Switch Statements for more details.
6729  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6730 nojtbound
6731 \begin_inset LatexCommand \index{\#pragma nojtbound}
6732
6733 \end_inset
6734
6735  can be used to turn off boundary checking for jump tables for a given function
6736  only.
6737 \layout List
6738 \labelwidthstring 00.00.0000
6739
6740
6741 \series bold
6742 -
6743 \begin_inset ERT
6744 status Collapsed
6745
6746 \layout Standard
6747
6748 \backslash
6749 /
6750 \end_inset
6751
6752 -noloopreverse
6753 \begin_inset LatexCommand \index{-\/-noloopreverse}
6754
6755 \end_inset
6756
6757
6758 \series default
6759 \size large
6760
6761 \size default
6762 Will not do loop reversal
6763 \begin_inset LatexCommand \index{Loop reversing}
6764
6765 \end_inset
6766
6767 optimization.
6768 \layout List
6769 \labelwidthstring 00.00.0000
6770
6771 -
6772 \begin_inset ERT
6773 status Collapsed
6774
6775 \layout Standard
6776
6777 \backslash
6778 /
6779 \end_inset
6780
6781 -
6782 \series bold
6783 nolabelopt
6784 \series default
6785
6786 \begin_inset LatexCommand \index{-\/-nolabelopt }
6787
6788 \end_inset
6789
6790 Will not optimize labels (makes the dumpfiles more readable).
6791 \layout List
6792 \labelwidthstring 00.00.0000
6793
6794
6795 \series bold
6796 -
6797 \begin_inset ERT
6798 status Collapsed
6799
6800 \layout Standard
6801
6802 \backslash
6803 /
6804 \end_inset
6805
6806 -no-xinit-opt
6807 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6808
6809 \end_inset
6810
6811
6812 \series default
6813  Will not memcpy initialized data from code space into xdata space.
6814  This saves a few bytes in code space if you don't have initialized data
6815 \begin_inset LatexCommand \index{Variable initialization}
6816
6817 \end_inset
6818
6819 .
6820 \layout List
6821 \labelwidthstring 00.00.0000
6822
6823
6824 \series bold
6825 -
6826 \begin_inset ERT
6827 status Collapsed
6828
6829 \layout Standard
6830
6831 \backslash
6832 /
6833 \end_inset
6834
6835 -nooverlay
6836 \begin_inset LatexCommand \index{-\/-nooverlay}
6837
6838 \end_inset
6839
6840
6841 \series default
6842   The compiler will not overlay parameters and local variables of any function,
6843  see section Parameters and local variables for more details.
6844 \layout List
6845 \labelwidthstring 00.00.0000
6846
6847
6848 \series bold
6849 -
6850 \begin_inset ERT
6851 status Collapsed
6852
6853 \layout Standard
6854
6855 \backslash
6856 /
6857 \end_inset
6858
6859 -no-peep
6860 \begin_inset LatexCommand \index{-\/-no-peep}
6861
6862 \end_inset
6863
6864
6865 \series default
6866  Disable peep-hole optimization.
6867 \layout List
6868 \labelwidthstring 00.00.0000
6869
6870
6871 \series bold
6872 -
6873 \begin_inset ERT
6874 status Collapsed
6875
6876 \layout Standard
6877
6878 \backslash
6879 /
6880 \end_inset
6881
6882 -peep-file
6883 \series default
6884
6885 \begin_inset LatexCommand \index{-\/-peep-file}
6886
6887 \end_inset
6888
6889 \SpecialChar ~
6890 <filename> This option can be used to use additional rules to be used by
6891  the peep hole optimizer.
6892  See section
6893 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6894
6895 \end_inset
6896
6897 \SpecialChar ~
6898 Peep Hole optimizations for details on how to write these rules.
6899 \layout List
6900 \labelwidthstring 00.00.0000
6901
6902
6903 \series bold
6904 -
6905 \begin_inset ERT
6906 status Collapsed
6907
6908 \layout Standard
6909
6910 \backslash
6911 /
6912 \end_inset
6913
6914 -peep-asm
6915 \begin_inset LatexCommand \index{-\/-peep-asm}
6916
6917 \end_inset
6918
6919
6920 \series default
6921  Pass the inline assembler code through the peep hole optimizer.
6922  This can cause unexpected changes to inline assembler code, please go through
6923  the peephole optimizer
6924 \begin_inset LatexCommand \index{Peephole optimizer}
6925
6926 \end_inset
6927
6928  rules defined in the source file tree '<target>/peeph.def' before using
6929  this option.
6930 \layout List
6931 \labelwidthstring 00.00.0000
6932
6933
6934 \series bold
6935 -
6936 \begin_inset ERT
6937 status Collapsed
6938
6939 \layout Standard
6940
6941 \backslash
6942 /
6943 \end_inset
6944
6945 -opt-code-speed
6946 \begin_inset LatexCommand \index{-\/-opt-code-speed}
6947
6948 \end_inset
6949
6950
6951 \series default
6952  The compiler will optimize code generation towards fast code, possibly
6953  at the expense of code size.
6954 \layout List
6955 \labelwidthstring 00.00.0000
6956
6957
6958 \series bold
6959 -
6960 \begin_inset ERT
6961 status Collapsed
6962
6963 \layout Standard
6964
6965 \backslash
6966 /
6967 \end_inset
6968
6969 -opt-code-size
6970 \begin_inset LatexCommand \index{-\/-opt-code-size}
6971
6972 \end_inset
6973
6974
6975 \series default
6976  The compiler will optimize code generation towards compact code, possibly
6977  at the expense of code speed.
6978 \layout Subsection
6979
6980 Other Options
6981 \begin_inset LatexCommand \index{Options other}
6982
6983 \end_inset
6984
6985
6986 \layout List
6987 \labelwidthstring 00.00.0000
6988
6989
6990 \series bold
6991 -c\SpecialChar ~
6992 -
6993 \begin_inset ERT
6994 status Collapsed
6995
6996 \layout Standard
6997
6998 \backslash
6999 /
7000 \end_inset
7001
7002 -compile-only
7003 \begin_inset LatexCommand \index{-\/-compile-only}
7004
7005 \end_inset
7006
7007
7008 \begin_inset LatexCommand \index{-c -\/-compile-only}
7009
7010 \end_inset
7011
7012
7013 \series default
7014  will compile and assemble the source, but will not call the linkage editor.
7015 \layout List
7016 \labelwidthstring 00.00.0000
7017
7018
7019 \series bold
7020 -
7021 \series default
7022
7023 \begin_inset ERT
7024 status Collapsed
7025
7026 \layout Standard
7027
7028 \backslash
7029 /
7030 \end_inset
7031
7032
7033 \series bold
7034 -c1mode
7035 \begin_inset LatexCommand \index{-\/-c1mode}
7036
7037 \end_inset
7038
7039
7040 \series default
7041  reads the preprocessed source from standard input and compiles it.
7042  The file name for the assembler output must be specified using the -o option.
7043 \layout List
7044 \labelwidthstring 00.00.0000
7045
7046
7047 \series bold
7048 -E
7049 \begin_inset LatexCommand \index{-E}
7050
7051 \end_inset
7052
7053
7054 \series default
7055  Run only the C preprocessor.
7056  Preprocess all the C source files specified and output the results to standard
7057  output.
7058 \layout List
7059 \labelwidthstring 00.00.0000
7060
7061
7062 \series bold
7063 -o\SpecialChar ~
7064 <path/file>
7065 \begin_inset LatexCommand \index{-o <path/file>}
7066
7067 \end_inset
7068
7069
7070 \series default
7071 The output path resp.
7072  file where everything will be placed.
7073  If the parameter is a path, it must have a trailing slash (or backslash
7074  for the Windows binaries) to be recognized as a path.
7075
7076 \layout List
7077 \labelwidthstring 00.00.0000
7078
7079
7080 \series bold
7081 -
7082 \begin_inset ERT
7083 status Collapsed
7084
7085 \layout Standard
7086
7087 \backslash
7088 /
7089 \end_inset
7090
7091 -stack-auto
7092 \begin_inset LatexCommand \index{-\/-stack-auto}
7093
7094 \end_inset
7095
7096
7097 \series default
7098 \size large
7099 \emph on
7100
7101 \size default
7102 \emph default
7103 All functions in the source file will be compiled as
7104 \emph on
7105 reentrant
7106 \emph default
7107
7108 \begin_inset LatexCommand \index{reentrant}
7109
7110 \end_inset
7111
7112 , i.e.
7113  the parameters and local variables will be allocated on the stack
7114 \begin_inset LatexCommand \index{stack}
7115
7116 \end_inset
7117
7118 .
7119  See section
7120 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7121
7122 \end_inset
7123
7124  Parameters and Local Variables for more details.
7125  If this option is used all source files in the project should be compiled
7126  with this option.
7127  It automatically implies --int-long-reent and --float-reent.
7128
7129 \layout List
7130 \labelwidthstring 00.00.0000
7131
7132
7133 \series bold
7134 -
7135 \begin_inset ERT
7136 status Collapsed
7137
7138 \layout Standard
7139
7140 \backslash
7141 /
7142 \end_inset
7143
7144 -callee-saves
7145 \begin_inset LatexCommand \index{-\/-callee-saves}
7146
7147 \end_inset
7148
7149  function1[,function2][,function3]....
7150
7151 \series default
7152  The compiler by default uses a caller saves convention for register saving
7153  across function calls, however this can cause unnecessary register pushing
7154  & popping when calling small functions from larger functions.
7155  This option can be used to switch the register saving convention for the
7156  function names specified.
7157  The compiler will not save registers when calling these functions, no extra
7158  code will be generated at the entry & exit (function prologue
7159 \series bold
7160
7161 \begin_inset LatexCommand \index{function prologue}
7162
7163 \end_inset
7164
7165
7166 \series default
7167  & epilogue
7168 \series bold
7169
7170 \begin_inset LatexCommand \index{function epilogue}
7171
7172 \end_inset
7173
7174
7175 \series default
7176 ) for these functions to save & restore the registers used by these functions,
7177  this can SUBSTANTIALLY reduce code & improve run time performance of the
7178  generated code.
7179  In the future the compiler (with inter procedural analysis) will be able
7180  to determine the appropriate scheme to use for each function call.
7181  DO NOT use this option for built-in functions such as _mulint..., if this
7182  option is used for a library function the appropriate library function
7183  needs to be recompiled with the same option.
7184  If the project consists of multiple source files then all the source file
7185  should be compiled with the same -
7186 \begin_inset ERT
7187 status Collapsed
7188
7189 \layout Standard
7190
7191 \backslash
7192 /
7193 \end_inset
7194
7195 -callee-saves option string.
7196  Also see #pragma\SpecialChar ~
7197 callee_saves
7198 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7199
7200 \end_inset
7201
7202 .
7203 \layout List
7204 \labelwidthstring 00.00.0000
7205
7206
7207 \series bold
7208 -
7209 \begin_inset ERT
7210 status Collapsed
7211
7212 \layout Standard
7213
7214 \backslash
7215 /
7216 \end_inset
7217
7218 -debug
7219 \begin_inset LatexCommand \index{-\/-debug}
7220
7221 \end_inset
7222
7223
7224 \bar under
7225
7226 \series default
7227 \bar default
7228 When this option is used the compiler will generate debug information.
7229  The debug information collected in a file with .cdb extension can be used
7230  with the SDCDB.
7231  For more information see documentation for SDCDB.
7232  Another file with no extension contains debug information in AOMF or AOMF51
7233 \begin_inset LatexCommand \index{AOMF, AOMF51}
7234
7235 \end_inset
7236
7237  format which is commonly used by third party tools.
7238 \layout List
7239 \labelwidthstring 00.00.0000
7240
7241
7242 \series bold
7243 -S
7244 \begin_inset LatexCommand \index{-S}
7245
7246 \end_inset
7247
7248
7249 \size large
7250 \bar under
7251
7252 \series default
7253 \size default
7254 \bar default
7255 Stop after the stage of compilation proper; do not assemble.
7256  The output is an assembler code file for the input file specified.
7257 \layout List
7258 \labelwidthstring 00.00.0000
7259
7260
7261 \series bold
7262 -
7263 \begin_inset ERT
7264 status Collapsed
7265
7266 \layout Standard
7267
7268 \backslash
7269 /
7270 \end_inset
7271
7272 -int-long-reent
7273 \begin_inset LatexCommand \index{-\/-int-long-reent}
7274
7275 \end_inset
7276
7277
7278 \series default
7279  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7280  Note by default these libraries are compiled as non-reentrant.
7281  See section Installation for more details.
7282 \layout List
7283 \labelwidthstring 00.00.0000
7284
7285
7286 \series bold
7287 -
7288 \begin_inset ERT
7289 status Collapsed
7290
7291 \layout Standard
7292
7293 \backslash
7294 /
7295 \end_inset
7296
7297 -cyclomatic
7298 \begin_inset LatexCommand \index{-\/-cyclomatic}
7299
7300 \end_inset
7301
7302
7303 \bar under
7304
7305 \series default
7306 \bar default
7307 This option will cause the compiler to generate an information message for
7308  each function in the source file.
7309  The message contains some
7310 \emph on
7311 important
7312 \emph default
7313  information about the function.
7314  The number of edges and nodes the compiler detected in the control flow
7315  graph of the function, and most importantly the
7316 \emph on
7317 cyclomatic complexity
7318 \begin_inset LatexCommand \index{Cyclomatic complexity}
7319
7320 \end_inset
7321
7322
7323 \emph default
7324  see section on Cyclomatic Complexity for more details.
7325 \layout List
7326 \labelwidthstring 00.00.0000
7327
7328
7329 \series bold
7330 -
7331 \begin_inset ERT
7332 status Collapsed
7333
7334 \layout Standard
7335
7336 \backslash
7337 /
7338 \end_inset
7339
7340 -float-reent
7341 \begin_inset LatexCommand \index{-\/-float-reent}
7342
7343 \end_inset
7344
7345
7346 \series default
7347  Floating point library is compiled as reentrant
7348 \begin_inset LatexCommand \index{reentrant}
7349
7350 \end_inset
7351
7352 .
7353  See section Installation for more details.
7354 \layout List
7355 \labelwidthstring 00.00.0000
7356
7357
7358 \series bold
7359 -
7360 \begin_inset ERT
7361 status Collapsed
7362
7363 \layout Standard
7364
7365 \backslash
7366 /
7367 \end_inset
7368
7369 -main-return
7370 \begin_inset LatexCommand \index{-\/-main-return}
7371
7372 \end_inset
7373
7374
7375 \series default
7376  This option can be used if the code generated is called by a monitor program
7377  or if the main routine includes an endless loop.
7378  This option might result in slightly smaller code and save two bytes of
7379  stack space.
7380  The return from the 'main'
7381 \begin_inset LatexCommand \index{main return}
7382
7383 \end_inset
7384
7385  function will return to the function calling main.
7386  The default setting is to lock up i.e.
7387  generate a '
7388 \family typewriter
7389 sjmp .
7390 \family default
7391 '.
7392 \layout List
7393 \labelwidthstring 00.00.0000
7394
7395
7396 \series bold
7397 -
7398 \begin_inset ERT
7399 status Collapsed
7400
7401 \layout Standard
7402
7403 \backslash
7404 /
7405 \end_inset
7406
7407 -nostdinc
7408 \begin_inset LatexCommand \index{-\/-nostdinc}
7409
7410 \end_inset
7411
7412
7413 \series default
7414  This will prevent the compiler from passing on the default include path
7415  to the preprocessor.
7416 \layout List
7417 \labelwidthstring 00.00.0000
7418
7419
7420 \series bold
7421 -
7422 \begin_inset ERT
7423 status Collapsed
7424
7425 \layout Standard
7426
7427 \backslash
7428 /
7429 \end_inset
7430
7431 -nostdlib
7432 \begin_inset LatexCommand \index{-\/-nostdlib}
7433
7434 \end_inset
7435
7436
7437 \series default
7438  This will prevent the compiler from passing on the default library
7439 \begin_inset LatexCommand \index{Libraries}
7440
7441 \end_inset
7442
7443  path to the linker.
7444 \layout List
7445 \labelwidthstring 00.00.0000
7446
7447
7448 \series bold
7449 -
7450 \begin_inset ERT
7451 status Collapsed
7452
7453 \layout Standard
7454
7455 \backslash
7456 /
7457 \end_inset
7458
7459 -verbose
7460 \begin_inset LatexCommand \index{-\/-verbose}
7461
7462 \end_inset
7463
7464
7465 \series default
7466  Shows the various actions the compiler is performing.
7467 \layout List
7468 \labelwidthstring 00.00.0000
7469
7470
7471 \series bold
7472 -V
7473 \begin_inset LatexCommand \index{-V}
7474
7475 \end_inset
7476
7477
7478 \series default
7479  Shows the actual commands the compiler is executing.
7480 \layout List
7481 \labelwidthstring 00.00.0000
7482
7483
7484 \series bold
7485 -
7486 \begin_inset ERT
7487 status Collapsed
7488
7489 \layout Standard
7490
7491 \backslash
7492 /
7493 \end_inset
7494
7495 -no-c-code-in-asm
7496 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7497
7498 \end_inset
7499
7500
7501 \series default
7502  Hides your ugly and inefficient c-code from the asm file, so you can always
7503  blame the compiler :)
7504 \layout List
7505 \labelwidthstring 00.00.0000
7506
7507
7508 \series bold
7509 -
7510 \begin_inset ERT
7511 status Collapsed
7512
7513 \layout Standard
7514
7515 \backslash
7516 /
7517 \end_inset
7518
7519 -no-peep-comments
7520 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7521
7522 \end_inset
7523
7524
7525 \series default
7526  Will not include peep-hole comments in the generated files.
7527 \layout List
7528 \labelwidthstring 00.00.0000
7529
7530
7531 \series bold
7532 -
7533 \begin_inset ERT
7534 status Collapsed
7535
7536 \layout Standard
7537
7538 \backslash
7539 /
7540 \end_inset
7541
7542 -i-code-in-asm
7543 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7544
7545 \end_inset
7546
7547
7548 \series default
7549  Include i-codes in the asm file.
7550  Sounds like noise but is most helpful for debugging the compiler itself.
7551 \layout List
7552 \labelwidthstring 00.00.0000
7553
7554
7555 \series bold
7556 -
7557 \begin_inset ERT
7558 status Collapsed
7559
7560 \layout Standard
7561
7562 \backslash
7563 /
7564 \end_inset
7565
7566 -less-pedantic
7567 \begin_inset LatexCommand \index{-\/-less-pedantic}
7568
7569 \end_inset
7570
7571
7572 \series default
7573  Disable some of the more pedantic warnings
7574 \begin_inset LatexCommand \index{Warnings}
7575
7576 \end_inset
7577
7578  (jwk burps: please be more specific here, please!).
7579 \layout List
7580 \labelwidthstring 00.00.0000
7581
7582
7583 \series bold
7584 -
7585 \begin_inset ERT
7586 status Collapsed
7587
7588 \layout Standard
7589
7590 \backslash
7591 /
7592 \end_inset
7593
7594 -disable-warning\SpecialChar ~
7595 <nnnn>
7596 \begin_inset LatexCommand \index{-\/-disable-warning}
7597
7598 \end_inset
7599
7600
7601 \series default
7602  Disable specific warning with number <nnnn>.
7603 \layout List
7604 \labelwidthstring 00.00.0000
7605
7606
7607 \series bold
7608 -
7609 \begin_inset ERT
7610 status Collapsed
7611
7612 \layout Standard
7613
7614 \backslash
7615 /
7616 \end_inset
7617
7618 -print-search-dirs
7619 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7620
7621 \end_inset
7622
7623
7624 \series default
7625  Display the directories in the compiler's search path
7626 \layout List
7627 \labelwidthstring 00.00.0000
7628
7629
7630 \series bold
7631 -
7632 \begin_inset ERT
7633 status Collapsed
7634
7635 \layout Standard
7636
7637 \backslash
7638 /
7639 \end_inset
7640
7641 -vc
7642 \begin_inset LatexCommand \index{-\/-vc}
7643
7644 \end_inset
7645
7646
7647 \series default
7648  Display errors and warnings using MSVC style, so you can use SDCC with
7649  visual studio.
7650 \layout List
7651 \labelwidthstring 00.00.0000
7652
7653
7654 \series bold
7655 -
7656 \begin_inset ERT
7657 status Collapsed
7658
7659 \layout Standard
7660
7661 \backslash
7662 /
7663 \end_inset
7664
7665 -use-stdout
7666 \begin_inset LatexCommand \index{-\/-use-stdout}
7667
7668 \end_inset
7669
7670
7671 \series default
7672  Send errors and warnings to stdout instead of stderr.
7673 \layout List
7674 \labelwidthstring 00.00.0000
7675
7676
7677 \series bold
7678 -Wa\SpecialChar ~
7679 asmOption[,asmOption]
7680 \series default
7681
7682 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7683
7684 \end_inset
7685
7686 ...
7687  Pass the asmOption to the assembler
7688 \begin_inset LatexCommand \index{Options assembler}
7689
7690 \end_inset
7691
7692
7693 \begin_inset LatexCommand \index{Assembler options}
7694
7695 \end_inset
7696
7697 .
7698  See file sdcc/as/doc/asxhtm.html for assembler options.cd
7699 \layout List
7700 \labelwidthstring 00.00.0000
7701
7702
7703 \series bold
7704 -
7705 \begin_inset ERT
7706 status Collapsed
7707
7708 \layout Standard
7709
7710 \backslash
7711 /
7712 \end_inset
7713
7714 -std-sdcc89
7715 \begin_inset LatexCommand \index{-\/-std-sdcc89}
7716
7717 \end_inset
7718
7719
7720 \series default
7721  Generally follow the C89 standard, but allow SDCC features that conflict
7722  with the standard (default).
7723 \layout List
7724 \labelwidthstring 00.00.0000
7725
7726
7727 \series bold
7728 -
7729 \begin_inset ERT
7730 status Collapsed
7731
7732 \layout Standard
7733
7734 \backslash
7735 /
7736 \end_inset
7737
7738 -std-c89
7739 \begin_inset LatexCommand \index{-\/-std-c89}
7740
7741 \end_inset
7742
7743
7744 \series default
7745  Follow the C89 standard and disable SDCC features that conflict with the
7746  standard.
7747 \layout List
7748 \labelwidthstring 00.00.0000
7749
7750
7751 \series bold
7752 -
7753 \begin_inset ERT
7754 status Collapsed
7755
7756 \layout Standard
7757
7758 \backslash
7759 /
7760 \end_inset
7761
7762 -std-sdcc99
7763 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7764
7765 \end_inset
7766
7767
7768 \series default
7769  Generally follow the C99 standard, but allow SDCC features that conflict
7770  with the standard (incomplete support).
7771 \layout List
7772 \labelwidthstring 00.00.0000
7773
7774
7775 \series bold
7776 -
7777 \begin_inset ERT
7778 status Collapsed
7779
7780 \layout Standard
7781
7782 \backslash
7783 /
7784 \end_inset
7785
7786 -std-c99
7787 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7788
7789 \end_inset
7790
7791
7792 \series default
7793  Follow the C99 standard and disable SDCC features that conflict with the
7794  standard (incomplete support).
7795 \layout List
7796 \labelwidthstring 00.00.0000
7797
7798
7799 \series bold
7800 more-pedantic
7801 \series default
7802  Actually this is
7803 \series bold
7804 \emph on
7805 not
7806 \series default
7807 \emph default
7808  a SDCC compiler option but if you want
7809 \emph on
7810 more
7811 \emph default
7812  warnings you can use a separate tool dedicated to syntax checking like
7813  splint
7814 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
7815
7816 \end_inset
7817
7818
7819 \begin_inset LatexCommand \index{lint (syntax checking tool)}
7820
7821 \end_inset
7822
7823
7824 \begin_inset LatexCommand \url{http://www.splint.org}
7825
7826 \end_inset
7827
7828 .
7829  To make your source files parseable by splint you will have to include
7830
7831 \family sans
7832 lint.h
7833 \family default
7834
7835 \begin_inset LatexCommand \index{splint (syntax checking tool)}
7836
7837 \end_inset
7838
7839  in your source file and add brackets around extended keywords (like
7840 \family sans
7841
7842 \begin_inset Quotes sld
7843 \end_inset
7844
7845 __at\SpecialChar ~
7846
7847 \series bold
7848 (
7849 \series default
7850 0xab
7851 \series bold
7852 )
7853 \series default
7854
7855 \begin_inset Quotes srd
7856 \end_inset
7857
7858
7859 \family default
7860  and
7861 \family sans
7862
7863 \begin_inset Quotes sld
7864 \end_inset
7865
7866 __interrupt\SpecialChar ~
7867 (2)
7868 \begin_inset Quotes srd
7869 \end_inset
7870
7871
7872 \family default
7873 ).
7874
7875 \newline
7876 Splint has an excellent on line manual at
7877 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
7878
7879 \end_inset
7880
7881  and it's capabilities go beyond pure syntax checking.
7882  You'll need to tell splint the location of SDCC's include files so a typical
7883  command line could look like this:
7884 \newline
7885
7886 \family sans
7887 splint\SpecialChar ~
7888 -I\SpecialChar ~
7889 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
7890 \SpecialChar ~
7891 myprogram.c
7892 \layout Subsection
7893
7894 Intermediate Dump Options
7895 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7896
7897 \end_inset
7898
7899
7900 \begin_inset LatexCommand \index{Options intermediate dump}
7901
7902 \end_inset
7903
7904
7905 \begin_inset LatexCommand \index{Intermediate dump options}
7906
7907 \end_inset
7908
7909
7910 \layout Standard
7911
7912 The following options are provided for the purpose of retargetting and debugging
7913  the compiler.
7914  They provide a means to dump the intermediate code (iCode
7915 \begin_inset LatexCommand \index{iCode}
7916
7917 \end_inset
7918
7919 ) generated by the compiler in human readable form at various stages of
7920  the compilation process.
7921  More on iCodes see chapter
7922 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7923
7924 \end_inset
7925
7926
7927 \begin_inset Quotes srd
7928 \end_inset
7929
7930 The anatomy of the compiler
7931 \begin_inset Quotes srd
7932 \end_inset
7933
7934 .
7935 \layout List
7936 \labelwidthstring 00.00.0000
7937
7938
7939 \series bold
7940 -
7941 \begin_inset ERT
7942 status Collapsed
7943
7944 \layout Standard
7945
7946 \backslash
7947 /
7948 \end_inset
7949
7950 -dumpraw
7951 \begin_inset LatexCommand \index{-\/-dumpraw}
7952
7953 \end_inset
7954
7955
7956 \series default
7957  This option will cause the compiler to dump the intermediate code into
7958  a file of named
7959 \emph on
7960 <source filename>.dumpraw
7961 \emph default
7962  just after the intermediate code has been generated for a function, i.e.
7963  before any optimizations are done.
7964  The basic blocks
7965 \begin_inset LatexCommand \index{Basic blocks}
7966
7967 \end_inset
7968
7969  at this stage ordered in the depth first number, so they may not be in
7970  sequence of execution.
7971 \layout List
7972 \labelwidthstring 00.00.0000
7973
7974
7975 \series bold
7976 -
7977 \begin_inset ERT
7978 status Collapsed
7979
7980 \layout Standard
7981
7982 \backslash
7983 /
7984 \end_inset
7985
7986 -dumpgcse
7987 \begin_inset LatexCommand \index{-\/-dumpgcse}
7988
7989 \end_inset
7990
7991
7992 \series default
7993  Will create a dump of iCode's, after global subexpression elimination
7994 \begin_inset LatexCommand \index{Global subexpression elimination}
7995
7996 \end_inset
7997
7998 , into a file named
7999 \emph on
8000 <source filename>.dumpgcse.
8001 \layout List
8002 \labelwidthstring 00.00.0000
8003
8004
8005 \series bold
8006 -
8007 \begin_inset ERT
8008 status Collapsed
8009
8010 \layout Standard
8011
8012 \backslash
8013 /
8014 \end_inset
8015
8016 -dumpdeadcode
8017 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8018
8019 \end_inset
8020
8021
8022 \series default
8023  Will create a dump of iCode's, after deadcode elimination
8024 \begin_inset LatexCommand \index{Dead-code elimination}
8025
8026 \end_inset
8027
8028 , into a file named
8029 \emph on
8030 <source filename>.dumpdeadcode.
8031 \layout List
8032 \labelwidthstring 00.00.0000
8033
8034
8035 \series bold
8036 -
8037 \begin_inset ERT
8038 status Collapsed
8039
8040 \layout Standard
8041
8042 \backslash
8043 /
8044 \end_inset
8045
8046 -dumploop
8047 \begin_inset LatexCommand \index{-\/-dumploop}
8048
8049 \end_inset
8050
8051
8052 \series default
8053 \size large
8054
8055 \size default
8056 Will create a dump of iCode's, after loop optimizations
8057 \begin_inset LatexCommand \index{Loop optimization}
8058
8059 \end_inset
8060
8061 , into a file named
8062 \emph on
8063 <source filename>.dumploop.
8064 \layout List
8065 \labelwidthstring 00.00.0000
8066
8067
8068 \series bold
8069 -
8070 \begin_inset ERT
8071 status Collapsed
8072
8073 \layout Standard
8074
8075 \backslash
8076 /
8077 \end_inset
8078
8079 -dumprange
8080 \begin_inset LatexCommand \index{-\/-dumprange}
8081
8082 \end_inset
8083
8084
8085 \series default
8086 \size large
8087
8088 \size default
8089 Will create a dump of iCode's, after live range analysis
8090 \begin_inset LatexCommand \index{Live range analysis}
8091
8092 \end_inset
8093
8094 , into a file named
8095 \emph on
8096 <source filename>.dumprange.
8097 \layout List
8098 \labelwidthstring 00.00.0000
8099
8100
8101 \series bold
8102 -
8103 \begin_inset ERT
8104 status Collapsed
8105
8106 \layout Standard
8107
8108 \backslash
8109 /
8110 \end_inset
8111
8112 -dumlrange
8113 \begin_inset LatexCommand \index{-\/-dumlrange}
8114
8115 \end_inset
8116
8117
8118 \series default
8119  Will dump the life ranges
8120 \begin_inset LatexCommand \index{Live range analysis}
8121
8122 \end_inset
8123
8124  for all symbols.
8125 \layout List
8126 \labelwidthstring 00.00.0000
8127
8128
8129 \series bold
8130 -
8131 \begin_inset ERT
8132 status Collapsed
8133
8134 \layout Standard
8135
8136 \backslash
8137 /
8138 \end_inset
8139
8140 -dumpregassign
8141 \begin_inset LatexCommand \index{-\/-dumpregassign}
8142
8143 \end_inset
8144
8145
8146 \bar under
8147
8148 \series default
8149 \bar default
8150 Will create a dump of iCode's, after register assignment
8151 \begin_inset LatexCommand \index{Register assignment}
8152
8153 \end_inset
8154
8155 , into a file named
8156 \emph on
8157 <source filename>.dumprassgn.
8158 \layout List
8159 \labelwidthstring 00.00.0000
8160
8161
8162 \series bold
8163 -
8164 \begin_inset ERT
8165 status Collapsed
8166
8167 \layout Standard
8168
8169 \backslash
8170 /
8171 \end_inset
8172
8173 -dumplrange
8174 \begin_inset LatexCommand \index{-\/-dumplrange}
8175
8176 \end_inset
8177
8178
8179 \series default
8180  Will create a dump of the live ranges of iTemp's
8181 \layout List
8182 \labelwidthstring 00.00.0000
8183
8184
8185 \series bold
8186 -
8187 \begin_inset ERT
8188 status Collapsed
8189
8190 \layout Standard
8191
8192 \backslash
8193 /
8194 \end_inset
8195
8196 -dumpall
8197 \begin_inset LatexCommand \index{-\/-dumpall}
8198
8199 \end_inset
8200
8201
8202 \size large
8203 \bar under
8204
8205 \series default
8206 \size default
8207 \bar default
8208 Will cause all the above mentioned dumps to be created.
8209 \layout Subsection
8210
8211 Redirecting output on Windows Shells
8212 \layout Standard
8213
8214 By default SDCC writes it's error messages to
8215 \begin_inset Quotes sld
8216 \end_inset
8217
8218 standard error
8219 \begin_inset Quotes srd
8220 \end_inset
8221
8222 .
8223  To force all messages to
8224 \begin_inset Quotes sld
8225 \end_inset
8226
8227 standard output
8228 \begin_inset Quotes srd
8229 \end_inset
8230
8231  use
8232 \series bold
8233 -
8234 \series default
8235 \emph on
8236
8237 \begin_inset ERT
8238 status Collapsed
8239
8240 \layout Standard
8241
8242 \backslash
8243 /
8244 \end_inset
8245
8246
8247 \series bold
8248 \emph default
8249 -
8250 \series default
8251 use-stdout
8252 \begin_inset LatexCommand \index{-\/-use-stdout}
8253
8254 \end_inset
8255
8256 .
8257  Additionally, if you happen to have visual studio installed in your windows
8258  machine, you can use it to compile your sources using a custom build and
8259  the SDCC -
8260 \emph on
8261
8262 \begin_inset ERT
8263 status Collapsed
8264
8265 \layout Standard
8266
8267 \backslash
8268 /
8269 \end_inset
8270
8271
8272 \emph default
8273 -vc
8274 \begin_inset LatexCommand \index{-\/-vc}
8275
8276 \end_inset
8277
8278  option.
8279  Something like this should work:
8280 \newline
8281
8282 \newline
8283
8284 \series bold
8285 c:
8286 \backslash
8287 sdcc
8288 \backslash
8289 bin
8290 \backslash
8291 sdcc.exe -
8292 \series default
8293 \emph on
8294
8295 \begin_inset ERT
8296 status Collapsed
8297
8298 \layout Standard
8299
8300 \backslash
8301 /
8302 \end_inset
8303
8304
8305 \series bold
8306 \emph default
8307 -vc -
8308 \series default
8309 \emph on
8310
8311 \begin_inset ERT
8312 status Collapsed
8313
8314 \layout Standard
8315
8316 \backslash
8317 /
8318 \end_inset
8319
8320
8321 \series bold
8322 \emph default
8323 -model-large -c $(InputPath)
8324 \layout Section
8325
8326 Environment variables
8327 \begin_inset LatexCommand \index{Environment variables}
8328
8329 \end_inset
8330
8331
8332 \layout Standard
8333
8334 SDCC recognizes the following environment variables:
8335 \layout List
8336 \labelwidthstring 00.00.0000
8337
8338
8339 \series bold
8340 SDCC_LEAVE_SIGNALS
8341 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
8342
8343 \end_inset
8344
8345
8346 \series default
8347  SDCC installs a signal handler
8348 \begin_inset LatexCommand \index{signal handler}
8349
8350 \end_inset
8351
8352  to be able to delete temporary files after an user break (^C) or an exception.
8353  If this environment variable is set, SDCC won't install the signal handler
8354  in order to be able to debug SDCC.
8355 \layout List
8356 \labelwidthstring 00.00.0000
8357
8358
8359 \series bold
8360 TMP,\SpecialChar ~
8361 TEMP,\SpecialChar ~
8362 TMPDIR
8363 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
8364
8365 \end_inset
8366
8367
8368 \series default
8369  Path, where temporary files will be created.
8370  The order of the variables is the search order.
8371  In a standard *nix environment these variables are not set, and there's
8372  no need to set them.
8373  On Windows it's recommended to set one of them.
8374 \layout List
8375 \labelwidthstring 00.00.0000
8376
8377
8378 \series bold
8379 SDCC_HOME
8380 \begin_inset LatexCommand \index{SDCC\_HOME}
8381
8382 \end_inset
8383
8384
8385 \series default
8386  Path, see section
8387 \begin_inset LatexCommand \ref{sub:Install-paths}
8388
8389 \end_inset
8390
8391 \SpecialChar ~
8392
8393 \begin_inset Quotes sld
8394 \end_inset
8395
8396  Install Paths
8397 \begin_inset Quotes srd
8398 \end_inset
8399
8400 .
8401 \layout List
8402 \labelwidthstring 00.00.0000
8403
8404
8405 \series bold
8406 SDCC_INCLUDE
8407 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8408
8409 \end_inset
8410
8411
8412 \series default
8413  Path, see section
8414 \begin_inset LatexCommand \ref{sub:Search-Paths}
8415
8416 \end_inset
8417
8418 \SpecialChar ~
8419
8420 \begin_inset Quotes sld
8421 \end_inset
8422
8423 Search Paths
8424 \begin_inset Quotes srd
8425 \end_inset
8426
8427 .
8428 \layout List
8429 \labelwidthstring 00.00.0000
8430
8431
8432 \series bold
8433 SDCC_LIB
8434 \begin_inset LatexCommand \index{SDCC\_LIB}
8435
8436 \end_inset
8437
8438
8439 \series default
8440  Path, see section
8441 \begin_inset LatexCommand \ref{sub:Search-Paths}
8442
8443 \end_inset
8444
8445 \SpecialChar ~
8446
8447 \begin_inset Quotes sld
8448 \end_inset
8449
8450 Search Paths
8451 \begin_inset Quotes srd
8452 \end_inset
8453
8454 ..
8455 \layout Standard
8456
8457 There are some more environment variables recognized by SDCC, but these
8458  are solely used for debugging purposes.
8459  They can change or disappear very quickly, and will never be documented.
8460 \layout Section
8461
8462 Storage Class Language Extensions
8463 \layout Subsection
8464
8465 MCS51/DS390 Storage Class
8466 \begin_inset LatexCommand \index{Storage class}
8467
8468 \end_inset
8469
8470  Language Extensions
8471 \layout Standard
8472
8473 In addition to the ANSI storage classes SDCC allows the following MCS51
8474  specific storage classes:
8475 \layout Subsubsection
8476
8477 data
8478 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8479
8480 \end_inset
8481
8482
8483 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
8484
8485 \end_inset
8486
8487  / near
8488 \begin_inset LatexCommand \index{near (storage class)}
8489
8490 \end_inset
8491
8492
8493 \begin_inset LatexCommand \index{\_\_near (storage class)}
8494
8495 \end_inset
8496
8497
8498 \layout Standard
8499
8500 This is the
8501 \series bold
8502 default
8503 \series default
8504  storage class for the Small Memory model (
8505 \emph on
8506 data
8507 \emph default
8508  and
8509 \emph on
8510 near
8511 \emph default
8512  can be used synonymously).
8513  Variables declared with this storage class will be allocated in the directly
8514  addressable portion of the internal RAM of a 8051, e.g.:
8515 \layout Verse
8516
8517
8518 \family typewriter
8519 data unsigned char test_data;
8520 \layout Standard
8521
8522 Writing 0x01 to this variable generates the assembly code:
8523 \layout Verse
8524
8525
8526 \family typewriter
8527 75*00 01\SpecialChar ~
8528 \SpecialChar ~
8529 \SpecialChar ~
8530 mov\SpecialChar ~
8531 \SpecialChar ~
8532 _test_data,#0x01
8533 \layout Subsubsection
8534
8535 xdata
8536 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8537
8538 \end_inset
8539
8540
8541 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
8542
8543 \end_inset
8544
8545  / far
8546 \begin_inset LatexCommand \index{far (storage class)}
8547
8548 \end_inset
8549
8550
8551 \begin_inset LatexCommand \index{\_\_far (storage class)}
8552
8553 \end_inset
8554
8555
8556 \layout Standard
8557
8558 Variables declared with this storage class will be placed in the external
8559  RAM.
8560  This is the
8561 \series bold
8562 default
8563 \series default
8564  storage class for the Large Memory model, e.g.:
8565 \layout Verse
8566
8567
8568 \family typewriter
8569 xdata unsigned char test_xdata;
8570 \layout Standard
8571
8572 Writing 0x01 to this variable generates the assembly code:
8573 \layout Verse
8574
8575
8576 \family typewriter
8577 90s00r00\SpecialChar ~
8578 \SpecialChar ~
8579 \SpecialChar ~
8580 mov\SpecialChar ~
8581 \SpecialChar ~
8582 dptr,#_test_xdata
8583 \newline
8584 74\SpecialChar ~
8585 01\SpecialChar ~
8586 \SpecialChar ~
8587 \SpecialChar ~
8588 \SpecialChar ~
8589 \SpecialChar ~
8590 \SpecialChar ~
8591 mov\SpecialChar ~
8592 \SpecialChar ~
8593 a,#0x01
8594 \newline
8595 F0\SpecialChar ~
8596 \SpecialChar ~
8597 \SpecialChar ~
8598 \SpecialChar ~
8599 \SpecialChar ~
8600 \SpecialChar ~
8601 \SpecialChar ~
8602 \SpecialChar ~
8603 \SpecialChar ~
8604 movx\SpecialChar ~
8605 @dptr,a
8606 \layout Subsubsection
8607
8608 idata
8609 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8610
8611 \end_inset
8612
8613
8614 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
8615
8616 \end_inset
8617
8618
8619 \layout Standard
8620
8621 Variables declared with this storage class will be allocated into the indirectly
8622  addressable portion of the internal ram of a 8051, e.g.:
8623 \layout Verse
8624
8625
8626 \family typewriter
8627 idata unsigned char test_idata;
8628 \layout Standard
8629
8630 Writing 0x01 to this variable generates the assembly code:
8631 \layout Verse
8632
8633
8634 \family typewriter
8635 78r00\SpecialChar ~
8636 \SpecialChar ~
8637 \SpecialChar ~
8638 \SpecialChar ~
8639 \SpecialChar ~
8640 \SpecialChar ~
8641 \SpecialChar ~
8642 mov\SpecialChar ~
8643 \SpecialChar ~
8644 r0,#_test_idata
8645 \newline
8646 76\SpecialChar ~
8647 01\SpecialChar ~
8648 \SpecialChar ~
8649 \SpecialChar ~
8650 \SpecialChar ~
8651 \SpecialChar ~
8652 \SpecialChar ~
8653 \SpecialChar ~
8654 mov\SpecialChar ~
8655 \SpecialChar ~
8656 @r0,#0x01
8657 \layout Standard
8658
8659 Please note, the first 128 byte of idata physically access the same RAM
8660  as the data memory.
8661  The original 8051 had 128 byte idata memory, nowadays most devices have
8662  256 byte idata memory.
8663  The stack
8664 \begin_inset LatexCommand \index{stack}
8665
8666 \end_inset
8667
8668  is located in idata memory.
8669 \layout Subsubsection
8670
8671 pdata
8672 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8673
8674 \end_inset
8675
8676
8677 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
8678
8679 \end_inset
8680
8681
8682 \layout Standard
8683
8684 Paged xdata access is just as straightforward as using the other addressing
8685  modes of a 8051.
8686  It is typically located at the start of xdata and has a maximum size of
8687  256 bytes.
8688  The following example writes 0x01 to the pdata variable.
8689  Please note, pdata access physically accesses xdata memory.
8690  The high byte of the address is determined by port P2
8691 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8692
8693 \end_inset
8694
8695 (or in case of some 8051 variants by a separate Special Function Register,
8696  see section
8697 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8698
8699 \end_inset
8700
8701 ).
8702 \layout Verse
8703
8704
8705 \family typewriter
8706 pdata unsigned char test_pdata;
8707 \layout Standard
8708
8709 Writing 0x01 to this variable generates the assembly code:
8710 \layout Verse
8711
8712
8713 \family typewriter
8714 78r00\SpecialChar ~
8715 \SpecialChar ~
8716 \SpecialChar ~
8717 \SpecialChar ~
8718 \SpecialChar ~
8719 \SpecialChar ~
8720 mov r0,#_test_pdata
8721 \newline
8722 74 01\SpecialChar ~
8723 \SpecialChar ~
8724 \SpecialChar ~
8725 \SpecialChar ~
8726 \SpecialChar ~
8727 \SpecialChar ~
8728 mov a,#0x01
8729 \newline
8730 F2\SpecialChar ~
8731 \SpecialChar ~
8732 \SpecialChar ~
8733 \SpecialChar ~
8734 \SpecialChar ~
8735 \SpecialChar ~
8736 \SpecialChar ~
8737 \SpecialChar ~
8738 \SpecialChar ~
8739 movx @r0,a
8740 \layout Standard
8741
8742 If the -
8743 \begin_inset ERT
8744 status Collapsed
8745
8746 \layout Standard
8747
8748 \backslash
8749 /
8750 \end_inset
8751
8752 -xstack
8753 \begin_inset LatexCommand \index{-\/-xstack}
8754
8755 \end_inset
8756
8757  option is used the pdata memory area is followed by the xstack memory area
8758  and the sum of their sizes is limited to 256 bytes.
8759 \layout Subsubsection
8760
8761 code
8762 \begin_inset LatexCommand \index{code}
8763
8764 \end_inset
8765
8766
8767 \begin_inset LatexCommand \index{\_\_code}
8768
8769 \end_inset
8770
8771
8772 \layout Standard
8773
8774 'Variables' declared with this storage class will be placed in the code
8775  memory:
8776 \layout Verse
8777
8778
8779 \family typewriter
8780 code unsigned char test_code;
8781 \layout Standard
8782
8783 Read access to this variable generates the assembly code:
8784 \layout Verse
8785
8786
8787 \family typewriter
8788 90s00r6F\SpecialChar ~
8789 \SpecialChar ~
8790 \SpecialChar ~
8791 mov dptr,#_test_code
8792 \newline
8793 E4\SpecialChar ~
8794 \SpecialChar ~
8795 \SpecialChar ~
8796 \SpecialChar ~
8797 \SpecialChar ~
8798 \SpecialChar ~
8799 \SpecialChar ~
8800 \SpecialChar ~
8801 \SpecialChar ~
8802 clr a
8803 \newline
8804 93\SpecialChar ~
8805 \SpecialChar ~
8806 \SpecialChar ~
8807 \SpecialChar ~
8808 \SpecialChar ~
8809 \SpecialChar ~
8810 \SpecialChar ~
8811 \SpecialChar ~
8812 \SpecialChar ~
8813 movc a,@a+dptr
8814 \layout Standard
8815
8816
8817 \family typewriter
8818 char
8819 \family default
8820  indexed arrays of characters in code memory can be accessed efficiently:
8821 \layout Verse
8822
8823
8824 \family typewriter
8825 code char test_array[] = {'c','h','e','a','p'};
8826 \layout Standard
8827
8828 Read access to this array using an 8-bit unsigned index generates the assembly
8829  code:
8830 \layout Verse
8831
8832
8833 \family typewriter
8834 E5*00\SpecialChar ~
8835 \SpecialChar ~
8836 \SpecialChar ~
8837 \SpecialChar ~
8838 \SpecialChar ~
8839 \SpecialChar ~
8840 mov a,_index
8841 \layout Verse
8842
8843
8844 \family typewriter
8845 90s00r41\SpecialChar ~
8846 \SpecialChar ~
8847 \SpecialChar ~
8848 mov dptr,#_test_array
8849 \layout Verse
8850
8851
8852 \family typewriter
8853 93\SpecialChar ~
8854 \SpecialChar ~
8855 \SpecialChar ~
8856 \SpecialChar ~
8857 \SpecialChar ~
8858 \SpecialChar ~
8859 \SpecialChar ~
8860 \SpecialChar ~
8861 \SpecialChar ~
8862 movc a,@a+dptr
8863 \layout Subsubsection
8864
8865 bit
8866 \begin_inset LatexCommand \index{bit}
8867
8868 \end_inset
8869
8870
8871 \begin_inset LatexCommand \index{\_\_bit}
8872
8873 \end_inset
8874
8875
8876 \layout Standard
8877
8878 This is a data-type and a storage class specifier.
8879  When a variable is declared as a bit, it is allocated into the bit addressable
8880  memory of 8051, e.g.:
8881 \layout Verse
8882
8883
8884 \family typewriter
8885 bit test_bit;
8886 \layout Standard
8887
8888 Writing 1 to this variable generates the assembly code:
8889 \layout Verse
8890
8891
8892 \family typewriter
8893 D2*00\SpecialChar ~
8894 \SpecialChar ~
8895 \SpecialChar ~
8896 \SpecialChar ~
8897 \SpecialChar ~
8898 \SpecialChar ~
8899 \SpecialChar ~
8900 setb\SpecialChar ~
8901 _test_bit
8902 \layout Standard
8903
8904 The bit addressable memory consists of 128 bits which are located from 0x20
8905  to 0x2f in data memory.
8906
8907 \newline
8908 Apart from this 8051 specific storage class most architectures support ANSI-C
8909  bitfields
8910 \begin_inset LatexCommand \index{bitfields}
8911
8912 \end_inset
8913
8914
8915 \begin_inset Foot
8916 collapsed false
8917
8918 \layout Standard
8919
8920 Not really meant as examples, but nevertheless showing what bitfields are
8921  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8922 \end_inset
8923
8924 .
8925  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
8926  signed modifier are implemented as unsigned.
8927 \layout Subsubsection
8928
8929 sfr
8930 \begin_inset LatexCommand \index{sfr}
8931
8932 \end_inset
8933
8934
8935 \begin_inset LatexCommand \index{\_\_sfr}
8936
8937 \end_inset
8938
8939  / sfr16
8940 \begin_inset LatexCommand \index{sfr16}
8941
8942 \end_inset
8943
8944
8945 \begin_inset LatexCommand \index{\_\_sfr16}
8946
8947 \end_inset
8948
8949  / sfr32
8950 \begin_inset LatexCommand \index{sfr32}
8951
8952 \end_inset
8953
8954
8955 \begin_inset LatexCommand \index{\_\_sfr32}
8956
8957 \end_inset
8958
8959  / sbit
8960 \begin_inset LatexCommand \index{\_\_sbit}
8961
8962 \end_inset
8963
8964
8965 \layout Standard
8966
8967 Like the bit keyword,
8968 \emph on
8969 sfr / sfr16 / sfr32 / sbit
8970 \emph default
8971 signify both a data-type and storage class, they are used to describe the
8972
8973 \emph on
8974 s
8975 \emph default
8976 pecial
8977 \emph on
8978 f
8979 \emph default
8980 unction
8981 \emph on
8982 r
8983 \emph default
8984 egisters and
8985 \emph on
8986 s
8987 \emph default
8988 pecial
8989 \emph on
8990 bit
8991 \emph default
8992  variables of a 8051, eg:
8993 \layout Verse
8994
8995
8996 \family typewriter
8997 sfr at
8998 \begin_inset LatexCommand \index{at}
8999
9000 \end_inset
9001
9002
9003 \begin_inset LatexCommand \index{\_\_at}
9004
9005 \end_inset
9006
9007  0x80 P0;\SpecialChar ~
9008  /* special function register P0 at location 0x80 */
9009 \newline
9010 /* 16 bit special function register combination for timer 0 */
9011 \newline
9012 /* with the high byte at location 0x8C and the low byte at location 0x8A
9013  */
9014 \newline
9015 sfr16 at
9016 \begin_inset LatexCommand \index{at}
9017
9018 \end_inset
9019
9020
9021 \begin_inset LatexCommand \index{\_\_at}
9022
9023 \end_inset
9024
9025  0x8C8A TMR0;
9026 \newline
9027 sbit at 0xd7 CY; /* CY (Carry Flag
9028 \begin_inset LatexCommand \index{Flags}
9029
9030 \end_inset
9031
9032
9033 \begin_inset LatexCommand \index{Carry flag}
9034
9035 \end_inset
9036
9037 ) */
9038 \layout Standard
9039
9040 Special function registers which are located on an address dividable by
9041  8 are bit-addressable, an
9042 \emph on
9043  sbit
9044 \emph default
9045  addresses a specific bit within these sfr.
9046 \newline
9047 16 Bit and 32 bit special function register combinations which require a
9048  certain access order are better not declared using
9049 \emph on
9050 sfr16
9051 \emph default
9052  or
9053 \emph on
9054 sfr32.
9055
9056 \emph default
9057  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9058  this is not guaranteed.
9059 \layout Subsubsection
9060
9061 Pointers
9062 \begin_inset LatexCommand \index{Pointer}
9063
9064 \end_inset
9065
9066  to MCS51/DS390 specific memory spaces
9067 \layout Standard
9068
9069 SDCC allows (via language extensions) pointers to explicitly point to any
9070  of the memory spaces
9071 \begin_inset LatexCommand \index{Memory model}
9072
9073 \end_inset
9074
9075  of the 8051.
9076  In addition to the explicit pointers, the compiler uses (by default) generic
9077  pointers which can be used to point to any of the memory spaces.
9078 \newline
9079
9080 \newline
9081 Pointer declaration examples:
9082 \layout Verse
9083
9084
9085 \family typewriter
9086 /* pointer physically in internal ram pointing to object in external ram
9087  */
9088 \newline
9089 xdata unsigned char * data p;
9090 \newline
9091
9092 \newline
9093 /* pointer physically in external ram pointing to object in internal ram
9094  */
9095 \newline
9096 data unsigned char * xdata p;
9097 \newline
9098
9099 \newline
9100 /* pointer physically in code rom pointing to data in xdata space */
9101 \newline
9102 xdata unsigned char * code p;
9103 \newline
9104
9105 \newline
9106 /* pointer physically in code space pointing to data in code space */
9107 \newline
9108 code unsigned char * code p;
9109 \newline
9110
9111 \newline
9112 /* the following is a generic pointer physically located in xdata space
9113  */
9114 \newline
9115 char * xdata p;
9116 \newline
9117
9118 \newline
9119 /* the following is a function pointer physically located in data space
9120  */
9121 \newline
9122 char (* data fp)(void);
9123 \layout Standard
9124
9125 Well you get the idea.
9126
9127 \newline
9128
9129 \newline
9130 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9131 \emph on
9132 generic
9133 \emph default
9134  pointers.
9135
9136 \size small
9137
9138 \newline
9139
9140 \newline
9141
9142 \size default
9143 The highest order byte of the
9144 \emph on
9145 generic
9146 \emph default
9147  pointers contains the data space information.
9148  Assembler support routines are called whenever data is stored or retrieved
9149  using
9150 \emph on
9151 generic
9152 \emph default
9153  pointers.
9154  These are useful for developing reusable library
9155 \begin_inset LatexCommand \index{Libraries}
9156
9157 \end_inset
9158
9159  routines.
9160  Explicitly specifying the pointer type will generate the most efficient
9161  code.
9162 \layout Subsubsection
9163
9164 Notes on MCS51 memory
9165 \begin_inset LatexCommand \index{MCS51 memory}
9166
9167 \end_inset
9168
9169  layout
9170 \layout Standard
9171
9172 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9173  RAM memory which is structured as follows:
9174 \newline
9175
9176 \newline
9177 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9178
9179 \newline
9180 - Bytes 20-2F - 16 bytes to hold 128 bit
9181 \begin_inset LatexCommand \index{bit}
9182
9183 \end_inset
9184
9185  variables and,
9186 \newline
9187 - Bytes 30-7F - 80 bytes for general purpose use.
9188 \newline
9189
9190 \layout Standard
9191
9192 Additionally some members of the MCS51 family may have up to 128 bytes of
9193  additional, indirectly addressable, internal RAM memory (
9194 \emph on
9195 idata
9196 \emph default
9197
9198 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9199
9200 \end_inset
9201
9202
9203 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9204
9205 \end_inset
9206
9207 ).
9208  Furthermore, some chips may have some built in external memory (
9209 \emph on
9210 xdata
9211 \emph default
9212
9213 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9214
9215 \end_inset
9216
9217
9218 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9219
9220 \end_inset
9221
9222 ) which should not be confused with the internal, directly addressable RAM
9223  memory (
9224 \emph on
9225 data
9226 \emph default
9227
9228 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9229
9230 \end_inset
9231
9232
9233 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9234
9235 \end_inset
9236
9237 ).
9238  Sometimes this built in
9239 \emph on
9240 xdata
9241 \emph default
9242  memory has to be activated before using it (you can probably find this
9243  information on the datasheet of the microcontroller your are using, see
9244  also section
9245 \begin_inset LatexCommand \ref{sub:Startup-Code}
9246
9247 \end_inset
9248
9249 \SpecialChar ~
9250 Startup-Code).
9251 \layout Standard
9252
9253 Normally SDCC will only use the first bank
9254 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9255
9256 \end_inset
9257
9258  of registers (register bank 0), but it is possible to specify that other
9259  banks of registers (keyword
9260 \emph on
9261 using
9262 \emph default
9263
9264 \emph on
9265
9266 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9267
9268 \end_inset
9269
9270
9271 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9272
9273 \end_inset
9274
9275
9276 \emph default
9277 ) should be used in interrupt
9278 \begin_inset LatexCommand \index{interrupt}
9279
9280 \end_inset
9281
9282
9283 \begin_inset LatexCommand \index{\_\_interrupt}
9284
9285 \end_inset
9286
9287  routines.
9288  By default, the compiler will place the stack after the last byte of allocated
9289  memory for variables.
9290  For example, if the first 2 banks of registers are used, and only four
9291  bytes are used for
9292 \emph on
9293 data
9294 \emph default
9295  variables, it will position the base of the internal stack at address 20
9296  (0x14).
9297  This implies that as the stack
9298 \begin_inset LatexCommand \index{stack}
9299
9300 \end_inset
9301
9302  grows, it will use up the remaining register banks, and the 16 bytes used
9303  by the 128 bit variables, and 80 bytes for general purpose use.
9304  If any bit variables are used, the data variables will be placed in unused
9305  register banks and after the byte holding the last bit variable.
9306  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9307  (two bytes used),
9308 \emph on
9309 data
9310 \emph default
9311  variables will be placed starting from address 0x10 to 0x20 and continue
9312  at address 0x22.
9313  You can also use -
9314 \begin_inset ERT
9315 status Collapsed
9316
9317 \layout Standard
9318
9319 \backslash
9320 /
9321 \end_inset
9322
9323 -data-loc
9324 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
9325
9326 \end_inset
9327
9328  to specify the start address of the
9329 \emph on
9330 data
9331 \emph default
9332  and -
9333 \begin_inset ERT
9334 status Collapsed
9335
9336 \layout Standard
9337
9338 \backslash
9339 /
9340 \end_inset
9341
9342 -iram-size
9343 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
9344
9345 \end_inset
9346
9347  to specify the size of the total internal RAM (
9348 \emph on
9349 data
9350 \emph default
9351 +
9352 \emph on
9353 idata
9354 \emph default
9355 ).
9356
9357 \layout Standard
9358
9359 By default the 8051 linker will place the stack after the last byte of (i)data
9360  variables.
9361  Option -
9362 \begin_inset ERT
9363 status Collapsed
9364
9365 \layout Standard
9366
9367 \backslash
9368 /
9369 \end_inset
9370
9371 -stack-loc
9372 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
9373
9374 \end_inset
9375
9376  allows you to specify the start of the stack, i.e.
9377  you could start it after any data in the general purpose area.
9378  If your microcontroller has additional indirectly addressable internal
9379  RAM (
9380 \emph on
9381 idata
9382 \emph default
9383 ) you can place the stack on it.
9384  You may also need to use -
9385 \begin_inset ERT
9386 status Collapsed
9387
9388 \layout Standard
9389
9390 \backslash
9391 /
9392 \end_inset
9393
9394 -xdata-loc
9395 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
9396
9397 \end_inset
9398
9399  to set the start address of the external RAM (
9400 \emph on
9401 xdata
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 -xram-size
9414 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
9415
9416 \end_inset
9417
9418  to specify its size.
9419  Same goes for the code memory, using -
9420 \begin_inset ERT
9421 status Collapsed
9422
9423 \layout Standard
9424
9425 \backslash
9426 /
9427 \end_inset
9428
9429 -code-loc
9430 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
9431
9432 \end_inset
9433
9434  and -
9435 \begin_inset ERT
9436 status Collapsed
9437
9438 \layout Standard
9439
9440 \backslash
9441 /
9442 \end_inset
9443
9444 -code-size
9445 \begin_inset LatexCommand \index{-\/-code-size <Value>}
9446
9447 \end_inset
9448
9449 .
9450  If in doubt, don't specify any options and see if the resulting memory
9451  layout is appropriate, then you can adjust it.
9452 \layout Standard
9453
9454 The linker generates two files with memory allocation information.
9455  The first, with extension .map
9456 \begin_inset LatexCommand \index{<file>.map}
9457
9458 \end_inset
9459
9460  shows all the variables and segments.
9461  The second with extension .mem
9462 \begin_inset LatexCommand \index{<file>.mem}
9463
9464 \end_inset
9465
9466  shows the final memory layout.
9467  The linker will complain either if memory segments overlap, there is not
9468  enough memory, or there is not enough space for stack.
9469  If you get any linking warnings and/or errors related to stack or segments
9470  allocation, take a look at either the .map or .mem files to find out what
9471  the problem is.
9472  The .mem file may even suggest a solution to the problem.
9473 \layout Subsection
9474
9475 Z80/Z180 Storage Class
9476 \begin_inset LatexCommand \index{Storage class}
9477
9478 \end_inset
9479
9480  Language Extensions
9481 \layout Subsubsection
9482
9483 sfr
9484 \begin_inset LatexCommand \index{sfr}
9485
9486 \end_inset
9487
9488
9489 \begin_inset LatexCommand \index{\_\_sfr}
9490
9491 \end_inset
9492
9493  (in/out to 8-bit addresses)
9494 \layout Standard
9495
9496 The Z80
9497 \begin_inset LatexCommand \index{Z80}
9498
9499 \end_inset
9500
9501  family has separate address spaces for memory and
9502 \emph on
9503 i
9504 \emph default
9505 nput/
9506 \emph on
9507 o
9508 \emph default
9509 utput memory.
9510  I/O memory
9511 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9512
9513 \end_inset
9514
9515  is accessed with special instructions, e.g.:
9516 \layout Verse
9517
9518
9519 \family typewriter
9520 sfr at 0x78 IoPort;\SpecialChar ~
9521 \SpecialChar ~
9522 /* define a var in I/O space at 78h called IoPort */
9523
9524 \layout Standard
9525
9526 Writing 0x01 to this variable generates the assembly code:
9527 \layout Verse
9528
9529
9530 \family typewriter
9531 3E 01\SpecialChar ~
9532 \SpecialChar ~
9533 \SpecialChar ~
9534 \SpecialChar ~
9535 \SpecialChar ~
9536 \SpecialChar ~
9537 ld a,#0x01
9538 \newline
9539 D3 78\SpecialChar ~
9540 \SpecialChar ~
9541 \SpecialChar ~
9542 \SpecialChar ~
9543 \SpecialChar ~
9544 \SpecialChar ~
9545 out (_IoPort),a
9546 \layout Subsubsection
9547
9548 banked sfr
9549 \begin_inset LatexCommand \index{sfr}
9550
9551 \end_inset
9552
9553
9554 \begin_inset LatexCommand \index{\_\_sfr}
9555
9556 \end_inset
9557
9558  (in/out to 16-bit addresses)
9559 \layout Standard
9560
9561 The keyword
9562 \emph on
9563 banked
9564 \emph default
9565  is used to support 16 bit addresses in I/O memory e.g.:
9566 \layout Verse
9567
9568
9569 \family typewriter
9570 sfr banked at
9571 \begin_inset LatexCommand \index{at}
9572
9573 \end_inset
9574
9575
9576 \begin_inset LatexCommand \index{\_\_at}
9577
9578 \end_inset
9579
9580  0x123 IoPort;
9581 \layout Standard
9582
9583 Writing 0x01 to this variable generates the assembly code:
9584 \layout Verse
9585
9586
9587 \family typewriter
9588 01 23 01\SpecialChar ~
9589 \SpecialChar ~
9590 \SpecialChar ~
9591 ld bc,#_IoPort
9592 \newline
9593 3E 01\SpecialChar ~
9594 \SpecialChar ~
9595 \SpecialChar ~
9596 \SpecialChar ~
9597 \SpecialChar ~
9598 \SpecialChar ~
9599 ld a,#0x01
9600 \newline
9601 ED 79\SpecialChar ~
9602 \SpecialChar ~
9603 \SpecialChar ~
9604 \SpecialChar ~
9605 \SpecialChar ~
9606 \SpecialChar ~
9607 out (c),a
9608 \layout Subsubsection
9609
9610 sfr
9611 \begin_inset LatexCommand \index{sfr}
9612
9613 \end_inset
9614
9615
9616 \begin_inset LatexCommand \index{\_\_sfr}
9617
9618 \end_inset
9619
9620  (in0/out0 to 8 bit addresses on Z180
9621 \begin_inset LatexCommand \index{Z180}
9622
9623 \end_inset
9624
9625 /HD64180
9626 \begin_inset LatexCommand \index{HD64180}
9627
9628 \end_inset
9629
9630 )
9631 \layout Standard
9632
9633 The compiler option -
9634 \begin_inset ERT
9635 status Collapsed
9636
9637 \layout Standard
9638
9639 \backslash
9640 /
9641 \end_inset
9642
9643 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9644 portmode
9645 \begin_inset LatexCommand \index{\#pragma portmode}
9646
9647 \end_inset
9648
9649 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9650 ns
9651 \family typewriter
9652 in0/out0
9653 \family default
9654  instead of
9655 \family typewriter
9656 in/out
9657 \family default
9658 .
9659  If you include the file z180.h this will be set automatically.
9660 \layout Subsection
9661
9662 HC08 Storage Class
9663 \begin_inset LatexCommand \index{Storage class}
9664
9665 \end_inset
9666
9667  Language Extensions
9668 \layout Subsubsection
9669
9670 data
9671 \begin_inset LatexCommand \index{data (hc08 storage class)}
9672
9673 \end_inset
9674
9675
9676 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
9677
9678 \end_inset
9679
9680
9681 \layout Standard
9682
9683 The data storage class declares a variable that resides in the first 256
9684  bytes of memory (the direct page).
9685  The HC08 is most efficient at accessing variables (especially pointers)
9686  stored here.
9687 \layout Subsubsection
9688
9689 xdata
9690 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
9691
9692 \end_inset
9693
9694
9695 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
9696
9697 \end_inset
9698
9699
9700 \layout Standard
9701
9702 The xdata storage class declares a variable that can reside anywhere in
9703  memory.
9704  This is the default if no storage class is specified.
9705
9706 \layout Section
9707
9708 Absolute Addressing
9709 \begin_inset LatexCommand \index{Absolute addressing}
9710
9711 \end_inset
9712
9713
9714 \layout Standard
9715
9716 Data items can be assigned an absolute address with the
9717 \emph on
9718 at
9719 \begin_inset LatexCommand \index{at}
9720
9721 \end_inset
9722
9723
9724 \begin_inset LatexCommand \index{\_\_at}
9725
9726 \end_inset
9727
9728  <address>
9729 \emph default
9730  keyword, in addition to a storage class, e.g.:
9731 \layout Verse
9732
9733
9734 \family typewriter
9735 xdata
9736 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9737
9738 \end_inset
9739
9740
9741 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9742
9743 \end_inset
9744
9745  at
9746 \begin_inset LatexCommand \index{at}
9747
9748 \end_inset
9749
9750
9751 \begin_inset LatexCommand \index{\_\_at}
9752
9753 \end_inset
9754
9755  0x7ffe unsigned int chksum;
9756 \layout Standard
9757
9758 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9759  of the external ram.
9760  The compiler does
9761 \emph on
9762 not
9763 \emph default
9764  reserve any space for variables declared in this way (they are implemented
9765  with an equate in the assembler).
9766  Thus it is left to the programmer to make sure there are no overlaps with
9767  other variables that are declared without the absolute address.
9768  The assembler listing file (.lst
9769 \begin_inset LatexCommand \index{<file>.lst}
9770
9771 \end_inset
9772
9773 ) and the linker output files (.rst
9774 \begin_inset LatexCommand \index{<file>.rst}
9775
9776 \end_inset
9777
9778 ) and (.map
9779 \begin_inset LatexCommand \index{<file>.map}
9780
9781 \end_inset
9782
9783 ) are good places to look for such overlaps.
9784  Variables with an absolute address are
9785 \emph on
9786 not
9787 \emph default
9788  initialized
9789 \begin_inset LatexCommand \index{Variable initialization}
9790
9791 \end_inset
9792
9793 .
9794 \layout Standard
9795
9796 In case of memory mapped I/O devices the keyword
9797 \emph on
9798 volatile
9799 \emph default
9800  has to be used to tell the compiler that accesses might not be removed:
9801 \layout Verse
9802
9803
9804 \family typewriter
9805 volatile
9806 \begin_inset LatexCommand \index{volatile}
9807
9808 \end_inset
9809
9810  xdata
9811 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9812
9813 \end_inset
9814
9815  at
9816 \begin_inset LatexCommand \index{at}
9817
9818 \end_inset
9819
9820  0x8000 unsigned char PORTA_8255;
9821 \layout Standard
9822
9823 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9824 r) array
9825 \family typewriter
9826 \size footnotesize
9827
9828 \begin_inset LatexCommand \index{Aligned array}
9829
9830 \end_inset
9831
9832
9833 \family default
9834 \size default
9835  starts at a block (256 byte) boundary
9836 \begin_inset LatexCommand \index{block boundary}
9837
9838 \end_inset
9839
9840  (section
9841 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9842
9843 \end_inset
9844
9845  has an example).
9846 \newline
9847 Absolute addresses can be specified for variables in all storage classes,
9848  e.g.:
9849 \layout Verse
9850
9851
9852 \family typewriter
9853 bit
9854 \begin_inset LatexCommand \index{bit}
9855
9856 \end_inset
9857
9858  at
9859 \begin_inset LatexCommand \index{at}
9860
9861 \end_inset
9862
9863  0x02 bvar;
9864 \layout Standard
9865
9866 The above example will allocate the variable at offset 0x02 in the bit-addressab
9867 le space.
9868  There is no real advantage to assigning absolute addresses to variables
9869  in this manner, unless you want strict control over all the variables allocated.
9870  One possible use would be to write hardware portable code.
9871  For example, if you have a routine that uses one or more of the microcontroller
9872  I/O pins, and such pins are different for two different hardwares, you
9873  can declare the I/O pins in your routine using:
9874 \layout Verse
9875
9876
9877 \family typewriter
9878 extern volatile
9879 \begin_inset LatexCommand \index{volatile}
9880
9881 \end_inset
9882
9883  bit MOSI;\SpecialChar ~
9884 \SpecialChar ~
9885 \SpecialChar ~
9886 \SpecialChar ~
9887 /* master out, slave in */
9888 \newline
9889 extern volatile bit MISO;\SpecialChar ~
9890 \SpecialChar ~
9891 \SpecialChar ~
9892 \SpecialChar ~
9893 /* master in, slave out */
9894 \newline
9895 extern volatile bit MCLK;\SpecialChar ~
9896 \SpecialChar ~
9897 \SpecialChar ~
9898 \SpecialChar ~
9899 /* master clock */
9900 \newline
9901
9902 \newline
9903 /* Input and Output of a byte on a 3-wire serial bus.
9904 \newline
9905 \SpecialChar ~
9906 \SpecialChar ~
9907 \SpecialChar ~
9908 If needed adapt polarity of clock, polarity of data and bit order
9909 \newline
9910 \SpecialChar ~
9911 */
9912 \newline
9913 unsigned char spi_io(unsigned char out_byte)
9914 \newline
9915 {
9916 \newline
9917 \SpecialChar ~
9918 \SpecialChar ~
9919 \SpecialChar ~
9920 \SpecialChar ~
9921 unsigned char i=8;
9922 \newline
9923 \SpecialChar ~
9924 \SpecialChar ~
9925 \SpecialChar ~
9926 \SpecialChar ~
9927 do {
9928 \newline
9929 \SpecialChar ~
9930 \SpecialChar ~
9931 \SpecialChar ~
9932 \SpecialChar ~
9933 \SpecialChar ~
9934 \SpecialChar ~
9935 \SpecialChar ~
9936 \SpecialChar ~
9937 MOSI = out_byte & 0x80;
9938 \newline
9939 \SpecialChar ~
9940 \SpecialChar ~
9941 \SpecialChar ~
9942 \SpecialChar ~
9943 \SpecialChar ~
9944 \SpecialChar ~
9945 \SpecialChar ~
9946 \SpecialChar ~
9947 out_byte <<= 1;
9948 \newline
9949 \SpecialChar ~
9950 \SpecialChar ~
9951 \SpecialChar ~
9952 \SpecialChar ~
9953 \SpecialChar ~
9954 \SpecialChar ~
9955 \SpecialChar ~
9956 \SpecialChar ~
9957 MCLK = 1;
9958 \newline
9959 \SpecialChar ~
9960 \SpecialChar ~
9961 \SpecialChar ~
9962 \SpecialChar ~
9963 \SpecialChar ~
9964 \SpecialChar ~
9965 \SpecialChar ~
9966 \SpecialChar ~
9967 /* _asm nop _endasm; */\SpecialChar ~
9968 \SpecialChar ~
9969 \SpecialChar ~
9970 \SpecialChar ~
9971 \SpecialChar ~
9972 \SpecialChar ~
9973 \SpecialChar ~
9974 \SpecialChar ~
9975 /* for slow peripherals */
9976 \newline
9977 \SpecialChar ~
9978 \SpecialChar ~
9979 \SpecialChar ~
9980 \SpecialChar ~
9981 \SpecialChar ~
9982 \SpecialChar ~
9983 \SpecialChar ~
9984 \SpecialChar ~
9985 if(MISO)
9986 \newline
9987 \SpecialChar ~
9988 \SpecialChar ~
9989 \SpecialChar ~
9990 \SpecialChar ~
9991 \SpecialChar ~
9992 \SpecialChar ~
9993 \SpecialChar ~
9994 \SpecialChar ~
9995 \SpecialChar ~
9996 \SpecialChar ~
9997 \SpecialChar ~
9998 \SpecialChar ~
9999 out_byte += 1;
10000 \newline
10001 \SpecialChar ~
10002 \SpecialChar ~
10003 \SpecialChar ~
10004 \SpecialChar ~
10005 \SpecialChar ~
10006 \SpecialChar ~
10007 \SpecialChar ~
10008 \SpecialChar ~
10009 MCLK = 0;
10010 \newline
10011 \SpecialChar ~
10012 \SpecialChar ~
10013 \SpecialChar ~
10014 \SpecialChar ~
10015 } while(--i);
10016 \newline
10017 \SpecialChar ~
10018 \SpecialChar ~
10019 \SpecialChar ~
10020 \SpecialChar ~
10021 return out_byte;
10022 \newline
10023 }
10024 \layout Standard
10025
10026 Then, someplace in the code for the first hardware you would use
10027 \layout Verse
10028
10029
10030 \family typewriter
10031 bit at
10032 \begin_inset LatexCommand \index{at}
10033
10034 \end_inset
10035
10036
10037 \begin_inset LatexCommand \index{\_\_at}
10038
10039 \end_inset
10040
10041  0x80 MOSI;\SpecialChar ~
10042 \SpecialChar ~
10043 \SpecialChar ~
10044 \SpecialChar ~
10045 /* I/O port 0, bit 0 */
10046 \newline
10047 bit at 0x81 MISO;\SpecialChar ~
10048 \SpecialChar ~
10049 \SpecialChar ~
10050 \SpecialChar ~
10051 /* I/O port 0, bit 1 */
10052 \newline
10053 bit at 0x82 MCLK;\SpecialChar ~
10054 \SpecialChar ~
10055 \SpecialChar ~
10056 \SpecialChar ~
10057 /* I/O port 0, bit 2 */
10058 \layout Standard
10059
10060 Similarly, for the second hardware you would use
10061 \layout Verse
10062
10063
10064 \family typewriter
10065 bit at 0x83 MOSI;\SpecialChar ~
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 \SpecialChar ~
10069 /* I/O port 0, bit 3 */
10070 \newline
10071 bit at 0x91 MISO;\SpecialChar ~
10072 \SpecialChar ~
10073 \SpecialChar ~
10074 \SpecialChar ~
10075 /* I/O port 1, bit 1 */
10076 \newline
10077 bit
10078 \begin_inset LatexCommand \index{bit}
10079
10080 \end_inset
10081
10082  at 0x92 MCLK;\SpecialChar ~
10083 \SpecialChar ~
10084 \SpecialChar ~
10085 \SpecialChar ~
10086 /* I/O port 1, bit 2 */
10087 \layout Standard
10088
10089 and you can use the same hardware dependent routine without changes, as
10090  for example in a library.
10091  This is somehow similar to sbit, but only one absolute address has to be
10092  specified in the whole project.
10093 \layout Section
10094
10095 Parameters
10096 \begin_inset LatexCommand \index{Parameters}
10097
10098 \end_inset
10099
10100
10101 \begin_inset LatexCommand \index{function parameter}
10102
10103 \end_inset
10104
10105  & Local Variables
10106 \begin_inset LatexCommand \index{local variables}
10107
10108 \end_inset
10109
10110
10111 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10112
10113 \end_inset
10114
10115
10116 \layout Standard
10117
10118 Automatic (local) variables and parameters to functions can either be placed
10119  on the stack or in data-space.
10120  The default action of the compiler is to place these variables in the internal
10121  RAM (for small model) or external RAM (for large model).
10122  This in fact makes them similar to
10123 \emph on
10124 static
10125 \begin_inset LatexCommand \index{static}
10126
10127 \end_inset
10128
10129
10130 \emph default
10131  so by default functions are non-reentrant
10132 \begin_inset LatexCommand \index{reentrant}
10133
10134 \end_inset
10135
10136 .
10137
10138 \newline
10139
10140 \newline
10141 They can be placed on the stack
10142 \begin_inset LatexCommand \index{stack}
10143
10144 \end_inset
10145
10146  by using the
10147 \emph on
10148  -
10149 \begin_inset ERT
10150 status Collapsed
10151
10152 \layout Standard
10153
10154 \backslash
10155 /
10156 \end_inset
10157
10158 -stack-auto
10159 \begin_inset LatexCommand \index{-\/-stack-auto}
10160
10161 \end_inset
10162
10163
10164 \emph default
10165  option, by using
10166 \emph on
10167 #pragma\SpecialChar ~
10168 stackauto
10169 \emph default
10170
10171 \begin_inset LatexCommand \index{\#pragma stackauto}
10172
10173 \end_inset
10174
10175  or by using the
10176 \emph on
10177 reentrant
10178 \begin_inset LatexCommand \index{reentrant}
10179
10180 \end_inset
10181
10182
10183 \emph default
10184  keyword in the function declaration, e.g.:
10185 \layout Verse
10186
10187
10188 \family typewriter
10189 unsigned char foo(char i) reentrant
10190 \newline
10191 {
10192 \newline
10193 \SpecialChar ~
10194 \SpecialChar ~
10195 \SpecialChar ~
10196 \SpecialChar ~
10197 ...
10198
10199 \newline
10200 }
10201 \layout Standard
10202
10203 Since stack space on 8051 is limited, the
10204 \emph on
10205 reentrant
10206 \emph default
10207 keyword or the
10208 \emph on
10209  -
10210 \begin_inset ERT
10211 status Collapsed
10212
10213 \layout Standard
10214
10215 \backslash
10216 /
10217 \end_inset
10218
10219 -stack-auto
10220 \emph default
10221  option should be used sparingly.
10222  Note that the reentrant keyword just means that the parameters & local
10223  variables will be allocated to the stack, it
10224 \emph on
10225 does not
10226 \emph default
10227  mean that the function is register bank
10228 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10229
10230 \end_inset
10231
10232  independent.
10233 \newline
10234
10235 \newline
10236 Local variables
10237 \begin_inset LatexCommand \index{local variables}
10238
10239 \end_inset
10240
10241  can be assigned storage classes and absolute
10242 \begin_inset LatexCommand \index{Absolute addressing}
10243
10244 \end_inset
10245
10246  addresses, e.g.:
10247 \layout Verse
10248
10249
10250 \family typewriter
10251 unsigned char foo()
10252 \newline
10253 {
10254 \newline
10255 \SpecialChar ~
10256 \SpecialChar ~
10257 \SpecialChar ~
10258 \SpecialChar ~
10259 xdata unsigned char i;
10260 \newline
10261 \SpecialChar ~
10262 \SpecialChar ~
10263 \SpecialChar ~
10264 \SpecialChar ~
10265 bit bvar;
10266 \newline
10267 \SpecialChar ~
10268 \SpecialChar ~
10269 \SpecialChar ~
10270 \SpecialChar ~
10271 data at
10272 \begin_inset LatexCommand \index{at}
10273
10274 \end_inset
10275
10276  0x31 unsigned char j;
10277 \newline
10278 \SpecialChar ~
10279 \SpecialChar ~
10280 \SpecialChar ~
10281 \SpecialChar ~
10282 ...
10283
10284 \newline
10285 }
10286 \layout Standard
10287
10288 In the above example the variable
10289 \emph on
10290 i
10291 \emph default
10292  will be allocated in the external ram,
10293 \emph on
10294 bvar
10295 \emph default
10296  in bit addressable space and
10297 \emph on
10298  j
10299 \emph default
10300  in internal ram.
10301  When compiled with
10302 \emph on
10303 -
10304 \begin_inset ERT
10305 status Collapsed
10306
10307 \layout Standard
10308
10309 \backslash
10310 /
10311 \end_inset
10312
10313 -stack-auto
10314 \emph default
10315  or when a function is declared as
10316 \emph on
10317 reentrant
10318 \emph default
10319  this should only be done for static variables.
10320 \layout Standard
10321
10322 Parameters
10323 \begin_inset LatexCommand \index{function parameter}
10324
10325 \end_inset
10326
10327  however are not allowed any storage class
10328 \begin_inset LatexCommand \index{Storage class}
10329
10330 \end_inset
10331
10332 , (storage classes for parameters will be ignored), their allocation is
10333  governed by the memory model in use, and the reentrancy options.
10334 \layout Section
10335
10336 Overlaying
10337 \begin_inset LatexCommand \label{sub:Overlaying}
10338
10339 \end_inset
10340
10341
10342 \begin_inset LatexCommand \index{Overlaying}
10343
10344 \end_inset
10345
10346
10347 \layout Standard
10348
10349 For non-reentrant
10350 \begin_inset LatexCommand \index{reentrant}
10351
10352 \end_inset
10353
10354  functions SDCC will try to reduce internal ram space usage by overlaying
10355  parameters and local variables of a function (if possible).
10356  Parameters and local variables
10357 \begin_inset LatexCommand \index{local variables}
10358
10359 \end_inset
10360
10361  of a function will be allocated to an overlayable segment if the function
10362  has
10363 \emph on
10364 no other function calls and the function is non-reentrant and the memory
10365  model
10366 \begin_inset LatexCommand \index{Memory model}
10367
10368 \end_inset
10369
10370  is small.
10371
10372 \emph default
10373  If an explicit storage class
10374 \begin_inset LatexCommand \index{Storage class}
10375
10376 \end_inset
10377
10378  is specified for a local variable, it will NOT be overlayed.
10379 \layout Standard
10380
10381 Note that the compiler (not the linkage editor) makes the decision for overlayin
10382 g the data items.
10383  Functions that are called from an interrupt service routine should be preceded
10384  by a #pragma\SpecialChar ~
10385 nooverlay
10386 \begin_inset LatexCommand \index{\#pragma nooverlay}
10387
10388 \end_inset
10389
10390  if they are not reentrant.
10391 \layout Standard
10392
10393 Also note that the compiler does not do any processing of inline assembler
10394  code, so the compiler might incorrectly assign local variables and parameters
10395  of a function into the overlay segment if the inline assembler code calls
10396  other c-functions that might use the overlay.
10397  In that case the #pragma\SpecialChar ~
10398 nooverlay should be used.
10399 \layout Standard
10400
10401 Parameters and local variables of functions that contain 16 or 32 bit multiplica
10402 tion
10403 \begin_inset LatexCommand \index{Multiplication}
10404
10405 \end_inset
10406
10407  or division
10408 \begin_inset LatexCommand \index{Division}
10409
10410 \end_inset
10411
10412  will NOT be overlayed since these are implemented using external functions,
10413  e.g.:
10414 \layout Verse
10415
10416
10417 \family typewriter
10418 #pragma save
10419 \newline
10420 #pragma nooverlay
10421 \begin_inset LatexCommand \index{\#pragma nooverlay}
10422
10423 \end_inset
10424
10425
10426 \newline
10427 void set_error(unsigned char errcd)
10428 \newline
10429 {
10430 \newline
10431 \SpecialChar ~
10432 \SpecialChar ~
10433 \SpecialChar ~
10434 \SpecialChar ~
10435 P3 = errcd;
10436 \newline
10437 }
10438 \newline
10439 #pragma restore
10440 \newline
10441
10442 \newline
10443 void some_isr () interrupt
10444 \begin_inset LatexCommand \index{interrupt}
10445
10446 \end_inset
10447
10448  2
10449 \newline
10450 {
10451 \newline
10452 \SpecialChar ~
10453 \SpecialChar ~
10454 \SpecialChar ~
10455 \SpecialChar ~
10456 ...
10457 \newline
10458 \SpecialChar ~
10459 \SpecialChar ~
10460 \SpecialChar ~
10461 \SpecialChar ~
10462 set_error(10);
10463 \newline
10464 \SpecialChar ~
10465 \SpecialChar ~
10466 \SpecialChar ~
10467 \SpecialChar ~
10468 ...
10469
10470 \newline
10471 }
10472 \layout Standard
10473
10474 In the above example the parameter
10475 \emph on
10476 errcd
10477 \emph default
10478  for the function
10479 \emph on
10480 set_error
10481 \emph default
10482  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
10483 nooverlay was
10484  not present, this could cause unpredictable runtime behavior when called
10485  from an interrupt service routine.
10486  The #pragma\SpecialChar ~
10487 nooverlay ensures that the parameters and local variables for
10488  the function are NOT overlayed.
10489 \layout Section
10490
10491 Interrupt Service Routines
10492 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
10493
10494 \end_inset
10495
10496
10497 \layout Subsection
10498
10499 General Information
10500 \layout Standard
10501
10502 SDCC allows
10503 \emph on
10504 i
10505 \emph default
10506 nterrupt
10507 \emph on
10508 s
10509 \emph default
10510 ervice
10511 \emph on
10512 r
10513 \emph default
10514 outines to be coded in C, with some extended keywords.
10515 \layout Verse
10516
10517
10518 \family typewriter
10519 void timer_isr (void) interrupt 1 using 1
10520 \newline
10521 {
10522 \newline
10523 \SpecialChar ~
10524 \SpecialChar ~
10525 \SpecialChar ~
10526 \SpecialChar ~
10527 ...
10528
10529 \newline
10530 }
10531 \layout Standard
10532
10533 The optional number following the
10534 \emph on
10535 interrupt
10536 \begin_inset LatexCommand \index{interrupt}
10537
10538 \end_inset
10539
10540
10541 \begin_inset LatexCommand \index{\_\_interrupt}
10542
10543 \end_inset
10544
10545
10546 \emph default
10547  keyword is the interrupt number this routine will service.
10548  When present, the compiler will insert a call to this routine in the interrupt
10549  vector table for the interrupt number specified.
10550  If you have multiple source files in your project, interrupt service routines
10551  can be present in any of them, but a prototype of the isr MUST be present
10552  or included in the file that contains the function
10553 \emph on
10554 main
10555 \emph default
10556 .
10557  The optional
10558 \emph on
10559 using
10560 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10561
10562 \end_inset
10563
10564
10565 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10566
10567 \end_inset
10568
10569
10570 \emph default
10571  keyword can be used to tell the compiler to use the specified register
10572  bank (8051 specific) when generating code for this function.
10573
10574 \newline
10575
10576 \layout Standard
10577
10578 Interrupt service routines open the door for some very interesting bugs:
10579 \newline
10580 If an interrupt service routine changes variables which are accessed by
10581  other functions these variables have to be declared
10582 \emph on
10583 volatile
10584 \emph default
10585
10586 \begin_inset LatexCommand \index{volatile}
10587
10588 \end_inset
10589
10590 .
10591
10592 \layout Standard
10593
10594 If the access to these variables is not
10595 \emph on
10596 atomic
10597 \begin_inset LatexCommand \index{atomic}
10598
10599 \end_inset
10600
10601
10602 \emph default
10603  (i.e.
10604  the processor needs more than one instruction for the access and could
10605  be interrupted while accessing the variable) the interrupt must be disabled
10606  during the access to avoid inconsistent data.
10607  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10608  and should be protected by disabling interrupts.
10609  You're not automatically on the safe side if you use 8 bit variables though.
10610  We need an example here: f.e.
10611  on the 8051 the harmless looking
10612 \begin_inset Quotes srd
10613 \end_inset
10614
10615
10616 \family typewriter
10617 flags\SpecialChar ~
10618 |=\SpecialChar ~
10619 0x80;
10620 \family default
10621
10622 \begin_inset Quotes sld
10623 \end_inset
10624
10625  is not atomic if
10626 \family typewriter
10627 flags
10628 \family default
10629  resides in xdata.
10630  Setting
10631 \begin_inset Quotes srd
10632 \end_inset
10633
10634
10635 \family typewriter
10636 flags\SpecialChar ~
10637 |=\SpecialChar ~
10638 0x40;
10639 \family default
10640
10641 \begin_inset Quotes sld
10642 \end_inset
10643
10644  from within an interrupt routine might get lost if the interrupt occurs
10645  at the wrong time.
10646
10647 \begin_inset Quotes sld
10648 \end_inset
10649
10650
10651 \family typewriter
10652 counter\SpecialChar ~
10653 +=\SpecialChar ~
10654 8;
10655 \family default
10656
10657 \begin_inset Quotes srd
10658 \end_inset
10659
10660  is not atomic on the 8051 even if
10661 \family typewriter
10662 counter
10663 \family default
10664  is located in data memory.
10665  Bugs like these are hard to reproduce and can cause a lot of trouble.
10666
10667 \layout Standard
10668
10669 The return address and the registers used in the interrupt service routine
10670  are saved on the stack
10671 \begin_inset LatexCommand \index{stack}
10672
10673 \end_inset
10674
10675  so there must be sufficient stack space.
10676  If there isn't variables or registers (or even the return address itself)
10677  will be corrupted.
10678  This
10679 \emph on
10680 stack overflow
10681 \emph default
10682
10683 \begin_inset LatexCommand \index{stack overflow}
10684
10685 \end_inset
10686
10687  is most likely to happen if the interrupt occurs during the
10688 \begin_inset Quotes sld
10689 \end_inset
10690
10691 deepest
10692 \begin_inset Quotes srd
10693 \end_inset
10694
10695  subroutine when the stack is already in use for f.e.
10696  many return addresses.
10697 \layout Standard
10698
10699 A special note here, int (16 bit) and long (32 bit) integer division
10700 \begin_inset LatexCommand \index{Division}
10701
10702 \end_inset
10703
10704 , multiplication
10705 \begin_inset LatexCommand \index{Multiplication}
10706
10707 \end_inset
10708
10709  & modulus
10710 \begin_inset LatexCommand \index{Modulus}
10711
10712 \end_inset
10713
10714  and floating-point
10715 \begin_inset LatexCommand \index{Floating point support}
10716
10717 \end_inset
10718
10719  operations are implemented using external support routines developed in
10720  ANSI-C.
10721  If an interrupt service routine needs to do any of these operations then
10722  the support routines (as mentioned in a following section) will have to
10723  be recompiled using the
10724 \emph on
10725  -
10726 \begin_inset ERT
10727 status Collapsed
10728
10729 \layout Standard
10730
10731 \backslash
10732 /
10733 \end_inset
10734
10735 -stack-auto
10736 \begin_inset LatexCommand \index{-\/-stack-auto}
10737
10738 \end_inset
10739
10740
10741 \emph default
10742  option and the source file will need to be compiled using the
10743 \emph on
10744 -
10745 \begin_inset ERT
10746 status Collapsed
10747
10748 \layout Standard
10749
10750 \backslash
10751 /
10752 \end_inset
10753
10754 -int-long-reent
10755 \emph default
10756
10757 \begin_inset LatexCommand \index{-\/-int-long-reent}
10758
10759 \end_inset
10760
10761  compiler option.
10762 \layout Standard
10763
10764 Calling other functions from an interrupt service routine is not recommended,
10765  avoid it if possible.
10766  Note that when some function is called from an interrupt service routine
10767  it should be preceded by a #pragma\SpecialChar ~
10768 nooverlay
10769 \begin_inset LatexCommand \index{\#pragma nooverlay}
10770
10771 \end_inset
10772
10773  if it is not reentrant.
10774  Furthermore nonreentrant functions should not be called from the main program
10775  while the interrupt service routine might be active.
10776
10777 \newline
10778
10779 \newline
10780 Also see section
10781 \begin_inset LatexCommand \ref{sub:Overlaying}
10782
10783 \end_inset
10784
10785 \SpecialChar ~
10786 about Overlaying and section
10787 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10788
10789 \end_inset
10790
10791 \SpecialChar ~
10792 about Functions using private register banks.
10793 \layout Subsection
10794
10795 MCS51/DS390 Interrupt Service Routines
10796 \layout Standard
10797
10798 Interrupt numbers and the corresponding address & descriptions for the Standard
10799  8051/8052 are listed below.
10800  SDCC will automatically adjust the interrupt vector table to the maximum
10801  interrupt number specified.
10802 \newline
10803
10804 \layout Standard
10805 \align center
10806
10807 \begin_inset  Tabular
10808 <lyxtabular version="3" rows="7" columns="3">
10809 <features>
10810 <column alignment="center" valignment="top" leftline="true" width="0in">
10811 <column alignment="center" valignment="top" leftline="true" width="0in">
10812 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10813 <row topline="true" bottomline="true">
10814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10815 \begin_inset Text
10816
10817 \layout Standard
10818
10819 Interrupt #
10820 \end_inset
10821 </cell>
10822 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10823 \begin_inset Text
10824
10825 \layout Standard
10826
10827 Description
10828 \end_inset
10829 </cell>
10830 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10831 \begin_inset Text
10832
10833 \layout Standard
10834
10835 Vector Address
10836 \end_inset
10837 </cell>
10838 </row>
10839 <row topline="true">
10840 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10841 \begin_inset Text
10842
10843 \layout Standard
10844
10845 0
10846 \end_inset
10847 </cell>
10848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10849 \begin_inset Text
10850
10851 \layout Standard
10852
10853 External 0
10854 \end_inset
10855 </cell>
10856 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10857 \begin_inset Text
10858
10859 \layout Standard
10860
10861 0x0003
10862 \end_inset
10863 </cell>
10864 </row>
10865 <row topline="true">
10866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10867 \begin_inset Text
10868
10869 \layout Standard
10870
10871 1
10872 \end_inset
10873 </cell>
10874 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10875 \begin_inset Text
10876
10877 \layout Standard
10878
10879 Timer 0
10880 \end_inset
10881 </cell>
10882 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10883 \begin_inset Text
10884
10885 \layout Standard
10886
10887 0x000B
10888 \end_inset
10889 </cell>
10890 </row>
10891 <row topline="true">
10892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10893 \begin_inset Text
10894
10895 \layout Standard
10896
10897 2
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 External 1
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 0x0013
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 3
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 Timer 1
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 0x001B
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 4
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 Serial
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 0x0023
10966 \end_inset
10967 </cell>
10968 </row>
10969 <row topline="true" bottomline="true">
10970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10971 \begin_inset Text
10972
10973 \layout Standard
10974
10975 5
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 Timer 2 (8052)
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 0x002B
10992 \end_inset
10993 </cell>
10994 </row>
10995 </lyxtabular>
10996
10997 \end_inset
10998
10999
11000 \newline
11001
11002 \layout Standard
11003
11004 If the interrupt service routine is defined without
11005 \emph on
11006 using
11007 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11008
11009 \end_inset
11010
11011
11012 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11013
11014 \end_inset
11015
11016
11017 \emph default
11018  a register bank or with register bank 0 (
11019 \emph on
11020 using
11021 \emph default
11022  0), the compiler will save the registers used by itself on the stack upon
11023  entry and restore them at exit, however if such an interrupt service routine
11024  calls another function then the entire register bank will be saved on the
11025  stack.
11026  This scheme may be advantageous for small interrupt service routines which
11027  have low register usage.
11028 \layout Standard
11029
11030 If the interrupt service routine is defined to be using a specific register
11031  bank then only
11032 \emph on
11033 a, b, dptr
11034 \emph default
11035  & psw are saved and restored, if such an interrupt service routine calls
11036  another function (using another register bank) then the entire register
11037  bank of the called function will be saved on the stack.
11038  This scheme is recommended for larger interrupt service routines.
11039 \layout Subsection
11040
11041 HC08 Interrupt Service Routines
11042 \layout Standard
11043
11044 Since the number of interrupts available is chip specific and the interrupt
11045  vector table always ends at the last byte of memory, the interrupt numbers
11046  corresponds to the interrupt vectors in reverse order of address.
11047  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11048  2 will use the interrupt vector at 0xfffa, and so on.
11049  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11050  this way; instead see section
11051 \begin_inset LatexCommand \ref{sub:Startup-Code}
11052
11053 \end_inset
11054
11055  for details on customizing startup.
11056 \layout Subsection
11057
11058 Z80 Interrupt Service Routines
11059 \layout Standard
11060
11061 The Z80 uses several different methods for determining the correct interrupt
11062  vector depending on the hardware implementation.
11063  Therefore, SDCC ignores the optional interrupt number and does not attempt
11064  to generate an interrupt vector table.
11065 \layout Standard
11066
11067 By default, SDCC generates code for a maskable interrupt, which uses an
11068  RETI instruction to return from the interrupt.
11069  To write an interrupt handler for the non-maskable interrupt, which needs
11070  an RETN instruction instead, add the
11071 \emph on
11072 critical
11073 \emph default
11074  keyword:
11075 \layout Verse
11076
11077
11078 \family typewriter
11079 void nmi_isr (void) critical interrupt
11080 \newline
11081 {
11082 \newline
11083 \SpecialChar ~
11084 \SpecialChar ~
11085 \SpecialChar ~
11086 \SpecialChar ~
11087 ...
11088
11089 \newline
11090 }
11091 \layout Section
11092
11093 Enabling and Disabling Interrupts
11094 \layout Subsection
11095
11096 Critical Functions and Critical Statements
11097 \layout Standard
11098
11099 A special keyword may be associated with a block or a function declaring
11100  it as
11101 \emph on
11102 critical
11103 \emph default
11104 .
11105  SDCC will generate code to disable all interrupts
11106 \begin_inset LatexCommand \index{interrupt}
11107
11108 \end_inset
11109
11110  upon entry to a critical function and restore the interrupt enable to the
11111  previous state before returning.
11112  Nesting critical functions will need one additional byte on the stack
11113 \begin_inset LatexCommand \index{stack}
11114
11115 \end_inset
11116
11117  for each call.
11118 \layout Verse
11119
11120
11121 \family typewriter
11122 int foo () critical
11123 \begin_inset LatexCommand \index{critical}
11124
11125 \end_inset
11126
11127
11128 \begin_inset LatexCommand \index{\_\_critical}
11129
11130 \end_inset
11131
11132
11133 \newline
11134 {
11135 \newline
11136 \SpecialChar ~
11137 \SpecialChar ~
11138 \SpecialChar ~
11139 \SpecialChar ~
11140 ...
11141
11142 \newline
11143 \SpecialChar ~
11144 \SpecialChar ~
11145 \SpecialChar ~
11146 \SpecialChar ~
11147 ...
11148
11149 \newline
11150 }
11151 \layout Standard
11152
11153 The critical attribute maybe used with other attributes like
11154 \emph on
11155 reentrant.
11156 \emph default
11157
11158 \newline
11159 The keyword
11160 \emph on
11161 critical
11162 \emph default
11163  may also be used to disable interrupts more locally:
11164 \layout Verse
11165
11166
11167 \family typewriter
11168 critical{ i++; }
11169 \layout Standard
11170
11171 More than one statement could have been included in the block.
11172 \layout Subsection
11173
11174 Enabling and Disabling Interrupts directly
11175 \layout Standard
11176
11177 Interrupts
11178 \begin_inset LatexCommand \index{interrupt}
11179
11180 \end_inset
11181
11182  can also be disabled and enabled directly (8051):
11183 \layout Verse
11184
11185
11186 \family typewriter
11187 EA = 0;\SpecialChar ~
11188 \SpecialChar ~
11189 \SpecialChar ~
11190 \SpecialChar ~
11191 \SpecialChar ~
11192 \SpecialChar ~
11193 \SpecialChar ~
11194 \SpecialChar ~
11195 \SpecialChar ~
11196 \SpecialChar ~
11197 \SpecialChar ~
11198 \SpecialChar ~
11199 or:\SpecialChar ~
11200 \SpecialChar ~
11201 \SpecialChar ~
11202 \SpecialChar ~
11203 \SpecialChar ~
11204 \SpecialChar ~
11205 \SpecialChar ~
11206 \SpecialChar ~
11207 \SpecialChar ~
11208 \SpecialChar ~
11209 \SpecialChar ~
11210 EA_SAVE = EA;
11211 \layout Verse
11212
11213
11214 \family typewriter
11215 ...\SpecialChar ~
11216 \SpecialChar ~
11217 \SpecialChar ~
11218 \SpecialChar ~
11219 \SpecialChar ~
11220 \SpecialChar ~
11221 \SpecialChar ~
11222 \SpecialChar ~
11223 \SpecialChar ~
11224 \SpecialChar ~
11225 \SpecialChar ~
11226 \SpecialChar ~
11227 \SpecialChar ~
11228 \SpecialChar ~
11229 \SpecialChar ~
11230 \SpecialChar ~
11231 \SpecialChar ~
11232 \SpecialChar ~
11233 \SpecialChar ~
11234 \SpecialChar ~
11235 \SpecialChar ~
11236 \SpecialChar ~
11237 \SpecialChar ~
11238 \SpecialChar ~
11239 \SpecialChar ~
11240 \SpecialChar ~
11241 \SpecialChar ~
11242 \SpecialChar ~
11243 \SpecialChar ~
11244 \SpecialChar ~
11245 EA = 0;
11246 \layout Verse
11247
11248
11249 \family typewriter
11250 EA = 1;\SpecialChar ~
11251 \SpecialChar ~
11252 \SpecialChar ~
11253 \SpecialChar ~
11254 \SpecialChar ~
11255 \SpecialChar ~
11256 \SpecialChar ~
11257 \SpecialChar ~
11258 \SpecialChar ~
11259 \SpecialChar ~
11260 \SpecialChar ~
11261 \SpecialChar ~
11262 \SpecialChar ~
11263 \SpecialChar ~
11264 \SpecialChar ~
11265 \SpecialChar ~
11266 \SpecialChar ~
11267 \SpecialChar ~
11268 \SpecialChar ~
11269 \SpecialChar ~
11270 \SpecialChar ~
11271 \SpecialChar ~
11272 \SpecialChar ~
11273 \SpecialChar ~
11274 \SpecialChar ~
11275 \SpecialChar ~
11276 ...
11277 \layout Verse
11278
11279
11280 \family typewriter
11281 \SpecialChar ~
11282 \SpecialChar ~
11283 \SpecialChar ~
11284 \SpecialChar ~
11285 \SpecialChar ~
11286 \SpecialChar ~
11287 \SpecialChar ~
11288 \SpecialChar ~
11289 \SpecialChar ~
11290 \SpecialChar ~
11291 \SpecialChar ~
11292 \SpecialChar ~
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 EA = EA_SAVE;
11315 \layout Standard
11316
11317 On other architectures which have seperate opcodes for enabling and disabling
11318  interrupts you might want to make use of defines with inline assembly
11319 \begin_inset LatexCommand \index{Assembler routines}
11320
11321 \end_inset
11322
11323  (HC08):
11324 \layout Verse
11325
11326
11327 \family typewriter
11328 #define CLI _asm
11329 \begin_inset LatexCommand \index{\_asm}
11330
11331 \end_inset
11332
11333 \SpecialChar ~
11334 \SpecialChar ~
11335 cli\SpecialChar ~
11336 \SpecialChar ~
11337 _endasm
11338 \begin_inset LatexCommand \index{\_endasm}
11339
11340 \end_inset
11341
11342 ;
11343 \layout Verse
11344
11345
11346 \family typewriter
11347 #define SEI _asm\SpecialChar ~
11348 \SpecialChar ~
11349 sei\SpecialChar ~
11350 \SpecialChar ~
11351 _endasm;
11352 \layout Verse
11353
11354
11355 \family typewriter
11356 ...
11357 \layout Standard
11358
11359 Note: it is sometimes sufficient to disable only a specific interrupt source
11360  like f.e.
11361  a timer or serial interrupt by manipulating an
11362 \emph on
11363 interrupt mask
11364 \begin_inset LatexCommand \index{interrupt mask}
11365
11366 \end_inset
11367
11368
11369 \emph default
11370  register.
11371
11372 \layout Standard
11373
11374 Usually the time during which interrupts are disabled should be kept as
11375  short as possible.
11376  This minimizes both
11377 \emph on
11378 interrupt latency
11379 \emph default
11380
11381 \begin_inset LatexCommand \index{interrupt latency}
11382
11383 \end_inset
11384
11385  (the time between the occurrence of the interrupt and the execution of
11386  the first code in the interrupt routine) and
11387 \emph on
11388 interrupt jitter
11389 \emph default
11390
11391 \begin_inset LatexCommand \index{interrupt jitter}
11392
11393 \end_inset
11394
11395  (the difference between the shortest and the longest interrupt latency).
11396  These really are something different, f.e.
11397  a serial interrupt has to be served before its buffer overruns so it cares
11398  for the maximum interrupt latency, whereas it does not care about jitter.
11399  On a loudspeaker driven via a digital to analog converter which is fed
11400  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11401  a much smaller jitter will be very audible.
11402 \layout Standard
11403
11404 You can reenable interrupts within an interrupt routine and on some architecture
11405 s you can make use of two (or more) levels of
11406 \emph on
11407 interrupt priorities
11408 \emph default
11409
11410 \begin_inset LatexCommand \index{interrupt priority}
11411
11412 \end_inset
11413
11414 .
11415  On some architectures which don't support interrupt priorities these can
11416  be implemented by manipulating the interrupt mask and reenabling interrupts
11417  within the interrupt routine.
11418  Check there is sufficient space on the stack
11419 \begin_inset LatexCommand \index{stack}
11420
11421 \end_inset
11422
11423  and don't add complexity unless you have to.
11424
11425 \layout Subsection
11426
11427 Semaphore
11428 \begin_inset LatexCommand \index{semaphore}
11429
11430 \end_inset
11431
11432  locking (mcs51/ds390)
11433 \layout Standard
11434
11435 Some architectures (mcs51/ds390) have an atomic
11436 \begin_inset LatexCommand \index{atomic}
11437
11438 \end_inset
11439
11440  bit test and
11441 \emph on
11442
11443 \emph default
11444 clear
11445 \emph on
11446
11447 \emph default
11448 instruction.
11449  These type of instructions are typically used in preemptive multitasking
11450  systems, where a routine f.e.
11451  claims the use of a data structure ('acquires a lock
11452 \begin_inset LatexCommand \index{lock}
11453
11454 \end_inset
11455
11456  on it'), makes some modifications and then releases the lock when the data
11457  structure is consistent again.
11458  The instruction may also be used if interrupt and non-interrupt code have
11459  to compete for a resource.
11460  With the atomic bit test and clear instruction interrupts
11461 \begin_inset LatexCommand \index{interrupt}
11462
11463 \end_inset
11464
11465  don't have to be disabled for the locking operation.
11466
11467 \layout Standard
11468
11469 SDCC generates this instruction if the source follows this pattern:
11470 \layout Verse
11471
11472
11473 \family typewriter
11474 volatile
11475 \begin_inset LatexCommand \index{volatile}
11476
11477 \end_inset
11478
11479  bit resource_is_free;
11480 \newline
11481
11482 \newline
11483 if (resource_is_free)
11484 \newline
11485 \SpecialChar ~
11486 \SpecialChar ~
11487 {
11488 \newline
11489 \SpecialChar ~
11490 \SpecialChar ~
11491 \SpecialChar ~
11492 \SpecialChar ~
11493 resource_is_free=0;
11494 \newline
11495 \SpecialChar ~
11496 \SpecialChar ~
11497 \SpecialChar ~
11498 \SpecialChar ~
11499 ...
11500
11501 \newline
11502 \SpecialChar ~
11503 \SpecialChar ~
11504 \SpecialChar ~
11505 \SpecialChar ~
11506 resource_is_free=1;
11507 \newline
11508 \SpecialChar ~
11509 \SpecialChar ~
11510 }
11511 \layout Standard
11512
11513 Note, mcs51 and ds390 support only an atomic
11514 \begin_inset LatexCommand \index{atomic}
11515
11516 \end_inset
11517
11518  bit test and
11519 \emph on
11520 clear
11521 \emph default
11522  instruction (as opposed to atomic bit test and
11523 \emph on
11524 set).
11525 \layout Section
11526
11527 Functions using private register banks
11528 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11529
11530 \end_inset
11531
11532  (mcs51/ds390)
11533 \layout Standard
11534
11535 Some architectures have support for quickly changing register sets.
11536  SDCC supports this feature with the
11537 \emph on
11538 using
11539 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11540
11541 \end_inset
11542
11543
11544 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11545
11546 \end_inset
11547
11548
11549 \emph default
11550  attribute (which tells the compiler to use a register bank
11551 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11552
11553 \end_inset
11554
11555  other than the default bank zero).
11556  It should only be applied to
11557 \emph on
11558 interrupt
11559 \begin_inset LatexCommand \index{interrupt}
11560
11561 \end_inset
11562
11563
11564 \emph default
11565  functions (see footnote below).
11566  This will in most circumstances make the generated ISR code more efficient
11567  since it will not have to save registers on the stack.
11568 \layout Standard
11569
11570 The
11571 \emph on
11572 using
11573 \emph default
11574  attribute will have no effect on the generated code for a
11575 \emph on
11576 non-interrupt
11577 \emph default
11578  function (but may occasionally be useful anyway
11579 \begin_inset Foot
11580 collapsed false
11581
11582 \layout Standard
11583
11584 possible exception: if a function is called ONLY from 'interrupt' functions
11585  using a particular bank, it can be declared with the same 'using' attribute
11586  as the calling 'interrupt' functions.
11587  For instance, if you have several ISRs using bank one, and all of them
11588  call memcpy(), it might make sense to create a specialized version of memcpy()
11589  'using 1', since this would prevent the ISR from having to save bank zero
11590  to the stack on entry and switch to bank zero before calling the function
11591 \end_inset
11592
11593 ).
11594 \newline
11595
11596 \emph on
11597 (pending: I don't think this has been done yet)
11598 \layout Standard
11599
11600 An
11601 \emph on
11602 interrupt
11603 \emph default
11604  function using a non-zero bank will assume that it can trash that register
11605  bank, and will not save it.
11606  Since high-priority interrupts
11607 \begin_inset LatexCommand \index{interrupts}
11608
11609 \end_inset
11610
11611
11612 \begin_inset LatexCommand \index{interrupt priority}
11613
11614 \end_inset
11615
11616  can interrupt low-priority ones on the 8051 and friends, this means that
11617  if a high-priority ISR
11618 \emph on
11619 using
11620 \emph default
11621  a particular bank occurs while processing a low-priority ISR
11622 \emph on
11623 using
11624 \emph default
11625  the same bank, terrible and bad things can happen.
11626  To prevent this, no single register bank should be
11627 \emph on
11628 used
11629 \emph default
11630  by both a high priority and a low priority ISR.
11631  This is probably most easily done by having all high priority ISRs use
11632  one bank and all low priority ISRs use another.
11633  If you have an ISR which can change priority at runtime, you're on your
11634  own: I suggest using the default bank zero and taking the small performance
11635  hit.
11636 \layout Standard
11637
11638 It is most efficient if your ISR calls no other functions.
11639  If your ISR must call other functions, it is most efficient if those functions
11640  use the same bank as the ISR (see note 1 below); the next best is if the
11641  called functions use bank zero.
11642  It is very inefficient to call a function using a different, non-zero bank
11643  from an ISR.
11644
11645 \layout Section
11646
11647 Startup Code
11648 \begin_inset LatexCommand \label{sub:Startup-Code}
11649
11650 \end_inset
11651
11652
11653 \begin_inset LatexCommand \index{Startup code}
11654
11655 \end_inset
11656
11657
11658 \layout Subsection
11659
11660 MCS51/DS390 Startup Code
11661 \layout Standard
11662
11663 The compiler inserts a call to the C routine
11664 \emph on
11665 _sdcc_external_startup()
11666 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11667
11668 \end_inset
11669
11670
11671 \series bold
11672 \emph default
11673
11674 \series default
11675 at the start of the CODE area.
11676  This routine is in the runtime library
11677 \begin_inset LatexCommand \index{Runtime library}
11678
11679 \end_inset
11680
11681 .
11682  By default this routine returns 0, if this routine returns a non-zero value,
11683  the static & global variable initialization will be skipped and the function
11684  main will be invoked.
11685  Otherwise static & global variables will be initialized before the function
11686  main is invoked.
11687  You could add a
11688 \emph on
11689 _sdcc_external_startup()
11690 \emph default
11691  routine to your program to override the default if you need to setup hardware
11692  or perform some other critical operation prior to static & global variable
11693  initialization
11694 \begin_inset LatexCommand \index{Variable initialization}
11695
11696 \end_inset
11697
11698 .
11699  On some mcs51 variants xdata
11700 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11701
11702 \end_inset
11703
11704  memory has to be explicitly enabled before it can be accessed or if the
11705  watchdog needs to be disabled, this is the place to do it.
11706  The startup code clears all internal data memory, 256 bytes by default,
11707  but from 0 to n-1 if
11708 \emph on
11709 -
11710 \begin_inset ERT
11711 status Collapsed
11712
11713 \layout Standard
11714
11715 \backslash
11716 /
11717 \end_inset
11718
11719 -iram-size
11720 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
11721
11722 \end_inset
11723
11724 n
11725 \emph default
11726  is used.
11727  (recommended for Chipcon CC1010).
11728 \layout Standard
11729
11730 See also the compiler option
11731 \emph on
11732 -
11733 \begin_inset ERT
11734 status Collapsed
11735
11736 \layout Standard
11737
11738 \backslash
11739 /
11740 \end_inset
11741
11742 -no-xinit
11743 \emph default
11744 -
11745 \emph on
11746 opt
11747 \emph default
11748
11749 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11750
11751 \end_inset
11752
11753  and section
11754 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11755
11756 \end_inset
11757
11758 \SpecialChar ~
11759 about MCS51-variants.
11760 \layout Subsection
11761
11762 HC08 Startup Code
11763 \layout Standard
11764
11765 The HC08 startup code follows the same scheme as the MCS51 startup code.
11766 \layout Subsection
11767
11768 Z80 Startup Code
11769 \layout Standard
11770
11771 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11772  from sdcc/device/lib/z80/crt0.s.
11773  If you need a different startup code you can use the compiler option
11774 \emph on
11775 -
11776 \series bold
11777 \emph default
11778
11779 \begin_inset ERT
11780 status Collapsed
11781
11782 \layout Standard
11783
11784 \backslash
11785 /
11786 \end_inset
11787
11788
11789 \series default
11790 \emph on
11791 -no-std-crt0
11792 \emph default
11793
11794 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11795
11796 \end_inset
11797
11798  and provide your own crt0.o.
11799
11800 \layout Section
11801
11802 Inline Assembler Code
11803 \begin_inset LatexCommand \index{Assembler routines}
11804
11805 \end_inset
11806
11807
11808 \layout Subsection
11809
11810 A Step by Step Introduction
11811 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11812
11813 \end_inset
11814
11815
11816 \layout Standard
11817
11818 Starting from a small snippet of c-code this example shows for the MCS51
11819  how to use inline assembly, access variables, a function parameter and
11820  an array in xdata memory.
11821  The example uses an MCS51 here but is easily adapted for other architectures.
11822  This is a buffer routine which should be optimized:
11823 \layout Verse
11824
11825
11826 \family typewriter
11827 \size footnotesize
11828 unsigned char far
11829 \begin_inset LatexCommand \index{far (storage class)}
11830
11831 \end_inset
11832
11833
11834 \begin_inset LatexCommand \index{\_\_far (storage class)}
11835
11836 \end_inset
11837
11838  at
11839 \begin_inset LatexCommand \index{at}
11840
11841 \end_inset
11842
11843
11844 \begin_inset LatexCommand \index{\_\_at}
11845
11846 \end_inset
11847
11848  0x7f00 buf[0x100];
11849 \begin_inset LatexCommand \index{Aligned array}
11850
11851 \end_inset
11852
11853
11854 \newline
11855 unsigned char head,tail;
11856 \newline
11857
11858 \newline
11859 void to_buffer( unsigned char c )
11860 \newline
11861 {
11862 \newline
11863 \SpecialChar ~
11864 \SpecialChar ~
11865 \SpecialChar ~
11866 \SpecialChar ~
11867 if( head != tail-1 )
11868 \newline
11869 \SpecialChar ~
11870 \SpecialChar ~
11871 \SpecialChar ~
11872 \SpecialChar ~
11873 \SpecialChar ~
11874 \SpecialChar ~
11875 \SpecialChar ~
11876 \SpecialChar ~
11877 buf[ head++ ] = c;\SpecialChar ~
11878 \SpecialChar ~
11879 \SpecialChar ~
11880 \SpecialChar ~
11881 /* access to a 256 byte aligned array */
11882 \newline
11883 }
11884 \layout Standard
11885
11886 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
11887  then a corresponding buffer.asm file is generated.
11888  We define a new function
11889 \family typewriter
11890 to_buffer_asm()
11891 \family default
11892  in file buffer.c in which we cut and paste the generated code, removing
11893  unwanted comments and some ':'.
11894  Then add
11895 \begin_inset Quotes sld
11896 \end_inset
11897
11898 _asm
11899 \begin_inset Quotes srd
11900 \end_inset
11901
11902  and
11903 \begin_inset Quotes sld
11904 \end_inset
11905
11906 _endasm;
11907 \begin_inset Quotes srd
11908 \end_inset
11909
11910  to the beginning and the end of the function body:
11911 \layout Verse
11912
11913
11914 \family typewriter
11915 \size footnotesize
11916 /* With a cut and paste from the .asm file, we have something to start with.
11917 \newline
11918 \SpecialChar ~
11919 \SpecialChar ~
11920 \SpecialChar ~
11921 The function is not yet OK! (registers aren't saved) */
11922 \newline
11923 void to_buffer_asm( unsigned char c )
11924 \newline
11925 {
11926 \newline
11927 \SpecialChar ~
11928 \SpecialChar ~
11929 \SpecialChar ~
11930 \SpecialChar ~
11931 _asm
11932 \begin_inset LatexCommand \index{\_asm}
11933
11934 \end_inset
11935
11936
11937 \begin_inset LatexCommand \index{\_\_asm}
11938
11939 \end_inset
11940
11941
11942 \newline
11943 \SpecialChar ~
11944 \SpecialChar ~
11945 \SpecialChar ~
11946 \SpecialChar ~
11947 mov\SpecialChar ~
11948 \SpecialChar ~
11949 r2,dpl
11950 \newline
11951 ;buffer.c if( head != tail-1 )
11952 \newline
11953 \SpecialChar ~
11954 \SpecialChar ~
11955 \SpecialChar ~
11956 \SpecialChar ~
11957 mov\SpecialChar ~
11958 \SpecialChar ~
11959 a,_tail
11960 \newline
11961 \SpecialChar ~
11962 \SpecialChar ~
11963 \SpecialChar ~
11964 \SpecialChar ~
11965 dec\SpecialChar ~
11966 \SpecialChar ~
11967 a
11968 \newline
11969 \SpecialChar ~
11970 \SpecialChar ~
11971 \SpecialChar ~
11972 \SpecialChar ~
11973 mov\SpecialChar ~
11974 \SpecialChar ~
11975 r3,a
11976 \newline
11977 \SpecialChar ~
11978 \SpecialChar ~
11979 \SpecialChar ~
11980 \SpecialChar ~
11981 mov\SpecialChar ~
11982 \SpecialChar ~
11983 a,_head
11984 \newline
11985 \SpecialChar ~
11986 \SpecialChar ~
11987 \SpecialChar ~
11988 \SpecialChar ~
11989 cjne a,ar3,00106$
11990 \newline
11991 \SpecialChar ~
11992 \SpecialChar ~
11993 \SpecialChar ~
11994 \SpecialChar ~
11995 ret
11996 \newline
11997 00106$:
11998 \newline
11999 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12000 \begin_inset LatexCommand \index{Aligned array}
12001
12002 \end_inset
12003
12004
12005 \newline
12006 \SpecialChar ~
12007 \SpecialChar ~
12008 \SpecialChar ~
12009 \SpecialChar ~
12010 mov\SpecialChar ~
12011 \SpecialChar ~
12012 r3,_head
12013 \newline
12014 \SpecialChar ~
12015 \SpecialChar ~
12016 \SpecialChar ~
12017 \SpecialChar ~
12018 inc\SpecialChar ~
12019 \SpecialChar ~
12020 _head
12021 \newline
12022 \SpecialChar ~
12023 \SpecialChar ~
12024 \SpecialChar ~
12025 \SpecialChar ~
12026 mov\SpecialChar ~
12027 \SpecialChar ~
12028 dpl,r3
12029 \newline
12030 \SpecialChar ~
12031 \SpecialChar ~
12032 \SpecialChar ~
12033 \SpecialChar ~
12034 mov\SpecialChar ~
12035 \SpecialChar ~
12036 dph,#(_buf >> 8)
12037 \newline
12038 \SpecialChar ~
12039 \SpecialChar ~
12040 \SpecialChar ~
12041 \SpecialChar ~
12042 mov\SpecialChar ~
12043 \SpecialChar ~
12044 a,r2
12045 \newline
12046 \SpecialChar ~
12047 \SpecialChar ~
12048 \SpecialChar ~
12049 \SpecialChar ~
12050 movx @dptr,a
12051 \newline
12052 00103$:
12053 \newline
12054 \SpecialChar ~
12055 \SpecialChar ~
12056 \SpecialChar ~
12057 \SpecialChar ~
12058 ret
12059 \newline
12060 \SpecialChar ~
12061 \SpecialChar ~
12062 \SpecialChar ~
12063 \SpecialChar ~
12064 _endasm
12065 \begin_inset LatexCommand \index{\_endasm}
12066
12067 \end_inset
12068
12069
12070 \begin_inset LatexCommand \index{\_\_endasm}
12071
12072 \end_inset
12073
12074 ;
12075 \newline
12076 }
12077 \layout Standard
12078
12079 The new file buffer.c should compile with only one warning about the unreferenced
12080  function argument 'c'.
12081  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12082  (1) and finally have:
12083 \layout Verse
12084
12085
12086 \family typewriter
12087 \size footnotesize
12088 unsigned char far at 0x7f00 buf[0x100];
12089 \newline
12090 unsigned char head,tail;
12091 \newline
12092 #define USE_ASSEMBLY (1)
12093 \newline
12094
12095 \newline
12096 #if !USE_ASSEMBLY
12097 \newline
12098
12099 \newline
12100 void to_buffer( unsigned char c )
12101 \newline
12102 {
12103 \newline
12104 \SpecialChar ~
12105 \SpecialChar ~
12106 \SpecialChar ~
12107 \SpecialChar ~
12108 if( head != tail-1 )
12109 \newline
12110 \SpecialChar ~
12111 \SpecialChar ~
12112 \SpecialChar ~
12113 \SpecialChar ~
12114 \SpecialChar ~
12115 \SpecialChar ~
12116 \SpecialChar ~
12117 \SpecialChar ~
12118 buf[ head++ ] = c;
12119 \newline
12120 }
12121 \newline
12122
12123 \newline
12124 #else
12125 \newline
12126
12127 \newline
12128 void to_buffer( unsigned char c )
12129 \newline
12130 {
12131 \newline
12132 \SpecialChar ~
12133 \SpecialChar ~
12134 \SpecialChar ~
12135 \SpecialChar ~
12136 c; // to avoid warning: unreferenced function argument
12137 \newline
12138 \SpecialChar ~
12139 \SpecialChar ~
12140 \SpecialChar ~
12141 \SpecialChar ~
12142 _asm
12143 \begin_inset LatexCommand \index{\_asm}
12144
12145 \end_inset
12146
12147
12148 \begin_inset LatexCommand \index{\_\_asm}
12149
12150 \end_inset
12151
12152
12153 \newline
12154 \SpecialChar ~
12155 \SpecialChar ~
12156 \SpecialChar ~
12157 \SpecialChar ~
12158 \SpecialChar ~
12159 \SpecialChar ~
12160 \SpecialChar ~
12161 \SpecialChar ~
12162 ; save used registers here.
12163
12164 \newline
12165 \SpecialChar ~
12166 \SpecialChar ~
12167 \SpecialChar ~
12168 \SpecialChar ~
12169 \SpecialChar ~
12170 \SpecialChar ~
12171 \SpecialChar ~
12172 \SpecialChar ~
12173 ; If we were still using r2,r3 we would have to push them here.
12174
12175 \newline
12176 ; if( head != tail-1 )
12177 \newline
12178 \SpecialChar ~
12179 \SpecialChar ~
12180 \SpecialChar ~
12181 \SpecialChar ~
12182 \SpecialChar ~
12183 \SpecialChar ~
12184 \SpecialChar ~
12185 \SpecialChar ~
12186 mov\SpecialChar ~
12187  a,_tail
12188 \newline
12189 \SpecialChar ~
12190 \SpecialChar ~
12191 \SpecialChar ~
12192 \SpecialChar ~
12193 \SpecialChar ~
12194 \SpecialChar ~
12195 \SpecialChar ~
12196 \SpecialChar ~
12197 dec\SpecialChar ~
12198  a
12199 \newline
12200 \SpecialChar ~
12201 \SpecialChar ~
12202 \SpecialChar ~
12203 \SpecialChar ~
12204 \SpecialChar ~
12205 \SpecialChar ~
12206 \SpecialChar ~
12207 \SpecialChar ~
12208 xrl\SpecialChar ~
12209  a,_head
12210 \newline
12211 \SpecialChar ~
12212 \SpecialChar ~
12213 \SpecialChar ~
12214 \SpecialChar ~
12215 \SpecialChar ~
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 \SpecialChar ~
12219 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
12220 \newline
12221 \SpecialChar ~
12222 \SpecialChar ~
12223 \SpecialChar ~
12224 \SpecialChar ~
12225 \SpecialChar ~
12226 \SpecialChar ~
12227 \SpecialChar ~
12228 \SpecialChar ~
12229 jz\SpecialChar ~
12230 \SpecialChar ~
12231  t_b_end$
12232 \newline
12233 \SpecialChar ~
12234 \SpecialChar ~
12235 \SpecialChar ~
12236 \SpecialChar ~
12237 \SpecialChar ~
12238 \SpecialChar ~
12239 \SpecialChar ~
12240 \SpecialChar ~
12241 ;
12242 \newline
12243 ; buf[ head++ ] = c;
12244 \newline
12245 \SpecialChar ~
12246 \SpecialChar ~
12247 \SpecialChar ~
12248 \SpecialChar ~
12249 \SpecialChar ~
12250 \SpecialChar ~
12251 \SpecialChar ~
12252 \SpecialChar ~
12253 mov\SpecialChar ~
12254  a,dpl \SpecialChar ~
12255 \SpecialChar ~
12256 \SpecialChar ~
12257 \SpecialChar ~
12258 \SpecialChar ~
12259 \SpecialChar ~
12260 \SpecialChar ~
12261 ; dpl holds lower byte of function argument
12262 \newline
12263 \SpecialChar ~
12264 \SpecialChar ~
12265 \SpecialChar ~
12266 \SpecialChar ~
12267 \SpecialChar ~
12268 \SpecialChar ~
12269 \SpecialChar ~
12270 \SpecialChar ~
12271 mov\SpecialChar ~
12272  dpl,_head \SpecialChar ~
12273 \SpecialChar ~
12274 \SpecialChar ~
12275 ; buf is 0x100 byte aligned so head can be used directly
12276 \newline
12277 \SpecialChar ~
12278 \SpecialChar ~
12279 \SpecialChar ~
12280 \SpecialChar ~
12281 \SpecialChar ~
12282 \SpecialChar ~
12283 \SpecialChar ~
12284 \SpecialChar ~
12285 mov\SpecialChar ~
12286  dph,#(_buf>>8)
12287 \newline
12288 \SpecialChar ~
12289 \SpecialChar ~
12290 \SpecialChar ~
12291 \SpecialChar ~
12292 \SpecialChar ~
12293 \SpecialChar ~
12294 \SpecialChar ~
12295 \SpecialChar ~
12296 movx @dptr,a
12297 \newline
12298 \SpecialChar ~
12299 \SpecialChar ~
12300 \SpecialChar ~
12301 \SpecialChar ~
12302 \SpecialChar ~
12303 \SpecialChar ~
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 inc \SpecialChar ~
12307 _head
12308 \newline
12309 \SpecialChar ~
12310 \SpecialChar ~
12311 \SpecialChar ~
12312 \SpecialChar ~
12313 \SpecialChar ~
12314 \SpecialChar ~
12315 \SpecialChar ~
12316 \SpecialChar ~
12317 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
12318 \newline
12319 t_b_end$:
12320 \newline
12321 \SpecialChar ~
12322 \SpecialChar ~
12323 \SpecialChar ~
12324 \SpecialChar ~
12325 \SpecialChar ~
12326 \SpecialChar ~
12327 \SpecialChar ~
12328 \SpecialChar ~
12329 ; restore used registers here
12330 \newline
12331 \SpecialChar ~
12332 \SpecialChar ~
12333 \SpecialChar ~
12334 \SpecialChar ~
12335 _endasm
12336 \begin_inset LatexCommand \index{\_endasm}
12337
12338 \end_inset
12339
12340
12341 \begin_inset LatexCommand \index{\_\_endasm}
12342
12343 \end_inset
12344
12345 ;
12346 \newline
12347 }
12348 \newline
12349 #endif
12350 \layout Standard
12351
12352 The inline assembler code can contain any valid code understood by the assembler
12353 , this includes any assembler directives and comment lines
12354 \begin_inset Foot
12355 collapsed false
12356
12357 \layout Standard
12358
12359 The assembler does not like some characters like ':' or ''' in comments.
12360  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
12361 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
12362
12363 \end_inset
12364
12365
12366 \begin_inset LatexCommand \index{Assembler documentation}
12367
12368 \end_inset
12369
12370
12371 \end_inset
12372
12373 .
12374  The compiler does not do any validation of the code within the
12375 \family typewriter
12376 _asm
12377 \begin_inset LatexCommand \index{\_asm}
12378
12379 \end_inset
12380
12381
12382 \begin_inset LatexCommand \index{\_\_asm}
12383
12384 \end_inset
12385
12386  ...
12387  _endasm
12388 \size footnotesize
12389
12390 \begin_inset LatexCommand \index{\_endasm}
12391
12392 \end_inset
12393
12394
12395 \begin_inset LatexCommand \index{\_\_endasm}
12396
12397 \end_inset
12398
12399
12400 \size default
12401 ;
12402 \family default
12403  keyword pair.
12404  Specifically it will not know which registers are used and thus register
12405  pushing/popping
12406 \begin_inset LatexCommand \index{push/pop}
12407
12408 \end_inset
12409
12410  has to be done manually.
12411
12412 \layout Standard
12413
12414 It is recommended that each assembly instruction (including labels) be placed
12415  in a separate line (as the example shows).
12416  When the -
12417 \begin_inset ERT
12418 status Collapsed
12419
12420 \layout Standard
12421
12422 \backslash
12423 /
12424 \end_inset
12425
12426 -
12427 \emph on
12428 peep-asm
12429 \begin_inset LatexCommand \index{-\/-peep-asm}
12430
12431 \end_inset
12432
12433
12434 \emph default
12435  command line option is used, the inline assembler code will be passed through
12436  the peephole optimizer
12437 \begin_inset LatexCommand \index{Peephole optimizer}
12438
12439 \end_inset
12440
12441 .
12442  There are only a few (if any) cases where this option makes sense, it might
12443  cause some unexpected changes in the inline assembler code.
12444  Please go through the peephole optimizer rules defined in file
12445 \emph on
12446 SDCCpeeph.def
12447 \emph default
12448  before using this option.
12449 \layout Subsection
12450
12451 Naked Functions
12452 \begin_inset LatexCommand \label{sub:Naked-Functions}
12453
12454 \end_inset
12455
12456
12457 \begin_inset LatexCommand \index{Naked functions}
12458
12459 \end_inset
12460
12461
12462 \layout Standard
12463
12464 A special keyword may be associated with a function declaring it as
12465 \emph on
12466 _naked
12467 \begin_inset LatexCommand \index{\_naked}
12468
12469 \end_inset
12470
12471
12472 \begin_inset LatexCommand \index{\_\_naked}
12473
12474 \end_inset
12475
12476 .
12477
12478 \emph default
12479 The
12480 \emph on
12481 _naked
12482 \emph default
12483  function modifier attribute prevents the compiler from generating prologue
12484 \begin_inset LatexCommand \index{function prologue}
12485
12486 \end_inset
12487
12488  and epilogue
12489 \begin_inset LatexCommand \index{function epilogue}
12490
12491 \end_inset
12492
12493  code for that function.
12494  This means that the user is entirely responsible for such things as saving
12495  any registers that may need to be preserved, selecting the proper register
12496  bank, generating the
12497 \emph on
12498 return
12499 \emph default
12500  instruction at the end, etc.
12501  Practically, this means that the contents of the function must be written
12502  in inline assembler.
12503  This is particularly useful for interrupt functions, which can have a large
12504  (and often unnecessary) prologue/epilogue.
12505  For example, compare the code generated by these two functions:
12506 \layout Verse
12507
12508
12509 \family typewriter
12510 volatile
12511 \begin_inset LatexCommand \index{volatile}
12512
12513 \end_inset
12514
12515  data unsigned char counter;
12516 \newline
12517
12518 \newline
12519 void simpleInterrupt(void) interrupt
12520 \begin_inset LatexCommand \index{interrupt}
12521
12522 \end_inset
12523
12524
12525 \begin_inset LatexCommand \index{\_\_interrupt}
12526
12527 \end_inset
12528
12529  1
12530 \newline
12531 {
12532 \newline
12533 \SpecialChar ~
12534 \SpecialChar ~
12535 \SpecialChar ~
12536 \SpecialChar ~
12537 counter++;
12538 \newline
12539 }
12540 \newline
12541
12542 \newline
12543 void nakedInterrupt(void) interrupt 2 _naked
12544 \newline
12545 {
12546 \newline
12547 \SpecialChar ~
12548 \SpecialChar ~
12549 \SpecialChar ~
12550 \SpecialChar ~
12551 _asm
12552 \begin_inset LatexCommand \index{\_asm}
12553
12554 \end_inset
12555
12556
12557 \begin_inset LatexCommand \index{\_\_asm}
12558
12559 \end_inset
12560
12561
12562 \newline
12563 \SpecialChar ~
12564 \SpecialChar ~
12565 \SpecialChar ~
12566 \SpecialChar ~
12567 \SpecialChar ~
12568 \SpecialChar ~
12569 inc\SpecialChar ~
12570 \SpecialChar ~
12571 \SpecialChar ~
12572 \SpecialChar ~
12573 \SpecialChar ~
12574 _counter ; does not change flags, no need to save psw
12575 \newline
12576 \SpecialChar ~
12577 \SpecialChar ~
12578 \SpecialChar ~
12579 \SpecialChar ~
12580 \SpecialChar ~
12581 \SpecialChar ~
12582 reti\SpecialChar ~
12583 \SpecialChar ~
12584 \SpecialChar ~
12585 \SpecialChar ~
12586 ; MUST explicitly include ret or reti in _naked function.
12587 \newline
12588 \SpecialChar ~
12589 \SpecialChar ~
12590 \SpecialChar ~
12591 \SpecialChar ~
12592 _endasm
12593 \begin_inset LatexCommand \index{\_endasm}
12594
12595 \end_inset
12596
12597
12598 \begin_inset LatexCommand \index{\_\_endasm}
12599
12600 \end_inset
12601
12602 ;
12603 \newline
12604 }
12605 \layout Standard
12606
12607 For an 8051 target, the generated simpleInterrupt looks like:
12608 \layout Verse
12609
12610
12611 \family typewriter
12612 _simpleInterrupt:
12613 \newline
12614 \SpecialChar ~
12615 \SpecialChar ~
12616 \SpecialChar ~
12617 \SpecialChar ~
12618 push\SpecialChar ~
12619 \SpecialChar ~
12620 \SpecialChar ~
12621 \SpecialChar ~
12622 acc
12623 \newline
12624 \SpecialChar ~
12625 \SpecialChar ~
12626 \SpecialChar ~
12627 \SpecialChar ~
12628 push\SpecialChar ~
12629 \SpecialChar ~
12630 \SpecialChar ~
12631 \SpecialChar ~
12632 b
12633 \newline
12634 \SpecialChar ~
12635 \SpecialChar ~
12636 \SpecialChar ~
12637 \SpecialChar ~
12638 push\SpecialChar ~
12639 \SpecialChar ~
12640 \SpecialChar ~
12641 \SpecialChar ~
12642 dpl
12643 \newline
12644 \SpecialChar ~
12645 \SpecialChar ~
12646 \SpecialChar ~
12647 \SpecialChar ~
12648 push\SpecialChar ~
12649 \SpecialChar ~
12650 \SpecialChar ~
12651 \SpecialChar ~
12652 dph
12653 \newline
12654 \SpecialChar ~
12655 \SpecialChar ~
12656 \SpecialChar ~
12657 \SpecialChar ~
12658 push\SpecialChar ~
12659 \SpecialChar ~
12660 \SpecialChar ~
12661 \SpecialChar ~
12662 psw
12663 \newline
12664 \SpecialChar ~
12665 \SpecialChar ~
12666 \SpecialChar ~
12667 \SpecialChar ~
12668 mov\SpecialChar ~
12669 \SpecialChar ~
12670 \SpecialChar ~
12671 \SpecialChar ~
12672 \SpecialChar ~
12673 psw,#0x00
12674 \newline
12675 \SpecialChar ~
12676 \SpecialChar ~
12677 \SpecialChar ~
12678 \SpecialChar ~
12679 inc\SpecialChar ~
12680 \SpecialChar ~
12681 \SpecialChar ~
12682 \SpecialChar ~
12683 \SpecialChar ~
12684 _counter
12685 \newline
12686 \SpecialChar ~
12687 \SpecialChar ~
12688 \SpecialChar ~
12689 \SpecialChar ~
12690 pop\SpecialChar ~
12691 \SpecialChar ~
12692 \SpecialChar ~
12693 \SpecialChar ~
12694 \SpecialChar ~
12695 psw
12696 \newline
12697 \SpecialChar ~
12698 \SpecialChar ~
12699 \SpecialChar ~
12700 \SpecialChar ~
12701 pop\SpecialChar ~
12702 \SpecialChar ~
12703 \SpecialChar ~
12704 \SpecialChar ~
12705 \SpecialChar ~
12706 dph
12707 \newline
12708 \SpecialChar ~
12709 \SpecialChar ~
12710 \SpecialChar ~
12711 \SpecialChar ~
12712 pop\SpecialChar ~
12713 \SpecialChar ~
12714 \SpecialChar ~
12715 \SpecialChar ~
12716 \SpecialChar ~
12717 dpl
12718 \newline
12719 \SpecialChar ~
12720 \SpecialChar ~
12721 \SpecialChar ~
12722 \SpecialChar ~
12723 pop\SpecialChar ~
12724 \SpecialChar ~
12725 \SpecialChar ~
12726 \SpecialChar ~
12727 \SpecialChar ~
12728 b
12729 \newline
12730 \SpecialChar ~
12731 \SpecialChar ~
12732 \SpecialChar ~
12733 \SpecialChar ~
12734 pop\SpecialChar ~
12735 \SpecialChar ~
12736 \SpecialChar ~
12737 \SpecialChar ~
12738 \SpecialChar ~
12739 acc
12740 \newline
12741 \SpecialChar ~
12742 \SpecialChar ~
12743 \SpecialChar ~
12744 \SpecialChar ~
12745 reti
12746 \layout Standard
12747
12748 whereas nakedInterrupt looks like:
12749 \layout Verse
12750
12751
12752 \family typewriter
12753 _nakedInterrupt:
12754 \newline
12755 \SpecialChar ~
12756 \SpecialChar ~
12757 \SpecialChar ~
12758 \SpecialChar ~
12759 inc\SpecialChar ~
12760 \SpecialChar ~
12761 \SpecialChar ~
12762 \SpecialChar ~
12763 _counter ; does not change flags, no need to save psw
12764 \newline
12765 \SpecialChar ~
12766 \SpecialChar ~
12767 \SpecialChar ~
12768 \SpecialChar ~
12769 reti\SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 \SpecialChar ~
12773 \SpecialChar ~
12774 \SpecialChar ~
12775 \SpecialChar ~
12776 \SpecialChar ~
12777 \SpecialChar ~
12778 \SpecialChar ~
12779 \SpecialChar ~
12780 \SpecialChar ~
12781 ; MUST explicitly include ret or reti in _naked function
12782 \layout Standard
12783
12784 The related directive #pragma exclude
12785 \begin_inset LatexCommand \index{\#pragma exclude}
12786
12787 \end_inset
12788
12789  allows a more fine grained control over pushing & popping
12790 \begin_inset LatexCommand \index{push/pop}
12791
12792 \end_inset
12793
12794  the registers.
12795 \layout Standard
12796
12797 While there is nothing preventing you from writing C code inside a
12798 \family typewriter
12799 _naked
12800 \family default
12801  function, there are many ways to shoot yourself in the foot doing this,
12802  and it is recommended that you stick to inline assembler.
12803 \layout Subsection
12804
12805 Use of Labels within Inline Assembler
12806 \layout Standard
12807
12808 SDCC allows the use of in-line assembler with a few restrictions regarding
12809  labels.
12810  In older versions of the compiler all labels defined within inline assembler
12811  code
12812 \emph on
12813 had to be
12814 \emph default
12815  of the form
12816 \emph on
12817 nnnnn$
12818 \emph default
12819  where nnnn is a number less than 100 (which implies a limit of utmost 100
12820  inline assembler labels
12821 \emph on
12822 per function
12823 \emph default
12824 \noun on
12825 )
12826 \noun default
12827 .
12828
12829 \layout Verse
12830
12831
12832 \family typewriter
12833 _asm
12834 \begin_inset LatexCommand \index{\_asm}
12835
12836 \end_inset
12837
12838
12839 \begin_inset LatexCommand \index{\_\_asm}
12840
12841 \end_inset
12842
12843
12844 \newline
12845 \SpecialChar ~
12846 \SpecialChar ~
12847 \SpecialChar ~
12848 \SpecialChar ~
12849 mov\SpecialChar ~
12850 \SpecialChar ~
12851 \SpecialChar ~
12852 \SpecialChar ~
12853 \SpecialChar ~
12854 b,#10
12855 \newline
12856 00001$:
12857 \newline
12858 \SpecialChar ~
12859 \SpecialChar ~
12860 \SpecialChar ~
12861 \SpecialChar ~
12862 djnz\SpecialChar ~
12863 \SpecialChar ~
12864 \SpecialChar ~
12865 \SpecialChar ~
12866 b,00001$
12867 \newline
12868 _endasm
12869 \begin_inset LatexCommand \index{\_endasm}
12870
12871 \end_inset
12872
12873
12874 \begin_inset LatexCommand \index{\_\_endasm}
12875
12876 \end_inset
12877
12878  ;
12879 \layout Standard
12880
12881 Inline assembler code cannot reference any C-Labels, however it can reference
12882  labels
12883 \begin_inset LatexCommand \index{Labels}
12884
12885 \end_inset
12886
12887  defined by the inline assembler, e.g.:
12888 \layout Verse
12889
12890
12891 \family typewriter
12892 foo() {
12893 \newline
12894 \SpecialChar ~
12895 \SpecialChar ~
12896 \SpecialChar ~
12897 \SpecialChar ~
12898 /* some c code */
12899 \newline
12900 \SpecialChar ~
12901 \SpecialChar ~
12902 \SpecialChar ~
12903 \SpecialChar ~
12904 _asm
12905 \newline
12906 \SpecialChar ~
12907 \SpecialChar ~
12908 \SpecialChar ~
12909 \SpecialChar ~
12910 \SpecialChar ~
12911 \SpecialChar ~
12912 ; some assembler code
12913 \newline
12914 \SpecialChar ~
12915 \SpecialChar ~
12916 \SpecialChar ~
12917 \SpecialChar ~
12918 \SpecialChar ~
12919 \SpecialChar ~
12920 ljmp $0003
12921 \newline
12922 \SpecialChar ~
12923 \SpecialChar ~
12924 \SpecialChar ~
12925 \SpecialChar ~
12926 _endasm;
12927 \newline
12928 \SpecialChar ~
12929 \SpecialChar ~
12930 \SpecialChar ~
12931 \SpecialChar ~
12932 /* some more c code */
12933 \newline
12934 clabel:\SpecialChar ~
12935 \SpecialChar ~
12936 /* inline assembler cannot reference this label */
12937 \newline
12938 \SpecialChar ~
12939 \SpecialChar ~
12940 \SpecialChar ~
12941 \SpecialChar ~
12942 _asm
12943 \newline
12944 \SpecialChar ~
12945 \SpecialChar ~
12946 \SpecialChar ~
12947 \SpecialChar ~
12948 $0003: ;label (can be referenced by inline assembler only)
12949 \newline
12950 \SpecialChar ~
12951 \SpecialChar ~
12952 \SpecialChar ~
12953 \SpecialChar ~
12954 _endasm
12955 \begin_inset LatexCommand \index{\_endasm}
12956
12957 \end_inset
12958
12959
12960 \begin_inset LatexCommand \index{\_\_endasm}
12961
12962 \end_inset
12963
12964  ;
12965 \newline
12966 \SpecialChar ~
12967 \SpecialChar ~
12968 \SpecialChar ~
12969 \SpecialChar ~
12970 /* some more c code */
12971 \newline
12972 }
12973 \layout Standard
12974
12975 In other words inline assembly code can access labels defined in inline
12976  assembly within the scope of the function.
12977  The same goes the other way, i.e.
12978  labels defines in inline assembly can not be accessed by C statements.
12979 \layout Section
12980
12981 Interfacing with Assembler Code
12982 \begin_inset LatexCommand \index{Assembler routines}
12983
12984 \end_inset
12985
12986
12987 \layout Subsection
12988
12989 Global Registers used for Parameter Passing
12990 \begin_inset LatexCommand \index{Parameter passing}
12991
12992 \end_inset
12993
12994
12995 \layout Standard
12996
12997 The compiler always uses the global registers
12998 \emph on
12999 DPL, DPH
13000 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13001
13002 \end_inset
13003
13004
13005 \begin_inset LatexCommand \index{DPTR}
13006
13007 \end_inset
13008
13009 , B
13010 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13011
13012 \end_inset
13013
13014
13015 \emph default
13016 and
13017 \emph on
13018  ACC
13019 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13020
13021 \end_inset
13022
13023
13024 \emph default
13025  to pass the first parameter to a routine.
13026  The second parameter onwards is either allocated on the stack (for reentrant
13027  routines or if -
13028 \begin_inset ERT
13029 status Collapsed
13030
13031 \layout Standard
13032
13033 \backslash
13034 /
13035 \end_inset
13036
13037 -stack-auto is used) or in data / xdata memory (depending on the memory
13038  model).
13039
13040 \layout Subsection
13041
13042 Assembler Routine (non-reentrant)
13043 \layout Standard
13044
13045 In the following example
13046 \begin_inset LatexCommand \index{reentrant}
13047
13048 \end_inset
13049
13050
13051 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13052
13053 \end_inset
13054
13055  the function c_func calls an assembler routine asm_func, which takes two
13056  parameters
13057 \begin_inset LatexCommand \index{function parameter}
13058
13059 \end_inset
13060
13061 .
13062 \layout Verse
13063
13064
13065 \family typewriter
13066 extern int asm_func(unsigned char, unsigned char);
13067 \newline
13068
13069 \newline
13070 int c_func (unsigned char i, unsigned char j)
13071 \newline
13072 {
13073 \newline
13074 \SpecialChar ~
13075 \SpecialChar ~
13076 \SpecialChar ~
13077 \SpecialChar ~
13078 return asm_func(i,j);
13079 \newline
13080 }
13081 \newline
13082
13083 \newline
13084 int main()
13085 \newline
13086 {
13087 \newline
13088 \SpecialChar ~
13089 \SpecialChar ~
13090 \SpecialChar ~
13091 \SpecialChar ~
13092 return c_func(10,9);
13093 \newline
13094 }
13095 \layout Standard
13096
13097 The corresponding assembler function is:
13098 \layout Verse
13099
13100
13101 \family typewriter
13102 .globl _asm_func_PARM_2
13103 \newline
13104 \SpecialChar ~
13105 \SpecialChar ~
13106 \SpecialChar ~
13107 \SpecialChar ~
13108 \SpecialChar ~
13109 \SpecialChar ~
13110 \SpecialChar ~
13111 \SpecialChar ~
13112 .globl _asm_func
13113 \newline
13114 \SpecialChar ~
13115 \SpecialChar ~
13116 \SpecialChar ~
13117 \SpecialChar ~
13118 \SpecialChar ~
13119 \SpecialChar ~
13120 \SpecialChar ~
13121 \SpecialChar ~
13122 .area OSEG
13123 \newline
13124 _asm_func_PARM_2:
13125 \newline
13126 \SpecialChar ~
13127 \SpecialChar ~
13128 \SpecialChar ~
13129 \SpecialChar ~
13130 \SpecialChar ~
13131 \SpecialChar ~
13132 \SpecialChar ~
13133 \SpecialChar ~
13134 .ds    1
13135 \newline
13136 \SpecialChar ~
13137 \SpecialChar ~
13138 \SpecialChar ~
13139 \SpecialChar ~
13140 \SpecialChar ~
13141 \SpecialChar ~
13142 \SpecialChar ~
13143 \SpecialChar ~
13144 .area CSEG
13145 \newline
13146 _asm_func:
13147 \newline
13148 \SpecialChar ~
13149 \SpecialChar ~
13150 \SpecialChar ~
13151 \SpecialChar ~
13152 \SpecialChar ~
13153 \SpecialChar ~
13154 \SpecialChar ~
13155 \SpecialChar ~
13156 mov\SpecialChar ~
13157 \SpecialChar ~
13158 \SpecialChar ~
13159 \SpecialChar ~
13160 a,dpl
13161 \newline
13162 \SpecialChar ~
13163 \SpecialChar ~
13164 \SpecialChar ~
13165 \SpecialChar ~
13166 \SpecialChar ~
13167 \SpecialChar ~
13168 \SpecialChar ~
13169 \SpecialChar ~
13170 add\SpecialChar ~
13171 \SpecialChar ~
13172 \SpecialChar ~
13173 \SpecialChar ~
13174 a,_asm_func_PARM_2
13175 \newline
13176 \SpecialChar ~
13177 \SpecialChar ~
13178 \SpecialChar ~
13179 \SpecialChar ~
13180 \SpecialChar ~
13181 \SpecialChar ~
13182 \SpecialChar ~
13183 \SpecialChar ~
13184 mov\SpecialChar ~
13185 \SpecialChar ~
13186 \SpecialChar ~
13187 \SpecialChar ~
13188 dpl,a
13189 \newline
13190 \SpecialChar ~
13191 \SpecialChar ~
13192 \SpecialChar ~
13193 \SpecialChar ~
13194 \SpecialChar ~
13195 \SpecialChar ~
13196 \SpecialChar ~
13197 \SpecialChar ~
13198 mov\SpecialChar ~
13199 \SpecialChar ~
13200 \SpecialChar ~
13201 \SpecialChar ~
13202 dph
13203 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13204
13205 \end_inset
13206
13207 ,#0x00
13208 \newline
13209 \SpecialChar ~
13210 \SpecialChar ~
13211 \SpecialChar ~
13212 \SpecialChar ~
13213 \SpecialChar ~
13214 \SpecialChar ~
13215 \SpecialChar ~
13216 \SpecialChar ~
13217 ret
13218 \layout Standard
13219
13220 Note here that the return values
13221 \begin_inset LatexCommand \index{return value}
13222
13223 \end_inset
13224
13225  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
13226  two byte values.
13227  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
13228 b' & 'acc' for four byte values.
13229 \layout Standard
13230
13231 The parameter naming convention is _<function_name>_PARM_<n>, where n is
13232  the parameter number starting from 1, and counting from the left.
13233  The first parameter is passed in
13234 \begin_inset Quotes eld
13235 \end_inset
13236
13237 dpl
13238 \begin_inset Quotes erd
13239 \end_inset
13240
13241  for a one byte parameter,
13242 \begin_inset Quotes eld
13243 \end_inset
13244
13245 dptr
13246 \begin_inset Quotes erd
13247 \end_inset
13248
13249  for two bytes,
13250 \begin_inset Quotes eld
13251 \end_inset
13252
13253 b,dptr
13254 \begin_inset Quotes erd
13255 \end_inset
13256
13257  for three bytes and
13258 \begin_inset Quotes eld
13259 \end_inset
13260
13261 acc,b,dptr
13262 \begin_inset Quotes erd
13263 \end_inset
13264
13265  for a four bytes parameter.
13266  The variable name for the second parameter will be _<function_name>_PARM_2.
13267 \newline
13268
13269 \newline
13270 Assemble the assembler routine with the following command:
13271 \newline
13272
13273 \newline
13274
13275 \family sans
13276 \series bold
13277 asx8051 -losg asmfunc.asm
13278 \newline
13279
13280 \newline
13281
13282 \family default
13283 \series default
13284 Then compile and link the assembler routine to the C source file with the
13285  following command:
13286 \newline
13287
13288 \newline
13289
13290 \family sans
13291 \series bold
13292 sdcc cfunc.c asmfunc.rel
13293 \layout Subsection
13294
13295 Assembler Routine (reentrant)
13296 \layout Standard
13297
13298 In this case
13299 \begin_inset LatexCommand \index{reentrant}
13300
13301 \end_inset
13302
13303
13304 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
13305
13306 \end_inset
13307
13308  the second parameter
13309 \begin_inset LatexCommand \index{function parameter}
13310
13311 \end_inset
13312
13313  onwards will be passed on the stack, the parameters are pushed from right
13314  to left i.e.
13315  after the call the leftmost parameter will be on the top of the stack.
13316  Here is an example:
13317 \layout Verse
13318
13319
13320 \family typewriter
13321 extern int asm_func(unsigned char, unsigned char);
13322 \newline
13323
13324 \newline
13325 int c_func (unsigned char i, unsigned char j) reentrant
13326 \newline
13327 {
13328 \newline
13329 \SpecialChar ~
13330 \SpecialChar ~
13331 \SpecialChar ~
13332 \SpecialChar ~
13333 return asm_func(i,j);
13334 \newline
13335 }
13336 \newline
13337
13338 \newline
13339 int main()
13340 \newline
13341 {
13342 \newline
13343 \SpecialChar ~
13344 \SpecialChar ~
13345 \SpecialChar ~
13346 \SpecialChar ~
13347 return c_func(10,9);
13348 \newline
13349 }
13350 \layout Standard
13351
13352 The corresponding assembler routine is:
13353 \layout Verse
13354
13355
13356 \family typewriter
13357 .globl _asm_func
13358 \newline
13359 _asm_func:
13360 \newline
13361 \SpecialChar ~
13362 \SpecialChar ~
13363 \SpecialChar ~
13364 \SpecialChar ~
13365 push  _bp
13366 \newline
13367 \SpecialChar ~
13368 \SpecialChar ~
13369 \SpecialChar ~
13370 \SpecialChar ~
13371 mov _bp,sp
13372 \newline
13373 \SpecialChar ~
13374 \SpecialChar ~
13375 \SpecialChar ~
13376 \SpecialChar ~
13377 mov r2,dpl
13378 \newline
13379 \SpecialChar ~
13380 \SpecialChar ~
13381 \SpecialChar ~
13382 \SpecialChar ~
13383 mov a,_bp
13384 \newline
13385 \SpecialChar ~
13386 \SpecialChar ~
13387 \SpecialChar ~
13388 \SpecialChar ~
13389 add a,#0xfd
13390 \newline
13391 \SpecialChar ~
13392 \SpecialChar ~
13393 \SpecialChar ~
13394 \SpecialChar ~
13395 mov r0,a
13396 \newline
13397 \SpecialChar ~
13398 \SpecialChar ~
13399 \SpecialChar ~
13400 \SpecialChar ~
13401 add  a,#0xfc ;?
13402 \newline
13403 \SpecialChar ~
13404 \SpecialChar ~
13405 \SpecialChar ~
13406 \SpecialChar ~
13407 mov  r1,a
13408 \newline
13409 \SpecialChar ~
13410 \SpecialChar ~
13411 \SpecialChar ~
13412 \SpecialChar ~
13413 mov  a,@r0
13414 \newline
13415 \SpecialChar ~
13416 \SpecialChar ~
13417 \SpecialChar ~
13418 \SpecialChar ~
13419 add  a,r2 ;?
13420 \newline
13421 \SpecialChar ~
13422 \SpecialChar ~
13423 \SpecialChar ~
13424 \SpecialChar ~
13425 mov  dpl,a
13426 \newline
13427 \SpecialChar ~
13428 \SpecialChar ~
13429 \SpecialChar ~
13430 \SpecialChar ~
13431 mov  dph,#0x00
13432 \newline
13433 \SpecialChar ~
13434 \SpecialChar ~
13435 \SpecialChar ~
13436 \SpecialChar ~
13437 mov  sp,_bp
13438 \newline
13439 \SpecialChar ~
13440 \SpecialChar ~
13441 \SpecialChar ~
13442 \SpecialChar ~
13443 pop  _bp
13444 \newline
13445 \SpecialChar ~
13446 \SpecialChar ~
13447 \SpecialChar ~
13448 \SpecialChar ~
13449 ret
13450 \layout Standard
13451
13452 The compiling and linking procedure remains the same, however note the extra
13453  entry & exit linkage required for the assembler code, _bp is the stack
13454  frame pointer and is used to compute the offset into the stack for parameters
13455  and local variables.
13456 \layout Section
13457
13458 int (16 bit)
13459 \begin_inset LatexCommand \index{int (16 bit)}
13460
13461 \end_inset
13462
13463  and long (32 bit)
13464 \begin_inset LatexCommand \index{long (32 bit)}
13465
13466 \end_inset
13467
13468  Support
13469 \layout Standard
13470
13471 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
13472  multiplication and modulus operations are implemented by support routines.
13473  These support routines are all developed in ANSI-C to facilitate porting
13474  to other MCUs, although some model specific assembler optimizations are
13475  used.
13476  The following files contain the described routines, all of them can be
13477  found in <installdir>/share/sdcc/lib.
13478 \newline
13479
13480 \layout Standard
13481 \align center
13482
13483 \begin_inset  Tabular
13484 <lyxtabular version="3" rows="11" columns="2">
13485 <features>
13486 <column alignment="center" valignment="top" leftline="true" width="0">
13487 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13488 <row topline="true" bottomline="true">
13489 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13490 \begin_inset Text
13491
13492 \layout Standard
13493
13494
13495 \series bold
13496 Function
13497 \end_inset
13498 </cell>
13499 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13500 \begin_inset Text
13501
13502 \layout Standard
13503
13504
13505 \series bold
13506 Description
13507 \end_inset
13508 </cell>
13509 </row>
13510 <row topline="true">
13511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13512 \begin_inset Text
13513
13514 \layout Standard
13515
13516 _mulint.c
13517 \end_inset
13518 </cell>
13519 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13520 \begin_inset Text
13521
13522 \layout Standard
13523
13524 16 bit multiplication
13525 \end_inset
13526 </cell>
13527 </row>
13528 <row topline="true">
13529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13530 \begin_inset Text
13531
13532 \layout Standard
13533
13534 _divsint.c
13535 \end_inset
13536 </cell>
13537 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13538 \begin_inset Text
13539
13540 \layout Standard
13541
13542  signed 16 bit division (calls _divuint)
13543 \end_inset
13544 </cell>
13545 </row>
13546 <row topline="true">
13547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13548 \begin_inset Text
13549
13550 \layout Standard
13551
13552 _divuint.c
13553 \end_inset
13554 </cell>
13555 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13556 \begin_inset Text
13557
13558 \layout Standard
13559
13560  unsigned 16 bit division
13561 \end_inset
13562 </cell>
13563 </row>
13564 <row topline="true">
13565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13566 \begin_inset Text
13567
13568 \layout Standard
13569
13570 _modsint.c
13571 \end_inset
13572 </cell>
13573 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13574 \begin_inset Text
13575
13576 \layout Standard
13577
13578 signed 16 bit modulus (calls _moduint)
13579 \end_inset
13580 </cell>
13581 </row>
13582 <row topline="true">
13583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13584 \begin_inset Text
13585
13586 \layout Standard
13587
13588 _moduint.c
13589 \end_inset
13590 </cell>
13591 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13592 \begin_inset Text
13593
13594 \layout Standard
13595
13596 unsigned 16 bit modulus
13597 \end_inset
13598 </cell>
13599 </row>
13600 <row topline="true">
13601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13602 \begin_inset Text
13603
13604 \layout Standard
13605
13606 _mullong.c
13607 \end_inset
13608 </cell>
13609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13610 \begin_inset Text
13611
13612 \layout Standard
13613
13614 32 bit multiplication
13615 \end_inset
13616 </cell>
13617 </row>
13618 <row topline="true">
13619 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13620 \begin_inset Text
13621
13622 \layout Standard
13623
13624 _divslong.c
13625 \end_inset
13626 </cell>
13627 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13628 \begin_inset Text
13629
13630 \layout Standard
13631
13632  signed 32 division (calls _divulong)
13633 \end_inset
13634 </cell>
13635 </row>
13636 <row topline="true">
13637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13638 \begin_inset Text
13639
13640 \layout Standard
13641
13642 _divulong.c
13643 \end_inset
13644 </cell>
13645 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13646 \begin_inset Text
13647
13648 \layout Standard
13649
13650 unsigned 32 division
13651 \end_inset
13652 </cell>
13653 </row>
13654 <row topline="true">
13655 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13656 \begin_inset Text
13657
13658 \layout Standard
13659
13660 _modslong.c
13661 \end_inset
13662 </cell>
13663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13664 \begin_inset Text
13665
13666 \layout Standard
13667
13668  signed 32 bit modulus (calls _modulong)
13669 \end_inset
13670 </cell>
13671 </row>
13672 <row topline="true" bottomline="true">
13673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13674 \begin_inset Text
13675
13676 \layout Standard
13677
13678 _modulong.c
13679 \end_inset
13680 </cell>
13681 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13682 \begin_inset Text
13683
13684 \layout Standard
13685
13686 unsigned 32 bit modulus
13687 \end_inset
13688 </cell>
13689 </row>
13690 </lyxtabular>
13691
13692 \end_inset
13693
13694
13695 \newline
13696
13697 \layout Standard
13698
13699 Since they are compiled as
13700 \emph on
13701 non-reentrant
13702 \emph default
13703
13704 \begin_inset LatexCommand \index{reentrant}
13705
13706 \end_inset
13707
13708 , interrupt
13709 \begin_inset LatexCommand \index{interrupt}
13710
13711 \end_inset
13712
13713  service routines should not do any of the above operations.
13714  If this is unavoidable then the above routines will need to be compiled
13715  with the
13716 \emph on
13717 -
13718 \begin_inset ERT
13719 status Collapsed
13720
13721 \layout Standard
13722
13723 \backslash
13724 /
13725 \end_inset
13726
13727 -stack-auto
13728 \begin_inset LatexCommand \index{-\/-stack-auto}
13729
13730 \end_inset
13731
13732
13733 \emph default
13734  option, after which the source program will have to be compiled with
13735 \emph on
13736 -
13737 \begin_inset ERT
13738 status Collapsed
13739
13740 \layout Standard
13741
13742 \backslash
13743 /
13744 \end_inset
13745
13746 -int-long-reent
13747 \begin_inset LatexCommand \index{-\/-int-long-reent}
13748
13749 \end_inset
13750
13751
13752 \emph default
13753  option.
13754  Notice that you don't have to call these routines directly.
13755  The compiler will use them automatically every time an integer operation
13756  is required.
13757 \layout Section
13758
13759 Floating Point Support
13760 \begin_inset LatexCommand \index{Floating point support}
13761
13762 \end_inset
13763
13764
13765 \layout Standard
13766
13767 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13768  floating point support routines are derived from gcc's floatlib.c and consist
13769  of the following routines:
13770 \newline
13771
13772 \layout Standard
13773 \align center
13774
13775 \size footnotesize
13776
13777 \begin_inset  Tabular
13778 <lyxtabular version="3" rows="17" columns="2">
13779 <features>
13780 <column alignment="center" valignment="top" leftline="true" width="0">
13781 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13782 <row topline="true" bottomline="true">
13783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13784 \begin_inset Text
13785
13786 \layout Standard
13787
13788
13789 \family roman
13790 \series medium
13791 \shape up
13792 \size normal
13793 \emph off
13794 \bar no
13795 \noun off
13796 \color none
13797 Function
13798 \end_inset
13799 </cell>
13800 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13801 \begin_inset Text
13802
13803 \layout Standard
13804
13805 Description
13806 \end_inset
13807 </cell>
13808 </row>
13809 <row topline="true">
13810 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13811 \begin_inset Text
13812
13813 \layout Standard
13814
13815
13816 \family roman
13817 \series medium
13818 \shape up
13819 \size normal
13820 \emph off
13821 \bar no
13822 \noun off
13823 \color none
13824 _fsadd.c
13825 \end_inset
13826 </cell>
13827 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13828 \begin_inset Text
13829
13830 \layout Standard
13831
13832
13833 \family roman
13834 \series medium
13835 \shape up
13836 \size normal
13837 \emph off
13838 \bar no
13839 \noun off
13840 \color none
13841 add floating point numbers
13842 \end_inset
13843 </cell>
13844 </row>
13845 <row topline="true">
13846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13847 \begin_inset Text
13848
13849 \layout Standard
13850
13851
13852 \family roman
13853 \series medium
13854 \shape up
13855 \size normal
13856 \emph off
13857 \bar no
13858 \noun off
13859 \color none
13860 _fssub.c
13861 \end_inset
13862 </cell>
13863 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13864 \begin_inset Text
13865
13866 \layout Standard
13867
13868
13869 \family roman
13870 \series medium
13871 \shape up
13872 \size normal
13873 \emph off
13874 \bar no
13875 \noun off
13876 \color none
13877 subtract floating point numbers
13878 \end_inset
13879 </cell>
13880 </row>
13881 <row topline="true">
13882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13883 \begin_inset Text
13884
13885 \layout Standard
13886
13887
13888 \family roman
13889 \series medium
13890 \shape up
13891 \size normal
13892 \emph off
13893 \bar no
13894 \noun off
13895 \color none
13896 _fsdiv.c
13897 \end_inset
13898 </cell>
13899 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13900 \begin_inset Text
13901
13902 \layout Standard
13903
13904
13905 \family roman
13906 \series medium
13907 \shape up
13908 \size normal
13909 \emph off
13910 \bar no
13911 \noun off
13912 \color none
13913 divide floating point numbers
13914 \end_inset
13915 </cell>
13916 </row>
13917 <row topline="true">
13918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13919 \begin_inset Text
13920
13921 \layout Standard
13922
13923
13924 \family roman
13925 \series medium
13926 \shape up
13927 \size normal
13928 \emph off
13929 \bar no
13930 \noun off
13931 \color none
13932 _fsmul.c
13933 \end_inset
13934 </cell>
13935 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13936 \begin_inset Text
13937
13938 \layout Standard
13939
13940
13941 \family roman
13942 \series medium
13943 \shape up
13944 \size normal
13945 \emph off
13946 \bar no
13947 \noun off
13948 \color none
13949 multiply floating point numbers
13950 \end_inset
13951 </cell>
13952 </row>
13953 <row topline="true">
13954 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13955 \begin_inset Text
13956
13957 \layout Standard
13958
13959
13960 \family roman
13961 \series medium
13962 \shape up
13963 \size normal
13964 \emph off
13965 \bar no
13966 \noun off
13967 \color none
13968 _fs2uchar.c
13969 \end_inset
13970 </cell>
13971 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13972 \begin_inset Text
13973
13974 \layout Standard
13975
13976
13977 \family roman
13978 \series medium
13979 \shape up
13980 \size normal
13981 \emph off
13982 \bar no
13983 \noun off
13984 \color none
13985 convert floating point to unsigned char
13986 \end_inset
13987 </cell>
13988 </row>
13989 <row topline="true">
13990 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13991 \begin_inset Text
13992
13993 \layout Standard
13994
13995
13996 \family roman
13997 \series medium
13998 \shape up
13999 \size normal
14000 \emph off
14001 \bar no
14002 \noun off
14003 \color none
14004 _fs2char.c
14005 \end_inset
14006 </cell>
14007 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14008 \begin_inset Text
14009
14010 \layout Standard
14011
14012
14013 \family roman
14014 \series medium
14015 \shape up
14016 \size normal
14017 \emph off
14018 \bar no
14019 \noun off
14020 \color none
14021 convert floating point to signed char
14022 \end_inset
14023 </cell>
14024 </row>
14025 <row topline="true">
14026 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14027 \begin_inset Text
14028
14029 \layout Standard
14030
14031
14032 \family roman
14033 \series medium
14034 \shape up
14035 \size normal
14036 \emph off
14037 \bar no
14038 \noun off
14039 \color none
14040 _fs2uint.c
14041 \end_inset
14042 </cell>
14043 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14044 \begin_inset Text
14045
14046 \layout Standard
14047
14048
14049 \family roman
14050 \series medium
14051 \shape up
14052 \size normal
14053 \emph off
14054 \bar no
14055 \noun off
14056 \color none
14057 convert floating point to unsigned int
14058 \end_inset
14059 </cell>
14060 </row>
14061 <row topline="true">
14062 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14063 \begin_inset Text
14064
14065 \layout Standard
14066
14067
14068 \family roman
14069 \series medium
14070 \shape up
14071 \size normal
14072 \emph off
14073 \bar no
14074 \noun off
14075 \color none
14076 _fs2int.c
14077 \end_inset
14078 </cell>
14079 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14080 \begin_inset Text
14081
14082 \layout Standard
14083
14084
14085 \family roman
14086 \series medium
14087 \shape up
14088 \size normal
14089 \emph off
14090 \bar no
14091 \noun off
14092 \color none
14093 convert floating point to signed int
14094 \end_inset
14095 </cell>
14096 </row>
14097 <row topline="true">
14098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14099 \begin_inset Text
14100
14101 \layout Standard
14102
14103
14104 \family roman
14105 \series medium
14106 \shape up
14107 \size normal
14108 \emph off
14109 \bar no
14110 \noun off
14111 \color none
14112 _fs2ulong.
14113 \family default
14114 \series default
14115 \shape default
14116 \size default
14117 \emph default
14118 \bar default
14119 \noun default
14120 \color default
14121 c
14122 \end_inset
14123 </cell>
14124 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14125 \begin_inset Text
14126
14127 \layout Standard
14128
14129
14130 \family roman
14131 \series medium
14132 \shape up
14133 \size normal
14134 \emph off
14135 \bar no
14136 \noun off
14137 \color none
14138 convert floating point to unsigned long
14139 \end_inset
14140 </cell>
14141 </row>
14142 <row topline="true">
14143 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14144 \begin_inset Text
14145
14146 \layout Standard
14147
14148
14149 \family roman
14150 \series medium
14151 \shape up
14152 \size normal
14153 \emph off
14154 \bar no
14155 \noun off
14156 \color none
14157 _fs2long.c
14158 \end_inset
14159 </cell>
14160 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14161 \begin_inset Text
14162
14163 \layout Standard
14164
14165
14166 \family roman
14167 \series medium
14168 \shape up
14169 \size normal
14170 \emph off
14171 \bar no
14172 \noun off
14173 \color none
14174 convert floating point to signed long
14175 \end_inset
14176 </cell>
14177 </row>
14178 <row topline="true">
14179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14180 \begin_inset Text
14181
14182 \layout Standard
14183
14184
14185 \family roman
14186 \series medium
14187 \shape up
14188 \size normal
14189 \emph off
14190 \bar no
14191 \noun off
14192 \color none
14193 _uchar2fs.c
14194 \end_inset
14195 </cell>
14196 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14197 \begin_inset Text
14198
14199 \layout Standard
14200
14201
14202 \family roman
14203 \series medium
14204 \shape up
14205 \size normal
14206 \emph off
14207 \bar no
14208 \noun off
14209 \color none
14210 convert unsigned char to floating point
14211 \end_inset
14212 </cell>
14213 </row>
14214 <row topline="true">
14215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14216 \begin_inset Text
14217
14218 \layout Standard
14219
14220
14221 \family roman
14222 \series medium
14223 \shape up
14224 \size normal
14225 \emph off
14226 \bar no
14227 \noun off
14228 \color none
14229 _char2fs.c
14230 \end_inset
14231 </cell>
14232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14233 \begin_inset Text
14234
14235 \layout Standard
14236
14237
14238 \family roman
14239 \series medium
14240 \shape up
14241 \size normal
14242 \emph off
14243 \bar no
14244 \noun off
14245 \color none
14246 convert char to floating point number
14247 \end_inset
14248 </cell>
14249 </row>
14250 <row topline="true">
14251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14252 \begin_inset Text
14253
14254 \layout Standard
14255
14256
14257 \family roman
14258 \series medium
14259 \shape up
14260 \size normal
14261 \emph off
14262 \bar no
14263 \noun off
14264 \color none
14265 _uint2fs.c
14266 \end_inset
14267 </cell>
14268 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14269 \begin_inset Text
14270
14271 \layout Standard
14272
14273
14274 \family roman
14275 \series medium
14276 \shape up
14277 \size normal
14278 \emph off
14279 \bar no
14280 \noun off
14281 \color none
14282 convert unsigned int to floating point
14283 \end_inset
14284 </cell>
14285 </row>
14286 <row topline="true">
14287 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14288 \begin_inset Text
14289
14290 \layout Standard
14291
14292
14293 \family roman
14294 \series medium
14295 \shape up
14296 \size normal
14297 \emph off
14298 \bar no
14299 \noun off
14300 \color none
14301 _int2fs.c
14302 \end_inset
14303 </cell>
14304 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14305 \begin_inset Text
14306
14307 \layout Standard
14308
14309
14310 \family roman
14311 \series medium
14312 \shape up
14313 \size normal
14314 \emph off
14315 \bar no
14316 \noun off
14317 \color none
14318 convert int to floating point numbers
14319 \end_inset
14320 </cell>
14321 </row>
14322 <row topline="true">
14323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14324 \begin_inset Text
14325
14326 \layout Standard
14327
14328
14329 \family roman
14330 \series medium
14331 \shape up
14332 \size normal
14333 \emph off
14334 \bar no
14335 \noun off
14336 \color none
14337 _ulong2fs.c
14338 \end_inset
14339 </cell>
14340 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14341 \begin_inset Text
14342
14343 \layout Standard
14344
14345
14346 \family roman
14347 \series medium
14348 \shape up
14349 \size normal
14350 \emph off
14351 \bar no
14352 \noun off
14353 \color none
14354 convert unsigned long to floating point number
14355 \end_inset
14356 </cell>
14357 </row>
14358 <row topline="true" bottomline="true">
14359 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14360 \begin_inset Text
14361
14362 \layout Standard
14363
14364
14365 \family roman
14366 \series medium
14367 \shape up
14368 \size normal
14369 \emph off
14370 \bar no
14371 \noun off
14372 \color none
14373 _long2fs.c
14374 \end_inset
14375 </cell>
14376 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14377 \begin_inset Text
14378
14379 \layout Standard
14380
14381
14382 \family roman
14383 \series medium
14384 \shape up
14385 \size normal
14386 \emph off
14387 \bar no
14388 \noun off
14389 \color none
14390 convert long to floating point number
14391 \end_inset
14392 </cell>
14393 </row>
14394 </lyxtabular>
14395
14396 \end_inset
14397
14398
14399 \newline
14400
14401 \layout Standard
14402
14403 These support routines are developed in ANSI-C so there is room for space
14404  and speed improvement
14405 \begin_inset Foot
14406 collapsed false
14407
14408 \layout Standard
14409
14410 The floating point routines for the mcs51 are implemented in assembler
14411 \end_inset
14412
14413 .
14414  Note if all these routines are used simultaneously the data space might
14415  overflow.
14416  For serious floating point usage the large model might be needed.
14417  Also notice that you don't have to call this routines directly.
14418  The compiler will use them automatically every time a floating point operation
14419  is required.
14420 \layout Section
14421
14422 Library Routines
14423 \begin_inset LatexCommand \index{Libraries}
14424
14425 \end_inset
14426
14427
14428 \layout Standard
14429
14430
14431 \emph on
14432 <pending: this is messy and incomplete - a little more information is in
14433  sdcc/doc/libdoc.txt
14434 \emph default
14435  >
14436 \layout Subsection
14437
14438 Compiler support routines (_gptrget, _mulint etc.)
14439 \layout Subsection
14440
14441 Stdclib functions (puts, printf, strcat etc.)
14442 \layout Subsubsection
14443
14444 <stdio.h>
14445 \layout Standard
14446
14447
14448 \begin_inset LatexCommand \index{<stdio.h>}
14449
14450 \end_inset
14451
14452 As usual on embedded systems you have to provide your own
14453 \family typewriter
14454 getchar()
14455 \begin_inset LatexCommand \index{getchar()}
14456
14457 \end_inset
14458
14459
14460 \family default
14461 and
14462 \family typewriter
14463 putchar()
14464 \begin_inset LatexCommand \index{putchar()}
14465
14466 \end_inset
14467
14468
14469 \family default
14470  routines.
14471  SDCC does not know whether the system connects to a serial line with or
14472  without handshake, LCD, keyboard or other device.
14473  You'll find examples for serial routines f.e.
14474  in sdcc/device/lib.
14475 \layout Standard
14476
14477 The default
14478 \family typewriter
14479  printf()
14480 \begin_inset LatexCommand \index{printf()}
14481
14482 \end_inset
14483
14484
14485 \family default
14486 implementation in
14487 \family typewriter
14488  printf_large.c
14489 \family default
14490  does not support float (except on ds390).
14491  To enable this recompile it with the option
14492 \emph on
14493 -
14494 \begin_inset ERT
14495 status Collapsed
14496
14497 \layout Standard
14498
14499 \backslash
14500 /
14501 \end_inset
14502
14503 DUSE_FLOATS=1
14504 \begin_inset LatexCommand \index{USE\_FLOATS}
14505
14506 \end_inset
14507
14508
14509 \emph default
14510  on the command line.
14511  Use
14512 \emph on
14513 -
14514 \begin_inset ERT
14515 status Collapsed
14516
14517 \layout Standard
14518
14519 \backslash
14520 /
14521 \end_inset
14522
14523 -model-large
14524 \begin_inset LatexCommand \index{-\/-model-large}
14525
14526 \end_inset
14527
14528
14529 \emph default
14530  for the mcs51 port, since this uses a lot of memory.
14531 \layout Standard
14532
14533 If you're short on memory you might want to use
14534 \family typewriter
14535 printf_small()
14536 \begin_inset LatexCommand \index{printf\_small()}
14537
14538 \end_inset
14539
14540
14541 \family default
14542
14543 \emph on
14544 instead
14545 \emph default
14546  of
14547 \family typewriter
14548  printf().
14549
14550 \family default
14551  For the mcs51 there additionally are assembly versions
14552 \family typewriter
14553 printf_tiny()
14554 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
14555
14556 \end_inset
14557
14558
14559 \family default
14560  and
14561 \family typewriter
14562 printf_fast()
14563 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
14564
14565 \end_inset
14566
14567
14568 \family default
14569 and
14570 \family typewriter
14571  printf_fast_f()
14572 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
14573
14574 \end_inset
14575
14576
14577 \family default
14578  which should fit the requirements of many embedded systems (printf_fast()
14579  can be customized by unsetting #defines to
14580 \emph on
14581 not
14582 \emph default
14583  support long variables and field widths).
14584 \layout Subsection
14585
14586 Math functions (sin, pow, sqrt etc.)
14587 \layout Subsection
14588
14589 Other libraries
14590 \layout Standard
14591
14592 Libraries
14593 \begin_inset LatexCommand \index{Libraries}
14594
14595 \end_inset
14596
14597  included in SDCC should have a license at least as liberal as the GNU Lesser
14598  General Public License
14599 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14600
14601 \end_inset
14602
14603
14604 \emph on
14605 LGPL
14606 \emph default
14607 .
14608 \layout Comment
14609
14610 license statements for the libraries are missing.
14611  sdcc/device/lib/ser_ir.c
14612 \layout Comment
14613
14614 or _decdptr f.e.
14615  come with a GPL (as opposed to LGPL) License - this will not be liberal
14616  enough for many embedded programmers.
14617 \layout Standard
14618
14619 If you have ported some library or want to share experience about some code
14620  which f.e.
14621  falls into any of these categories Busses (I
14622 \begin_inset Formula $^{\textrm{2}}$
14623 \end_inset
14624
14625 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14626  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14627  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14628 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14629
14630 \end_inset
14631
14632 \SpecialChar ~
14633 would certainly like to hear about it.
14634  Programmers coding for embedded systems are not especially famous for being
14635  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14636 e these references are very valuable.
14637  Let's help to create a climate where information is shared.
14638 \layout Section
14639
14640 Memory Models
14641 \layout Subsection
14642
14643 MCS51 Memory Models
14644 \begin_inset LatexCommand \index{Memory model}
14645
14646 \end_inset
14647
14648
14649 \begin_inset LatexCommand \index{MCS51 memory model}
14650
14651 \end_inset
14652
14653
14654 \layout Subsubsection
14655
14656 Small and Large
14657 \layout Standard
14658
14659 SDCC allows two memory models for MCS51 code,
14660 \shape slanted
14661 small
14662 \shape default
14663  and
14664 \shape slanted
14665 large
14666 \shape default
14667 .
14668  Modules compiled with different memory models should
14669 \emph on
14670 never
14671 \emph default
14672  be combined together or the results would be unpredictable.
14673  The library routines supplied with the compiler are compiled as both small
14674  and large.
14675  The compiled library modules are contained in separate directories as small
14676  and large so that you can link to either set.
14677
14678 \layout Standard
14679
14680 When the large model is used all variables declared without a storage class
14681  will be allocated into the external ram, this includes all parameters and
14682  local variables (for non-reentrant
14683 \begin_inset LatexCommand \index{reentrant}
14684
14685 \end_inset
14686
14687  functions).
14688  When the small model is used variables without storage class are allocated
14689  in the internal ram.
14690 \layout Standard
14691
14692 Judicious usage of the processor specific storage classes
14693 \begin_inset LatexCommand \index{Storage class}
14694
14695 \end_inset
14696
14697  and the 'reentrant' function type will yield much more efficient code,
14698  than using the large model.
14699  Several optimizations are disabled when the program is compiled using the
14700  large model, it is therefore recommended that the small model be used unless
14701  absolutely required.
14702 \layout Subsubsection
14703
14704 External Stack
14705 \begin_inset LatexCommand \label{sub:External-Stack}
14706
14707 \end_inset
14708
14709
14710 \begin_inset LatexCommand \index{stack}
14711
14712 \end_inset
14713
14714
14715 \begin_inset LatexCommand \index{External stack (mcs51)}
14716
14717 \end_inset
14718
14719
14720 \layout Standard
14721
14722 The external stack (-
14723 \begin_inset ERT
14724 status Collapsed
14725
14726 \layout Standard
14727
14728 \backslash
14729 /
14730 \end_inset
14731
14732 -xstack option
14733 \begin_inset LatexCommand \index{-\/-xstack}
14734
14735 \end_inset
14736
14737 ) is located in pdata
14738 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14739
14740 \end_inset
14741
14742  memory (usually at the start of the external ram segment) and uses all
14743  unused space in pdata (max.
14744  256 bytes).
14745  When -
14746 \begin_inset ERT
14747 status Collapsed
14748
14749 \layout Standard
14750
14751 \backslash
14752 /
14753 \end_inset
14754
14755 -xstack option is used to compile the program, the parameters and local
14756  variables
14757 \begin_inset LatexCommand \index{local variables}
14758
14759 \end_inset
14760
14761  of all reentrant functions are allocated in this area.
14762  This option is provided for programs with large stack space requirements.
14763  When used with the -
14764 \begin_inset ERT
14765 status Collapsed
14766
14767 \layout Standard
14768
14769 \backslash
14770 /
14771 \end_inset
14772
14773 -stack-auto
14774 \begin_inset LatexCommand \index{-\/-stack-auto}
14775
14776 \end_inset
14777
14778  option, all parameters and local variables are allocated on the external
14779  stack (note: support libraries will need to be recompiled with the same
14780  options.
14781  There is a predefined target in the library makefile).
14782 \layout Standard
14783
14784 The compiler outputs the higher order address byte of the external ram segment
14785  into port P2
14786 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14787
14788 \end_inset
14789
14790  (see also section
14791 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14792
14793 \end_inset
14794
14795 ), therefore when using the External Stack option, this port
14796 \emph on
14797 may not
14798 \emph default
14799  be used by the application program.
14800 \layout Subsection
14801
14802 DS390 Memory Model
14803 \begin_inset LatexCommand \index{Memory model}
14804
14805 \end_inset
14806
14807
14808 \begin_inset LatexCommand \index{DS390 memory model}
14809
14810 \end_inset
14811
14812
14813 \layout Standard
14814
14815 The only model supported is Flat 24
14816 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
14817
14818 \end_inset
14819
14820 .
14821  This generates code for the 24 bit contiguous addressing mode of the Dallas
14822  DS80C390 part.
14823  In this mode, up to four meg of external RAM or code space can be directly
14824  addressed.
14825  See the data sheets at www.dalsemi.com for further information on this part.
14826 \newline
14827
14828 \newline
14829 Note that the compiler does not generate any code to place the processor
14830  into 24 bitmode (although
14831 \emph on
14832 tinibios
14833 \emph default
14834  in the ds390 libraries will do that for you).
14835  If you don't use
14836 \emph on
14837 tinibios
14838 \emph default
14839
14840 \begin_inset LatexCommand \index{Tinibios (DS390)}
14841
14842 \end_inset
14843
14844 , the boot loader or similar code must ensure that the processor is in 24
14845  bit contiguous addressing mode before calling the SDCC startup code.
14846 \newline
14847
14848 \newline
14849 Like the
14850 \emph on
14851 -
14852 \begin_inset ERT
14853 status Collapsed
14854
14855 \layout Standard
14856
14857 \backslash
14858 /
14859 \end_inset
14860
14861 -model-large
14862 \emph default
14863  option, variables will by default be placed into the XDATA segment.
14864
14865 \newline
14866
14867 \newline
14868 Segments may be placed anywhere in the 4 meg address space using the usual
14869  -
14870 \begin_inset ERT
14871 status Collapsed
14872
14873 \layout Standard
14874
14875 \backslash
14876 /
14877 \end_inset
14878
14879 -*-loc options.
14880  Note that if any segments are located above 64K, the -r flag must be passed
14881  to the linker to generate the proper segment relocations, and the Intel
14882  HEX output format must be used.
14883  The -r flag can be passed to the linker by using the option
14884 \emph on
14885 -Wl-r
14886 \emph default
14887  on the SDCC command line.
14888  However, currently the linker can not handle code segments > 64k.
14889 \layout Section
14890
14891 Pragmas
14892 \begin_inset LatexCommand \index{Pragmas}
14893
14894 \end_inset
14895
14896
14897 \layout Standard
14898
14899 SDCC supports the following #pragma directives:
14900 \layout Itemize
14901
14902 save
14903 \begin_inset LatexCommand \index{\#pragma save}
14904
14905 \end_inset
14906
14907  - this will save all current options to the save/restore stack.
14908  See #pragma\SpecialChar ~
14909 restore.
14910 \layout Itemize
14911
14912 restore
14913 \begin_inset LatexCommand \index{\#pragma restore}
14914
14915 \end_inset
14916
14917  - will restore saved options from the last save.
14918  saves & restores can be nested.
14919  SDCC uses a save/restore stack: save pushes current options to the stack,
14920  restore pulls current options from the stack.
14921  See #pragma\SpecialChar ~
14922 save.
14923 \newline
14924
14925 \layout Itemize
14926
14927 callee_saves
14928 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14929
14930 \end_inset
14931
14932
14933 \begin_inset LatexCommand \index{function prologue}
14934
14935 \end_inset
14936
14937  function1[,function2[,function3...]] - The compiler by default uses a caller
14938  saves convention for register saving across function calls, however this
14939  can cause unnecessary register pushing & popping
14940 \begin_inset LatexCommand \index{push/pop}
14941
14942 \end_inset
14943
14944  when calling small functions from larger functions.
14945  This option can be used to switch off the register saving convention for
14946  the function names specified.
14947  The compiler will not save registers when calling these functions, extra
14948  code need to be manually inserted at the entry & exit for these functions
14949  to save & restore the registers used by these functions, this can SUBSTANTIALLY
14950  reduce code & improve run time performance of the generated code.
14951  In the future the compiler (with inter procedural analysis) may be able
14952  to determine the appropriate scheme to use for each function call.
14953  If -
14954 \begin_inset ERT
14955 status Collapsed
14956
14957 \layout Standard
14958
14959 \backslash
14960 /
14961 \end_inset
14962
14963 -callee-saves command line option is used, the function names specified
14964  in #pragma\SpecialChar ~
14965 callee_saves
14966 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14967
14968 \end_inset
14969
14970  is appended to the list of functions specified in the command line.
14971 \layout Itemize
14972
14973 exclude
14974 \begin_inset LatexCommand \index{\#pragma exclude}
14975
14976 \end_inset
14977
14978  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
14979  of pairs of push/pop
14980 \begin_inset LatexCommand \index{push/pop}
14981
14982 \end_inset
14983
14984  instructions in
14985 \emph on
14986 I
14987 \emph default
14988 nterrupt
14989 \begin_inset LatexCommand \index{interrupt}
14990
14991 \end_inset
14992
14993
14994 \emph on
14995 S
14996 \emph default
14997 ervice
14998 \emph on
14999 R
15000 \emph default
15001 outines.
15002  The directive should be placed immediately before the ISR function definition
15003  and it affects ALL ISR functions following it.
15004  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15005 exclude\SpecialChar ~
15006 none
15007 \begin_inset LatexCommand \index{\#pragma exclude}
15008
15009 \end_inset
15010
15011 .
15012  See also the related keyword _naked
15013 \begin_inset LatexCommand \index{\_naked}
15014
15015 \end_inset
15016
15017
15018 \begin_inset LatexCommand \index{\_\_naked}
15019
15020 \end_inset
15021
15022 .
15023 \layout Itemize
15024
15025 less_pedantic
15026 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15027
15028 \end_inset
15029
15030  - the compiler will not warn you anymore for obvious mistakes, you'r on
15031  your own now ;-(
15032 \layout Itemize
15033
15034 disable_warning <nnnn>
15035 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15036
15037 \end_inset
15038
15039  - the compiler will not warn you anymore about warning number <nnnn>.
15040 \layout Itemize
15041
15042 nogcse
15043 \begin_inset LatexCommand \index{\#pragma nogcse}
15044
15045 \end_inset
15046
15047  - will stop global common subexpression elimination.
15048 \layout Itemize
15049
15050 noinduction
15051 \begin_inset LatexCommand \index{\#pragma noinduction}
15052
15053 \end_inset
15054
15055  - will stop loop induction optimizations.
15056 \layout Itemize
15057
15058 noinvariant
15059 \begin_inset LatexCommand \index{\#pragma noinvariant}
15060
15061 \end_inset
15062
15063  - will not do loop invariant optimizations.
15064  For more details see Loop Invariants in section
15065 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15066
15067 \end_inset
15068
15069 .
15070 \layout Itemize
15071
15072 noiv
15073 \begin_inset LatexCommand \index{\#pragma noiv}
15074
15075 \end_inset
15076
15077  - Do not generate interrupt
15078 \begin_inset LatexCommand \index{interrupt}
15079
15080 \end_inset
15081
15082  vector table entries for all ISR functions defined after the pragma.
15083  This is useful in cases where the interrupt vector table must be defined
15084  manually, or when there is a secondary, manually defined interrupt vector
15085  table (e.g.
15086  for the autovector feature of the Cypress EZ-USB FX2).
15087  More elegantly this can be achieved by obmitting the optional interrupt
15088  number after the interrupt keyword, see section
15089 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15090
15091 \end_inset
15092
15093 \SpecialChar ~
15094 about interrupts.
15095 \layout Itemize
15096
15097 nojtbound
15098 \begin_inset LatexCommand \index{\#pragma nojtbound}
15099
15100 \end_inset
15101
15102  - will not generate code for boundary value checking, when switch statements
15103  are turned into jump-tables (dangerous).
15104  For more details see section
15105 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15106
15107 \end_inset
15108
15109 .
15110 \layout Itemize
15111
15112 noloopreverse
15113 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15114
15115 \end_inset
15116
15117  - Will not do loop reversal optimization
15118 \layout Itemize
15119
15120 nooverlay
15121 \begin_inset LatexCommand \index{\#pragma nooverlay}
15122
15123 \end_inset
15124
15125  - the compiler will not overlay the parameters and local variables of a
15126  function.
15127 \layout Itemize
15128
15129 stackauto
15130 \begin_inset LatexCommand \index{\#pragma stackauto}
15131
15132 \end_inset
15133
15134 - See option -
15135 \begin_inset ERT
15136 status Collapsed
15137
15138 \layout Standard
15139
15140 \backslash
15141 /
15142 \end_inset
15143
15144 -stack-auto
15145 \begin_inset LatexCommand \index{-\/-stack-auto}
15146
15147 \end_inset
15148
15149  and section
15150 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
15151
15152 \end_inset
15153
15154  Parameters and Local Variables.
15155 \layout Itemize
15156
15157 opt_code_speed
15158 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
15159
15160 \end_inset
15161
15162 - The compiler will optimize code generation towards fast code, possibly
15163  at the expense of code size.
15164 \layout Itemize
15165
15166 opt_code_size
15167 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
15168
15169 \end_inset
15170
15171 - The compiler will optimize code generation towards compact code, possibly
15172  at the expense of code speed.
15173 \layout Itemize
15174
15175 opt_code_balanced
15176 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
15177
15178 \end_inset
15179
15180 - The compiler will attempt to generate code that is both compact and fast,
15181  as long as meeting one goal is not a detriment to the other (this is the
15182  default).
15183
15184 \layout Itemize
15185
15186 std_sdcc89
15187 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
15188
15189 \end_inset
15190
15191 - Generally follow the C89 standard, but allow SDCC features that conflict
15192  with the standard (default).
15193 \layout Itemize
15194
15195 std_c89
15196 \begin_inset LatexCommand \index{\#pragma std\_c89}
15197
15198 \end_inset
15199
15200 - Follow the C89 standard and disable SDCC features that conflict with the
15201  standard.
15202 \layout Itemize
15203
15204 std_sdcc99
15205 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
15206
15207 \end_inset
15208
15209 - Generally follow the C99 standard, but allow SDCC features that conflict
15210  with the standard (incomplete support).
15211 \layout Itemize
15212
15213 std_c99
15214 \begin_inset LatexCommand \index{\#pragma std\_c99}
15215
15216 \end_inset
15217
15218 - Follow the C99 standard and disable SDCC features that conflict with the
15219  standard (incomplete support).
15220 \layout Standard
15221
15222 SDCPP supports the following #pragma directives:
15223 \layout Itemize
15224
15225 preproc_asm
15226 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
15227
15228 \end_inset
15229
15230  (+ | -) - switch _asm _endasm block preprocessing on / off.
15231  Default is on.
15232 \layout Standard
15233
15234 The pragma's are intended to be used to turn-on or off certain optimizations
15235  which might cause the compiler to generate extra stack / data space to
15236  store compiler generated temporary variables.
15237  This usually happens in large functions.
15238  Pragma directives should be used as shown in the following example, they
15239  are used to control options & optimizations for a given function; pragmas
15240  should be placed before and/or after a function, placing pragma's inside
15241  a function body could have unpredictable results.
15242 \layout Verse
15243
15244
15245 \family typewriter
15246 #pragma save
15247 \begin_inset LatexCommand \index{\#pragma save}
15248
15249 \end_inset
15250
15251  \SpecialChar ~
15252 \SpecialChar ~
15253 \SpecialChar ~
15254 \SpecialChar ~
15255 \SpecialChar ~
15256 \SpecialChar ~
15257 \SpecialChar ~
15258 /* save the current settings */
15259 \newline
15260 #pragma nogcse
15261 \begin_inset LatexCommand \index{\#pragma nogcse}
15262
15263 \end_inset
15264
15265  \SpecialChar ~
15266 \SpecialChar ~
15267 \SpecialChar ~
15268 \SpecialChar ~
15269 \SpecialChar ~
15270 /* turnoff global subexpression elimination */
15271 \newline
15272 #pragma noinduction
15273 \begin_inset LatexCommand \index{\#pragma noinduction}
15274
15275 \end_inset
15276
15277  /* turn off induction optimizations */
15278 \newline
15279 int foo ()
15280 \newline
15281 {
15282 \newline
15283 \SpecialChar ~
15284  \SpecialChar ~
15285  ...
15286
15287 \newline
15288 \SpecialChar ~
15289  \SpecialChar ~
15290  /* large code */
15291 \newline
15292 \SpecialChar ~
15293  \SpecialChar ~
15294  ...
15295
15296 \newline
15297 }
15298 \newline
15299 #pragma restore
15300 \begin_inset LatexCommand \index{\#pragma restore}
15301
15302 \end_inset
15303
15304  /* turn the optimizations back on */
15305 \layout Standard
15306
15307 The compiler will generate a warning message when extra space is allocated.
15308  It is strongly recommended that the save and restore pragma's be used when
15309  changing options for a function.
15310 \layout Section
15311
15312 Defines Created by the Compiler
15313 \layout Standard
15314
15315 The compiler creates the following #defines
15316 \begin_inset LatexCommand \index{\#defines}
15317
15318 \end_inset
15319
15320
15321 \begin_inset LatexCommand \index{Defines created by the compiler}
15322
15323 \end_inset
15324
15325 :
15326 \newline
15327
15328 \layout Standard
15329
15330
15331 \begin_inset  Tabular
15332 <lyxtabular version="3" rows="10" columns="2">
15333 <features>
15334 <column alignment="center" valignment="top" leftline="true" width="0">
15335 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15336 <row topline="true" bottomline="true">
15337 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15338 \begin_inset Text
15339
15340 \layout Standard
15341
15342
15343 \series bold
15344 #define
15345 \end_inset
15346 </cell>
15347 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15348 \begin_inset Text
15349
15350 \layout Standard
15351
15352
15353 \series bold
15354 Description
15355 \end_inset
15356 </cell>
15357 </row>
15358 <row topline="true">
15359 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15360 \begin_inset Text
15361
15362 \layout Standard
15363
15364 SDCC
15365 \begin_inset LatexCommand \index{SDCC}
15366
15367 \end_inset
15368
15369
15370 \end_inset
15371 </cell>
15372 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15373 \begin_inset Text
15374
15375 \layout Standard
15376
15377 this Symbol is always defined
15378 \end_inset
15379 </cell>
15380 </row>
15381 <row topline="true">
15382 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15383 \begin_inset Text
15384
15385 \layout Standard
15386
15387 SDCC_mcs51
15388 \begin_inset LatexCommand \index{SDCC\_mcs51}
15389
15390 \end_inset
15391
15392  or SDCC_ds390
15393 \begin_inset LatexCommand \index{SDCC\_ds390}
15394
15395 \end_inset
15396
15397  or SDCC_z80
15398 \begin_inset LatexCommand \index{SDCC\_z80}
15399
15400 \end_inset
15401
15402 , etc
15403 \end_inset
15404 </cell>
15405 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15406 \begin_inset Text
15407
15408 \layout Standard
15409
15410 depending on the model used (e.g.: -mds390
15411 \end_inset
15412 </cell>
15413 </row>
15414 <row topline="true">
15415 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15416 \begin_inset Text
15417
15418 \layout Standard
15419
15420 __mcs51
15421 \begin_inset LatexCommand \index{\_\_mcs51}
15422
15423 \end_inset
15424
15425 , __ds390
15426 \begin_inset LatexCommand \index{\_\_ds390}
15427
15428 \end_inset
15429
15430 , __hc08
15431 \begin_inset LatexCommand \index{\_\_hc08}
15432
15433 \end_inset
15434
15435 , __z80
15436 \begin_inset LatexCommand \index{\_\_z80}
15437
15438 \end_inset
15439
15440 , etc
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 depending on the model used (e.g.
15449  -mz80)
15450 \end_inset
15451 </cell>
15452 </row>
15453 <row topline="true">
15454 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15455 \begin_inset Text
15456
15457 \layout Standard
15458
15459 SDCC_STACK_AUTO
15460 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
15461
15462 \end_inset
15463
15464
15465 \end_inset
15466 </cell>
15467 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15468 \begin_inset Text
15469
15470 \layout Standard
15471
15472 when
15473 \emph on
15474 -
15475 \begin_inset ERT
15476 status Collapsed
15477
15478 \layout Standard
15479
15480 \backslash
15481 /
15482 \end_inset
15483
15484 -stack-auto
15485 \emph default
15486  option is used
15487 \end_inset
15488 </cell>
15489 </row>
15490 <row topline="true">
15491 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15492 \begin_inset Text
15493
15494 \layout Standard
15495
15496 SDCC_MODEL_SMALL
15497 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
15498
15499 \end_inset
15500
15501
15502 \end_inset
15503 </cell>
15504 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15505 \begin_inset Text
15506
15507 \layout Standard
15508
15509 when
15510 \emph on
15511 -
15512 \begin_inset ERT
15513 status Collapsed
15514
15515 \layout Standard
15516
15517 \backslash
15518 /
15519 \end_inset
15520
15521 -model-small
15522 \emph default
15523  is used
15524 \end_inset
15525 </cell>
15526 </row>
15527 <row topline="true">
15528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15529 \begin_inset Text
15530
15531 \layout Standard
15532
15533 SDCC_MODEL_LARGE
15534 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
15535
15536 \end_inset
15537
15538
15539 \end_inset
15540 </cell>
15541 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15542 \begin_inset Text
15543
15544 \layout Standard
15545
15546 when
15547 \emph on
15548 -
15549 \begin_inset ERT
15550 status Collapsed
15551
15552 \layout Standard
15553
15554 \backslash
15555 /
15556 \end_inset
15557
15558 -model-large
15559 \emph default
15560  is used
15561 \end_inset
15562 </cell>
15563 </row>
15564 <row topline="true">
15565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15566 \begin_inset Text
15567
15568 \layout Standard
15569
15570 SDCC_USE_XSTACK
15571 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15572
15573 \end_inset
15574
15575
15576 \end_inset
15577 </cell>
15578 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15579 \begin_inset Text
15580
15581 \layout Standard
15582
15583 when
15584 \emph on
15585 -
15586 \begin_inset ERT
15587 status Collapsed
15588
15589 \layout Standard
15590
15591 \backslash
15592 /
15593 \end_inset
15594
15595 -xstack
15596 \emph default
15597  option is used
15598 \end_inset
15599 </cell>
15600 </row>
15601 <row topline="true">
15602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15603 \begin_inset Text
15604
15605 \layout Standard
15606
15607 SDCC_STACK_TENBIT
15608 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
15609
15610 \end_inset
15611
15612
15613 \end_inset
15614 </cell>
15615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15616 \begin_inset Text
15617
15618 \layout Standard
15619
15620 when
15621 \emph on
15622 -mds390
15623 \emph default
15624  is used
15625 \end_inset
15626 </cell>
15627 </row>
15628 <row topline="true" bottomline="true">
15629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15630 \begin_inset Text
15631
15632 \layout Standard
15633
15634 SDCC_MODEL_FLAT24
15635 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
15636
15637 \end_inset
15638
15639
15640 \end_inset
15641 </cell>
15642 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15643 \begin_inset Text
15644
15645 \layout Standard
15646
15647 when
15648 \emph on
15649 -mds390
15650 \emph default
15651  is used
15652 \end_inset
15653 </cell>
15654 </row>
15655 </lyxtabular>
15656
15657 \end_inset
15658
15659
15660 \layout Chapter
15661
15662 Notes on supported Processors
15663 \layout Section
15664
15665 MCS51 variants
15666 \begin_inset LatexCommand \label{sub:MCS51-variants}
15667
15668 \end_inset
15669
15670
15671 \begin_inset LatexCommand \index{MCS51 variants}
15672
15673 \end_inset
15674
15675
15676 \layout Standard
15677
15678 MCS51 processors are available from many vendors and come in many different
15679  flavours.
15680  While they might differ considerably in respect to Special Function Registers
15681  the core MCS51 is usually not modified or is kept compatible.
15682
15683 \layout Subsection
15684
15685 pdata access by SFR
15686 \layout Standard
15687
15688 With the upcome of devices with internal xdata and flash memory devices
15689  using port P2
15690 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15691
15692 \end_inset
15693
15694  as dedicated I/O port is becoming more popular.
15695  Switching the high byte for pdata
15696 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15697
15698 \end_inset
15699
15700  access which was formerly done by port P2 is then achieved by a Special
15701  Function Register
15702 \begin_inset LatexCommand \index{sfr}
15703
15704 \end_inset
15705
15706 .
15707  In well-established MCS51 tradition the address of this
15708 \emph on
15709 sfr
15710 \emph default
15711  is where the chip designers decided to put it.
15712  Needless to say that they didn't agree on a common name either.
15713  So that the startup code can correctly initialize xdata variables, you
15714  should define an sfr with the name _XPAGE
15715 \family typewriter
15716
15717 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
15718
15719 \end_inset
15720
15721
15722 \family default
15723  at the appropriate location if the default, port P2, is not used for this.
15724  Some examples are:
15725 \layout Verse
15726
15727
15728 \family typewriter
15729 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
15730 \layout Verse
15731
15732
15733 \family typewriter
15734 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
15735 \layout Verse
15736
15737
15738 \family typewriter
15739 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
15740 \layout Standard
15741
15742 For more exotic implementations further customizations may be needed.
15743  See section
15744 \begin_inset LatexCommand \ref{sub:Startup-Code}
15745
15746 \end_inset
15747
15748  for other possibilities.
15749 \layout Subsection
15750
15751 Other Features available by SFR
15752 \layout Standard
15753
15754 Some MCS51 variants offer features like Double DPTR
15755 \begin_inset LatexCommand \index{DPTR}
15756
15757 \end_inset
15758
15759 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
15760  These are currently not used for the MCS51 port.
15761  If you absolutely need them you can fall back to inline assembly or submit
15762  a patch to SDCC.
15763 \layout Section
15764
15765 DS400 port
15766 \layout Standard
15767
15768 The DS80C400 microcontroller has a rich set of peripherals.
15769  In its built-in ROM library it includes functions to access some of the
15770  features, among them is a TCP stack with IP4 and IP6 support.
15771  Library headers (currently in beta status) and other files are provided
15772  at
15773 \size footnotesize
15774
15775 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
15776
15777 \end_inset
15778
15779 .
15780
15781 \layout Section
15782
15783 The Z80 and gbz80 port
15784 \layout Standard
15785
15786 SDCC can target both the Zilog
15787 \begin_inset LatexCommand \index{Z80}
15788
15789 \end_inset
15790
15791  and the Nintendo Gameboy's Z80-like gbz80
15792 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
15793
15794 \end_inset
15795
15796 .
15797  The Z80 port is passed through the same
15798 \emph on
15799 regressions tests
15800 \begin_inset LatexCommand \index{Regression test}
15801
15802 \end_inset
15803
15804
15805 \emph default
15806  as the MCS51 and DS390 ports, so floating point support, support for long
15807  variables and bitfield support is fine.
15808  See mailing lists and forums about interrupt routines.
15809 \layout Standard
15810
15811 As always, the code is the authoritative reference - see z80/ralloc.c and
15812  z80/gen.c.
15813  The stack
15814 \begin_inset LatexCommand \index{stack}
15815
15816 \end_inset
15817
15818  frame is similar to that generated by the IAR Z80 compiler.
15819  IX is used as the base pointer, HL and IY are used as a temporary registers,
15820  and BC and DE are available for holding variables.
15821  Return values
15822 \begin_inset LatexCommand \index{return value}
15823
15824 \end_inset
15825
15826  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
15827  bytes).
15828  The gbz80 port use the same set of registers for the return values, but
15829  in a different order of significance: E (one byte), DE (two bytes), or
15830  HLDE (four bytes).
15831 \layout Section
15832
15833 The HC08 port
15834 \layout Standard
15835
15836 The port to the Motorola HC08
15837 \begin_inset LatexCommand \index{HC08}
15838
15839 \end_inset
15840
15841  family has been added in October 2003, and is still undergoing some basic
15842  development.
15843  The code generator is complete, but the register allocation is still quite
15844  unoptimized.
15845  Some of the SDCC's standard C library functions have embedded non-HC08
15846  inline assembly and so are not yet usable.
15847 \newline
15848
15849 \newline
15850
15851 \layout Section
15852
15853 The PIC14 port
15854 \layout Standard
15855
15856 The 14bit PIC
15857 \begin_inset LatexCommand \index{PIC14}
15858
15859 \end_inset
15860
15861  port still requires a major effort from the development community.
15862  However it can work for very simple code.
15863 \layout Subsection
15864
15865 C code and 14bit PIC code page
15866 \begin_inset LatexCommand \index{code page (pic14)}
15867
15868 \end_inset
15869
15870  and RAM banks
15871 \begin_inset LatexCommand \index{RAM bank (pic14)}
15872
15873 \end_inset
15874
15875
15876 \layout Standard
15877
15878 The linker organizes allocation for the code page and RAM banks.
15879  It does not have intimate knowledge of the code flow.
15880  It will put all the code section of a single asm file into a single code
15881  page.
15882  In order to make use of multiple code pages, separate asm files must be
15883  used.
15884  The compiler treats all functions of a single C file as being in the same
15885  code page unless it is non static.
15886  The compiler treats all local variables of a single C file as being in
15887  the same RAM bank unless it is an extern.
15888 \newline
15889
15890 \newline
15891 To get the best follow these guide lines:
15892 \layout Enumerate
15893
15894 make local functions static, as non static functions require code page selection
15895  overhead.
15896 \layout Enumerate
15897
15898 Make local variables static as extern variables require RAM bank selection
15899  overhead.
15900 \layout Enumerate
15901
15902 For devices that have multiple code pages it is more efficient to use the
15903  same number of files as pages, i.e.
15904  for the 16F877 use 4 separate files and i.e.
15905  for the 16F874 use 2 separate files.
15906  This way the linker can put the code for each file into different code
15907  pages and the compiler can allocate reusable variables more efficiently
15908  and there's less page selection overhead.
15909  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
15910  instruction set) use 'unsigned char' whereever possible instead of 'int'.
15911 \layout Subsection
15912
15913 Creating a device include file
15914 \layout Standard
15915
15916 For generating a device include file use the support perl script inc2h.pl
15917  kept in directory support/script.
15918 \layout Subsection
15919
15920 Interrupt code
15921 \layout Standard
15922
15923 For the interrupt function, use the keyword 'interrupt'
15924 \begin_inset LatexCommand \index{interrupt}
15925
15926 \end_inset
15927
15928  with level number of 0 (PIC14 only has 1 interrupt so this number is only
15929  there to avoid a syntax error - it ought to be fixed).
15930  E.g.:
15931 \layout Verse
15932
15933
15934 \family typewriter
15935 void Intr(void) interrupt 0
15936 \newline
15937 {
15938 \newline
15939 \SpecialChar ~
15940 \SpecialChar ~
15941 T0IF = 0; /* Clear timer interrupt */
15942 \newline
15943 }
15944 \layout Subsection
15945
15946 Linking and assembling
15947 \layout Standard
15948
15949 For assembling you can use either GPUTILS'
15950 \begin_inset LatexCommand \index{gputils (pic tools)}
15951
15952 \end_inset
15953
15954  gpasm.exe or MPLAB's mpasmwin.exe.
15955  GPUTILS is available from
15956 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
15957
15958 \end_inset
15959
15960 .
15961  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
15962  If you use MPLAB and an interrupt function then the linker script file
15963  vectors section will need to be enlarged to link with mplink.
15964 \newline
15965
15966 \newline
15967 Here is a
15968 \family typewriter
15969 Makefile
15970 \family default
15971  using GPUTILS:
15972 \layout Verse
15973
15974
15975 \family typewriter
15976 .c.o:
15977 \newline
15978 \SpecialChar ~
15979 \SpecialChar ~
15980 \SpecialChar ~
15981 \SpecialChar ~
15982 \SpecialChar ~
15983 \SpecialChar ~
15984 \SpecialChar ~
15985 \SpecialChar ~
15986 sdcc -S -V -mpic14 -p16F877 $<
15987 \newline
15988 \SpecialChar ~
15989 \SpecialChar ~
15990 \SpecialChar ~
15991 \SpecialChar ~
15992 \SpecialChar ~
15993 \SpecialChar ~
15994 \SpecialChar ~
15995 \SpecialChar ~
15996 gpasm -c $*.asm
15997 \newline
15998
15999 \newline
16000 $(PRJ).hex: $(OBJS)
16001 \newline
16002 \SpecialChar ~
16003 \SpecialChar ~
16004 \SpecialChar ~
16005 \SpecialChar ~
16006 \SpecialChar ~
16007 \SpecialChar ~
16008 \SpecialChar ~
16009 \SpecialChar ~
16010 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
16011 \layout Standard
16012
16013 Here is a
16014 \family typewriter
16015 Makefile
16016 \family default
16017  using MPLAB:
16018 \layout Verse
16019
16020
16021 \family typewriter
16022 .c.o:
16023 \newline
16024 \SpecialChar ~
16025 \SpecialChar ~
16026 \SpecialChar ~
16027 \SpecialChar ~
16028 \SpecialChar ~
16029 \SpecialChar ~
16030 \SpecialChar ~
16031 \SpecialChar ~
16032 sdcc -S -V -mpic14 -p16F877 $<
16033 \newline
16034 \SpecialChar ~
16035 \SpecialChar ~
16036 \SpecialChar ~
16037 \SpecialChar ~
16038 \SpecialChar ~
16039 \SpecialChar ~
16040 \SpecialChar ~
16041 \SpecialChar ~
16042 mpasmwin /q /o $*.asm
16043 \newline
16044
16045 \newline
16046 $(PRJ).hex: $(OBJS)
16047 \newline
16048 \SpecialChar ~
16049 \SpecialChar ~
16050 \SpecialChar ~
16051 \SpecialChar ~
16052 \SpecialChar ~
16053 \SpecialChar ~
16054 \SpecialChar ~
16055 \SpecialChar ~
16056 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
16057 \layout Standard
16058
16059 Please note that indentations within a
16060 \family typewriter
16061  Makefile
16062 \family default
16063  have to be done with a tabulator character.
16064 \layout Section
16065
16066 The PIC16
16067 \begin_inset LatexCommand \index{PIC16}
16068
16069 \end_inset
16070
16071  port
16072 \layout Standard
16073
16074 The PIC16
16075 \begin_inset LatexCommand \index{PIC16}
16076
16077 \end_inset
16078
16079  port is the portion of SDCC that is responsible to produce code for the
16080  Microchip
16081 \begin_inset LatexCommand \index{Microchip}
16082
16083 \end_inset
16084
16085 (TM) microcontrollers with 16 bit core.
16086  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
16087  Currently supported devices are:
16088 \layout Standard
16089 \align center
16090
16091 \begin_inset  Tabular
16092 <lyxtabular version="3" rows="4" columns="6">
16093 <features>
16094 <column alignment="center" valignment="top" leftline="true" width="0">
16095 <column alignment="center" valignment="top" leftline="true" width="0">
16096 <column alignment="center" valignment="top" leftline="true" width="0">
16097 <column alignment="center" valignment="top" leftline="true" width="0">
16098 <column alignment="center" valignment="top" leftline="true" width="0">
16099 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16100 <row topline="true">
16101 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16102 \begin_inset Text
16103
16104 \layout Standard
16105
16106 18F242
16107 \end_inset
16108 </cell>
16109 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16110 \begin_inset Text
16111
16112 \layout Standard
16113
16114 18F248
16115 \end_inset
16116 </cell>
16117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16118 \begin_inset Text
16119
16120 \layout Standard
16121
16122 18F252
16123 \end_inset
16124 </cell>
16125 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16126 \begin_inset Text
16127
16128 \layout Standard
16129
16130 18F258
16131 \end_inset
16132 </cell>
16133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16134 \begin_inset Text
16135
16136 \layout Standard
16137
16138 18F442
16139 \end_inset
16140 </cell>
16141 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16142 \begin_inset Text
16143
16144 \layout Standard
16145
16146 18F448
16147 \end_inset
16148 </cell>
16149 </row>
16150 <row topline="true">
16151 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16152 \begin_inset Text
16153
16154 \layout Standard
16155
16156 18F452
16157 \end_inset
16158 </cell>
16159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16160 \begin_inset Text
16161
16162 \layout Standard
16163
16164 18F458
16165 \end_inset
16166 </cell>
16167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16168 \begin_inset Text
16169
16170 \layout Standard
16171
16172 18F1220
16173 \end_inset
16174 </cell>
16175 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16176 \begin_inset Text
16177
16178 \layout Standard
16179
16180 18F2220
16181 \end_inset
16182 </cell>
16183 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16184 \begin_inset Text
16185
16186 \layout Standard
16187
16188 18F2550
16189 \end_inset
16190 </cell>
16191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16192 \begin_inset Text
16193
16194 \layout Standard
16195
16196 18F4331
16197 \end_inset
16198 </cell>
16199 </row>
16200 <row topline="true">
16201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16202 \begin_inset Text
16203
16204 \layout Standard
16205
16206 18F4455
16207 \end_inset
16208 </cell>
16209 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16210 \begin_inset Text
16211
16212 \layout Standard
16213
16214 18F6520
16215 \end_inset
16216 </cell>
16217 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16218 \begin_inset Text
16219
16220 \layout Standard
16221
16222 18F6620
16223 \end_inset
16224 </cell>
16225 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16226 \begin_inset Text
16227
16228 \layout Standard
16229
16230 18F6680
16231 \end_inset
16232 </cell>
16233 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16234 \begin_inset Text
16235
16236 \layout Standard
16237
16238 18F6720
16239 \end_inset
16240 </cell>
16241 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16242 \begin_inset Text
16243
16244 \layout Standard
16245
16246 18F8520
16247 \end_inset
16248 </cell>
16249 </row>
16250 <row topline="true" bottomline="true">
16251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16252 \begin_inset Text
16253
16254 \layout Standard
16255
16256 18F8620
16257 \end_inset
16258 </cell>
16259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16260 \begin_inset Text
16261
16262 \layout Standard
16263
16264 18F8680
16265 \end_inset
16266 </cell>
16267 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16268 \begin_inset Text
16269
16270 \layout Standard
16271
16272 18F8720
16273 \end_inset
16274 </cell>
16275 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16276 \begin_inset Text
16277
16278 \layout Standard
16279
16280 \end_inset
16281 </cell>
16282 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16283 \begin_inset Text
16284
16285 \layout Standard
16286
16287 \end_inset
16288 </cell>
16289 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16290 \begin_inset Text
16291
16292 \layout Standard
16293
16294 \end_inset
16295 </cell>
16296 </row>
16297 </lyxtabular>
16298
16299 \end_inset
16300
16301
16302 \layout Subsection
16303
16304 Global Options
16305 \layout Standard
16306
16307 PIC16 port supports the standard command line arguments as supposed, with
16308  the exception of certain cases that will be mentioned in the following
16309  list:
16310 \layout List
16311 \labelwidthstring 00.00.0000
16312
16313 -
16314 \begin_inset ERT
16315 status Collapsed
16316
16317 \layout Standard
16318
16319 \backslash
16320 /
16321 \end_inset
16322
16323 -callee-saves See -
16324 \begin_inset ERT
16325 status Collapsed
16326
16327 \layout Standard
16328
16329 \backslash
16330 /
16331 \end_inset
16332
16333 -all-callee-saves
16334 \layout List
16335 \labelwidthstring 00.00.0000
16336
16337 -
16338 \begin_inset ERT
16339 status Collapsed
16340
16341 \layout Standard
16342
16343 \backslash
16344 /
16345 \end_inset
16346
16347 -all-callee-saves All function arguments are passed on stack by default.
16348
16349 \emph on
16350 There is no need to specify this in the command line.
16351 \layout List
16352 \labelwidthstring 00.00.0000
16353
16354 -
16355 \begin_inset ERT
16356 status Collapsed
16357
16358 \layout Standard
16359
16360 \backslash
16361 /
16362 \end_inset
16363
16364 -fommit-frame-pointer Frame pointer will be omitted when the function uses
16365  no local variables.
16366 \layout Subsection
16367
16368 Port Specific Options
16369 \begin_inset LatexCommand \index{Options PIC16}
16370
16371 \end_inset
16372
16373
16374 \layout Standard
16375
16376 The port specific options appear after the global options in the sdcc --help
16377  output.
16378 \layout Subsubsection
16379
16380 General Options
16381 \layout Standard
16382
16383 General options enable certain port features and optimizations.
16384 \layout List
16385 \labelwidthstring 00.00.0000
16386
16387 -
16388 \begin_inset ERT
16389 status Collapsed
16390
16391 \layout Standard
16392
16393 \backslash
16394 /
16395 \end_inset
16396
16397 -stack-model=[model] Used in conjuction with the command above.
16398  Defines the stack model to be used, valid stack models are :
16399 \begin_deeper
16400 \layout List
16401 \labelwidthstring 00.00.0000
16402
16403
16404 \emph on
16405 small
16406 \emph default
16407  Selects small stack model.
16408  8 bit stack and frame pointers.
16409  Supports 256 bytes stack size.
16410 \layout List
16411 \labelwidthstring 00.00.0000
16412
16413
16414 \emph on
16415 large
16416 \emph default
16417  Selects large stack model.
16418  16 bit stack and frame pointers.
16419  Supports 65536 bytes stack size.
16420 \end_deeper
16421 \layout List
16422 \labelwidthstring 00.00.0000
16423
16424 -
16425 \begin_inset ERT
16426 status Collapsed
16427
16428 \layout Standard
16429
16430 \backslash
16431 /
16432 \end_inset
16433
16434 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
16435  unitialized data variables with [kword].
16436  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
16437 \layout List
16438 \labelwidthstring 00.00.0000
16439
16440 -
16441 \begin_inset ERT
16442 status Collapsed
16443
16444 \layout Standard
16445
16446 \backslash
16447 /
16448 \end_inset
16449
16450 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
16451  Useful for bootloaders.
16452 \layout List
16453 \labelwidthstring 00.00.0000
16454
16455 -
16456 \begin_inset ERT
16457 status Collapsed
16458
16459 \layout Standard
16460
16461 \backslash
16462 /
16463 \end_inset
16464
16465 -asm= sets the full path and name of an external assembler to call.
16466 \layout List
16467 \labelwidthstring 00.00.0000
16468
16469 -
16470 \begin_inset ERT
16471 status Collapsed
16472
16473 \layout Standard
16474
16475 \backslash
16476 /
16477 \end_inset
16478
16479 -link= sets the full path and name of an external linker to call.
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 -mplab-comp MPLAB compatibility option.
16494  Currently only suppresses special gpasm directives.
16495 \layout Subsubsection
16496
16497 Optimization Options
16498 \layout List
16499 \labelwidthstring 00.00.0000
16500
16501 -
16502 \begin_inset ERT
16503 status Collapsed
16504
16505 \layout Standard
16506
16507 \backslash
16508 /
16509 \end_inset
16510
16511 -optimize-goto Try to use (conditional) BRA instead of GOTO
16512 \layout List
16513 \labelwidthstring 00.00.0000
16514
16515 -
16516 \begin_inset ERT
16517 status Collapsed
16518
16519 \layout Standard
16520
16521 \backslash
16522 /
16523 \end_inset
16524
16525 -optimize-cmp Try to optimize some compares.
16526 \layout List
16527 \labelwidthstring 00.00.0000
16528
16529 -
16530 \begin_inset ERT
16531 status Collapsed
16532
16533 \layout Standard
16534
16535 \backslash
16536 /
16537 \end_inset
16538
16539 -obanksel=nn Set optimization level for inserting BANKSELs.
16540 \newline
16541
16542 \begin_deeper
16543 \layout List
16544 \labelwidthstring 00.00.0000
16545
16546 0 no optimization
16547 \layout List
16548 \labelwidthstring 00.00.0000
16549
16550 1 checks previous used register and if it is the same then does not emit
16551  BANKSEL, accounts only for labels.
16552 \layout List
16553 \labelwidthstring 00.00.0000
16554
16555 2 tries to check the location of (even different) symbols and removes BANKSELs
16556  if they are in the same bank.
16557
16558 \newline
16559
16560 \emph on
16561 Important: There might be problems if the linker script has data sections
16562  across bank borders!
16563 \end_deeper
16564 \layout Subsubsection
16565
16566 Linking Options
16567 \layout List
16568 \labelwidthstring 00.00.0000
16569
16570 -
16571 \begin_inset ERT
16572 status Collapsed
16573
16574 \layout Standard
16575
16576 \backslash
16577 /
16578 \end_inset
16579
16580 -nodefaultlibs do not link default libraries when linking
16581 \layout List
16582 \labelwidthstring 00.00.0000
16583
16584 -
16585 \begin_inset ERT
16586 status Collapsed
16587
16588 \layout Standard
16589
16590 \backslash
16591 /
16592 \end_inset
16593
16594 -no-crt Don't link the default run-time modules
16595 \layout List
16596 \labelwidthstring 00.00.0000
16597
16598 -
16599 \begin_inset ERT
16600 status Collapsed
16601
16602 \layout Standard
16603
16604 \backslash
16605 /
16606 \end_inset
16607
16608 -use-crt= Use a custom run-time module instead of the defaults.
16609 \layout Subsubsection
16610
16611 Debugging Options
16612 \layout Standard
16613
16614 Debugging options enable extra debugging information in the output files.
16615 \layout List
16616 \labelwidthstring 00.00.0000
16617
16618 -
16619 \begin_inset ERT
16620 status Collapsed
16621
16622 \layout Standard
16623
16624 \backslash
16625 /
16626 \end_inset
16627
16628 -debug-xtra Similar to -
16629 \begin_inset ERT
16630 status Collapsed
16631
16632 \layout Standard
16633
16634 \backslash
16635 /
16636 \end_inset
16637
16638 -debug
16639 \begin_inset LatexCommand \index{-\/-debug}
16640
16641 \end_inset
16642
16643 , but dumps more information.
16644 \layout List
16645 \labelwidthstring 00.00.0000
16646
16647 -
16648 \begin_inset ERT
16649 status Collapsed
16650
16651 \layout Standard
16652
16653 \backslash
16654 /
16655 \end_inset
16656
16657 -debug-ralloc Force register allocator to dump <source>.d file with debugging
16658  information.
16659  <source> is the name of the file compiled.
16660 \layout List
16661 \labelwidthstring 00.00.0000
16662
16663 -
16664 \begin_inset ERT
16665 status Collapsed
16666
16667 \layout Standard
16668
16669 \backslash
16670 /
16671 \end_inset
16672
16673 -pcode-verbose Enable pcode debugging information in translation.
16674 \layout List
16675 \labelwidthstring 00.00.0000
16676
16677 -
16678 \begin_inset ERT
16679 status Collapsed
16680
16681 \layout Standard
16682
16683 \backslash
16684 /
16685 \end_inset
16686
16687 -denable-peeps Force the usage of peepholes.
16688  Use with care.
16689 \layout List
16690 \labelwidthstring 00.00.0000
16691
16692 -
16693 \begin_inset ERT
16694 status Collapsed
16695
16696 \layout Standard
16697
16698 \backslash
16699 /
16700 \end_inset
16701
16702 -gstack Trace push/pops for stack pointer overflow
16703 \layout List
16704 \labelwidthstring 00.00.0000
16705
16706 -
16707 \begin_inset ERT
16708 status Collapsed
16709
16710 \layout Standard
16711
16712 \backslash
16713 /
16714 \end_inset
16715
16716 -call-tree dump call tree in .calltree file
16717 \layout Subsection
16718
16719 Enviromental Variables
16720 \layout Standard
16721
16722 There is a number of enviromental variables that can be used when running
16723  SDCC to enable certain optimizations or force a specific program behaviour.
16724  these variables are primarily for debugging purposes so they can be enabled/dis
16725 abled at will.
16726 \layout Standard
16727
16728 Currently there is only two such variables available:
16729 \layout List
16730 \labelwidthstring 00.00.0000
16731
16732 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
16733  bitfields is optimized by directly loading FSR0 with the address of the
16734  bitfield structure.
16735  Normally SDCC will cast the bitfield structure to a bitfield pointer and
16736  then load FSR0.
16737  This step saves data ram and code space for functions that perform heavy
16738  use of bitfields.
16739  (ie.
16740  80 bytes of code space are saved when compiling malloc.c with this option).
16741
16742 \layout List
16743 \labelwidthstring 00.00.0000
16744
16745 NO_REG_OPT do not perform pCode registers optimization.
16746  This should be used for debugging purposes.
16747  In some where bugs in the pcode optimizer are found, users can benefit
16748  from temporarily disabling the optimizer until the bug is fixed.
16749 \layout Subsection
16750
16751 Preprocessor Macros
16752 \layout Standard
16753
16754 PIC16 port defines the following preprocessor macros while translating a
16755  source.
16756 \layout Standard
16757 \align center
16758
16759 \begin_inset  Tabular
16760 <lyxtabular version="3" rows="6" columns="2">
16761 <features>
16762 <column alignment="center" valignment="top" leftline="true" width="0">
16763 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16764 <row topline="true" bottomline="true">
16765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16766 \begin_inset Text
16767
16768 \layout Standard
16769
16770 Macro
16771 \end_inset
16772 </cell>
16773 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16774 \begin_inset Text
16775
16776 \layout Standard
16777
16778 Description
16779 \end_inset
16780 </cell>
16781 </row>
16782 <row topline="true">
16783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16784 \begin_inset Text
16785
16786 \layout Standard
16787
16788 SDCC_pic16
16789 \end_inset
16790 </cell>
16791 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16792 \begin_inset Text
16793
16794 \layout Standard
16795
16796 Port identification
16797 \end_inset
16798 </cell>
16799 </row>
16800 <row topline="true">
16801 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16802 \begin_inset Text
16803
16804 \layout Standard
16805
16806 _
16807 \begin_inset ERT
16808 status Collapsed
16809
16810 \layout Standard
16811
16812 \backslash
16813 /
16814 \end_inset
16815
16816 _pic16
16817 \end_inset
16818 </cell>
16819 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16820 \begin_inset Text
16821
16822 \layout Standard
16823
16824 Port identification (same as above)
16825 \end_inset
16826 </cell>
16827 </row>
16828 <row topline="true">
16829 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16830 \begin_inset Text
16831
16832 \layout Standard
16833
16834 pic18fxxxx
16835 \end_inset
16836 </cell>
16837 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16838 \begin_inset Text
16839
16840 \layout Standard
16841
16842 MCU Identification.
16843
16844 \emph on
16845 xxxx
16846 \emph default
16847  is the microcontrol identification number, i.e.
16848  452, 6620, etc
16849 \end_inset
16850 </cell>
16851 </row>
16852 <row topline="true">
16853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16854 \begin_inset Text
16855
16856 \layout Standard
16857
16858 _
16859 \begin_inset ERT
16860 status Collapsed
16861
16862 \layout Standard
16863
16864 \backslash
16865 /
16866 \end_inset
16867
16868 _18Fxxxx
16869 \end_inset
16870 </cell>
16871 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16872 \begin_inset Text
16873
16874 \layout Standard
16875
16876 MCU Identification (same as above)
16877 \end_inset
16878 </cell>
16879 </row>
16880 <row topline="true" bottomline="true">
16881 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16882 \begin_inset Text
16883
16884 \layout Standard
16885
16886 STACK_MODEL_nnn
16887 \end_inset
16888 </cell>
16889 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16890 \begin_inset Text
16891
16892 \layout Standard
16893
16894 nnn = SMALL or LARGE respectively according to the stack model used
16895 \end_inset
16896 </cell>
16897 </row>
16898 </lyxtabular>
16899
16900 \end_inset
16901
16902
16903 \layout Standard
16904
16905 In addition the following macros are defined when calling assembler:
16906 \layout Standard
16907 \align center
16908
16909 \begin_inset  Tabular
16910 <lyxtabular version="3" rows="4" columns="2">
16911 <features>
16912 <column alignment="center" valignment="top" leftline="true" width="0">
16913 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16914 <row topline="true" bottomline="true">
16915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16916 \begin_inset Text
16917
16918 \layout Standard
16919
16920 Macro
16921 \end_inset
16922 </cell>
16923 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16924 \begin_inset Text
16925
16926 \layout Standard
16927
16928 Description
16929 \end_inset
16930 </cell>
16931 </row>
16932 <row topline="true">
16933 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16934 \begin_inset Text
16935
16936 \layout Standard
16937
16938 __18Fxxxx
16939 \end_inset
16940 </cell>
16941 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16942 \begin_inset Text
16943
16944 \layout Standard
16945
16946 MCU Identification.
16947
16948 \emph on
16949 xxxx
16950 \emph default
16951  is the microcontrol identification number, i.e.
16952  452, 6620, etc
16953 \end_inset
16954 </cell>
16955 </row>
16956 <row topline="true">
16957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16958 \begin_inset Text
16959
16960 \layout Standard
16961
16962 SDCC_MODEL_nnn
16963 \end_inset
16964 </cell>
16965 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16966 \begin_inset Text
16967
16968 \layout Standard
16969
16970 nnn = SMALL or LARGE respectively according to the memory model used for
16971  SDCC
16972 \end_inset
16973 </cell>
16974 </row>
16975 <row topline="true" bottomline="true">
16976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16977 \begin_inset Text
16978
16979 \layout Standard
16980
16981 STACK_MODEL_nnn
16982 \end_inset
16983 </cell>
16984 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16985 \begin_inset Text
16986
16987 \layout Standard
16988
16989 nnn = SMALL or LARGE respectively according to the stack model used
16990 \end_inset
16991 </cell>
16992 </row>
16993 </lyxtabular>
16994
16995 \end_inset
16996
16997
16998 \layout Subsection
16999
17000 Directories
17001 \layout Standard
17002
17003 PIC16
17004 \begin_inset LatexCommand \index{PIC16}
17005
17006 \end_inset
17007
17008  port uses the following directories for searching header files and libraries.
17009 \layout Standard
17010 \align center
17011
17012 \begin_inset  Tabular
17013 <lyxtabular version="3" rows="3" columns="4">
17014 <features>
17015 <column alignment="center" valignment="top" leftline="true" width="0">
17016 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17017 <column alignment="center" valignment="top" width="0">
17018 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17019 <row topline="true" bottomline="true">
17020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17021 \begin_inset Text
17022
17023 \layout Standard
17024
17025 Directory
17026 \end_inset
17027 </cell>
17028 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17029 \begin_inset Text
17030
17031 \layout Standard
17032
17033 Description
17034 \end_inset
17035 </cell>
17036 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17037 \begin_inset Text
17038
17039 \layout Standard
17040
17041 Target
17042 \end_inset
17043 </cell>
17044 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17045 \begin_inset Text
17046
17047 \layout Standard
17048
17049 Command prefix
17050 \end_inset
17051 </cell>
17052 </row>
17053 <row topline="true">
17054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17055 \begin_inset Text
17056
17057 \layout Standard
17058
17059 PREFIX/sdcc/include/pic16
17060 \end_inset
17061 </cell>
17062 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17063 \begin_inset Text
17064
17065 \layout Standard
17066
17067 PIC16 specific headers
17068 \end_inset
17069 </cell>
17070 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17071 \begin_inset Text
17072
17073 \layout Standard
17074
17075 Compiler
17076 \end_inset
17077 </cell>
17078 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17079 \begin_inset Text
17080
17081 \layout Standard
17082
17083 -I
17084 \end_inset
17085 </cell>
17086 </row>
17087 <row topline="true" bottomline="true">
17088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17089 \begin_inset Text
17090
17091 \layout Standard
17092
17093 PREFIX/sdcc/lib/pic16
17094 \end_inset
17095 </cell>
17096 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17097 \begin_inset Text
17098
17099 \layout Standard
17100
17101 PIC16 specific libraries
17102 \end_inset
17103 </cell>
17104 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17105 \begin_inset Text
17106
17107 \layout Standard
17108
17109 Linker
17110 \end_inset
17111 </cell>
17112 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17113 \begin_inset Text
17114
17115 \layout Standard
17116
17117 -L
17118 \end_inset
17119 </cell>
17120 </row>
17121 </lyxtabular>
17122
17123 \end_inset
17124
17125
17126 \layout Subsection
17127
17128 Pragmas
17129 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
17130
17131 \end_inset
17132
17133
17134 \layout Standard
17135
17136 PIC16 port currently supports the following pragmas:
17137 \layout List
17138 \labelwidthstring 00.00.0000
17139
17140 stack pragma stack forces the code generator to initialize the stack & frame
17141  pointers at a specific address.
17142  This is an adhoc solution for cases where no STACK directive is available
17143  in the linker script or gplink is not instructed to create a stack section.
17144 \newline
17145 The stack pragma should be used only once in a project.
17146  Multiple pragmas may result in indeterminate behaviour of the program.
17147 \begin_inset Foot
17148 collapsed false
17149
17150 \layout Standard
17151
17152 The old format (ie.
17153  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
17154  cross page boundaries (or even exceed the available data RAM) and crash
17155  the program.
17156  Make sure that stack does not cross page boundaries when using the SMALL
17157  stack model.
17158 \end_inset
17159
17160
17161 \newline
17162 The format is as follows:
17163 \layout LyX-Code
17164
17165 #pragma stack bottom_address [stack_size]
17166 \layout Standard
17167
17168
17169 \emph on
17170 bottom_address
17171 \emph default
17172  is the lower bound of the stack section.
17173  The stack pointer initially will point at address (bottom_address+stack_size-1).
17174 \layout LyX-Code
17175
17176 Example:
17177 \layout LyX-Code
17178
17179 \layout LyX-Code
17180
17181 /* initializes stack of 100 bytes at RAM address 0x200 */
17182 \layout LyX-Code
17183
17184 #pragma stack 0x200 100
17185 \layout Standard
17186
17187 If the stack_size field is omitted then a stack is created with the default
17188  size of 64.
17189  This size might be enough for most programs, but its not enough for operations
17190  with deep function nesting or excessive stack usage.
17191 \layout List
17192 \labelwidthstring 00.00.0000
17193
17194 wparam
17195 \emph on
17196 This pragma is deprecated.
17197  Its use will cause a warning message to be issued.
17198 \emph default
17199
17200 \newline
17201
17202 \layout List
17203 \labelwidthstring 00.00.0000
17204
17205 code place a function symbol at static FLASH address
17206 \layout LyX-Code
17207
17208 Example:
17209 \layout LyX-Code
17210
17211 \layout LyX-Code
17212
17213 /* place function test_func at 0x4000 */
17214 \layout LyX-Code
17215
17216 #pragma code test_func 0x4000
17217 \layout LyX-Code
17218
17219 \layout List
17220 \labelwidthstring 00.00.0000
17221
17222 library instructs the linker to use a library module.
17223 \newline
17224 Usage:
17225 \layout LyX-Code
17226
17227 #pragma library module_name
17228 \layout Standard
17229
17230
17231 \emph on
17232 module_name
17233 \emph default
17234  can be any library or object file (including its path).
17235  Note that there are four reserved keywords which have special meaning.
17236  These are:
17237 \layout Standard
17238 \align center
17239
17240 \begin_inset  Tabular
17241 <lyxtabular version="3" rows="6" columns="3">
17242 <features>
17243 <column alignment="center" valignment="top" leftline="true" width="0">
17244 <column alignment="block" valignment="top" leftline="true" width="20page%">
17245 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
17246 <row topline="true" bottomline="true">
17247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17248 \begin_inset Text
17249
17250 \layout Standard
17251
17252 Keyword
17253 \end_inset
17254 </cell>
17255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17256 \begin_inset Text
17257
17258 \layout Standard
17259
17260 Description
17261 \end_inset
17262 </cell>
17263 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17264 \begin_inset Text
17265
17266 \layout Standard
17267
17268 Module to link
17269 \end_inset
17270 </cell>
17271 </row>
17272 <row topline="true">
17273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17274 \begin_inset Text
17275
17276 \layout Standard
17277
17278
17279 \series bold
17280 ignore
17281 \end_inset
17282 </cell>
17283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17284 \begin_inset Text
17285
17286 \layout Standard
17287
17288 ignore all library pragmas
17289 \end_inset
17290 </cell>
17291 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17292 \begin_inset Text
17293
17294 \layout Standard
17295
17296
17297 \emph on
17298 (none)
17299 \end_inset
17300 </cell>
17301 </row>
17302 <row topline="true">
17303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17304 \begin_inset Text
17305
17306 \layout Standard
17307
17308
17309 \series bold
17310 c
17311 \end_inset
17312 </cell>
17313 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17314 \begin_inset Text
17315
17316 \layout Standard
17317
17318 link the C library
17319 \end_inset
17320 </cell>
17321 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17322 \begin_inset Text
17323
17324 \layout Standard
17325
17326
17327 \emph on
17328 libc18f
17329 \emph default
17330 .lib
17331 \end_inset
17332 </cell>
17333 </row>
17334 <row topline="true">
17335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17336 \begin_inset Text
17337
17338 \layout Standard
17339
17340
17341 \series bold
17342 math
17343 \end_inset
17344 </cell>
17345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17346 \begin_inset Text
17347
17348 \layout Standard
17349
17350 link the Math libarary
17351 \end_inset
17352 </cell>
17353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17354 \begin_inset Text
17355
17356 \layout Standard
17357
17358
17359 \emph on
17360 libm18f
17361 \emph default
17362 .lib
17363 \end_inset
17364 </cell>
17365 </row>
17366 <row topline="true">
17367 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17368 \begin_inset Text
17369
17370 \layout Standard
17371
17372
17373 \series bold
17374 io
17375 \end_inset
17376 </cell>
17377 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17378 \begin_inset Text
17379
17380 \layout Standard
17381
17382 link the I/O library
17383 \end_inset
17384 </cell>
17385 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17386 \begin_inset Text
17387
17388 \layout Standard
17389
17390
17391 \emph on
17392 libio18f*
17393 \emph default
17394 .lib
17395 \end_inset
17396 </cell>
17397 </row>
17398 <row topline="true" bottomline="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 debug
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 debug 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 libdebug
17425 \emph default
17426 .lib
17427 \end_inset
17428 </cell>
17429 </row>
17430 </lyxtabular>
17431
17432 \end_inset
17433
17434
17435 \newline
17436 * is the device number, i.e.
17437  452 for PIC18F452 MCU.
17438 \layout Standard
17439
17440 This feature allows for linking with specific libraries withoug having to
17441  explicit name them in the command line.
17442  Note that the
17443 \noun on
17444 ignore
17445 \noun default
17446  keyword will reject all modules specified by the library pragma.
17447 \layout List
17448 \labelwidthstring 00.00.0000
17449
17450 udata pragma udata instructs the compiler to emit code so that linker will
17451  place a variable at a specific memory bank
17452 \layout LyX-Code
17453
17454 Example:
17455 \layout LyX-Code
17456
17457 \layout LyX-Code
17458
17459 /* places variable foo at bank2 */
17460 \layout LyX-Code
17461
17462 #pragma udata bank2 foo
17463 \layout LyX-Code
17464
17465 char foo;
17466 \layout Standard
17467
17468 In order for this pragma to work extra SECTION directives should be added
17469  in the .lkr script.
17470  In the following example a sample .lkr file is shown:
17471 \layout LyX-Code
17472
17473 \layout LyX-Code
17474
17475 // Sample linker script for the PIC18F452 processor
17476 \layout LyX-Code
17477
17478 LIBPATH .
17479 \layout LyX-Code
17480
17481 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
17482 \layout LyX-Code
17483
17484 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
17485 \layout LyX-Code
17486
17487 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
17488 \layout LyX-Code
17489
17490 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
17491 \layout LyX-Code
17492
17493 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
17494 \layout LyX-Code
17495
17496 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
17497 \layout LyX-Code
17498
17499 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
17500 \layout LyX-Code
17501
17502 \layout LyX-Code
17503
17504 DATABANK   NAME=gpr0       START=0x80           END=0xFF
17505 \layout LyX-Code
17506
17507 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
17508 \layout LyX-Code
17509
17510 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
17511 \layout LyX-Code
17512
17513 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
17514 \layout LyX-Code
17515
17516 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
17517 \layout LyX-Code
17518
17519 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
17520 \layout LyX-Code
17521
17522 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
17523 \layout LyX-Code
17524
17525 \layout LyX-Code
17526
17527 SECTION    NAME=CONFIG     ROM=config
17528 \layout LyX-Code
17529
17530 \layout LyX-Code
17531
17532 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
17533 \layout LyX-Code
17534
17535 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
17536 \layout LyX-Code
17537
17538 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
17539 \layout LyX-Code
17540
17541 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
17542 \layout LyX-Code
17543
17544 SECTION    NAME=bank4      RAM=gpr4
17545 \layout LyX-Code
17546
17547 SECTION    NAME=bank5      RAM=gpr5
17548 \layout Standard
17549
17550 The linker will recognise the section name set in the pragma statement and
17551  will position the variable at the memory bank set with the RAM field at
17552  the SECTION line in the linker script file.
17553 \layout Subsection
17554
17555 Header Files
17556 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
17557
17558 \end_inset
17559
17560
17561 \layout Standard
17562
17563 There is one main header file that can be included to the source files using
17564  the pic16 port.
17565  That file is the
17566 \series bold
17567 pic18fregs.h
17568 \series default
17569 .
17570  This header file contains the definitions for the processor special registers,
17571  so it is necessary if the source accesses them.
17572  It can be included by adding the following line in the beginning of the
17573  file:
17574 \layout LyX-Code
17575
17576 #include <pic18fregs.h>
17577 \layout Standard
17578
17579 The specific microcontroller is selected within the pic18fregs.h automatically,
17580  so the same source can be used with a variety of devices.
17581 \layout Subsection
17582
17583 Libraries
17584 \layout Standard
17585
17586 The libraries that PIC16
17587 \begin_inset LatexCommand \index{PIC16}
17588
17589 \end_inset
17590
17591  port depends on are the microcontroller device libraries which contain
17592  the symbol definitions for the microcontroller special function registers.
17593  These libraries have the format pic18fxxxx.lib, where
17594 \emph on
17595 xxxx
17596 \emph default
17597  is the microcontroller identification number.
17598  The specific library is selected automatically by the compiler at link
17599  stage according to the selected device.
17600 \layout Standard
17601
17602 Libraries are created with gplib which is part of the gputils package
17603 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17604
17605 \end_inset
17606
17607 .
17608 \layout Subsubsection*
17609
17610 Building the libraries
17611 \layout Standard
17612
17613 Before using SDCC/pic16 there are some libraries that need to be compiled.
17614  This process is not done automatically by SDCC since not all users use
17615  SDCC for pic16 projects.
17616  So each user should compile the libraries separately.
17617 \layout Standard
17618
17619 The steps to compile the pic16 libraries under Linux are:
17620 \layout LyX-Code
17621
17622 cd device/lib/pic16
17623 \layout LyX-Code
17624
17625 ./configure
17626 \layout LyX-Code
17627
17628 make
17629 \layout LyX-Code
17630
17631 cd ..
17632 \layout LyX-Code
17633
17634 make model-pic16
17635 \layout LyX-Code
17636
17637 su -c 'make install'     # install the libraries, you need the root password
17638 \layout Standard
17639
17640 If you need to install the headers too, do:
17641 \layout LyX-Code
17642
17643 cd device/include
17644 \layout LyX-Code
17645
17646 su -c 'make install'     # install the headers, you need the root password
17647 \layout Standard
17648
17649 There exist a special target to build the I/O libraries.
17650  This target is not automatically build because it will build the I/O library
17651  for
17652 \emph on
17653 every
17654 \emph default
17655  supported device.
17656  This way building will take quite a lot of time.
17657  Users are advised to edit the
17658 \series bold
17659 device/lib/pic16/pics.build
17660 \series default
17661  file and then execute:
17662 \layout LyX-Code
17663
17664 make lib-io
17665 \layout Subsection
17666
17667 Memory Models
17668 \layout Standard
17669
17670 The following memory models are supported by the PIC16 port:
17671 \layout Itemize
17672
17673 small model
17674 \layout Itemize
17675
17676 large model
17677 \layout Standard
17678
17679 Memory model affects the default size of pointers within the source.
17680  The sizes are shown in the next table:
17681 \layout Standard
17682 \align center
17683
17684 \begin_inset  Tabular
17685 <lyxtabular version="3" rows="3" columns="3">
17686 <features>
17687 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17688 <column alignment="center" valignment="top" leftline="true" width="0">
17689 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17690 <row topline="true" bottomline="true">
17691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17692 \begin_inset Text
17693
17694 \layout Standard
17695
17696 Pointer sizes according to memory model
17697 \end_inset
17698 </cell>
17699 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17700 \begin_inset Text
17701
17702 \layout Standard
17703
17704 small model
17705 \end_inset
17706 </cell>
17707 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17708 \begin_inset Text
17709
17710 \layout Standard
17711
17712 large model
17713 \end_inset
17714 </cell>
17715 </row>
17716 <row topline="true" bottomline="true">
17717 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17718 \begin_inset Text
17719
17720 \layout Standard
17721
17722 code pointers
17723 \end_inset
17724 </cell>
17725 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17726 \begin_inset Text
17727
17728 \layout Standard
17729
17730 16-bits
17731 \end_inset
17732 </cell>
17733 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17734 \begin_inset Text
17735
17736 \layout Standard
17737
17738 24-bits
17739 \end_inset
17740 </cell>
17741 </row>
17742 <row topline="true" bottomline="true">
17743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17744 \begin_inset Text
17745
17746 \layout Standard
17747
17748 data pointers
17749 \end_inset
17750 </cell>
17751 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
17752 \begin_inset Text
17753
17754 \layout Standard
17755
17756 16-bits
17757 \end_inset
17758 </cell>
17759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17760 \begin_inset Text
17761
17762 \layout Standard
17763
17764 16-bits
17765 \end_inset
17766 </cell>
17767 </row>
17768 </lyxtabular>
17769
17770 \end_inset
17771
17772
17773 \layout Standard
17774
17775 It is advisable that all sources within a project are compiled with the
17776  same memory model.
17777  If one wants to override the default memory model, this can be done by
17778  declaring a pointer as
17779 \series bold
17780 far
17781 \series default
17782  or
17783 \series bold
17784 near
17785 \series default
17786 .
17787  Far selects large memory model's pointers, while near selects small memory
17788  model's pointers.
17789 \layout Standard
17790
17791 The standard device libraries (see
17792 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
17793
17794 \end_inset
17795
17796 ) contain no reference to pointers, so they can be used with both memory
17797  models.
17798 \layout Subsection
17799
17800 Stack
17801 \layout Standard
17802
17803 The stack implementation for the PIC16 port uses two indirect registers,
17804  FSR1 and FSR2.
17805 \layout List
17806 \labelwidthstring 00.00.0000
17807
17808 FSR1 is assigned as stack pointer
17809 \layout List
17810 \labelwidthstring 00.00.0000
17811
17812 FSR2 is assigned as frame pointer
17813 \layout Standard
17814
17815 The following stack models are supported by the PIC16 port
17816 \layout Itemize
17817
17818
17819 \noun on
17820 small
17821 \noun default
17822  model
17823 \layout Itemize
17824
17825
17826 \noun on
17827 large
17828 \noun default
17829  model
17830 \layout Standard
17831
17832
17833 \noun on
17834 Small
17835 \noun default
17836  model means that only the FSRxL byte is used to access stack and frame,
17837  while
17838 \emph on
17839 \noun on
17840 large
17841 \emph default
17842 \noun default
17843  uses both FSRxL and FSRxH registers.
17844  The following table shows the stack/frame pointers sizes according to stack
17845  model and the maximum space they can address:
17846 \layout Standard
17847 \align center
17848
17849 \begin_inset  Tabular
17850 <lyxtabular version="3" rows="3" columns="3">
17851 <features>
17852 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17853 <column alignment="center" valignment="top" leftline="true" width="0">
17854 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17855 <row topline="true" bottomline="true">
17856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17857 \begin_inset Text
17858
17859 \layout Standard
17860
17861 Stack & Frame pointer sizes according to stack model
17862 \end_inset
17863 </cell>
17864 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17865 \begin_inset Text
17866
17867 \layout Standard
17868
17869 small
17870 \end_inset
17871 </cell>
17872 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17873 \begin_inset Text
17874
17875 \layout Standard
17876
17877 large
17878 \end_inset
17879 </cell>
17880 </row>
17881 <row topline="true">
17882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17883 \begin_inset Text
17884
17885 \layout Standard
17886
17887 Stack pointer FSR1
17888 \end_inset
17889 </cell>
17890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17891 \begin_inset Text
17892
17893 \layout Standard
17894
17895 8-bits
17896 \end_inset
17897 </cell>
17898 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17899 \begin_inset Text
17900
17901 \layout Standard
17902
17903 16-bits
17904 \end_inset
17905 </cell>
17906 </row>
17907 <row topline="true" bottomline="true">
17908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17909 \begin_inset Text
17910
17911 \layout Standard
17912
17913 Frame pointer FSR2
17914 \end_inset
17915 </cell>
17916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17917 \begin_inset Text
17918
17919 \layout Standard
17920
17921 8-bits
17922 \end_inset
17923 </cell>
17924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17925 \begin_inset Text
17926
17927 \layout Standard
17928
17929 16-bits
17930 \end_inset
17931 </cell>
17932 </row>
17933 </lyxtabular>
17934
17935 \end_inset
17936
17937
17938 \layout Standard
17939
17940
17941 \noun on
17942 Large
17943 \noun default
17944 stack model is currently not working properly throughout the code generator.
17945  So its use is not advised.
17946  Also there are some other points that need special care:
17947 \newline
17948
17949 \layout Enumerate
17950
17951 Do not create stack sections with size more than one physical bank (that
17952  is 256 bytes)
17953 \layout Enumerate
17954
17955 Stack sections should no cross physical bank limits (i.e.
17956  #pragma stack 0x50 0x100)
17957 \layout Standard
17958
17959 These limitations are caused by the fact that only FSRxL is modified when
17960  using SMALL stack model, so no more than 256 bytes of stack can be used.
17961  This problem will disappear after LARGE model is fully implemented.
17962 \layout Subsection
17963
17964 Functions
17965 \layout Standard
17966
17967 In addition to the standard SDCC function keywords, PIC16 port makes available
17968  two more:
17969 \layout List
17970 \labelwidthstring 00.00.0000
17971
17972 wparam Use the WREG to pass one byte of the first function argument.
17973  This improves speed but you may not use this for functions with arguments
17974  that are called via function pointers, otherwise the first byte of the
17975  first parameter will get lost.
17976  Usage:
17977 \layout LyX-Code
17978
17979 void func_wparam(int a) wparam
17980 \layout LyX-Code
17981
17982 {
17983 \layout LyX-Code
17984
17985     /* WREG hold the lower part of a */
17986 \layout LyX-Code
17987
17988     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
17989  */
17990 \layout LyX-Code
17991
17992 ...
17993 \layout LyX-Code
17994
17995 }
17996 \layout Standard
17997
17998 This keyword replaces the deprecated wparam pragma.
17999 \layout List
18000 \labelwidthstring 00.00.0000
18001
18002 shadowregs When entering/exiting an ISR, it is possible to take advantage
18003  of the PIC18F hardware shadow registers which hold the values of WREG,
18004  STATUS and BSR registers.
18005  This can be done by adding the keyword
18006 \emph on
18007 shadowregs
18008 \emph default
18009  before the
18010 \emph on
18011 interrupt
18012 \emph default
18013  keyword in the function's header.
18014 \layout LyX-Code
18015
18016 void isr_shadow(void) shadowregs interrupt 1
18017 \layout LyX-Code
18018
18019 {
18020 \layout LyX-Code
18021
18022 ...
18023 \layout LyX-Code
18024
18025 }
18026 \layout Standard
18027
18028
18029 \emph on
18030 shadowregs
18031 \emph default
18032  instructs the code generator not to store/restore WREG, STATUS, BSR when
18033  entering/exiting the ISR.
18034 \layout Subsection
18035
18036 Function return values
18037 \layout Standard
18038
18039 Return values from functions are placed to the appropriate registers following
18040  a modified Microchip policy optimized for SDCC.
18041  The following table shows these registers:
18042 \layout Standard
18043 \align center
18044
18045 \begin_inset  Tabular
18046 <lyxtabular version="3" rows="6" columns="2">
18047 <features>
18048 <column alignment="center" valignment="top" leftline="true" width="0">
18049 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18050 <row topline="true" bottomline="true">
18051 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18052 \begin_inset Text
18053
18054 \layout Standard
18055
18056 size
18057 \end_inset
18058 </cell>
18059 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18060 \begin_inset Text
18061
18062 \layout Standard
18063
18064 destination register
18065 \end_inset
18066 </cell>
18067 </row>
18068 <row topline="true">
18069 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18070 \begin_inset Text
18071
18072 \layout Standard
18073
18074 8 bits
18075 \end_inset
18076 </cell>
18077 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18078 \begin_inset Text
18079
18080 \layout Standard
18081
18082 WREG
18083 \end_inset
18084 </cell>
18085 </row>
18086 <row topline="true">
18087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18088 \begin_inset Text
18089
18090 \layout Standard
18091
18092 16 bits
18093 \end_inset
18094 </cell>
18095 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18096 \begin_inset Text
18097
18098 \layout Standard
18099
18100 PRODL:WREG
18101 \end_inset
18102 </cell>
18103 </row>
18104 <row topline="true">
18105 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18106 \begin_inset Text
18107
18108 \layout Standard
18109
18110 24 bits
18111 \end_inset
18112 </cell>
18113 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18114 \begin_inset Text
18115
18116 \layout Standard
18117
18118 PRODH:PRODL:WREG
18119 \end_inset
18120 </cell>
18121 </row>
18122 <row topline="true">
18123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18124 \begin_inset Text
18125
18126 \layout Standard
18127
18128 32 bits
18129 \end_inset
18130 </cell>
18131 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18132 \begin_inset Text
18133
18134 \layout Standard
18135
18136 FSR0L:PRODH:PRODL:WREG
18137 \end_inset
18138 </cell>
18139 </row>
18140 <row topline="true" bottomline="true">
18141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18142 \begin_inset Text
18143
18144 \layout Standard
18145
18146 >32 bits
18147 \end_inset
18148 </cell>
18149 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18150 \begin_inset Text
18151
18152 \layout Standard
18153
18154 on stack, FSR0 points to the beginning
18155 \end_inset
18156 </cell>
18157 </row>
18158 </lyxtabular>
18159
18160 \end_inset
18161
18162
18163 \layout Subsection
18164
18165 Interrupts
18166 \layout Standard
18167
18168 An interrupt servive routine (ISR) is declared using the
18169 \emph on
18170 interrupt
18171 \emph default
18172  keyword.
18173 \layout LyX-Code
18174
18175 void isr(void) interrupt
18176 \emph on
18177 n
18178 \layout LyX-Code
18179
18180 {
18181 \layout LyX-Code
18182
18183 ...
18184 \layout LyX-Code
18185
18186 }
18187 \layout Standard
18188
18189
18190 \emph on
18191 n
18192 \emph default
18193  is the interrupt number, which for PIC18F devices can be:
18194 \layout Standard
18195 \align center
18196
18197 \begin_inset  Tabular
18198 <lyxtabular version="3" rows="4" columns="3">
18199 <features>
18200 <column alignment="center" valignment="top" leftline="true" width="0">
18201 <column alignment="center" valignment="top" leftline="true" width="0">
18202 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18203 <row topline="true" bottomline="true">
18204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18205 \begin_inset Text
18206
18207 \layout Standard
18208
18209
18210 \emph on
18211 n
18212 \end_inset
18213 </cell>
18214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18215 \begin_inset Text
18216
18217 \layout Standard
18218
18219 Interrupt Vector
18220 \end_inset
18221 </cell>
18222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18223 \begin_inset Text
18224
18225 \layout Standard
18226
18227 Interrupt Vector Address
18228 \end_inset
18229 </cell>
18230 </row>
18231 <row topline="true">
18232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18233 \begin_inset Text
18234
18235 \layout Standard
18236
18237 0
18238 \end_inset
18239 </cell>
18240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18241 \begin_inset Text
18242
18243 \layout Standard
18244
18245 RESET vector
18246 \end_inset
18247 </cell>
18248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18249 \begin_inset Text
18250
18251 \layout Standard
18252
18253 0x000000
18254 \end_inset
18255 </cell>
18256 </row>
18257 <row topline="true">
18258 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18259 \begin_inset Text
18260
18261 \layout Standard
18262
18263
18264 \family roman
18265 \series medium
18266 \shape up
18267 \size normal
18268 \emph off
18269 \bar no
18270 \noun off
18271 \color none
18272 1
18273 \end_inset
18274 </cell>
18275 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18276 \begin_inset Text
18277
18278 \layout Standard
18279
18280
18281 \family roman
18282 \series medium
18283 \shape up
18284 \size normal
18285 \emph off
18286 \bar no
18287 \noun off
18288 \color none
18289 HIGH priority interrupts
18290 \end_inset
18291 </cell>
18292 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18293 \begin_inset Text
18294
18295 \layout Standard
18296
18297 0x000008
18298 \end_inset
18299 </cell>
18300 </row>
18301 <row topline="true" bottomline="true">
18302 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18303 \begin_inset Text
18304
18305 \layout Standard
18306
18307 2
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 LOW priority interrupts
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 0x000018
18324 \end_inset
18325 </cell>
18326 </row>
18327 </lyxtabular>
18328
18329 \end_inset
18330
18331
18332 \layout Standard
18333
18334 When generating assembly code for ISR the code generator places a
18335 \noun on
18336 goto
18337 \noun default
18338 instruction at the
18339 \emph on
18340 Interrupt Vector Address
18341 \emph default
18342  which points at the genetated ISR.
18343  This single GOTO instruction is part of an automatically generated
18344 \emph on
18345 interrupt entry point
18346 \emph default
18347  function.
18348  The actuall ISR code is placed as normally would in the code space.
18349  Upon interrupt request, the GOTO instruction is executed which jumps to
18350  the ISR code.
18351  When declaring interrupt functions as _naked this GOTO instruction is
18352 \series bold
18353 not
18354 \series default
18355  generated.
18356  The whole interrupt functions is therefore placed at the Interrupt Vector
18357  Address of the specific interrupt.
18358  This is not a problem for the LOW priority interrupts, but it is a problem
18359  for the RESET and the HIGH priority interrupts because code may be written
18360  at the next interrupt´s vector address and cause undeterminate program
18361  behaviour if that interrupt is raised.
18362 \begin_inset Foot
18363 collapsed false
18364
18365 \layout Standard
18366
18367 This is not a problem when
18368 \layout Enumerate
18369
18370 this is a HIGH interrupt ISR and LOW interrupts are
18371 \emph on
18372 disabled
18373 \emph default
18374  or not used.
18375 \layout Enumerate
18376
18377 when the ISR is small enough not to reach the next interrupt´s vector address.
18378 \end_inset
18379
18380
18381 \layout Standard
18382
18383
18384 \emph on
18385 n
18386 \emph default
18387  is possible to be omitted.
18388  This way a function is generated similar to an ISR, but it is not assigned
18389  to any interrupt.
18390 \layout Standard
18391
18392 When entering an interrupt, currently the PIC16
18393 \begin_inset LatexCommand \index{PIC16}
18394
18395 \end_inset
18396
18397  port automatically saves the following registers:
18398 \layout Itemize
18399
18400 WREG
18401 \layout Itemize
18402
18403 STATUS
18404 \layout Itemize
18405
18406 BSR
18407 \layout Itemize
18408
18409 PROD (PRODL and PRODH)
18410 \layout Itemize
18411
18412 FSR0 (FSR0L and FSR0H)
18413 \layout Standard
18414
18415 These registers are restored upon return from the interrupt routine.
18416 \begin_inset Foot
18417 collapsed false
18418
18419 \layout Standard
18420
18421 NOTE that when the _naked attribute is specified for an interrupt routine,
18422  then NO registers are stored or restored.
18423 \end_inset
18424
18425
18426 \layout Subsection
18427
18428 Generic Pointers
18429 \layout Standard
18430
18431 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
18432  There are 3 types of generic pointers currently implemented data, code
18433  and eeprom pointers.
18434  They are differentiated by the value of the 7th and 6th bits of the upper
18435  byte:
18436 \layout Standard
18437 \align center
18438
18439 \begin_inset  Tabular
18440 <lyxtabular version="3" rows="5" columns="5">
18441 <features>
18442 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18443 <column alignment="center" valignment="top" width="0">
18444 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18445 <column alignment="center" valignment="top" width="0">
18446 <column alignment="left" valignment="top" rightline="true" width="0">
18447 <row topline="true" bottomline="true">
18448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18449 \begin_inset Text
18450
18451 \layout Standard
18452
18453 pointer type
18454 \end_inset
18455 </cell>
18456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18457 \begin_inset Text
18458
18459 \layout Standard
18460
18461 7th bit
18462 \end_inset
18463 </cell>
18464 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18465 \begin_inset Text
18466
18467 \layout Standard
18468
18469 6th bit
18470 \end_inset
18471 </cell>
18472 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18473 \begin_inset Text
18474
18475 \layout Standard
18476
18477 rest of the pointer
18478 \end_inset
18479 </cell>
18480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18481 \begin_inset Text
18482
18483 \layout Standard
18484
18485 descrption
18486 \end_inset
18487 </cell>
18488 </row>
18489 <row topline="true" bottomline="true">
18490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18491 \begin_inset Text
18492
18493 \layout Standard
18494
18495 data
18496 \end_inset
18497 </cell>
18498 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18499 \begin_inset Text
18500
18501 \layout Standard
18502
18503 1
18504 \end_inset
18505 </cell>
18506 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18507 \begin_inset Text
18508
18509 \layout Standard
18510
18511 0
18512 \end_inset
18513 </cell>
18514 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18515 \begin_inset Text
18516
18517 \layout Standard
18518
18519
18520 \family typewriter
18521 \shape slanted
18522 \emph on
18523 uuuuuu uuuuxxxx xxxxxxxx
18524 \end_inset
18525 </cell>
18526 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18527 \begin_inset Text
18528
18529 \layout Standard
18530
18531 a 12-bit data pointer in data RAM memory
18532 \end_inset
18533 </cell>
18534 </row>
18535 <row bottomline="true">
18536 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18537 \begin_inset Text
18538
18539 \layout Standard
18540
18541 code
18542 \end_inset
18543 </cell>
18544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18545 \begin_inset Text
18546
18547 \layout Standard
18548
18549 0
18550 \end_inset
18551 </cell>
18552 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18553 \begin_inset Text
18554
18555 \layout Standard
18556
18557 0
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
18566 \family typewriter
18567 \shape slanted
18568 \emph on
18569 uxxxxx xxxxxxxx xxxxxxxx
18570 \end_inset
18571 </cell>
18572 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18573 \begin_inset Text
18574
18575 \layout Standard
18576
18577 a 21-bit code pointer in FLASH memory
18578 \end_inset
18579 </cell>
18580 </row>
18581 <row bottomline="true">
18582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18583 \begin_inset Text
18584
18585 \layout Standard
18586
18587 eeprom
18588 \end_inset
18589 </cell>
18590 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18591 \begin_inset Text
18592
18593 \layout Standard
18594
18595 0
18596 \end_inset
18597 </cell>
18598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18599 \begin_inset Text
18600
18601 \layout Standard
18602
18603 1
18604 \end_inset
18605 </cell>
18606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18607 \begin_inset Text
18608
18609 \layout Standard
18610
18611
18612 \family typewriter
18613 \shape slanted
18614 \emph on
18615 uuuuuu uuuuuuxx xxxxxxxx
18616 \end_inset
18617 </cell>
18618 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18619 \begin_inset Text
18620
18621 \layout Standard
18622
18623 a 10-bit eeprom pointer in EEPROM memory
18624 \end_inset
18625 </cell>
18626 </row>
18627 <row bottomline="true">
18628 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18629 \begin_inset Text
18630
18631 \layout Standard
18632
18633 (unimplemented)
18634 \end_inset
18635 </cell>
18636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18637 \begin_inset Text
18638
18639 \layout Standard
18640
18641 1
18642 \end_inset
18643 </cell>
18644 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18645 \begin_inset Text
18646
18647 \layout Standard
18648
18649 1
18650 \end_inset
18651 </cell>
18652 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18653 \begin_inset Text
18654
18655 \layout Standard
18656
18657
18658 \family typewriter
18659 \shape slanted
18660 \emph on
18661 xxxxxx xxxxxxxx xxxxxxxx
18662 \end_inset
18663 </cell>
18664 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18665 \begin_inset Text
18666
18667 \layout Standard
18668
18669 unimplemented pointer type
18670 \end_inset
18671 </cell>
18672 </row>
18673 </lyxtabular>
18674
18675 \end_inset
18676
18677
18678 \layout Standard
18679
18680 Generic pointer are read and written with a set of library functions which
18681  read/write 1, 2, 3, 4 bytes.
18682 \layout Subsection
18683
18684 PIC16 C Libraries
18685 \layout Subsubsection
18686
18687 Standard I/O Streams
18688 \layout Standard
18689
18690 In the
18691 \emph on
18692 stdio.h
18693 \emph default
18694  the type FILE is defined as:
18695 \layout LyX-Code
18696
18697 typedef char * FILE;
18698 \layout Standard
18699
18700 This type is the stream type implemented I/O in the PIC18F devices.
18701  Also the standard input and output streams are declared in stdio.h:
18702 \layout LyX-Code
18703
18704 extern FILE * stdin;
18705 \layout LyX-Code
18706
18707 extern FILE * stdout;
18708 \layout Standard
18709
18710 The FILE type is actually a generic pointer which defines one more type
18711  of generic pointers, the
18712 \emph on
18713 stream
18714 \emph default
18715 pointer.
18716  This new type has the format:
18717 \layout Standard
18718 \align center
18719
18720 \begin_inset  Tabular
18721 <lyxtabular version="3" rows="2" columns="7">
18722 <features>
18723 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18724 <column alignment="center" valignment="top" width="0">
18725 <column alignment="center" valignment="top" leftline="true" width="0">
18726 <column alignment="center" valignment="top" leftline="true" width="0">
18727 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18728 <column alignment="center" valignment="top" width="0">
18729 <column alignment="left" valignment="top" rightline="true" width="0">
18730 <row topline="true" bottomline="true">
18731 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18732 \begin_inset Text
18733
18734 \layout Standard
18735
18736 pointer type
18737 \end_inset
18738 </cell>
18739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18740 \begin_inset Text
18741
18742 \layout Standard
18743
18744 <7:6>
18745 \end_inset
18746 </cell>
18747 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18748 \begin_inset Text
18749
18750 \layout Standard
18751
18752 <5>
18753 \end_inset
18754 </cell>
18755 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18756 \begin_inset Text
18757
18758 \layout Standard
18759
18760 <4>
18761 \end_inset
18762 </cell>
18763 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18764 \begin_inset Text
18765
18766 \layout Standard
18767
18768 <3:0>
18769 \end_inset
18770 </cell>
18771 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18772 \begin_inset Text
18773
18774 \layout Standard
18775
18776 rest of the pointer
18777 \end_inset
18778 </cell>
18779 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18780 \begin_inset Text
18781
18782 \layout Standard
18783
18784 descrption
18785 \end_inset
18786 </cell>
18787 </row>
18788 <row topline="true" bottomline="true">
18789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18790 \begin_inset Text
18791
18792 \layout Standard
18793
18794 stream
18795 \end_inset
18796 </cell>
18797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18798 \begin_inset Text
18799
18800 \layout Standard
18801
18802 00
18803 \end_inset
18804 </cell>
18805 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18806 \begin_inset Text
18807
18808 \layout Standard
18809
18810 1
18811 \end_inset
18812 </cell>
18813 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18814 \begin_inset Text
18815
18816 \layout Standard
18817
18818 0
18819 \end_inset
18820 </cell>
18821 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18822 \begin_inset Text
18823
18824 \layout Standard
18825
18826 nnnn
18827 \end_inset
18828 </cell>
18829 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18830 \begin_inset Text
18831
18832 \layout Standard
18833
18834
18835 \family typewriter
18836 \shape slanted
18837 \emph on
18838 uuuuuuuu uuuuuuuu
18839 \end_inset
18840 </cell>
18841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18842 \begin_inset Text
18843
18844 \layout Standard
18845
18846 upper byte high nubble is 0x2n, the rest are zeroes
18847 \end_inset
18848 </cell>
18849 </row>
18850 </lyxtabular>
18851
18852 \end_inset
18853
18854
18855 \layout Standard
18856
18857 Currently implemented there are 3 types of streams defined:
18858 \layout Standard
18859 \align center
18860
18861 \begin_inset  Tabular
18862 <lyxtabular version="3" rows="4" columns="4">
18863 <features>
18864 <column alignment="center" valignment="top" leftline="true" width="0">
18865 <column alignment="center" valignment="top" leftline="true" width="0">
18866 <column alignment="center" valignment="top" leftline="true" width="0">
18867 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18868 <row topline="true" bottomline="true">
18869 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18870 \begin_inset Text
18871
18872 \layout Standard
18873
18874 stream type
18875 \end_inset
18876 </cell>
18877 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18878 \begin_inset Text
18879
18880 \layout Standard
18881
18882 value
18883 \end_inset
18884 </cell>
18885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18886 \begin_inset Text
18887
18888 \layout Standard
18889
18890 module
18891 \end_inset
18892 </cell>
18893 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18894 \begin_inset Text
18895
18896 \layout Standard
18897
18898 description
18899 \end_inset
18900 </cell>
18901 </row>
18902 <row topline="true">
18903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18904 \begin_inset Text
18905
18906 \layout Standard
18907
18908 STREAM_USART
18909 \end_inset
18910 </cell>
18911 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18912 \begin_inset Text
18913
18914 \layout Standard
18915
18916
18917 \family typewriter
18918 0x200000UL
18919 \end_inset
18920 </cell>
18921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18922 \begin_inset Text
18923
18924 \layout Standard
18925
18926 USART
18927 \end_inset
18928 </cell>
18929 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18930 \begin_inset Text
18931
18932 \layout Standard
18933
18934 Writes/Reads characters via the USART peripheral
18935 \end_inset
18936 </cell>
18937 </row>
18938 <row topline="true">
18939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18940 \begin_inset Text
18941
18942 \layout Standard
18943
18944 STREAM_MSSP
18945 \end_inset
18946 </cell>
18947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18948 \begin_inset Text
18949
18950 \layout Standard
18951
18952
18953 \family typewriter
18954 0x210000UL
18955 \end_inset
18956 </cell>
18957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18958 \begin_inset Text
18959
18960 \layout Standard
18961
18962 MSSP
18963 \end_inset
18964 </cell>
18965 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18966 \begin_inset Text
18967
18968 \layout Standard
18969
18970 Writes/Reads characters via the MSSP peripheral
18971 \end_inset
18972 </cell>
18973 </row>
18974 <row topline="true" bottomline="true">
18975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18976 \begin_inset Text
18977
18978 \layout Standard
18979
18980 STREAM_USER
18981 \end_inset
18982 </cell>
18983 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18984 \begin_inset Text
18985
18986 \layout Standard
18987
18988
18989 \family typewriter
18990 0x2f0000UL
18991 \end_inset
18992 </cell>
18993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18994 \begin_inset Text
18995
18996 \layout Standard
18997
18998 (none)
18999 \end_inset
19000 </cell>
19001 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19002 \begin_inset Text
19003
19004 \layout Standard
19005
19006 Writes/Reads characters via used defined functions
19007 \end_inset
19008 </cell>
19009 </row>
19010 </lyxtabular>
19011
19012 \end_inset
19013
19014
19015 \layout Standard
19016
19017 The stream identifiers are declared as macros in the stdio.h header.
19018 \layout Standard
19019
19020 In the libc library there exist the functions that are used to write to
19021  each of the above streams.
19022  These are
19023 \layout List
19024 \labelwidthstring 00.00.0000
19025
19026 _
19027 \begin_inset ERT
19028 status Collapsed
19029
19030 \layout Standard
19031
19032 \backslash
19033 /
19034 \end_inset
19035
19036 _stream_usart_putchar writes a character at the USART stream
19037 \layout List
19038 \labelwidthstring 00.00.0000
19039
19040 _
19041 \begin_inset ERT
19042 status Collapsed
19043
19044 \layout Standard
19045
19046 \backslash
19047 /
19048 \end_inset
19049
19050 _stream_mssp_putchar writes a character at the MSSP stream
19051 \layout List
19052 \labelwidthstring 00.00.0000
19053
19054 putchar dummy function.
19055  This writes a character to a user specified manner.
19056 \layout Standard
19057
19058 In order to increase performance
19059 \emph on
19060 putchar
19061 \emph default
19062 is declared in stdio.h as having its parameter in WREG (it has the wparam
19063  keyword).
19064  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
19065  in a user-friendly way.
19066
19067 \emph on
19068 arg
19069 \emph default
19070  is the name of the variable that holds the character to print.
19071  An example follows:
19072 \layout LyX-Code
19073
19074 #include <pic18fregs.h>
19075 \newline
19076 #include <stdio.h>
19077 \newline
19078
19079 \newline
19080 PUTCHAR( c )
19081 \layout LyX-Code
19082
19083 {
19084 \layout LyX-Code
19085
19086     PORTA = c;    /* dump character c to PORTA */
19087 \layout LyX-Code
19088
19089 }
19090 \newline
19091
19092 \newline
19093 void main(void)
19094 \layout LyX-Code
19095
19096 {
19097 \layout LyX-Code
19098
19099     stdout = STREAM_USER;    /* this is not necessery, since stdout points
19100 \layout LyX-Code
19101
19102                               * by default to STREAM_USER */
19103 \layout LyX-Code
19104
19105     printf (¨This is a printf test
19106 \backslash
19107 n¨);
19108 \layout LyX-Code
19109
19110 }
19111 \layout LyX-Code
19112
19113 \layout Subsubsection
19114
19115 Printing functions
19116 \layout Standard
19117
19118 PIC16 contains an implementation of the printf-family of functions.
19119  There exist the following functions:
19120 \layout LyX-Code
19121
19122 extern unsigned int sprintf(char *buf, char *fmt, ...);
19123 \layout LyX-Code
19124
19125 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
19126 \layout LyX-Code
19127
19128 \layout LyX-Code
19129
19130 extern unsigned int printf(char *fmt, ...);
19131 \layout LyX-Code
19132
19133 extern unsigned int vprintf(char *fmt, va_lista ap);
19134 \layout LyX-Code
19135
19136 \layout LyX-Code
19137
19138 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
19139 \layout LyX-Code
19140
19141 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
19142 \layout Standard
19143
19144 For sprintf and vsprintf
19145 \emph on
19146 buf
19147 \emph default
19148 should normally be a data pointer where the resulting string will be placed.
19149  No range checking is done so the user should allocate the necessery buffer.
19150  For fprintf and vfprintf
19151 \emph on
19152 fp
19153 \emph default
19154  should be a stream pointer (i.e.
19155  stdout, STREAM_MSSP, etc...).
19156 \layout Subsubsection
19157
19158 Signals
19159 \layout Standard
19160
19161 The PIC18F family of microcontrollers supports a number of interrupt sources.
19162  A list of these interrupts is shown in the following table:
19163 \layout Standard
19164 \align center
19165
19166 \begin_inset  Tabular
19167 <lyxtabular version="3" rows="11" columns="4">
19168 <features>
19169 <column alignment="left" valignment="top" leftline="true" width="0">
19170 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19171 <column alignment="left" valignment="top" leftline="true" width="0">
19172 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19173 <row topline="true" bottomline="true">
19174 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19175 \begin_inset Text
19176
19177 \layout Standard
19178
19179 signal name
19180 \end_inset
19181 </cell>
19182 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19183 \begin_inset Text
19184
19185 \layout Standard
19186
19187 description
19188 \end_inset
19189 </cell>
19190 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19191 \begin_inset Text
19192
19193 \layout Standard
19194
19195 signal name
19196 \end_inset
19197 </cell>
19198 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19199 \begin_inset Text
19200
19201 \layout Standard
19202
19203 descritpion
19204 \end_inset
19205 </cell>
19206 </row>
19207 <row topline="true">
19208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19209 \begin_inset Text
19210
19211 \layout Standard
19212
19213 SIG_RB
19214 \end_inset
19215 </cell>
19216 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19217 \begin_inset Text
19218
19219 \layout Standard
19220
19221 PORTB change interrupt
19222 \end_inset
19223 </cell>
19224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19225 \begin_inset Text
19226
19227 \layout Standard
19228
19229 SIG_EE
19230 \end_inset
19231 </cell>
19232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19233 \begin_inset Text
19234
19235 \layout Standard
19236
19237 EEPROM/FLASH write complete interrupt
19238 \end_inset
19239 </cell>
19240 </row>
19241 <row topline="true">
19242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19243 \begin_inset Text
19244
19245 \layout Standard
19246
19247 SIG_INT0
19248 \end_inset
19249 </cell>
19250 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19251 \begin_inset Text
19252
19253 \layout Standard
19254
19255 INT0 external interrupt
19256 \end_inset
19257 </cell>
19258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19259 \begin_inset Text
19260
19261 \layout Standard
19262
19263 SIG_BCOL
19264 \end_inset
19265 </cell>
19266 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19267 \begin_inset Text
19268
19269 \layout Standard
19270
19271 Bus collision interrupt
19272 \end_inset
19273 </cell>
19274 </row>
19275 <row topline="true">
19276 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19277 \begin_inset Text
19278
19279 \layout Standard
19280
19281 SIG_INT1
19282 \end_inset
19283 </cell>
19284 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19285 \begin_inset Text
19286
19287 \layout Standard
19288
19289 INT1 external interrupt
19290 \end_inset
19291 </cell>
19292 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19293 \begin_inset Text
19294
19295 \layout Standard
19296
19297 SIG_LVD
19298 \end_inset
19299 </cell>
19300 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19301 \begin_inset Text
19302
19303 \layout Standard
19304
19305 Low voltage detect interrupt
19306 \end_inset
19307 </cell>
19308 </row>
19309 <row topline="true">
19310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19311 \begin_inset Text
19312
19313 \layout Standard
19314
19315 SIG_INT2
19316 \end_inset
19317 </cell>
19318 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19319 \begin_inset Text
19320
19321 \layout Standard
19322
19323 INT2 external interrupt
19324 \end_inset
19325 </cell>
19326 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19327 \begin_inset Text
19328
19329 \layout Standard
19330
19331 SIG_PSP
19332 \end_inset
19333 </cell>
19334 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19335 \begin_inset Text
19336
19337 \layout Standard
19338
19339 Parallel slave port interrupt
19340 \end_inset
19341 </cell>
19342 </row>
19343 <row topline="true">
19344 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19345 \begin_inset Text
19346
19347 \layout Standard
19348
19349 SIG_CCP1
19350 \end_inset
19351 </cell>
19352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19353 \begin_inset Text
19354
19355 \layout Standard
19356
19357 CCP1 module interrupt
19358 \end_inset
19359 </cell>
19360 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19361 \begin_inset Text
19362
19363 \layout Standard
19364
19365 SIG_AD
19366 \end_inset
19367 </cell>
19368 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19369 \begin_inset Text
19370
19371 \layout Standard
19372
19373 AD convertion complete interrupt
19374 \end_inset
19375 </cell>
19376 </row>
19377 <row topline="true">
19378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19379 \begin_inset Text
19380
19381 \layout Standard
19382
19383 SIG_CCP2
19384 \end_inset
19385 </cell>
19386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19387 \begin_inset Text
19388
19389 \layout Standard
19390
19391 CCP2 module interrupt
19392 \end_inset
19393 </cell>
19394 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19395 \begin_inset Text
19396
19397 \layout Standard
19398
19399 SIG_RC
19400 \end_inset
19401 </cell>
19402 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19403 \begin_inset Text
19404
19405 \layout Standard
19406
19407 USART receive interrupt
19408 \end_inset
19409 </cell>
19410 </row>
19411 <row topline="true">
19412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19413 \begin_inset Text
19414
19415 \layout Standard
19416
19417 SIG_TMR0
19418 \end_inset
19419 </cell>
19420 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19421 \begin_inset Text
19422
19423 \layout Standard
19424
19425 TMR0 overflow interrupt
19426 \end_inset
19427 </cell>
19428 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19429 \begin_inset Text
19430
19431 \layout Standard
19432
19433 SIG_TX
19434 \end_inset
19435 </cell>
19436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19437 \begin_inset Text
19438
19439 \layout Standard
19440
19441 USART transmit interrupt
19442 \end_inset
19443 </cell>
19444 </row>
19445 <row topline="true">
19446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19447 \begin_inset Text
19448
19449 \layout Standard
19450
19451 SIG_TMR1
19452 \end_inset
19453 </cell>
19454 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19455 \begin_inset Text
19456
19457 \layout Standard
19458
19459 TMR1 overflow interrupt
19460 \end_inset
19461 </cell>
19462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19463 \begin_inset Text
19464
19465 \layout Standard
19466
19467 SIG_MSSP
19468 \end_inset
19469 </cell>
19470 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19471 \begin_inset Text
19472
19473 \layout Standard
19474
19475 SSP receive/transmit interrupt
19476 \end_inset
19477 </cell>
19478 </row>
19479 <row topline="true">
19480 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19481 \begin_inset Text
19482
19483 \layout Standard
19484
19485 SIG_TMR2
19486 \end_inset
19487 </cell>
19488 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19489 \begin_inset Text
19490
19491 \layout Standard
19492
19493 TMR2 matches PR2 interrupt
19494 \end_inset
19495 </cell>
19496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19497 \begin_inset Text
19498
19499 \layout Standard
19500
19501 \end_inset
19502 </cell>
19503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19504 \begin_inset Text
19505
19506 \layout Standard
19507
19508 \end_inset
19509 </cell>
19510 </row>
19511 <row topline="true" bottomline="true">
19512 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19513 \begin_inset Text
19514
19515 \layout Standard
19516
19517 SIG_TMR3
19518 \end_inset
19519 </cell>
19520 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19521 \begin_inset Text
19522
19523 \layout Standard
19524
19525 TMR3 overflow interrupt
19526 \end_inset
19527 </cell>
19528 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19529 \begin_inset Text
19530
19531 \layout Standard
19532
19533 \end_inset
19534 </cell>
19535 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19536 \begin_inset Text
19537
19538 \layout Standard
19539
19540 \end_inset
19541 </cell>
19542 </row>
19543 </lyxtabular>
19544
19545 \end_inset
19546
19547
19548 \layout Standard
19549
19550 The prototypes for these names are defined in the header file
19551 \emph on
19552 signal.h
19553 \emph default
19554  .
19555 \layout Standard
19556
19557 In order to simplify signal handling, a number of macros is provided:
19558 \layout List
19559 \labelwidthstring 00.00.0000
19560
19561 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
19562  high priority interrupts.
19563
19564 \emph on
19565 name
19566 \emph default
19567  is the function name to use.
19568 \layout List
19569 \labelwidthstring 00.00.0000
19570
19571 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
19572  low priority interrupt.
19573
19574 \emph on
19575 name
19576 \emph default
19577  is the function name to use.
19578 \layout List
19579 \labelwidthstring 00.00.0000
19580
19581 DEF_HANDLER(sig,handler) define a handler for signal
19582 \emph on
19583 sig.
19584 \layout List
19585 \labelwidthstring 00.00.0000
19586
19587 END_DEF end the declaration of the dispatch table.
19588 \layout Standard
19589
19590 Additionally there are two more macros to simplify the declaration of the
19591  signal handler:
19592 \layout List
19593 \labelwidthstring 00.00.0000
19594
19595
19596 \series medium
19597 SIGHANDLER(handler)
19598 \series default
19599 this declares the function prototype for the
19600 \emph on
19601 handler
19602 \emph default
19603  function.
19604 \layout List
19605 \labelwidthstring 00.00.0000
19606
19607 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
19608 \layout Standard
19609
19610 An example of using the macros above is shown below:
19611 \layout LyX-Code
19612
19613 #include <pic18fregs.h>
19614 \layout LyX-Code
19615
19616 #include <signal.h>
19617 \newline
19618
19619 \newline
19620 DEF_INTHIGH(high_int)
19621 \layout LyX-Code
19622
19623 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
19624 \layout LyX-Code
19625
19626 DEF_HANDLER(SIG_BCOL, _bcol_handler)
19627 \layout LyX-Code
19628
19629 END_DEF
19630 \newline
19631
19632 \newline
19633 SIGHANDLER(_tmr0_handler)
19634 \layout LyX-Code
19635
19636 {
19637 \layout LyX-Code
19638
19639   /* action to be taken when timer 0 overflows */
19640 \layout LyX-Code
19641
19642 }
19643 \newline
19644
19645 \newline
19646 SIGHANDLERNAKED(_bcol_handler)
19647 \layout LyX-Code
19648
19649 {
19650 \layout LyX-Code
19651
19652   _asm
19653 \layout LyX-Code
19654
19655     /* action to be taken when bus collision occurs */
19656 \layout LyX-Code
19657
19658     retfie
19659 \layout LyX-Code
19660
19661  _endasm;
19662 \layout LyX-Code
19663
19664 }
19665 \layout Standard
19666
19667
19668 \series bold
19669 NOTES:
19670 \series default
19671  Special care should be taken when using the above scheme:
19672 \layout Itemize
19673
19674 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
19675 \layout Itemize
19676
19677 when declaring SIGHANDLERNAKED handler never forget to use
19678 \emph on
19679 retfie
19680 \emph default
19681  for proper returning.
19682 \layout Subsection
19683
19684 PIC16 Port -- Tips
19685 \layout Standard
19686
19687 Here you can find some general tips for compiling programs with SDCC/pic16.
19688 \layout Subsubsection
19689
19690 Stack size
19691 \layout Standard
19692
19693 The default stack size (that is 64 bytes) probably is enough for many programs.
19694  One must take care that when there are many levels of function nesting,
19695  or there is excessive usage of stack, its size should be extended.
19696  An example of such a case is the printf/sprintf family of functions.
19697  If you encounter problems like not being able to print integers, then you
19698  need to set the stack size around the maximum (256 for small stack model).
19699  The following diagram shows what happens when calling printf to print an
19700  integer:
19701 \layout LyX-Code
19702
19703 printf () --> ltoa () --> ultoa () --> divschar ()
19704 \layout Standard
19705
19706 It is should be understood that stack is easily consumed when calling complicate
19707 d functions.
19708  Using command line arguments like -
19709 \begin_inset ERT
19710 status Collapsed
19711
19712 \layout Standard
19713
19714 \backslash
19715 /
19716 \end_inset
19717
19718 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
19719  stack frames.
19720  Other ways to reduce stack usage may exist.
19721 \layout Chapter
19722
19723 Debugging with SDCDB
19724 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
19725
19726 \end_inset
19727
19728
19729 \begin_inset LatexCommand \index{sdcdb (debugger)}
19730
19731 \end_inset
19732
19733
19734 \layout Standard
19735
19736 SDCC is distributed with a source level debugger
19737 \begin_inset LatexCommand \index{Debugger}
19738
19739 \end_inset
19740
19741 .
19742  The debugger uses a command line interface, the command repertoire of the
19743  debugger has been kept as close to gdb
19744 \begin_inset LatexCommand \index{gdb}
19745
19746 \end_inset
19747
19748  (the GNU debugger) as possible.
19749  The configuration and build process is part of the standard compiler installati
19750 on, which also builds and installs the debugger in the target directory
19751  specified during configuration.
19752  The debugger allows you debug BOTH at the C source and at the ASM source
19753  level.
19754  Sdcdb is available on Unix platforms only.
19755 \layout Section
19756
19757 Compiling for Debugging
19758 \layout Standard
19759
19760 The -
19761 \begin_inset ERT
19762 status Collapsed
19763
19764 \layout Standard
19765
19766 \backslash
19767 /
19768 \end_inset
19769
19770 -debug
19771 \begin_inset LatexCommand \index{-\/-debug}
19772
19773 \end_inset
19774
19775  option must be specified for all files for which debug information is to
19776  be generated.
19777  The complier generates a .adb file for each of these files.
19778  The linker creates the .cdb
19779 \begin_inset LatexCommand \index{<file>.cdb}
19780
19781 \end_inset
19782
19783  file from the .adb
19784 \begin_inset LatexCommand \index{<file>.adb}
19785
19786 \end_inset
19787
19788  files and the address information.
19789  This .cdb is used by the debugger.
19790 \layout Section
19791
19792 How the Debugger Works
19793 \layout Standard
19794
19795 When the -
19796 \begin_inset ERT
19797 status Collapsed
19798
19799 \layout Standard
19800
19801 \backslash
19802 /
19803 \end_inset
19804
19805 -debug option is specified the compiler generates extra symbol information
19806  some of which are put into the assembler source and some are put into the
19807  .adb file.
19808   Then the linker creates the .cdb file from the individual .adb files with
19809  the address information for the symbols.
19810  The debugger reads the symbolic information generated by the compiler &
19811  the address information generated by the linker.
19812  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
19813  execution is controlled by the debugger.
19814  When a command is issued for the debugger, it translates it into appropriate
19815  commands for the simulator.
19816 \layout Section
19817
19818 Starting the Debugger
19819 \layout Standard
19820
19821 The debugger can be started using the following command line.
19822  (Assume the file you are debugging has the file name foo).
19823 \newline
19824
19825 \newline
19826
19827 \family sans
19828 \series bold
19829 sdcdb foo
19830 \newline
19831
19832 \family default
19833 \series default
19834
19835 \newline
19836 The debugger will look for the following files.
19837 \layout Itemize
19838
19839 foo.c - the source file.
19840 \layout Itemize
19841
19842 foo.cdb - the debugger symbol information file.
19843 \layout Itemize
19844
19845 foo.ihx - the Intel hex format
19846 \begin_inset LatexCommand \index{Intel hex format}
19847
19848 \end_inset
19849
19850  object file.
19851 \layout Section
19852
19853 Command Line Options
19854 \layout Itemize
19855
19856 -
19857 \begin_inset ERT
19858 status Collapsed
19859
19860 \layout Standard
19861
19862 \backslash
19863 /
19864 \end_inset
19865
19866 -directory=<source file directory> this option can used to specify the directory
19867  search list.
19868  The debugger will look into the directory list specified for source, cdb
19869  & ihx files.
19870  The items in the directory list must be separated by ':', e.g.
19871  if the source files can be in the directories /home/src1 and /home/src2,
19872  the -
19873 \begin_inset ERT
19874 status Collapsed
19875
19876 \layout Standard
19877
19878 \backslash
19879 /
19880 \end_inset
19881
19882 -directory option should be -
19883 \begin_inset ERT
19884 status Collapsed
19885
19886 \layout Standard
19887
19888 \backslash
19889 /
19890 \end_inset
19891
19892 -directory=/home/src1:/home/src2.
19893  Note there can be no spaces in the option.
19894
19895 \layout Itemize
19896
19897 -cd <directory> - change to the <directory>.
19898 \layout Itemize
19899
19900 -fullname - used by GUI front ends.
19901 \layout Itemize
19902
19903 -cpu <cpu-type> - this argument is passed to the simulator please see the
19904  simulator docs for details.
19905 \layout Itemize
19906
19907 -X <Clock frequency > this options is passed to the simulator please see
19908  the simulator docs for details.
19909 \layout Itemize
19910
19911 -s <serial port file> passed to simulator see the simulator docs for details.
19912 \layout Itemize
19913
19914 -S <serial in,out> passed to simulator see the simulator docs for details.
19915 \layout Itemize
19916
19917 -k <port number> passed to simulator see the simulator docs for details.
19918 \layout Section
19919
19920 Debugger Commands
19921 \layout Standard
19922
19923 As mentioned earlier the command interface for the debugger has been deliberatel
19924 y kept as close the GNU debugger gdb, as possible.
19925  This will help the integration with existing graphical user interfaces
19926  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
19927  If you use a graphical user interface for the debugger you can skip this
19928  section.
19929 \layout Subsubsection*
19930
19931 break [line | file:line | function | file:function]
19932 \layout Standard
19933
19934 Set breakpoint at specified line or function:
19935 \newline
19936
19937 \newline
19938
19939 \family sans
19940 \series bold
19941 sdcdb>break 100
19942 \newline
19943 sdcdb>break foo.c:100
19944 \newline
19945 sdcdb>break funcfoo
19946 \newline
19947 sdcdb>break foo.c:funcfoo
19948 \layout Subsubsection*
19949
19950 clear [line | file:line | function | file:function ]
19951 \layout Standard
19952
19953 Clear breakpoint at specified line or function:
19954 \newline
19955
19956 \newline
19957
19958 \family sans
19959 \series bold
19960 sdcdb>clear 100
19961 \newline
19962 sdcdb>clear foo.c:100
19963 \newline
19964 sdcdb>clear funcfoo
19965 \newline
19966 sdcdb>clear foo.c:funcfoo
19967 \layout Subsubsection*
19968
19969 continue
19970 \layout Standard
19971
19972 Continue program being debugged, after breakpoint.
19973 \layout Subsubsection*
19974
19975 finish
19976 \layout Standard
19977
19978 Execute till the end of the current function.
19979 \layout Subsubsection*
19980
19981 delete [n]
19982 \layout Standard
19983
19984 Delete breakpoint number 'n'.
19985  If used without any option clear ALL user defined break points.
19986 \layout Subsubsection*
19987
19988 info [break | stack | frame | registers ]
19989 \layout Itemize
19990
19991 info break - list all breakpoints
19992 \layout Itemize
19993
19994 info stack - show the function call stack.
19995 \layout Itemize
19996
19997 info frame - show information about the current execution frame.
19998 \layout Itemize
19999
20000 info registers - show content of all registers.
20001 \layout Subsubsection*
20002
20003 step
20004 \layout Standard
20005
20006 Step program until it reaches a different source line.
20007  Note: pressing <return> repeats the last command.
20008 \layout Subsubsection*
20009
20010 next
20011 \layout Standard
20012
20013 Step program, proceeding through subroutine calls.
20014 \layout Subsubsection*
20015
20016 run
20017 \layout Standard
20018
20019 Start debugged program.
20020 \layout Subsubsection*
20021
20022 ptype variable
20023 \layout Standard
20024
20025 Print type information of the variable.
20026 \layout Subsubsection*
20027
20028 print variable
20029 \layout Standard
20030
20031 print value of variable.
20032 \layout Subsubsection*
20033
20034 file filename
20035 \layout Standard
20036
20037 load the given file name.
20038  Note this is an alternate method of loading file for debugging.
20039 \layout Subsubsection*
20040
20041 frame
20042 \layout Standard
20043
20044 print information about current frame.
20045 \layout Subsubsection*
20046
20047 set srcmode
20048 \layout Standard
20049
20050 Toggle between C source & assembly source.
20051 \layout Subsubsection*
20052
20053 ! simulator command
20054 \layout Standard
20055
20056 Send the string following '!' to the simulator, the simulator response is
20057  displayed.
20058  Note the debugger does not interpret the command being sent to the simulator,
20059  so if a command like 'go' is sent the debugger can loose its execution
20060  context and may display incorrect values.
20061 \layout Subsubsection*
20062
20063 quit
20064 \layout Standard
20065
20066 "Watch me now.
20067  Iam going Down.
20068  My name is Bobby Brown"
20069 \layout Section
20070
20071 Interfacing with DDD
20072 \layout Comment
20073
20074 The screenshot was converted from png to eps with:
20075 \begin_inset Quotes sld
20076 \end_inset
20077
20078 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
20079 \begin_inset Quotes srd
20080 \end_inset
20081
20082  which produces a pretty compact eps file which is free from compression
20083  artifacts.
20084 \layout Comment
20085
20086 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
20087  as this broke the build system on Sourceforge (pdf-file was broken).
20088 \layout Standard
20089
20090 The .eps File
20091 \size footnotesize
20092
20093 \begin_inset LatexCommand \url{http://cvs.sourceforge.net/viewcvs.py/*checkout*/sdcc/sdcc/doc/figures/ddd_example.eps}
20094
20095 \end_inset
20096
20097
20098 \size default
20099  shows a screenshot of a debugging session with DDD
20100 \begin_inset LatexCommand \index{DDD (debugger)}
20101
20102 \end_inset
20103
20104  (Unix only) on a simulated 8032.
20105  The debugging session might not run as smoothly as the screenshot suggests.
20106  The debugger allows setting of breakpoints, displaying and changing variables,
20107  single stepping through C and assembler code.
20108
20109 \newline
20110 The source was compiled with
20111 \family sans
20112 \series bold
20113
20114 \newline
20115
20116 \newline
20117 sdcc -
20118 \family default
20119 \series default
20120
20121 \begin_inset ERT
20122 status Collapsed
20123
20124 \layout Standard
20125
20126 \backslash
20127 /
20128 \end_inset
20129
20130
20131 \family sans
20132 \series bold
20133 -debug ddd_example.c
20134 \family default
20135 \series default
20136
20137 \family sans
20138 \series bold
20139
20140 \newline
20141
20142 \family default
20143 \series default
20144
20145 \newline
20146 and DDD was invoked with
20147 \family sans
20148 \series bold
20149
20150 \newline
20151
20152 \newline
20153 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
20154 \layout Section
20155
20156 Interfacing with XEmacs
20157 \begin_inset LatexCommand \index{XEmacs}
20158
20159 \end_inset
20160
20161
20162 \begin_inset LatexCommand \index{Emacs}
20163
20164 \end_inset
20165
20166
20167 \layout Standard
20168
20169 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
20170  sdcdb.el and sdcdbsrc.el.
20171  These two files can be found in the $(prefix)/bin directory after the installat
20172 ion is complete.
20173  These files need to be loaded into XEmacs for the interface to work.
20174  This can be done at XEmacs startup time by inserting the following into
20175  your '.xemacs' file (which can be found in your HOME directory):
20176 \newline
20177
20178 \newline
20179
20180 \family typewriter
20181 (load-file sdcdbsrc.el)
20182 \family default
20183
20184 \newline
20185
20186 \newline
20187 .xemacs is a lisp file so the () around the command is REQUIRED.
20188  The files can also be loaded dynamically while XEmacs is running, set the
20189  environment variable 'EMACSLOADPATH' to the installation bin directory
20190  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
20191  To start the interface enter the following command:
20192 \newline
20193
20194 \newline
20195
20196 \family sans
20197 \series bold
20198 ESC-x sdcdbsrc
20199 \family default
20200 \series default
20201
20202 \newline
20203
20204 \newline
20205 You will prompted to enter the file name to be debugged.
20206
20207 \newline
20208
20209 \newline
20210 The command line options that are passed to the simulator directly are bound
20211  to default values in the file sdcdbsrc.el.
20212  The variables are listed below, these values maybe changed as required.
20213 \layout Itemize
20214
20215 sdcdbsrc-cpu-type '51
20216 \layout Itemize
20217
20218 sdcdbsrc-frequency '11059200
20219 \layout Itemize
20220
20221 sdcdbsrc-serial nil
20222 \layout Standard
20223
20224 The following is a list of key mapping for the debugger interface.
20225 \layout Standard
20226
20227 \SpecialChar ~
20228
20229 \family typewriter
20230
20231 \newline
20232 ;;\SpecialChar ~
20233 Current Listing ::
20234 \newline
20235 ;;key\SpecialChar ~
20236 \SpecialChar ~
20237 \SpecialChar ~
20238 \SpecialChar ~
20239 \SpecialChar ~
20240 \SpecialChar ~
20241 \SpecialChar ~
20242 \SpecialChar ~
20243 \SpecialChar ~
20244 \SpecialChar ~
20245 \SpecialChar ~
20246 \SpecialChar ~
20247 \SpecialChar ~
20248 \SpecialChar ~
20249 binding\SpecialChar ~
20250 \SpecialChar ~
20251 \SpecialChar ~
20252 \SpecialChar ~
20253 \SpecialChar ~
20254 \SpecialChar ~
20255 \SpecialChar ~
20256 \SpecialChar ~
20257 \SpecialChar ~
20258 \SpecialChar ~
20259 \SpecialChar ~
20260 \SpecialChar ~
20261 \SpecialChar ~
20262 \SpecialChar ~
20263 \SpecialChar ~
20264 \SpecialChar ~
20265 \SpecialChar ~
20266 \SpecialChar ~
20267 \SpecialChar ~
20268 \SpecialChar ~
20269 \SpecialChar ~
20270 \SpecialChar ~
20271 Comment
20272 \newline
20273 ;;---\SpecialChar ~
20274 \SpecialChar ~
20275 \SpecialChar ~
20276 \SpecialChar ~
20277 \SpecialChar ~
20278 \SpecialChar ~
20279 \SpecialChar ~
20280 \SpecialChar ~
20281 \SpecialChar ~
20282 \SpecialChar ~
20283 \SpecialChar ~
20284 \SpecialChar ~
20285 \SpecialChar ~
20286 \SpecialChar ~
20287 -------\SpecialChar ~
20288 \SpecialChar ~
20289 \SpecialChar ~
20290 \SpecialChar ~
20291 \SpecialChar ~
20292 \SpecialChar ~
20293 \SpecialChar ~
20294 \SpecialChar ~
20295 \SpecialChar ~
20296 \SpecialChar ~
20297 \SpecialChar ~
20298 \SpecialChar ~
20299 \SpecialChar ~
20300 \SpecialChar ~
20301 \SpecialChar ~
20302 \SpecialChar ~
20303 \SpecialChar ~
20304 \SpecialChar ~
20305 \SpecialChar ~
20306 \SpecialChar ~
20307 \SpecialChar ~
20308 \SpecialChar ~
20309 -------
20310 \newline
20311 ;;
20312 \newline
20313 ;;\SpecialChar ~
20314 n\SpecialChar ~
20315 \SpecialChar ~
20316 \SpecialChar ~
20317 \SpecialChar ~
20318 \SpecialChar ~
20319 \SpecialChar ~
20320 \SpecialChar ~
20321 \SpecialChar ~
20322 \SpecialChar ~
20323 \SpecialChar ~
20324 \SpecialChar ~
20325 \SpecialChar ~
20326 \SpecialChar ~
20327 \SpecialChar ~
20328 \SpecialChar ~
20329 sdcdb-next-from-src\SpecialChar ~
20330 \SpecialChar ~
20331 \SpecialChar ~
20332 \SpecialChar ~
20333 \SpecialChar ~
20334 \SpecialChar ~
20335 \SpecialChar ~
20336 \SpecialChar ~
20337 \SpecialChar ~
20338 \SpecialChar ~
20339 SDCDB next command
20340 \newline
20341 ;;\SpecialChar ~
20342 b\SpecialChar ~
20343 \SpecialChar ~
20344 \SpecialChar ~
20345 \SpecialChar ~
20346 \SpecialChar ~
20347 \SpecialChar ~
20348 \SpecialChar ~
20349 \SpecialChar ~
20350 \SpecialChar ~
20351 \SpecialChar ~
20352 \SpecialChar ~
20353 \SpecialChar ~
20354 \SpecialChar ~
20355 \SpecialChar ~
20356 \SpecialChar ~
20357 sdcdb-back-from-src\SpecialChar ~
20358 \SpecialChar ~
20359 \SpecialChar ~
20360 \SpecialChar ~
20361 \SpecialChar ~
20362 \SpecialChar ~
20363 \SpecialChar ~
20364 \SpecialChar ~
20365 \SpecialChar ~
20366 \SpecialChar ~
20367 SDCDB back command
20368 \newline
20369 ;;\SpecialChar ~
20370 c\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 sdcdb-cont-from-src\SpecialChar ~
20386 \SpecialChar ~
20387 \SpecialChar ~
20388 \SpecialChar ~
20389 \SpecialChar ~
20390 \SpecialChar ~
20391 \SpecialChar ~
20392 \SpecialChar ~
20393 \SpecialChar ~
20394 \SpecialChar ~
20395 SDCDB continue command
20396 \newline
20397 ;;\SpecialChar ~
20398 s\SpecialChar ~
20399 \SpecialChar ~
20400 \SpecialChar ~
20401 \SpecialChar ~
20402 \SpecialChar ~
20403 \SpecialChar ~
20404 \SpecialChar ~
20405 \SpecialChar ~
20406 \SpecialChar ~
20407 \SpecialChar ~
20408 \SpecialChar ~
20409 \SpecialChar ~
20410 \SpecialChar ~
20411 \SpecialChar ~
20412 \SpecialChar ~
20413 sdcdb-step-from-src\SpecialChar ~
20414 \SpecialChar ~
20415 \SpecialChar ~
20416 \SpecialChar ~
20417 \SpecialChar ~
20418 \SpecialChar ~
20419 \SpecialChar ~
20420 \SpecialChar ~
20421 \SpecialChar ~
20422 \SpecialChar ~
20423 SDCDB step command
20424 \newline
20425 ;;\SpecialChar ~
20426 ?\SpecialChar ~
20427 \SpecialChar ~
20428 \SpecialChar ~
20429 \SpecialChar ~
20430 \SpecialChar ~
20431 \SpecialChar ~
20432 \SpecialChar ~
20433 \SpecialChar ~
20434 \SpecialChar ~
20435 \SpecialChar ~
20436 \SpecialChar ~
20437 \SpecialChar ~
20438 \SpecialChar ~
20439 \SpecialChar ~
20440 \SpecialChar ~
20441 sdcdb-whatis-c-sexp\SpecialChar ~
20442 \SpecialChar ~
20443 \SpecialChar ~
20444 \SpecialChar ~
20445 \SpecialChar ~
20446 \SpecialChar ~
20447 \SpecialChar ~
20448 \SpecialChar ~
20449 \SpecialChar ~
20450 \SpecialChar ~
20451 SDCDB ptypecommand for data at
20452 \newline
20453 ;;\SpecialChar ~
20454 \SpecialChar ~
20455 \SpecialChar ~
20456 \SpecialChar ~
20457 \SpecialChar ~
20458 \SpecialChar ~
20459 \SpecialChar ~
20460 \SpecialChar ~
20461 \SpecialChar ~
20462 \SpecialChar ~
20463 \SpecialChar ~
20464 \SpecialChar ~
20465 \SpecialChar ~
20466 \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 \SpecialChar ~
20482 \SpecialChar ~
20483 \SpecialChar ~
20484 \SpecialChar ~
20485 \SpecialChar ~
20486 \SpecialChar ~
20487 \SpecialChar ~
20488 \SpecialChar ~
20489 \SpecialChar ~
20490 \SpecialChar ~
20491 \SpecialChar ~
20492 \SpecialChar ~
20493 \SpecialChar ~
20494 \SpecialChar ~
20495 \SpecialChar ~
20496 \SpecialChar ~
20497 \SpecialChar ~
20498 \SpecialChar ~
20499 \SpecialChar ~
20500 buffer point
20501 \newline
20502 ;;\SpecialChar ~
20503 x\SpecialChar ~
20504 \SpecialChar ~
20505 \SpecialChar ~
20506 \SpecialChar ~
20507 \SpecialChar ~
20508 \SpecialChar ~
20509 \SpecialChar ~
20510 \SpecialChar ~
20511 \SpecialChar ~
20512 \SpecialChar ~
20513 \SpecialChar ~
20514 \SpecialChar ~
20515 \SpecialChar ~
20516 \SpecialChar ~
20517 \SpecialChar ~
20518 sdcdbsrc-delete\SpecialChar ~
20519 \SpecialChar ~
20520 \SpecialChar ~
20521 \SpecialChar ~
20522 \SpecialChar ~
20523 \SpecialChar ~
20524 \SpecialChar ~
20525 \SpecialChar ~
20526 \SpecialChar ~
20527 \SpecialChar ~
20528 \SpecialChar ~
20529 \SpecialChar ~
20530 \SpecialChar ~
20531 \SpecialChar ~
20532 SDCDB Delete all breakpoints if no arg
20533 \newline
20534 ;;\SpecialChar ~
20535 \SpecialChar ~
20536 \SpecialChar ~
20537 \SpecialChar ~
20538 \SpecialChar ~
20539 \SpecialChar ~
20540 \SpecialChar ~
20541 \SpecialChar ~
20542 \SpecialChar ~
20543 \SpecialChar ~
20544 \SpecialChar ~
20545 \SpecialChar ~
20546 \SpecialChar ~
20547 \SpecialChar ~
20548 \SpecialChar ~
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 given or delete arg (C-u arg x)
20582 \newline
20583 ;;\SpecialChar ~
20584 m\SpecialChar ~
20585 \SpecialChar ~
20586 \SpecialChar ~
20587 \SpecialChar ~
20588 \SpecialChar ~
20589 \SpecialChar ~
20590 \SpecialChar ~
20591 \SpecialChar ~
20592 \SpecialChar ~
20593 \SpecialChar ~
20594 \SpecialChar ~
20595 \SpecialChar ~
20596 \SpecialChar ~
20597 \SpecialChar ~
20598 \SpecialChar ~
20599 sdcdbsrc-frame\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 SDCDB Display current frame if no arg,
20615 \newline
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 \SpecialChar ~
20629 \SpecialChar ~
20630 \SpecialChar ~
20631 \SpecialChar ~
20632 \SpecialChar ~
20633 \SpecialChar ~
20634 \SpecialChar ~
20635 \SpecialChar ~
20636 \SpecialChar ~
20637 \SpecialChar ~
20638 \SpecialChar ~
20639 \SpecialChar ~
20640 \SpecialChar ~
20641 \SpecialChar ~
20642 \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 given or display frame arg
20664 \newline
20665 ;;\SpecialChar ~
20666 \SpecialChar ~
20667 \SpecialChar ~
20668 \SpecialChar ~
20669 \SpecialChar ~
20670 \SpecialChar ~
20671 \SpecialChar ~
20672 \SpecialChar ~
20673 \SpecialChar ~
20674 \SpecialChar ~
20675 \SpecialChar ~
20676 \SpecialChar ~
20677 \SpecialChar ~
20678 \SpecialChar ~
20679 \SpecialChar ~
20680 \SpecialChar ~
20681 \SpecialChar ~
20682 \SpecialChar ~
20683 \SpecialChar ~
20684 \SpecialChar ~
20685 \SpecialChar ~
20686 \SpecialChar ~
20687 \SpecialChar ~
20688 \SpecialChar ~
20689 \SpecialChar ~
20690 \SpecialChar ~
20691 \SpecialChar ~
20692 \SpecialChar ~
20693 \SpecialChar ~
20694 \SpecialChar ~
20695 \SpecialChar ~
20696 \SpecialChar ~
20697 \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 \SpecialChar ~
20711 \SpecialChar ~
20712 buffer point
20713 \newline
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 sdcdbsrc-goto-sdcdb\SpecialChar ~
20731 \SpecialChar ~
20732 \SpecialChar ~
20733 \SpecialChar ~
20734 \SpecialChar ~
20735 \SpecialChar ~
20736 \SpecialChar ~
20737 \SpecialChar ~
20738 \SpecialChar ~
20739 \SpecialChar ~
20740 Goto the SDCDB output buffer
20741 \newline
20742 ;;\SpecialChar ~
20743 p\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 sdcdb-print-c-sexp\SpecialChar ~
20759 \SpecialChar ~
20760 \SpecialChar ~
20761 \SpecialChar ~
20762 \SpecialChar ~
20763 \SpecialChar ~
20764 \SpecialChar ~
20765 \SpecialChar ~
20766 \SpecialChar ~
20767 \SpecialChar ~
20768 \SpecialChar ~
20769 SDCDB print command for data at
20770 \newline
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 \SpecialChar ~
20809 \SpecialChar ~
20810 \SpecialChar ~
20811 \SpecialChar ~
20812 \SpecialChar ~
20813 \SpecialChar ~
20814 \SpecialChar ~
20815 \SpecialChar ~
20816 \SpecialChar ~
20817 \SpecialChar ~
20818 buffer point
20819 \newline
20820 ;;\SpecialChar ~
20821 g\SpecialChar ~
20822 \SpecialChar ~
20823 \SpecialChar ~
20824 \SpecialChar ~
20825 \SpecialChar ~
20826 \SpecialChar ~
20827 \SpecialChar ~
20828 \SpecialChar ~
20829 \SpecialChar ~
20830 \SpecialChar ~
20831 \SpecialChar ~
20832 \SpecialChar ~
20833 \SpecialChar ~
20834 \SpecialChar ~
20835 \SpecialChar ~
20836 sdcdbsrc-goto-sdcdb\SpecialChar ~
20837 \SpecialChar ~
20838 \SpecialChar ~
20839 \SpecialChar ~
20840 \SpecialChar ~
20841 \SpecialChar ~
20842 \SpecialChar ~
20843 \SpecialChar ~
20844 \SpecialChar ~
20845 \SpecialChar ~
20846 Goto the SDCDB output buffer
20847 \newline
20848 ;;\SpecialChar ~
20849 t\SpecialChar ~
20850 \SpecialChar ~
20851 \SpecialChar ~
20852 \SpecialChar ~
20853 \SpecialChar ~
20854 \SpecialChar ~
20855 \SpecialChar ~
20856 \SpecialChar ~
20857 \SpecialChar ~
20858 \SpecialChar ~
20859 \SpecialChar ~
20860 \SpecialChar ~
20861 \SpecialChar ~
20862 \SpecialChar ~
20863 \SpecialChar ~
20864 sdcdbsrc-mode\SpecialChar ~
20865 \SpecialChar ~
20866 \SpecialChar ~
20867 \SpecialChar ~
20868 \SpecialChar ~
20869 \SpecialChar ~
20870 \SpecialChar ~
20871 \SpecialChar ~
20872 \SpecialChar ~
20873 \SpecialChar ~
20874 \SpecialChar ~
20875 \SpecialChar ~
20876 \SpecialChar ~
20877 \SpecialChar ~
20878 \SpecialChar ~
20879 \SpecialChar ~
20880 Toggles Sdcdbsrc mode (turns it off)
20881 \newline
20882 ;;
20883 \newline
20884 ;;\SpecialChar ~
20885 C-c\SpecialChar ~
20886 C-f\SpecialChar ~
20887 \SpecialChar ~
20888 \SpecialChar ~
20889 \SpecialChar ~
20890 \SpecialChar ~
20891 \SpecialChar ~
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895 sdcdb-finish-from-src\SpecialChar ~
20896 \SpecialChar ~
20897 \SpecialChar ~
20898 \SpecialChar ~
20899 \SpecialChar ~
20900 \SpecialChar ~
20901 \SpecialChar ~
20902 \SpecialChar ~
20903 SDCDB finish command
20904 \newline
20905 ;;
20906 \newline
20907 ;;\SpecialChar ~
20908 C-x\SpecialChar ~
20909 SPC\SpecialChar ~
20910 \SpecialChar ~
20911 \SpecialChar ~
20912 \SpecialChar ~
20913 \SpecialChar ~
20914 \SpecialChar ~
20915 \SpecialChar ~
20916 \SpecialChar ~
20917 \SpecialChar ~
20918 sdcdb-break\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 \SpecialChar ~
20933 \SpecialChar ~
20934 \SpecialChar ~
20935 \SpecialChar ~
20936 Set break for line with point
20937 \newline
20938 ;;\SpecialChar ~
20939 ESC\SpecialChar ~
20940 t\SpecialChar ~
20941 \SpecialChar ~
20942 \SpecialChar ~
20943 \SpecialChar ~
20944 \SpecialChar ~
20945 \SpecialChar ~
20946 \SpecialChar ~
20947 \SpecialChar ~
20948 \SpecialChar ~
20949 \SpecialChar ~
20950 \SpecialChar ~
20951 sdcdbsrc-mode\SpecialChar ~
20952 \SpecialChar ~
20953 \SpecialChar ~
20954 \SpecialChar ~
20955 \SpecialChar ~
20956 \SpecialChar ~
20957 \SpecialChar ~
20958 \SpecialChar ~
20959 \SpecialChar ~
20960 \SpecialChar ~
20961 \SpecialChar ~
20962 \SpecialChar ~
20963 \SpecialChar ~
20964 \SpecialChar ~
20965 \SpecialChar ~
20966 \SpecialChar ~
20967 Toggle Sdcdbsrc mode
20968 \newline
20969 ;;\SpecialChar ~
20970 ESC\SpecialChar ~
20971 m\SpecialChar ~
20972 \SpecialChar ~
20973 \SpecialChar ~
20974 \SpecialChar ~
20975 \SpecialChar ~
20976 \SpecialChar ~
20977 \SpecialChar ~
20978 \SpecialChar ~
20979 \SpecialChar ~
20980 \SpecialChar ~
20981 \SpecialChar ~
20982 sdcdbsrc-srcmode\SpecialChar ~
20983 \SpecialChar ~
20984 \SpecialChar ~
20985 \SpecialChar ~
20986 \SpecialChar ~
20987 \SpecialChar ~
20988 \SpecialChar ~
20989 \SpecialChar ~
20990 \SpecialChar ~
20991 \SpecialChar ~
20992 \SpecialChar ~
20993 \SpecialChar ~
20994 \SpecialChar ~
20995 Toggle list mode
20996 \newline
20997 ;;
20998 \newline
20999
21000 \layout Chapter
21001 \pagebreak_top
21002 TIPS
21003 \layout Standard
21004
21005 Here are a few guidelines that will help the compiler generate more efficient
21006  code, some of the tips are specific to this compiler others are generally
21007  good programming practice.
21008 \layout Itemize
21009
21010 Use the smallest data type to represent your data-value.
21011  If it is known in advance that the value is going to be less than 256 then
21012  use an 'unsigned char' instead of a 'short' or 'int'.
21013  Please note, that ANSI C requires both signed and unsigned chars to be
21014  promoted to 'signed int' before doing any operation.
21015  This promotion
21016 \begin_inset LatexCommand \index{type promotion}
21017
21018 \end_inset
21019
21020  can be omitted, if the result is the same.
21021  The effect of the promotion rules together with the sign-extension is often
21022  surprising:
21023 \begin_deeper
21024 \layout Verse
21025
21026
21027 \family typewriter
21028 unsigned char uc = 0xfe;
21029 \newline
21030 if (uc * uc < 0) /* this is true! */
21031 \newline
21032 {
21033 \newline
21034 \SpecialChar ~
21035 \SpecialChar ~
21036 \SpecialChar ~
21037 \SpecialChar ~
21038 ....
21039 \newline
21040 }
21041 \layout Standard
21042
21043
21044 \family typewriter
21045 uc * uc
21046 \family default
21047  is evaluated as
21048 \family typewriter
21049 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
21050 \family default
21051 .
21052
21053 \newline
21054 Another one:
21055 \layout Verse
21056
21057
21058 \family typewriter
21059 (unsigned char) -12 / (signed char) -3 = ...
21060 \layout Standard
21061
21062 No, the result is not 4:
21063 \layout Verse
21064
21065
21066 \family typewriter
21067 (int) (unsigned char) -12 / (int) (signed char) -3 =
21068 \newline
21069 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
21070 \newline
21071 (int) 0x00f4 / (int) 0xfffd =
21072 \newline
21073 (int) 0x00f4 / (int) 0xfffd =
21074 \newline
21075 (int) 244 / (int) -3 =
21076 \newline
21077 (int) -81 = (int) 0xffaf;
21078 \layout Standard
21079
21080 Don't complain, that gcc gives you a different result.
21081  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
21082  Therefore the results are different.
21083 \newline
21084 From
21085 \begin_inset Quotes sld
21086 \end_inset
21087
21088 comp.lang.c FAQ
21089 \begin_inset Quotes srd
21090 \end_inset
21091
21092 :
21093 \layout Quote
21094
21095 If well-defined overflow characteristics are important and negative values
21096  are not, or if you want to steer clear of sign-extension problems when
21097  manipulating bits or bytes, use one of the corresponding unsigned types.
21098  (Beware when mixing signed and unsigned values in expressions, though.)
21099 \newline
21100 Although character types (especially unsigned char) can be used as "tiny"
21101  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
21102 ble sign extension and increased code size.
21103 \end_deeper
21104 \layout Itemize
21105
21106 Use unsigned when it is known in advance that the value is not going to
21107  be negative.
21108  This helps especially if you are doing division or multiplication, bit-shifting
21109  or are using an array index.
21110 \layout Itemize
21111
21112 NEVER jump into a LOOP.
21113 \layout Itemize
21114
21115 Declare the variables to be local
21116 \begin_inset LatexCommand \index{local variables}
21117
21118 \end_inset
21119
21120  whenever possible, especially loop control variables (induction).
21121 \layout Itemize
21122
21123 Since the compiler does not always do implicit integral promotion, the programme
21124 r should do an explicit cast when integral promotion is required.
21125 \layout Itemize
21126
21127 Reducing the size of division, multiplication & modulus operations can reduce
21128  code size substantially.
21129  Take the following code for example.
21130 \begin_deeper
21131 \layout Verse
21132
21133
21134 \family typewriter
21135 foobar(unsigned int p1, unsigned char ch)
21136 \newline
21137 {
21138 \newline
21139 \SpecialChar ~
21140 \SpecialChar ~
21141 \SpecialChar ~
21142 \SpecialChar ~
21143 unsigned char ch1 = p1 % ch ;
21144 \newline
21145 \SpecialChar ~
21146 \SpecialChar ~
21147 \SpecialChar ~
21148 \SpecialChar ~
21149 ....
21150 \newline
21151 }
21152 \layout Standard
21153
21154 For the modulus operation the variable ch will be promoted to unsigned int
21155  first then the modulus operation will be performed (this will lead to a
21156  call to support routine _moduint()), and the result will be casted to a
21157  char.
21158  If the code is changed to
21159 \layout Verse
21160
21161
21162 \family typewriter
21163 foobar(unsigned int p1, unsigned char ch)
21164 \newline
21165 {
21166 \newline
21167 \SpecialChar ~
21168 \SpecialChar ~
21169 \SpecialChar ~
21170 \SpecialChar ~
21171 unsigned char ch1 = (unsigned char)p1 % ch ;
21172 \newline
21173 \SpecialChar ~
21174 \SpecialChar ~
21175 \SpecialChar ~
21176 \SpecialChar ~
21177 ....
21178 \newline
21179 }
21180 \layout Standard
21181
21182 It would substantially reduce the code generated (future versions of the
21183  compiler will be smart enough to detect such optimization opportunities).
21184 \end_deeper
21185 \layout Itemize
21186
21187 Have a look at the assembly listing to get a
21188 \begin_inset Quotes sld
21189 \end_inset
21190
21191 feeling
21192 \begin_inset Quotes srd
21193 \end_inset
21194
21195  for the code generation.
21196 \layout Section
21197
21198 Tools
21199 \begin_inset LatexCommand \index{Tools}
21200
21201 \end_inset
21202
21203  included in the distribution
21204 \layout Standard
21205 \align center
21206
21207 \begin_inset  Tabular
21208 <lyxtabular version="3" rows="12" columns="3">
21209 <features>
21210 <column alignment="center" valignment="top" leftline="true" width="0pt">
21211 <column alignment="center" valignment="top" leftline="true" width="0pt">
21212 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21213 <row topline="true" bottomline="true">
21214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21215 \begin_inset Text
21216
21217 \layout Standard
21218
21219 Name
21220 \end_inset
21221 </cell>
21222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21223 \begin_inset Text
21224
21225 \layout Standard
21226
21227 Purpose
21228 \end_inset
21229 </cell>
21230 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21231 \begin_inset Text
21232
21233 \layout Standard
21234
21235 Directory
21236 \end_inset
21237 </cell>
21238 </row>
21239 <row topline="true">
21240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21241 \begin_inset Text
21242
21243 \layout Standard
21244
21245 uCsim
21246 \end_inset
21247 </cell>
21248 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21249 \begin_inset Text
21250
21251 \layout Standard
21252
21253 Simulator for various architectures
21254 \end_inset
21255 </cell>
21256 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21257 \begin_inset Text
21258
21259 \layout Standard
21260
21261 sdcc/sim/ucsim
21262 \end_inset
21263 </cell>
21264 </row>
21265 <row topline="true">
21266 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21267 \begin_inset Text
21268
21269 \layout Standard
21270
21271 keil2sdcc.pl
21272 \end_inset
21273 </cell>
21274 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21275 \begin_inset Text
21276
21277 \layout Standard
21278
21279 header file conversion
21280 \end_inset
21281 </cell>
21282 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21283 \begin_inset Text
21284
21285 \layout Standard
21286
21287 sdcc/support/scripts
21288 \end_inset
21289 </cell>
21290 </row>
21291 <row topline="true">
21292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21293 \begin_inset Text
21294
21295 \layout Standard
21296
21297 mh2h.c
21298 \end_inset
21299 </cell>
21300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21301 \begin_inset Text
21302
21303 \layout Standard
21304
21305 header file conversion
21306 \end_inset
21307 </cell>
21308 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21309 \begin_inset Text
21310
21311 \layout Standard
21312
21313 sdcc/support/scripts
21314 \end_inset
21315 </cell>
21316 </row>
21317 <row topline="true">
21318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21319 \begin_inset Text
21320
21321 \layout Standard
21322
21323 as-gbz80
21324 \end_inset
21325 </cell>
21326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21327 \begin_inset Text
21328
21329 \layout Standard
21330
21331 Assembler
21332 \end_inset
21333 </cell>
21334 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21335 \begin_inset Text
21336
21337 \layout Standard
21338
21339
21340 \family roman
21341 \series medium
21342 \shape up
21343 \size normal
21344 \emph off
21345 \bar no
21346 \noun off
21347 \color none
21348 sdcc/bin
21349 \end_inset
21350 </cell>
21351 </row>
21352 <row topline="true">
21353 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21354 \begin_inset Text
21355
21356 \layout Standard
21357
21358 as-z80
21359 \end_inset
21360 </cell>
21361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21362 \begin_inset Text
21363
21364 \layout Standard
21365
21366 Assembler
21367 \end_inset
21368 </cell>
21369 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21370 \begin_inset Text
21371
21372 \layout Standard
21373
21374
21375 \family roman
21376 \series medium
21377 \shape up
21378 \size normal
21379 \emph off
21380 \bar no
21381 \noun off
21382 \color none
21383 sdcc/bin
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 asx8051
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 Assembler
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
21410 \family roman
21411 \series medium
21412 \shape up
21413 \size normal
21414 \emph off
21415 \bar no
21416 \noun off
21417 \color none
21418 sdcc/bin
21419 \end_inset
21420 </cell>
21421 </row>
21422 <row topline="true">
21423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21424 \begin_inset Text
21425
21426 \layout Standard
21427
21428 sdcdb
21429 \end_inset
21430 </cell>
21431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21432 \begin_inset Text
21433
21434 \layout Standard
21435
21436 Simulator
21437 \end_inset
21438 </cell>
21439 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21440 \begin_inset Text
21441
21442 \layout Standard
21443
21444
21445 \family roman
21446 \series medium
21447 \shape up
21448 \size normal
21449 \emph off
21450 \bar no
21451 \noun off
21452 \color none
21453 sdcc/bin
21454 \end_inset
21455 </cell>
21456 </row>
21457 <row topline="true">
21458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21459 \begin_inset Text
21460
21461 \layout Standard
21462
21463 aslink
21464 \end_inset
21465 </cell>
21466 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21467 \begin_inset Text
21468
21469 \layout Standard
21470
21471 Linker
21472 \end_inset
21473 </cell>
21474 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21475 \begin_inset Text
21476
21477 \layout Standard
21478
21479
21480 \family roman
21481 \series medium
21482 \shape up
21483 \size normal
21484 \emph off
21485 \bar no
21486 \noun off
21487 \color none
21488 sdcc/bin
21489 \end_inset
21490 </cell>
21491 </row>
21492 <row topline="true">
21493 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21494 \begin_inset Text
21495
21496 \layout Standard
21497
21498 link-z80
21499 \end_inset
21500 </cell>
21501 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21502 \begin_inset Text
21503
21504 \layout Standard
21505
21506 Linker
21507 \end_inset
21508 </cell>
21509 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21510 \begin_inset Text
21511
21512 \layout Standard
21513
21514
21515 \family roman
21516 \series medium
21517 \shape up
21518 \size normal
21519 \emph off
21520 \bar no
21521 \noun off
21522 \color none
21523 sdcc/bin
21524 \end_inset
21525 </cell>
21526 </row>
21527 <row topline="true">
21528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21529 \begin_inset Text
21530
21531 \layout Standard
21532
21533 link-gbz80
21534 \end_inset
21535 </cell>
21536 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21537 \begin_inset Text
21538
21539 \layout Standard
21540
21541 Linker
21542 \end_inset
21543 </cell>
21544 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21545 \begin_inset Text
21546
21547 \layout Standard
21548
21549
21550 \family roman
21551 \series medium
21552 \shape up
21553 \size normal
21554 \emph off
21555 \bar no
21556 \noun off
21557 \color none
21558 sdcc/bin
21559 \end_inset
21560 </cell>
21561 </row>
21562 <row topline="true" bottomline="true">
21563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21564 \begin_inset Text
21565
21566 \layout Standard
21567
21568 packihx
21569 \end_inset
21570 </cell>
21571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21572 \begin_inset Text
21573
21574 \layout Standard
21575
21576 ihx packer
21577 \end_inset
21578 </cell>
21579 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21580 \begin_inset Text
21581
21582 \layout Standard
21583
21584
21585 \family roman
21586 \series medium
21587 \shape up
21588 \size normal
21589 \emph off
21590 \bar no
21591 \noun off
21592 \color none
21593 sdcc/bin
21594 \end_inset
21595 </cell>
21596 </row>
21597 </lyxtabular>
21598
21599 \end_inset
21600
21601
21602 \newline
21603
21604 \layout Section
21605
21606 Documentation
21607 \begin_inset LatexCommand \index{Documentation}
21608
21609 \end_inset
21610
21611  included in the distribution
21612 \layout Standard
21613 \align center
21614
21615 \begin_inset  Tabular
21616 <lyxtabular version="3" rows="10" columns="2">
21617 <features>
21618 <column alignment="left" valignment="top" leftline="true" width="0">
21619 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21620 <row topline="true" bottomline="true">
21621 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21622 \begin_inset Text
21623
21624 \layout Standard
21625
21626 Subject / Title
21627 \end_inset
21628 </cell>
21629 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21630 \begin_inset Text
21631
21632 \layout Standard
21633
21634 Where to get / filename
21635 \end_inset
21636 </cell>
21637 </row>
21638 <row topline="true">
21639 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21640 \begin_inset Text
21641
21642 \layout Standard
21643
21644 SDCC Compiler User Guide
21645 \end_inset
21646 </cell>
21647 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21648 \begin_inset Text
21649
21650 \layout Standard
21651
21652 You're reading it right now
21653 \end_inset
21654 </cell>
21655 </row>
21656 <row topline="true">
21657 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21658 \begin_inset Text
21659
21660 \layout Standard
21661
21662 Changelog of SDCC
21663 \end_inset
21664 </cell>
21665 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21666 \begin_inset Text
21667
21668 \layout Standard
21669
21670 sdcc/Changelog
21671 \end_inset
21672 </cell>
21673 </row>
21674 <row topline="true">
21675 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21676 \begin_inset Text
21677
21678 \layout Standard
21679
21680 ASXXXX
21681 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
21682
21683 \end_inset
21684
21685
21686 \begin_inset LatexCommand \index{Assembler documentation}
21687
21688 \end_inset
21689
21690  Assemblers and ASLINK
21691 \begin_inset LatexCommand \index{aslink}
21692
21693 \end_inset
21694
21695
21696 \begin_inset LatexCommand \index{Linker documentation}
21697
21698 \end_inset
21699
21700  Relocating Linker
21701 \end_inset
21702 </cell>
21703 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21704 \begin_inset Text
21705
21706 \layout Standard
21707
21708 sdcc/as/doc/asxhtm.html
21709 \end_inset
21710 </cell>
21711 </row>
21712 <row topline="true">
21713 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21714 \begin_inset Text
21715
21716 \layout Standard
21717
21718 SDCC regression test
21719 \begin_inset LatexCommand \index{Regression test}
21720
21721 \end_inset
21722
21723
21724 \end_inset
21725 </cell>
21726 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21727 \begin_inset Text
21728
21729 \layout Standard
21730
21731 sdcc/doc/test_suite_spec.pdf
21732 \end_inset
21733 </cell>
21734 </row>
21735 <row topline="true">
21736 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21737 \begin_inset Text
21738
21739 \layout Standard
21740
21741 Various notes
21742 \end_inset
21743 </cell>
21744 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21745 \begin_inset Text
21746
21747 \layout Standard
21748
21749 sdcc/doc/*
21750 \end_inset
21751 </cell>
21752 </row>
21753 <row topline="true">
21754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21755 \begin_inset Text
21756
21757 \layout Standard
21758
21759 Notes on debugging with sdcdb
21760 \begin_inset LatexCommand \index{sdcdb (debugger)}
21761
21762 \end_inset
21763
21764
21765 \end_inset
21766 </cell>
21767 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21768 \begin_inset Text
21769
21770 \layout Standard
21771
21772 sdcc/debugger/README
21773 \end_inset
21774 </cell>
21775 </row>
21776 <row topline="true">
21777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21778 \begin_inset Text
21779
21780 \layout Standard
21781
21782 Software simulator for microcontrollers
21783 \end_inset
21784 </cell>
21785 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21786 \begin_inset Text
21787
21788 \layout Standard
21789
21790
21791 \family roman
21792 \series medium
21793 \shape up
21794 \size normal
21795 \emph off
21796 \bar no
21797 \noun off
21798 \color none
21799 sdcc/sim/ucsim/doc
21800 \family default
21801 \series default
21802 \shape default
21803 \size default
21804 \emph default
21805 \bar default
21806 \noun default
21807 \color default
21808 /index.html
21809 \end_inset
21810 </cell>
21811 </row>
21812 <row topline="true">
21813 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21814 \begin_inset Text
21815
21816 \layout Standard
21817
21818 Temporary notes on the pic16
21819 \begin_inset LatexCommand \index{PIC16}
21820
21821 \end_inset
21822
21823  port
21824 \end_inset
21825 </cell>
21826 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21827 \begin_inset Text
21828
21829 \layout Standard
21830
21831 sdcc/src/pic16/NOTES
21832 \end_inset
21833 </cell>
21834 </row>
21835 <row topline="true" bottomline="true">
21836 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21837 \begin_inset Text
21838
21839 \layout Standard
21840
21841 SDCC internal documentation (debugging file format)
21842 \end_inset
21843 </cell>
21844 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21845 \begin_inset Text
21846
21847 \layout Standard
21848
21849 sdcc/doc/
21850 \family roman
21851 \series medium
21852 \shape up
21853 \size normal
21854 \emph off
21855 \bar no
21856 \noun off
21857 \color none
21858 cdbfileformat.pd
21859 \family default
21860 \series default
21861 \shape default
21862 \size default
21863 \emph default
21864 \bar default
21865 \noun default
21866 \color default
21867 f
21868 \end_inset
21869 </cell>
21870 </row>
21871 </lyxtabular>
21872
21873 \end_inset
21874
21875
21876 \newline
21877
21878 \layout Section
21879
21880 Related open source tools
21881 \begin_inset LatexCommand \index{Related tools}
21882
21883 \end_inset
21884
21885
21886 \layout Standard
21887 \align center
21888
21889 \begin_inset  Tabular
21890 <lyxtabular version="3" rows="11" columns="3">
21891 <features>
21892 <column alignment="center" valignment="top" leftline="true" width="0pt">
21893 <column alignment="block" valignment="top" leftline="true" width="30line%">
21894 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21895 <row topline="true" bottomline="true">
21896 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21897 \begin_inset Text
21898
21899 \layout Standard
21900
21901 Name
21902 \end_inset
21903 </cell>
21904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21905 \begin_inset Text
21906
21907 \layout Standard
21908
21909 Purpose
21910 \end_inset
21911 </cell>
21912 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21913 \begin_inset Text
21914
21915 \layout Standard
21916
21917 Where to get
21918 \end_inset
21919 </cell>
21920 </row>
21921 <row topline="true">
21922 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21923 \begin_inset Text
21924
21925 \layout Standard
21926
21927 gpsim
21928 \begin_inset LatexCommand \index{gpsim (pic simulator)}
21929
21930 \end_inset
21931
21932
21933 \end_inset
21934 </cell>
21935 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21936 \begin_inset Text
21937
21938 \layout Standard
21939
21940 PIC simulator
21941 \end_inset
21942 </cell>
21943 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21944 \begin_inset Text
21945
21946 \layout Standard
21947
21948
21949 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
21950
21951 \end_inset
21952
21953
21954 \end_inset
21955 </cell>
21956 </row>
21957 <row topline="true">
21958 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21959 \begin_inset Text
21960
21961 \layout Standard
21962
21963 gputils
21964 \begin_inset LatexCommand \index{gputils (pic tools)}
21965
21966 \end_inset
21967
21968
21969 \end_inset
21970 </cell>
21971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21972 \begin_inset Text
21973
21974 \layout Standard
21975
21976 GNU PIC utilities
21977 \end_inset
21978 </cell>
21979 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21980 \begin_inset Text
21981
21982 \layout Standard
21983
21984
21985 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
21986
21987 \end_inset
21988
21989
21990 \end_inset
21991 </cell>
21992 </row>
21993 <row topline="true">
21994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21995 \begin_inset Text
21996
21997 \layout Standard
21998
21999 flP5
22000 \end_inset
22001 </cell>
22002 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22003 \begin_inset Text
22004
22005 \layout Standard
22006
22007 PIC programmer
22008 \end_inset
22009 </cell>
22010 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22011 \begin_inset Text
22012
22013 \layout Standard
22014
22015
22016 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
22017
22018 \end_inset
22019
22020
22021 \end_inset
22022 </cell>
22023 </row>
22024 <row topline="true">
22025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22026 \begin_inset Text
22027
22028 \layout Standard
22029
22030 indent
22031 \begin_inset LatexCommand \index{indent (source formatting tool)}
22032
22033 \end_inset
22034
22035
22036 \end_inset
22037 </cell>
22038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22039 \begin_inset Text
22040
22041 \layout Standard
22042
22043 Formats C source - Master of the white spaces
22044 \end_inset
22045 </cell>
22046 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22047 \begin_inset Text
22048
22049 \layout Standard
22050
22051
22052 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
22053
22054 \end_inset
22055
22056
22057 \end_inset
22058 </cell>
22059 </row>
22060 <row topline="true">
22061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22062 \begin_inset Text
22063
22064 \layout Standard
22065
22066 srecord
22067 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
22068
22069 \end_inset
22070
22071
22072 \end_inset
22073 </cell>
22074 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22075 \begin_inset Text
22076
22077 \layout Standard
22078
22079 Object file conversion, checksumming, ...
22080 \end_inset
22081 </cell>
22082 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22083 \begin_inset Text
22084
22085 \layout Standard
22086
22087
22088 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
22089
22090 \end_inset
22091
22092
22093 \end_inset
22094 </cell>
22095 </row>
22096 <row topline="true">
22097 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22098 \begin_inset Text
22099
22100 \layout Standard
22101
22102 objdump
22103 \begin_inset LatexCommand \index{objdump (tool)}
22104
22105 \end_inset
22106
22107
22108 \end_inset
22109 </cell>
22110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22111 \begin_inset Text
22112
22113 \layout Standard
22114
22115 Object file conversion, ...
22116 \end_inset
22117 </cell>
22118 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22119 \begin_inset Text
22120
22121 \layout Standard
22122
22123 Part of binutils (should be there anyway)
22124 \end_inset
22125 </cell>
22126 </row>
22127 <row topline="true">
22128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22129 \begin_inset Text
22130
22131 \layout Standard
22132
22133 doxygen
22134 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
22135
22136 \end_inset
22137
22138
22139 \end_inset
22140 </cell>
22141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22142 \begin_inset Text
22143
22144 \layout Standard
22145
22146 Source code documentation system
22147 \end_inset
22148 </cell>
22149 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22150 \begin_inset Text
22151
22152 \layout Standard
22153
22154
22155 \begin_inset LatexCommand \url{http://www.doxygen.org}
22156
22157 \end_inset
22158
22159
22160 \end_inset
22161 </cell>
22162 </row>
22163 <row topline="true">
22164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22165 \begin_inset Text
22166
22167 \layout Standard
22168
22169 kdevelop
22170 \end_inset
22171 </cell>
22172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22173 \begin_inset Text
22174
22175 \layout Standard
22176
22177 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
22178 \end_inset
22179 </cell>
22180 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22181 \begin_inset Text
22182
22183 \layout Standard
22184
22185
22186 \begin_inset LatexCommand \url{http://www.kdevelop.org}
22187
22188 \end_inset
22189
22190
22191 \end_inset
22192 </cell>
22193 </row>
22194 <row topline="true">
22195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22196 \begin_inset Text
22197
22198 \layout Standard
22199
22200 splint
22201 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22202
22203 \end_inset
22204
22205
22206 \end_inset
22207 </cell>
22208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22209 \begin_inset Text
22210
22211 \layout Standard
22212
22213 Statically checks c sources (see
22214 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22215
22216 \end_inset
22217
22218 )
22219 \end_inset
22220 </cell>
22221 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22222 \begin_inset Text
22223
22224 \layout Standard
22225
22226
22227 \begin_inset LatexCommand \url{http://www.splint.org}
22228
22229 \end_inset
22230
22231
22232 \end_inset
22233 </cell>
22234 </row>
22235 <row topline="true" bottomline="true">
22236 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22237 \begin_inset Text
22238
22239 \layout Standard
22240
22241 ddd
22242 \begin_inset LatexCommand \index{ddd (debugger)}
22243
22244 \end_inset
22245
22246
22247 \end_inset
22248 </cell>
22249 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22250 \begin_inset Text
22251
22252 \layout Standard
22253
22254 Debugger, serves nicely as GUI to sdcdb
22255 \begin_inset LatexCommand \index{sdcdb (debugger)}
22256
22257 \end_inset
22258
22259  (Unix only)
22260 \end_inset
22261 </cell>
22262 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22263 \begin_inset Text
22264
22265 \layout Standard
22266
22267
22268 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
22269
22270 \end_inset
22271
22272
22273 \end_inset
22274 </cell>
22275 </row>
22276 </lyxtabular>
22277
22278 \end_inset
22279
22280
22281 \newline
22282
22283 \layout Section
22284
22285 Related documentation / recommended reading
22286 \layout Standard
22287 \align center
22288
22289 \begin_inset  Tabular
22290 <lyxtabular version="3" rows="6" columns="3">
22291 <features>
22292 <column alignment="center" valignment="top" leftline="true" width="0pt">
22293 <column alignment="block" valignment="top" leftline="true" width="30line%">
22294 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
22295 <row topline="true" bottomline="true">
22296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22297 \begin_inset Text
22298
22299 \layout Standard
22300
22301 Name
22302 \end_inset
22303 </cell>
22304 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22305 \begin_inset Text
22306
22307 \layout Standard
22308
22309 Subject / Title
22310 \end_inset
22311 </cell>
22312 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22313 \begin_inset Text
22314
22315 \layout Standard
22316
22317 Where to get
22318 \end_inset
22319 </cell>
22320 </row>
22321 <row topline="true">
22322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22323 \begin_inset Text
22324
22325 \layout Standard
22326
22327
22328 \family roman
22329 \series medium
22330 \shape up
22331 \size normal
22332 \emph off
22333 \bar no
22334 \noun off
22335 \color none
22336 c-refcard.pdf
22337 \end_inset
22338 </cell>
22339 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22340 \begin_inset Text
22341
22342 \layout Standard
22343
22344 C Reference Card
22345 \begin_inset LatexCommand \index{C Reference card}
22346
22347 \end_inset
22348
22349 , 2 pages
22350 \end_inset
22351 </cell>
22352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22353 \begin_inset Text
22354
22355 \layout Standard
22356
22357
22358 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
22359
22360 \end_inset
22361
22362
22363 \end_inset
22364 </cell>
22365 </row>
22366 <row topline="true">
22367 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22368 \begin_inset Text
22369
22370 \layout Standard
22371
22372 c-faq
22373 \end_inset
22374 </cell>
22375 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22376 \begin_inset Text
22377
22378 \layout Standard
22379
22380 C-FAQ-list
22381 \end_inset
22382 </cell>
22383 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22384 \begin_inset Text
22385
22386 \layout Standard
22387
22388
22389 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
22390
22391 \end_inset
22392
22393
22394 \end_inset
22395 </cell>
22396 </row>
22397 <row topline="true">
22398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22399 \begin_inset Text
22400
22401 \layout Standard
22402
22403 \end_inset
22404 </cell>
22405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22406 \begin_inset Text
22407
22408 \layout Standard
22409
22410 Latest datasheet of the target CPU
22411 \end_inset
22412 </cell>
22413 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22414 \begin_inset Text
22415
22416 \layout Standard
22417
22418 vendor
22419 \end_inset
22420 </cell>
22421 </row>
22422 <row topline="true">
22423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22424 \begin_inset Text
22425
22426 \layout Standard
22427
22428 \end_inset
22429 </cell>
22430 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22431 \begin_inset Text
22432
22433 \layout Standard
22434
22435 Revision history of datasheet
22436 \end_inset
22437 </cell>
22438 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22439 \begin_inset Text
22440
22441 \layout Standard
22442
22443 vendor
22444 \end_inset
22445 </cell>
22446 </row>
22447 <row topline="true" bottomline="true">
22448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22449 \begin_inset Text
22450
22451 \layout Standard
22452
22453 S.
22454  S.
22455  Muchnick
22456 \end_inset
22457 </cell>
22458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22459 \begin_inset Text
22460
22461 \layout Standard
22462
22463 Advanced Compiler Design and Implementation
22464 \end_inset
22465 </cell>
22466 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22467 \begin_inset Text
22468
22469 \layout Standard
22470
22471 bookstore (very dedicated, probably read other books first)
22472 \end_inset
22473 </cell>
22474 </row>
22475 </lyxtabular>
22476
22477 \end_inset
22478
22479
22480 \newline
22481
22482 \layout Section
22483
22484 Some Questions
22485 \layout Standard
22486
22487 Some questions answered, some pointers given - it might be time to in turn
22488  ask
22489 \emph on
22490 you
22491 \emph default
22492  some questions:
22493 \layout Itemize
22494
22495 can you solve your project with the selected microcontroller? Would you
22496  find out early or rather late that your target is too small/slow/whatever?
22497  Can you switch to a slightly better device if it doesn't fit?
22498 \layout Itemize
22499
22500 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
22501  and/or another programming language be more adequate? Would an operating
22502  system on the target device help?
22503 \layout Itemize
22504
22505 if you solved the problem, will the marketing department be happy?
22506 \layout Itemize
22507
22508 if the marketing department is happy, will customers be happy?
22509 \layout Itemize
22510
22511 if you're the project manager, marketing department and maybe even the customer
22512  in one person, have you tried to see the project from the outside?
22513 \layout Itemize
22514
22515 is the project done if you think it is done? Or is just that other interface/pro
22516 tocol/feature/configuration/option missing? How about website, manual(s),
22517  internationali(z|s)ation, packaging, labels, 2nd source for components,
22518  electromagnetic compatability/interference, documentation for production,
22519  production test software, update mechanism, patent issues?
22520 \layout Itemize
22521
22522 is your project adequately positioned in that magic triangle: fame, fortune,
22523  fun?
22524 \layout Standard
22525
22526 Maybe not all answers to these questions are known and some answers may
22527  even be
22528 \emph on
22529 no
22530 \emph default
22531 , nevertheless knowing these questions may help you to avoid burnout
22532 \begin_inset Foot
22533 collapsed false
22534
22535 \layout Standard
22536
22537 burnout is bad for electronic devices, programmers and motorcycle tyres
22538 \end_inset
22539
22540 .
22541  Chances are you didn't want to hear some of them...
22542 \layout Chapter
22543
22544 Support
22545 \begin_inset LatexCommand \index{Support}
22546
22547 \end_inset
22548
22549
22550 \layout Standard
22551
22552 SDCC has grown to be a large project.
22553  The compiler alone (without the preprocessor, assembler and linker) is
22554  well over 100,000 lines of code (blank stripped).
22555  The open source nature of this project is a key to its continued growth
22556  and support.
22557  You gain the benefit and support of many active software developers and
22558  end users.
22559  Is SDCC perfect? No, that's why we need your help.
22560  The developers take pride in fixing reported bugs.
22561  You can help by reporting the bugs and helping other SDCC users.
22562  There are lots of ways to contribute, and we encourage you to take part
22563  in making SDCC a great software package.
22564
22565 \layout Standard
22566
22567 The SDCC project is hosted on the SDCC sourceforge site at
22568 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
22569
22570 \end_inset
22571
22572 .
22573  You'll find the complete set of mailing lists
22574 \begin_inset LatexCommand \index{Mailing list(s)}
22575
22576 \end_inset
22577
22578 , forums, bug reporting system, patch submission
22579 \begin_inset LatexCommand \index{Patch submission}
22580
22581 \end_inset
22582
22583  system, download
22584 \begin_inset LatexCommand \index{download}
22585
22586 \end_inset
22587
22588  area and cvs code repository
22589 \begin_inset LatexCommand \index{cvs code repository}
22590
22591 \end_inset
22592
22593  there.
22594 \layout Section
22595
22596 Reporting Bugs
22597 \begin_inset LatexCommand \index{Bug reporting}
22598
22599 \end_inset
22600
22601
22602 \begin_inset LatexCommand \index{Reporting bugs}
22603
22604 \end_inset
22605
22606
22607 \layout Standard
22608
22609 The recommended way of reporting bugs is using the infrastructure of the
22610  sourceforge site.
22611  You can follow the status of bug reports there and have an overview about
22612  the known bugs.
22613 \layout Standard
22614
22615 Bug reports are automatically forwarded to the developer mailing list and
22616  will be fixed ASAP.
22617  When reporting a bug, it is very useful to include a small test program
22618  (the smaller the better) which reproduces the problem.
22619  If you can isolate the problem by looking at the generated assembly code,
22620  this can be very helpful.
22621  Compiling your program with the -
22622 \begin_inset ERT
22623 status Collapsed
22624
22625 \layout Standard
22626
22627 \backslash
22628 /
22629 \end_inset
22630
22631 -dumpall
22632 \begin_inset LatexCommand \index{-\/-dumpall}
22633
22634 \end_inset
22635
22636  option can sometimes be useful in locating optimization problems.
22637  When reporting a bug please maker sure you:
22638 \layout Enumerate
22639
22640 Attach the code you are compiling with SDCC.
22641
22642 \layout Enumerate
22643
22644 Specify the exact command you use to run SDCC, or attach your Makefile.
22645
22646 \layout Enumerate
22647
22648 Specify the SDCC version (type "
22649 \family sans
22650 \series bold
22651 sdcc -v
22652 \family default
22653 \series default
22654 "), your platform, and operating system.
22655
22656 \layout Enumerate
22657
22658 Provide an exact copy of any error message or incorrect output.
22659
22660 \layout Enumerate
22661
22662 Put something meaningful in the subject of your message.
22663 \layout Standard
22664
22665 Please attempt to include these 5 important parts, as applicable, in all
22666  requests for support or when reporting any problems or bugs with SDCC.
22667  Though this will make your message lengthy, it will greatly improve your
22668  chance that SDCC users and developers will be able to help you.
22669  Some SDCC developers are frustrated by bug reports without code provided
22670  that they can use to reproduce and ultimately fix the problem, so please
22671  be sure to provide sample code if you are reporting a bug!
22672 \layout Standard
22673
22674 Please have a short check that you are using a recent version of SDCC and
22675  the bug is not yet known.
22676  This is the link for reporting bugs:
22677 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
22678
22679 \end_inset
22680
22681 .
22682 \layout Section
22683
22684 Requesting Features
22685 \begin_inset LatexCommand \label{sub:Requesting-Features}
22686
22687 \end_inset
22688
22689
22690 \begin_inset LatexCommand \index{Feature request}
22691
22692 \end_inset
22693
22694
22695 \begin_inset LatexCommand \index{Requesting features}
22696
22697 \end_inset
22698
22699
22700 \layout Standard
22701
22702 Like bug reports feature requests are forwarded to the developer mailing
22703  list.
22704  This is the link for requesting features:
22705 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
22706
22707 \end_inset
22708
22709 .
22710 \layout Section
22711
22712 Submitting patches
22713 \layout Standard
22714
22715 Like bug reports contributed patches are forwarded to the developer mailing
22716  list.
22717  This is the link for submitting patches
22718 \begin_inset LatexCommand \index{Patch submission}
22719
22720 \end_inset
22721
22722 :
22723 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
22724
22725 \end_inset
22726
22727 .
22728 \layout Standard
22729
22730 You need to specify some parameters to the
22731 \family typewriter
22732 diff
22733 \family default
22734  command for the patches to be useful.
22735  If you modified more than one file a patch created f.e.
22736  with
22737 \family sans
22738 \series bold
22739
22740 \begin_inset Quotes sld
22741 \end_inset
22742
22743 diff -Naur unmodified_directory modified_directory >my_changes.patch
22744 \begin_inset Quotes srd
22745 \end_inset
22746
22747
22748 \family default
22749 \series default
22750  will be fine, otherwise
22751 \family sans
22752 \series bold
22753
22754 \begin_inset Quotes sld
22755 \end_inset
22756
22757 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
22758 \begin_inset Quotes srd
22759 \end_inset
22760
22761
22762 \series default
22763
22764 \family default
22765 will do.
22766 \layout Section
22767
22768 Getting Help
22769 \layout Standard
22770
22771 These links should take you directly to the
22772 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
22773
22774 \end_inset
22775
22776
22777 \begin_inset Foot
22778 collapsed false
22779
22780 \layout Standard
22781
22782 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
22783  automated messages (mid 2003)
22784 \end_inset
22785
22786  and the
22787 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
22788
22789 \end_inset
22790
22791 , lists
22792 \begin_inset LatexCommand \index{Mailing list(s)}
22793
22794 \end_inset
22795
22796  and forums are archived and searchable so if you are lucky someone already
22797  had a similar problem.
22798  While mails to the lists themselves are delivered promptly their web front
22799  end on sourceforge sometimes shows a severe time lag (up to several weeks),
22800  if you're seriously using SDCC please consider subscribing to the lists.
22801 \layout Section
22802
22803 ChangeLog
22804 \layout Standard
22805
22806 You can follow the status of the cvs version
22807 \begin_inset LatexCommand \index{version}
22808
22809 \end_inset
22810
22811  of SDCC by watching the Changelog
22812 \begin_inset LatexCommand \index{Changelog}
22813
22814 \end_inset
22815
22816  in the cvs-repository
22817 \newline
22818
22819 \size footnotesize
22820
22821 \begin_inset LatexCommand \htmlurl{http://cvs.sf.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
22822
22823 \end_inset
22824
22825 .
22826 \layout Section
22827
22828 Release policy
22829 \begin_inset LatexCommand \index{Release policy}
22830
22831 \end_inset
22832
22833
22834 \layout Standard
22835
22836 Historically there often were long delays between official releases and
22837  the sourceforge download area tends to get not updated at all.
22838  Excuses in the past might have referred to problems with live range analysis,
22839  but as this was fixed a while ago, the current problem is that another
22840  excuse has to be found.
22841  Kidding aside, we have to get better there! On the other hand there are
22842  daily snapshots available at
22843 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
22844
22845 \end_inset
22846
22847 , and you can always build the very last version (hopefully with many bugs
22848  fixed, and features added) from the source code available at
22849 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
22850
22851 \end_inset
22852
22853 .
22854 \layout Section
22855
22856 Examples
22857 \begin_inset LatexCommand \index{Examples}
22858
22859 \end_inset
22860
22861
22862 \layout Standard
22863
22864 You'll find some small examples in the directory
22865 \emph on
22866 sdcc/device/examples/.
22867
22868 \emph default
22869 More examples and libraries are available at
22870 \emph on
22871  The SDCC Open Knowledge Resource
22872 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
22873
22874 \end_inset
22875
22876
22877 \emph default
22878 web site or at
22879 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
22880
22881 \end_inset
22882
22883 .
22884 \layout Comment
22885
22886 I did insert a reference to Paul's web site here although it seems rather
22887  dedicated to a specific 8032 board (I think it's okay because it f.e.
22888  shows LCD/Harddisc interface and has a free 8051 monitor.
22889  Independent 8032 board vendors face hard competition of heavily subsidized
22890  development boards anyway).
22891 \layout Comment
22892
22893 Maybe we should include some links to real world applications.
22894  Preferably pointer to pointers (one for each architecture) so this stays
22895  manageable here?
22896 \layout Section
22897
22898 Quality control
22899 \begin_inset LatexCommand \index{Quality control}
22900
22901 \end_inset
22902
22903
22904 \layout Standard
22905
22906 The compiler is passed through nightly compile and build checks.
22907  The so called
22908 \shape italic
22909 regression tests
22910 \shape default
22911
22912 \begin_inset LatexCommand \index{Regression test}
22913
22914 \end_inset
22915
22916  check that SDCC itself compiles flawlessly on several platforms and checks
22917  the quality of the code generated by SDCC by running the code through simulator
22918 s.
22919  There is a separate document
22920 \shape italic
22921 test_suite.pdf
22922 \begin_inset LatexCommand \index{Test suite}
22923
22924 \end_inset
22925
22926
22927 \shape default
22928  about this.
22929 \layout Standard
22930
22931 You'll find the test code in the directory
22932 \shape italic
22933 sdcc/support/regression
22934 \shape default
22935 .
22936  You can run these tests manually by running
22937 \family sans
22938 make
22939 \family default
22940  in this directory (or f.e.
22941
22942 \family sans
22943 \series bold
22944
22945 \begin_inset Quotes sld
22946 \end_inset
22947
22948 make test-mcs51
22949 \begin_inset Quotes srd
22950 \end_inset
22951
22952
22953 \family default
22954 \series default
22955  if you don't want to run the complete tests).
22956  The test code might also be interesting if you want to look for examples
22957 \begin_inset LatexCommand \index{Examples}
22958
22959 \end_inset
22960
22961  checking corner cases of SDCC or if you plan to submit patches
22962 \begin_inset LatexCommand \index{Patch submission}
22963
22964 \end_inset
22965
22966 .
22967 \layout Standard
22968
22969 The pic port uses a different set of regression tests, you'll find them
22970  in the directory
22971 \shape italic
22972 sdcc/src/regression
22973 \shape default
22974 .
22975 \layout Chapter
22976 \pagebreak_top
22977 SDCC Technical Data
22978 \layout Section
22979
22980 Optimizations
22981 \begin_inset LatexCommand \index{Optimizations}
22982
22983 \end_inset
22984
22985
22986 \layout Standard
22987
22988 SDCC performs a host of standard optimizations in addition to some MCU specific
22989  optimizations.
22990
22991 \layout Subsection
22992
22993 Sub-expression Elimination
22994 \begin_inset LatexCommand \index{Subexpression elimination}
22995
22996 \end_inset
22997
22998
22999 \layout Standard
23000
23001 The compiler does local and
23002 \emph on
23003 g
23004 \emph default
23005 lobal
23006 \emph on
23007 c
23008 \emph default
23009 ommon
23010 \emph on
23011 s
23012 \emph default
23013 ubexpression
23014 \emph on
23015 e
23016 \emph default
23017 limination, e.g.:
23018 \layout Verse
23019
23020
23021 \family typewriter
23022 i = x + y + 1;
23023 \newline
23024 j = x + y;
23025 \layout Standard
23026
23027 will be translated to
23028 \layout Verse
23029
23030
23031 \family typewriter
23032 iTemp = x + y;
23033 \newline
23034 i = iTemp + 1;
23035 \newline
23036 j = iTemp;
23037 \layout Standard
23038
23039 Some subexpressions are not as obvious as the above example, e.g.:
23040 \layout Verse
23041
23042
23043 \family typewriter
23044 a->b[i].c = 10;
23045 \newline
23046 a->b[i].d = 11;
23047 \layout Standard
23048
23049 In this case the address arithmetic a->b[i] will be computed only once;
23050  the equivalent code in C would be.
23051 \layout Verse
23052
23053
23054 \family typewriter
23055 iTemp = a->b[i];
23056 \newline
23057 iTemp.c = 10;
23058 \newline
23059 iTemp.d = 11;
23060 \layout Standard
23061
23062 The compiler will try to keep these temporary variables in registers.
23063 \layout Subsection
23064
23065 Dead-Code Elimination
23066 \begin_inset LatexCommand \index{Dead-code elimination}
23067
23068 \end_inset
23069
23070
23071 \layout Verse
23072
23073
23074 \family typewriter
23075 int global;
23076 \newline
23077
23078 \newline
23079 void f () {
23080 \newline
23081 \SpecialChar ~
23082 \SpecialChar ~
23083 int i;
23084 \newline
23085 \SpecialChar ~
23086 \SpecialChar ~
23087 i = 1; \SpecialChar ~
23088 \SpecialChar ~
23089 \SpecialChar ~
23090 \SpecialChar ~
23091 \SpecialChar ~
23092 /* dead store */
23093 \newline
23094 \SpecialChar ~
23095 \SpecialChar ~
23096 global = 1;\SpecialChar ~
23097 /* dead store */
23098 \newline
23099 \SpecialChar ~
23100 \SpecialChar ~
23101 global = 2;
23102 \newline
23103 \SpecialChar ~
23104 \SpecialChar ~
23105 return;
23106 \newline
23107 \SpecialChar ~
23108 \SpecialChar ~
23109 global = 3;\SpecialChar ~
23110 /* unreachable */
23111 \newline
23112 }
23113 \layout Standard
23114
23115 will be changed to
23116 \layout Verse
23117
23118
23119 \family typewriter
23120 int global;
23121 \newline
23122
23123 \newline
23124 void f () {
23125 \newline
23126 \SpecialChar ~
23127 \SpecialChar ~
23128 global = 2;
23129 \newline
23130 }
23131 \layout Subsection
23132
23133 Copy-Propagation
23134 \begin_inset LatexCommand \index{Copy propagation}
23135
23136 \end_inset
23137
23138
23139 \layout Verse
23140
23141
23142 \family typewriter
23143 int f() {
23144 \newline
23145 \SpecialChar ~
23146 \SpecialChar ~
23147 int i, j;
23148 \newline
23149 \SpecialChar ~
23150 \SpecialChar ~
23151 i = 10;
23152 \newline
23153 \SpecialChar ~
23154 \SpecialChar ~
23155 j = i;
23156 \newline
23157 \SpecialChar ~
23158 \SpecialChar ~
23159 return j;
23160 \newline
23161 }
23162 \layout Standard
23163
23164 will be changed to
23165 \layout Verse
23166
23167
23168 \family typewriter
23169 int f() {
23170 \newline
23171 \SpecialChar ~
23172 \SpecialChar ~
23173 int i, j;
23174 \newline
23175 \SpecialChar ~
23176 \SpecialChar ~
23177 i = 10;
23178 \newline
23179 \SpecialChar ~
23180 \SpecialChar ~
23181 j = 10;
23182 \newline
23183 \SpecialChar ~
23184 \SpecialChar ~
23185 return 10;
23186 \newline
23187 }
23188 \layout Standard
23189
23190 Note: the dead stores created by this copy propagation will be eliminated
23191  by dead-code elimination.
23192 \layout Subsection
23193
23194 Loop Optimizations
23195 \begin_inset LatexCommand \index{Loop optimization}
23196
23197 \end_inset
23198
23199
23200 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
23201
23202 \end_inset
23203
23204
23205 \layout Standard
23206
23207 Two types of loop optimizations are done by SDCC
23208 \emph on
23209 loop invariant
23210 \emph default
23211  lifting and
23212 \emph on
23213  strength reduction
23214 \emph default
23215  of loop induction variables.
23216  In addition to the strength reduction the optimizer marks the induction
23217  variables and the register allocator tries to keep the induction variables
23218  in registers for the duration of the loop.
23219  Because of this preference of the register allocator
23220 \begin_inset LatexCommand \index{Register allocation}
23221
23222 \end_inset
23223
23224 , loop induction optimization causes an increase in register pressure, which
23225  may cause unwanted spilling of other temporary variables into the stack
23226 \begin_inset LatexCommand \index{stack}
23227
23228 \end_inset
23229
23230  / data space.
23231  The compiler will generate a warning message when it is forced to allocate
23232  extra space either on the stack or data space.
23233  If this extra space allocation is undesirable then induction optimization
23234  can be eliminated either for the entire source file (with -
23235 \begin_inset ERT
23236 status Collapsed
23237
23238 \layout Standard
23239
23240 \backslash
23241 /
23242 \end_inset
23243
23244 -noinduction option) or for a given function only using #pragma\SpecialChar ~
23245 noinduction
23246 \begin_inset LatexCommand \index{\#pragma noinduction}
23247
23248 \end_inset
23249
23250 .
23251 \newline
23252
23253 \newline
23254 Loop Invariant:
23255 \layout Verse
23256
23257
23258 \family typewriter
23259 for (i = 0 ; i < 100 ; i ++)
23260 \newline
23261 \SpecialChar ~
23262 \SpecialChar ~
23263 \SpecialChar ~
23264 \SpecialChar ~
23265 f += k + l;
23266 \layout Standard
23267
23268 changed to
23269 \layout Verse
23270
23271
23272 \family typewriter
23273 itemp = k + l;
23274 \newline
23275 for (i = 0; i < 100; i++)
23276 \newline
23277 \SpecialChar ~
23278 \SpecialChar ~
23279 \SpecialChar ~
23280 \SpecialChar ~
23281 f += itemp;
23282 \layout Standard
23283
23284 As mentioned previously some loop invariants are not as apparent, all static
23285  address computations are also moved out of the loop.
23286 \newline
23287
23288 \newline
23289 Strength Reduction
23290 \begin_inset LatexCommand \index{Strength reduction}
23291
23292 \end_inset
23293
23294 , this optimization substitutes an expression by a cheaper expression:
23295 \layout Verse
23296
23297
23298 \family typewriter
23299 for (i=0;i < 100; i++)
23300 \newline
23301 \SpecialChar ~
23302 \SpecialChar ~
23303 \SpecialChar ~
23304 \SpecialChar ~
23305 ar[i*5] = i*3;
23306 \layout Standard
23307
23308 changed to
23309 \layout Verse
23310
23311
23312 \family typewriter
23313 itemp1 = 0;
23314 \newline
23315 itemp2 = 0;
23316 \newline
23317 for (i=0;i< 100;i++) {
23318 \newline
23319 \SpecialChar ~
23320 \SpecialChar ~
23321 \SpecialChar ~
23322 \SpecialChar ~
23323 ar[itemp1] = itemp2;
23324 \newline
23325 \SpecialChar ~
23326 \SpecialChar ~
23327 \SpecialChar ~
23328 \SpecialChar ~
23329 itemp1 += 5;
23330 \newline
23331 \SpecialChar ~
23332 \SpecialChar ~
23333 \SpecialChar ~
23334 \SpecialChar ~
23335 itemp2 += 3;
23336 \newline
23337 }
23338 \layout Standard
23339
23340 The more expensive multiplication
23341 \begin_inset LatexCommand \index{Multiplication}
23342
23343 \end_inset
23344
23345  is changed to a less expensive addition.
23346 \layout Subsection
23347
23348 Loop Reversing
23349 \begin_inset LatexCommand \index{Loop reversing}
23350
23351 \end_inset
23352
23353
23354 \layout Standard
23355
23356 This optimization is done to reduce the overhead of checking loop boundaries
23357  for every iteration.
23358  Some simple loops can be reversed and implemented using a
23359 \begin_inset Quotes eld
23360 \end_inset
23361
23362 decrement and jump if not zero
23363 \begin_inset Quotes erd
23364 \end_inset
23365
23366  instruction.
23367  SDCC checks for the following criterion to determine if a loop is reversible
23368  (note: more sophisticated compilers use data-dependency analysis to make
23369  this determination, SDCC uses a more simple minded analysis).
23370 \layout Itemize
23371
23372 The 'for' loop is of the form
23373 \newline
23374
23375 \newline
23376
23377 \family typewriter
23378 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
23379  += 1])
23380 \newline
23381 \SpecialChar ~
23382 \SpecialChar ~
23383 \SpecialChar ~
23384 \SpecialChar ~
23385 <for body>
23386 \layout Itemize
23387
23388 The <for body> does not contain
23389 \begin_inset Quotes eld
23390 \end_inset
23391
23392 continue
23393 \begin_inset Quotes erd
23394 \end_inset
23395
23396  or 'break
23397 \begin_inset Quotes erd
23398 \end_inset
23399
23400 .
23401 \layout Itemize
23402
23403 All goto's are contained within the loop.
23404 \layout Itemize
23405
23406 No function calls within the loop.
23407 \layout Itemize
23408
23409 The loop control variable <sym> is not assigned any value within the loop
23410 \layout Itemize
23411
23412 The loop control variable does NOT participate in any arithmetic operation
23413  within the loop.
23414 \layout Itemize
23415
23416 There are NO switch statements in the loop.
23417 \layout Subsection
23418
23419 Algebraic Simplifications
23420 \layout Standard
23421
23422 SDCC does numerous algebraic simplifications, the following is a small sub-set
23423  of these optimizations.
23424 \layout Verse
23425
23426
23427 \family typewriter
23428 i = j + 0;\SpecialChar ~
23429 \SpecialChar ~
23430 \SpecialChar ~
23431 \SpecialChar ~
23432  /* changed to: */\SpecialChar ~
23433 \SpecialChar ~
23434 \SpecialChar ~
23435 \SpecialChar ~
23436  i = j;
23437 \newline
23438 i /= 2;\SpecialChar ~
23439 \SpecialChar ~
23440 \SpecialChar ~
23441 \SpecialChar ~
23442 \SpecialChar ~
23443 \SpecialChar ~
23444 \SpecialChar ~
23445  /* changed to: */\SpecialChar ~
23446 \SpecialChar ~
23447 \SpecialChar ~
23448 \SpecialChar ~
23449  i >>= 1;
23450 \newline
23451 i = j - j;\SpecialChar ~
23452 \SpecialChar ~
23453 \SpecialChar ~
23454 \SpecialChar ~
23455  /* changed to: */\SpecialChar ~
23456 \SpecialChar ~
23457 \SpecialChar ~
23458 \SpecialChar ~
23459  i = 0;
23460 \newline
23461 i = j / 1;\SpecialChar ~
23462 \SpecialChar ~
23463 \SpecialChar ~
23464 \SpecialChar ~
23465  /* changed to: */\SpecialChar ~
23466 \SpecialChar ~
23467 \SpecialChar ~
23468 \SpecialChar ~
23469  i = j;
23470 \layout Standard
23471
23472 Note the subexpressions
23473 \begin_inset LatexCommand \index{Subexpression}
23474
23475 \end_inset
23476
23477  given above are generally introduced by macro expansions or as a result
23478  of copy/constant propagation.
23479 \layout Subsection
23480
23481 'switch' Statements
23482 \begin_inset LatexCommand \label{sub:'switch'-Statements}
23483
23484 \end_inset
23485
23486
23487 \begin_inset LatexCommand \index{switch statement}
23488
23489 \end_inset
23490
23491
23492 \layout Standard
23493
23494 SDCC can optimize switch statements to jump tables
23495 \begin_inset LatexCommand \index{jump tables}
23496
23497 \end_inset
23498
23499 .
23500  It makes the decision based on an estimate of the generated code size.
23501  SDCC is quite liberal in the requirements for jump table generation:
23502 \layout Itemize
23503
23504 The labels need not be in order, and the starting number need not be one
23505  or zero, the case labels are in numerical sequence or not too many case
23506  labels are missing.
23507 \begin_deeper
23508 \layout Verse
23509
23510
23511 \family typewriter
23512 switch(i) {\SpecialChar ~
23513 \SpecialChar ~
23514 \SpecialChar ~
23515 \SpecialChar ~
23516 \SpecialChar ~
23517 \SpecialChar ~
23518 \SpecialChar ~
23519 \SpecialChar ~
23520 \SpecialChar ~
23521 \SpecialChar ~
23522 \SpecialChar ~
23523 \SpecialChar ~
23524 \SpecialChar ~
23525 \SpecialChar ~
23526 \SpecialChar ~
23527 \SpecialChar ~
23528 \SpecialChar ~
23529 \SpecialChar ~
23530 \SpecialChar ~
23531 \SpecialChar ~
23532 \SpecialChar ~
23533 \SpecialChar ~
23534 \SpecialChar ~
23535 \SpecialChar ~
23536 \SpecialChar ~
23537 \SpecialChar ~
23538 switch (i) {
23539 \newline
23540 \SpecialChar ~
23541 \SpecialChar ~
23542 \SpecialChar ~
23543 case 4: ...\SpecialChar ~
23544 \SpecialChar ~
23545 \SpecialChar ~
23546 \SpecialChar ~
23547 \SpecialChar ~
23548 \SpecialChar ~
23549 \SpecialChar ~
23550 \SpecialChar ~
23551 \SpecialChar ~
23552 \SpecialChar ~
23553 \SpecialChar ~
23554 \SpecialChar ~
23555 \SpecialChar ~
23556 \SpecialChar ~
23557 \SpecialChar ~
23558 \SpecialChar ~
23559 \SpecialChar ~
23560 \SpecialChar ~
23561 \SpecialChar ~
23562 \SpecialChar ~
23563 \SpecialChar ~
23564 \SpecialChar ~
23565 \SpecialChar ~
23566 \SpecialChar ~
23567 \SpecialChar ~
23568 \SpecialChar ~
23569 case 0: ...
23570
23571 \newline
23572 \SpecialChar ~
23573 \SpecialChar ~
23574 \SpecialChar ~
23575 case 5: ...\SpecialChar ~
23576 \SpecialChar ~
23577 \SpecialChar ~
23578 \SpecialChar ~
23579 \SpecialChar ~
23580 \SpecialChar ~
23581 \SpecialChar ~
23582 \SpecialChar ~
23583 \SpecialChar ~
23584 \SpecialChar ~
23585 \SpecialChar ~
23586 \SpecialChar ~
23587 \SpecialChar ~
23588 \SpecialChar ~
23589 \SpecialChar ~
23590 \SpecialChar ~
23591 \SpecialChar ~
23592 \SpecialChar ~
23593 \SpecialChar ~
23594 \SpecialChar ~
23595 \SpecialChar ~
23596 \SpecialChar ~
23597 \SpecialChar ~
23598 \SpecialChar ~
23599 \SpecialChar ~
23600 \SpecialChar ~
23601 case 1: ...
23602
23603 \newline
23604 \SpecialChar ~
23605 \SpecialChar ~
23606 \SpecialChar ~
23607 case 3: ...\SpecialChar ~
23608 \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
23634 \newline
23635 \SpecialChar ~
23636 \SpecialChar ~
23637 \SpecialChar ~
23638 case 6: ...\SpecialChar ~
23639 \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 case 3: ...
23665
23666 \newline
23667 \SpecialChar ~
23668 \SpecialChar ~
23669 \SpecialChar ~
23670 case 7: ...\SpecialChar ~
23671 \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 case 4: ...
23697
23698 \newline
23699 \SpecialChar ~
23700 \SpecialChar ~
23701 \SpecialChar ~
23702 case 8: ...\SpecialChar ~
23703 \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 case 5: ...
23729
23730 \newline
23731 \SpecialChar ~
23732 \SpecialChar ~
23733 \SpecialChar ~
23734 case 9: ...\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 6: ...
23761
23762 \newline
23763 \SpecialChar ~
23764 \SpecialChar ~
23765 \SpecialChar ~
23766 case 10: ...\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 case 7: ...
23792
23793 \newline
23794 \SpecialChar ~
23795 \SpecialChar ~
23796 \SpecialChar ~
23797 case 11: ...\SpecialChar ~
23798 \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 case 8: ...
23823
23824 \newline
23825 }\SpecialChar ~
23826 \SpecialChar ~
23827 \SpecialChar ~
23828 \SpecialChar ~
23829 \SpecialChar ~
23830 \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 \SpecialChar ~
23857 \SpecialChar ~
23858 \SpecialChar ~
23859 \SpecialChar ~
23860 \SpecialChar ~
23861 }
23862 \layout Standard
23863
23864 Both the above switch statements will be implemented using a jump-table.
23865  The example to the right side is slightly more efficient as the check for
23866  the lower boundary of the jump-table is not needed.
23867 \end_deeper
23868 \layout Itemize
23869
23870 The number of case labels is not larger than supported by the target architectur
23871 e.
23872 \layout Itemize
23873
23874 If the case labels are not in numerical sequence ('gaps' between cases)
23875  SDCC checks whether a jump table with additionally inserted dummy cases
23876  is still attractive.
23877
23878 \layout Itemize
23879
23880 If the starting number is not zero and a check for the lower boundary of
23881  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
23882  ...
23883  .
23884 \layout Standard
23885
23886 Switch statements which have large gaps in the numeric sequence or those
23887  that have too many case labels can be split into more than one switch statement
23888  for efficient code generation, e.g.:
23889 \layout Verse
23890
23891
23892 \family typewriter
23893 switch (i) {
23894 \newline
23895 \SpecialChar ~
23896 \SpecialChar ~
23897 case 1: ...
23898
23899 \newline
23900 \SpecialChar ~
23901 \SpecialChar ~
23902 case 2: ...
23903
23904 \newline
23905 \SpecialChar ~
23906 \SpecialChar ~
23907 case 3: ...
23908
23909 \newline
23910 \SpecialChar ~
23911 \SpecialChar ~
23912 case 4: ...
23913
23914 \newline
23915 \SpecialChar ~
23916 \SpecialChar ~
23917 case 5: ...
23918
23919 \newline
23920 \SpecialChar ~
23921 \SpecialChar ~
23922 case 6: ...
23923
23924 \newline
23925 \SpecialChar ~
23926 \SpecialChar ~
23927 case 7: ...
23928
23929 \newline
23930 \SpecialChar ~
23931 \SpecialChar ~
23932 case 101: ...
23933
23934 \newline
23935 \SpecialChar ~
23936 \SpecialChar ~
23937 case 102: ...
23938
23939 \newline
23940 \SpecialChar ~
23941 \SpecialChar ~
23942 case 103: ...
23943
23944 \newline
23945 \SpecialChar ~
23946 \SpecialChar ~
23947 case 104: ...
23948
23949 \newline
23950 \SpecialChar ~
23951 \SpecialChar ~
23952 case 105: ...
23953
23954 \newline
23955 \SpecialChar ~
23956 \SpecialChar ~
23957 case 106: ...
23958
23959 \newline
23960 \SpecialChar ~
23961 \SpecialChar ~
23962 case 107: ...
23963
23964 \newline
23965 }
23966 \layout Standard
23967
23968 If the above switch statement is broken down into two switch statements
23969 \layout Verse
23970
23971
23972 \family typewriter
23973 switch (i) {
23974 \newline
23975 \SpecialChar ~
23976 \SpecialChar ~
23977 case 1: ...
23978
23979 \newline
23980 \SpecialChar ~
23981 \SpecialChar ~
23982 case 2: ...
23983
23984 \newline
23985 \SpecialChar ~
23986 \SpecialChar ~
23987 case 3: ...
23988
23989 \newline
23990 \SpecialChar ~
23991 \SpecialChar ~
23992 case 4: ...
23993
23994 \newline
23995 \SpecialChar ~
23996 \SpecialChar ~
23997 case 5: ...
23998
23999 \newline
24000 \SpecialChar ~
24001 \SpecialChar ~
24002 case 6: ...
24003
24004 \newline
24005 \SpecialChar ~
24006 \SpecialChar ~
24007 case 7: ...
24008
24009 \newline
24010 }
24011 \layout Standard
24012
24013 and
24014 \layout Verse
24015
24016
24017 \family typewriter
24018 switch (i) {
24019 \newline
24020 \SpecialChar ~
24021 \SpecialChar ~
24022 case 101: ...
24023
24024 \newline
24025 \SpecialChar ~
24026 \SpecialChar ~
24027 case 102: ...
24028
24029 \newline
24030 \SpecialChar ~
24031 \SpecialChar ~
24032 case 103: ...
24033
24034 \newline
24035 \SpecialChar ~
24036 \SpecialChar ~
24037 case 104: ...
24038
24039 \newline
24040 \SpecialChar ~
24041 \SpecialChar ~
24042 case 105: ...
24043
24044 \newline
24045 \SpecialChar ~
24046 \SpecialChar ~
24047 case 106: ...
24048
24049 \newline
24050 \SpecialChar ~
24051 \SpecialChar ~
24052 case 107: ...
24053
24054 \newline
24055 }
24056 \layout Standard
24057
24058 then both the switch statements will be implemented using jump-tables whereas
24059  the unmodified switch statement will not be.
24060 \layout Comment
24061
24062 There might be reasons which SDCC cannot know about to either favour or
24063  not favour jump tables.
24064  If the target system has to be as quick for the last switch case as for
24065  the first (pro jump table), or if the switch argument is known to be zero
24066  in the majority of the cases (contra jump table).
24067 \layout Standard
24068
24069 The pragma nojtbound
24070 \begin_inset LatexCommand \index{\#pragma nojtbound}
24071
24072 \end_inset
24073
24074  can be used to turn off checking the
24075 \emph on
24076 j
24077 \emph default
24078 ump
24079 \emph on
24080 t
24081 \emph default
24082 able
24083 \emph on
24084 bound
24085 \emph default
24086 aries.
24087  It has no effect if a default label is supplied.
24088  Use of this pragma is dangerous: if the switch
24089 \begin_inset LatexCommand \index{switch statement}
24090
24091 \end_inset
24092
24093  argument is not matched by a case statement the processor will happily
24094  jump into Nirvana.
24095 \layout Subsection
24096
24097 Bit-shifting Operations
24098 \begin_inset LatexCommand \index{Bit shifting}
24099
24100 \end_inset
24101
24102 .
24103 \layout Standard
24104
24105 Bit shifting is one of the most frequently used operation in embedded programmin
24106 g.
24107  SDCC tries to implement bit-shift operations in the most efficient way
24108  possible, e.g.:
24109 \layout Verse
24110
24111
24112 \family typewriter
24113 unsigned char i;
24114 \newline
24115 ...
24116
24117 \newline
24118 i >>= 4;
24119 \newline
24120 ...
24121 \layout Standard
24122
24123 generates the following code:
24124 \layout Verse
24125
24126
24127 \family typewriter
24128 mov\SpecialChar ~
24129  a,_i
24130 \newline
24131 swap a
24132 \newline
24133 anl\SpecialChar ~
24134  a,#0x0f
24135 \newline
24136 mov\SpecialChar ~
24137  _i,a
24138 \layout Standard
24139
24140 In general SDCC will never setup a loop if the shift count is known.
24141  Another example:
24142 \layout Verse
24143
24144
24145 \family typewriter
24146 unsigned int i;
24147 \newline
24148 ...
24149
24150 \newline
24151 i >>= 9;
24152 \newline
24153 ...
24154 \layout Standard
24155
24156 will generate:
24157 \layout Verse
24158
24159
24160 \family typewriter
24161 mov\SpecialChar ~
24162 \SpecialChar ~
24163 a,(_i + 1)
24164 \newline
24165 mov\SpecialChar ~
24166 \SpecialChar ~
24167 (_i + 1),#0x00
24168 \newline
24169 clr\SpecialChar ~
24170 \SpecialChar ~
24171 c
24172 \newline
24173 rrc\SpecialChar ~
24174 \SpecialChar ~
24175 a
24176 \newline
24177 mov\SpecialChar ~
24178 \SpecialChar ~
24179 _i,a
24180 \layout Subsection
24181
24182 Bit-rotation
24183 \begin_inset LatexCommand \index{Bit rotation}
24184
24185 \end_inset
24186
24187
24188 \layout Standard
24189
24190 A special case of the bit-shift operation is bit rotation
24191 \begin_inset LatexCommand \index{rotating bits}
24192
24193 \end_inset
24194
24195 , SDCC recognizes the following expression to be a left bit-rotation:
24196 \layout Verse
24197
24198
24199 \family typewriter
24200 \series bold
24201 unsigned
24202 \series default
24203 \SpecialChar ~
24204 \SpecialChar ~
24205 char i;\SpecialChar ~
24206 \SpecialChar ~
24207 \SpecialChar ~
24208 \SpecialChar ~
24209 \SpecialChar ~
24210 \SpecialChar ~
24211 \SpecialChar ~
24212 \SpecialChar ~
24213 \SpecialChar ~
24214 \SpecialChar ~
24215 \SpecialChar ~
24216 /* unsigned is needed for rotation */
24217 \newline
24218 ...
24219
24220 \newline
24221 i = ((i << 1) | (i >> 7));
24222 \family default
24223
24224 \newline
24225
24226 \family typewriter
24227 ...
24228 \layout Standard
24229
24230 will generate the following code:
24231 \layout Verse
24232
24233
24234 \family typewriter
24235 mov\SpecialChar ~
24236 \SpecialChar ~
24237 a,_i
24238 \newline
24239 rl\SpecialChar ~
24240 \SpecialChar ~
24241 \SpecialChar ~
24242 a
24243 \newline
24244 mov\SpecialChar ~
24245 \SpecialChar ~
24246 _i,a
24247 \layout Standard
24248
24249 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
24250 ns of this case will also be recognized as bit-rotation, i.e.:
24251 \layout Verse
24252
24253
24254 \family typewriter
24255 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
24256 \layout Subsection
24257
24258 Nibble and Byte Swapping
24259 \layout Standard
24260
24261 Other special cases of the bit-shift operations are nibble or byte swapping
24262 \begin_inset LatexCommand \index{swapping nibbles/bytes}
24263
24264 \end_inset
24265
24266 , SDCC recognizes the following expressions:
24267 \layout Verse
24268
24269
24270 \family typewriter
24271 \series bold
24272 unsigned
24273 \series default
24274 \SpecialChar ~
24275 \SpecialChar ~
24276 char i;
24277 \newline
24278
24279 \series bold
24280 unsigned
24281 \series default
24282 \SpecialChar ~
24283 \SpecialChar ~
24284 int j;
24285 \newline
24286 ...
24287
24288 \newline
24289 i = ((i << 4) | (i >> 4));
24290 \family default
24291
24292 \newline
24293
24294 \family typewriter
24295 j = ((j << 8) | (j >> 8));
24296 \layout Standard
24297
24298 and generates a swap instruction for the nibble swapping
24299 \begin_inset LatexCommand \index{Nibble swapping}
24300
24301 \end_inset
24302
24303  or move instructions for the byte swapping
24304 \begin_inset LatexCommand \index{Byte swapping}
24305
24306 \end_inset
24307
24308 .
24309  The
24310 \begin_inset Quotes sld
24311 \end_inset
24312
24313 j
24314 \begin_inset Quotes srd
24315 \end_inset
24316
24317  example can be used to convert from little to big-endian or vice versa.
24318  If you want to change the endianness of a
24319 \emph on
24320 signed
24321 \emph default
24322  integer you have to cast to
24323 \family typewriter
24324 (unsigned int)
24325 \family default
24326  first.
24327 \layout Standard
24328
24329 Note that SDCC stores numbers in little-endian
24330 \begin_inset Foot
24331 collapsed false
24332
24333 \layout Standard
24334
24335 Usually 8-bit processors don't care much about endianness.
24336  This is not the case for the standard 8051 which only has an instruction
24337  to increment its
24338 \emph on
24339 dptr
24340 \emph default
24341
24342 \begin_inset LatexCommand \index{DPTR}
24343
24344 \end_inset
24345
24346 -datapointer
24347 \emph on
24348
24349 \emph default
24350 so little-endian is the more efficient byte order.
24351 \end_inset
24352
24353
24354 \begin_inset LatexCommand \index{little-endian}
24355
24356 \end_inset
24357
24358
24359 \begin_inset LatexCommand \index{Endianness}
24360
24361 \end_inset
24362
24363  format (i.e.
24364  lowest order first).
24365 \layout Subsection
24366
24367 Highest Order Bit
24368 \begin_inset LatexCommand \index{Highest Order Bit}
24369
24370 \end_inset
24371
24372
24373 \layout Standard
24374
24375 It is frequently required to obtain the highest order bit of an integral
24376  type (long, int, short or char types).
24377  SDCC recognizes the following expression to yield the highest order bit
24378  and generates optimized code for it, e.g.:
24379 \layout Verse
24380
24381
24382 \family typewriter
24383 unsigned int gint;
24384 \newline
24385
24386 \newline
24387 foo () {
24388 \newline
24389 \SpecialChar ~
24390 \SpecialChar ~
24391 unsigned char hob;
24392 \newline
24393 \SpecialChar ~
24394 \SpecialChar ~
24395 ...
24396
24397 \newline
24398 \SpecialChar ~
24399 \SpecialChar ~
24400 hob = (gint >> 15) & 1;
24401 \newline
24402 \SpecialChar ~
24403 \SpecialChar ~
24404 ..
24405
24406 \newline
24407 }
24408 \layout Standard
24409
24410 will generate the following code:
24411 \layout Verse
24412
24413
24414 \family typewriter
24415 \SpecialChar ~
24416 \SpecialChar ~
24417 \SpecialChar ~
24418 \SpecialChar ~
24419 \SpecialChar ~
24420 \SpecialChar ~
24421 \SpecialChar ~
24422 \SpecialChar ~
24423 \SpecialChar ~
24424 \SpecialChar ~
24425 \SpecialChar ~
24426 \SpecialChar ~
24427 \SpecialChar ~
24428 \SpecialChar ~
24429 \SpecialChar ~
24430 \SpecialChar ~
24431 \SpecialChar ~
24432 \SpecialChar ~
24433 \SpecialChar ~
24434 \SpecialChar ~
24435 \SpecialChar ~
24436 \SpecialChar ~
24437 \SpecialChar ~
24438 \SpecialChar ~
24439 \SpecialChar ~
24440  61 ;\SpecialChar ~
24441  hob.c 7
24442 \newline
24443 000A E5*01\SpecialChar ~
24444 \SpecialChar ~
24445 \SpecialChar ~
24446 \SpecialChar ~
24447 \SpecialChar ~
24448 \SpecialChar ~
24449 \SpecialChar ~
24450 \SpecialChar ~
24451 \SpecialChar ~
24452 \SpecialChar ~
24453 \SpecialChar ~
24454 \SpecialChar ~
24455 \SpecialChar ~
24456 \SpecialChar ~
24457 \SpecialChar ~
24458  62\SpecialChar ~
24459 \SpecialChar ~
24460 \SpecialChar ~
24461 \SpecialChar ~
24462 \SpecialChar ~
24463 \SpecialChar ~
24464 \SpecialChar ~
24465 \SpecialChar ~
24466  mov\SpecialChar ~
24467 \SpecialChar ~
24468  a,(_gint + 1)
24469 \newline
24470 000C 23\SpecialChar ~
24471 \SpecialChar ~
24472 \SpecialChar ~
24473 \SpecialChar ~
24474 \SpecialChar ~
24475 \SpecialChar ~
24476 \SpecialChar ~
24477 \SpecialChar ~
24478 \SpecialChar ~
24479 \SpecialChar ~
24480 \SpecialChar ~
24481 \SpecialChar ~
24482 \SpecialChar ~
24483 \SpecialChar ~
24484 \SpecialChar ~
24485 \SpecialChar ~
24486 \SpecialChar ~
24487 \SpecialChar ~
24488  63\SpecialChar ~
24489 \SpecialChar ~
24490 \SpecialChar ~
24491 \SpecialChar ~
24492 \SpecialChar ~
24493 \SpecialChar ~
24494 \SpecialChar ~
24495 \SpecialChar ~
24496  rl\SpecialChar ~
24497 \SpecialChar ~
24498 \SpecialChar ~
24499  a
24500 \newline
24501 000D 54 01\SpecialChar ~
24502 \SpecialChar ~
24503 \SpecialChar ~
24504 \SpecialChar ~
24505 \SpecialChar ~
24506 \SpecialChar ~
24507 \SpecialChar ~
24508 \SpecialChar ~
24509 \SpecialChar ~
24510 \SpecialChar ~
24511 \SpecialChar ~
24512 \SpecialChar ~
24513 \SpecialChar ~
24514 \SpecialChar ~
24515 \SpecialChar ~
24516  64\SpecialChar ~
24517 \SpecialChar ~
24518 \SpecialChar ~
24519 \SpecialChar ~
24520 \SpecialChar ~
24521 \SpecialChar ~
24522 \SpecialChar ~
24523 \SpecialChar ~
24524  anl\SpecialChar ~
24525 \SpecialChar ~
24526  a,#0x01
24527 \newline
24528 000F F5*02\SpecialChar ~
24529 \SpecialChar ~
24530 \SpecialChar ~
24531 \SpecialChar ~
24532 \SpecialChar ~
24533 \SpecialChar ~
24534 \SpecialChar ~
24535 \SpecialChar ~
24536 \SpecialChar ~
24537 \SpecialChar ~
24538 \SpecialChar ~
24539 \SpecialChar ~
24540 \SpecialChar ~
24541 \SpecialChar ~
24542 \SpecialChar ~
24543  65\SpecialChar ~
24544 \SpecialChar ~
24545 \SpecialChar ~
24546 \SpecialChar ~
24547 \SpecialChar ~
24548 \SpecialChar ~
24549 \SpecialChar ~
24550 \SpecialChar ~
24551  mov\SpecialChar ~
24552 \SpecialChar ~
24553  _foo_hob_1_1,a
24554 \layout Standard
24555
24556 Variations of this case however will
24557 \emph on
24558 not
24559 \emph default
24560  be recognized.
24561  It is a standard C expression, so I heartily recommend this be the only
24562  way to get the highest order bit, (it is portable).
24563  Of course it will be recognized even if it is embedded in other expressions,
24564  e.g.:
24565 \layout Verse
24566
24567
24568 \family typewriter
24569 xyz = gint + ((gint >> 15) & 1);
24570 \layout Standard
24571
24572 will still be recognized.
24573 \layout Subsection
24574
24575 Peephole Optimizer
24576 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
24577
24578 \end_inset
24579
24580
24581 \begin_inset LatexCommand \index{Peephole optimizer}
24582
24583 \end_inset
24584
24585
24586 \layout Standard
24587
24588 The compiler uses a rule based, pattern matching and re-writing mechanism
24589  for peep-hole optimization.
24590  It is inspired by
24591 \emph on
24592 copt
24593 \emph default
24594  a peep-hole optimizer by Christopher W.
24595  Fraser (cwfraser\SpecialChar ~
24596 @\SpecialChar ~
24597 microsoft.com).
24598  A default set of rules are compiled into the compiler, additional rules
24599  may be added with the
24600 \emph on
24601 -
24602 \begin_inset ERT
24603 status Collapsed
24604
24605 \layout Standard
24606
24607 \backslash
24608 /
24609 \end_inset
24610
24611 -peep-file
24612 \begin_inset LatexCommand \index{-\/-peep-file}
24613
24614 \end_inset
24615
24616  <filename>
24617 \emph default
24618  option.
24619  The rule language is best illustrated with examples.
24620 \layout Verse
24621
24622
24623 \family typewriter
24624 replace {
24625 \newline
24626 \SpecialChar ~
24627 \SpecialChar ~
24628 mov %1,a
24629 \newline
24630 \SpecialChar ~
24631 \SpecialChar ~
24632 mov a,%1
24633 \newline
24634 } by {
24635 \newline
24636 \SpecialChar ~
24637 \SpecialChar ~
24638 mov %1,a
24639 \newline
24640 }
24641 \layout Standard
24642
24643 The above rule will change the following assembly
24644 \begin_inset LatexCommand \index{Assembler routines}
24645
24646 \end_inset
24647
24648  sequence:
24649 \layout Verse
24650
24651
24652 \family typewriter
24653 mov r1,a
24654 \newline
24655 mov a,r1
24656 \layout Standard
24657
24658 to
24659 \layout Verse
24660
24661
24662 \family typewriter
24663 mov r1,a
24664 \layout Standard
24665
24666 Note: All occurrences of a
24667 \emph on
24668 %n
24669 \emph default
24670  (pattern variable) must denote the same string.
24671  With the above rule, the assembly sequence:
24672 \layout Verse
24673
24674
24675 \family typewriter
24676 mov r1,a
24677 \newline
24678 mov a,r2
24679 \layout Standard
24680
24681 will remain unmodified.
24682 \newline
24683
24684 \newline
24685 Other special case optimizations may be added by the user (via
24686 \emph on
24687 -
24688 \begin_inset ERT
24689 status Collapsed
24690
24691 \layout Standard
24692
24693 \backslash
24694 /
24695 \end_inset
24696
24697 -peep-file option
24698 \emph default
24699 ).
24700  E.g.
24701  some variants of the 8051 MCU
24702 \begin_inset LatexCommand \index{MCS51 variants}
24703
24704 \end_inset
24705
24706  allow only
24707 \family typewriter
24708 ajmp
24709 \family default
24710  and
24711 \family typewriter
24712 acall
24713 \family default
24714 .
24715  The following two rules will change all
24716 \family typewriter
24717 ljmp
24718 \family default
24719  and
24720 \family typewriter
24721 lcall
24722 \family default
24723  to
24724 \family typewriter
24725 ajmp
24726 \family default
24727  and
24728 \family typewriter
24729 acall
24730 \layout Verse
24731
24732
24733 \family typewriter
24734 replace { lcall %1 } by { acall %1 }
24735 \newline
24736 replace { ljmp %1 } by { ajmp %1 }
24737 \layout Standard
24738
24739 The
24740 \emph on
24741 inline-assembler code
24742 \emph default
24743  is also passed through the peep hole optimizer, thus the peephole optimizer
24744  can also be used as an assembly level macro expander.
24745  The rules themselves are MCU dependent whereas the rule language infra-structur
24746 e is MCU independent.
24747  Peephole optimization rules for other MCU can be easily programmed using
24748  the rule language.
24749 \newline
24750
24751 \newline
24752 The syntax for a rule is as follows:
24753 \layout Verse
24754
24755
24756 \family typewriter
24757 rule := replace [ restart ] '{' <assembly sequence> '
24758 \backslash
24759 n'
24760 \newline
24761 \SpecialChar ~
24762  \SpecialChar ~
24763  \SpecialChar ~
24764  \SpecialChar ~
24765  \SpecialChar ~
24766  \SpecialChar ~
24767  \SpecialChar ~
24768  \SpecialChar ~
24769  \SpecialChar ~
24770  \SpecialChar ~
24771  \SpecialChar ~
24772  \SpecialChar ~
24773  \SpecialChar ~
24774  \SpecialChar ~
24775  '}' by '{' '
24776 \backslash
24777 n'
24778 \newline
24779 \SpecialChar ~
24780  \SpecialChar ~
24781  \SpecialChar ~
24782  \SpecialChar ~
24783  \SpecialChar ~
24784  \SpecialChar ~
24785  \SpecialChar ~
24786  \SpecialChar ~
24787  \SpecialChar ~
24788  \SpecialChar ~
24789  \SpecialChar ~
24790  \SpecialChar ~
24791  \SpecialChar ~
24792  \SpecialChar ~
24793  \SpecialChar ~
24794  \SpecialChar ~
24795  <assembly sequence> '
24796 \backslash
24797 n'
24798 \newline
24799 \SpecialChar ~
24800  \SpecialChar ~
24801  \SpecialChar ~
24802  \SpecialChar ~
24803  \SpecialChar ~
24804  \SpecialChar ~
24805  \SpecialChar ~
24806  \SpecialChar ~
24807  \SpecialChar ~
24808  \SpecialChar ~
24809  \SpecialChar ~
24810  \SpecialChar ~
24811  \SpecialChar ~
24812  \SpecialChar ~
24813  '}' [if <functionName> ] '
24814 \backslash
24815 n'
24816 \layout Standard
24817
24818 <assembly sequence> := assembly instruction (each instruction including
24819  labels must be on a separate line).
24820 \newline
24821
24822 \newline
24823 The optimizer will apply to the rules one by one from the top in the sequence
24824  of their appearance, it will terminate when all rules are exhausted.
24825  If the 'restart' option is specified, then the optimizer will start matching
24826  the rules again from the top, this option for a rule is expensive (performance)
24827 , it is intended to be used in situations where a transformation will trigger
24828  the same rule again.
24829  An example of this (not a good one, it has side effects) is the following
24830  rule:
24831 \layout Verse
24832
24833
24834 \family typewriter
24835 replace restart {
24836 \newline
24837 \SpecialChar ~
24838 \SpecialChar ~
24839 pop %1
24840 \newline
24841 \SpecialChar ~
24842 \SpecialChar ~
24843 push %1 } by {
24844 \newline
24845 \SpecialChar ~
24846 \SpecialChar ~
24847 ; nop
24848 \newline
24849 }
24850 \layout Standard
24851
24852 Note that the replace pattern cannot be a blank, but can be a comment line.
24853  Without the 'restart' option only the innermost 'pop' 'push' pair would
24854  be eliminated, i.e.:
24855 \layout Verse
24856
24857
24858 \family typewriter
24859 pop ar1
24860 \newline
24861 pop ar2
24862 \newline
24863 push ar2
24864 \newline
24865 push ar1
24866 \layout Standard
24867
24868 would result in:
24869 \layout Verse
24870
24871
24872 \family typewriter
24873 pop ar1
24874 \newline
24875 ; nop
24876 \newline
24877 push ar1
24878 \layout Standard
24879
24880
24881 \emph on
24882 with
24883 \emph default
24884  the restart option the rule will be applied again to the resulting code
24885  and then all the pop-push pairs will be eliminated to yield:
24886 \layout Verse
24887
24888
24889 \family typewriter
24890 ; nop
24891 \newline
24892 ; nop
24893 \layout Standard
24894
24895 A conditional function can be attached to a rule.
24896  Attaching rules are somewhat more involved, let me illustrate this with
24897  an example.
24898 \layout Verse
24899
24900
24901 \family typewriter
24902 replace {
24903 \newline
24904 \SpecialChar ~
24905  \SpecialChar ~
24906  \SpecialChar ~
24907 ljmp %5
24908 \newline
24909 %2:
24910 \newline
24911 } by {
24912 \newline
24913 \SpecialChar ~
24914  \SpecialChar ~
24915  \SpecialChar ~
24916 sjmp %5
24917 \newline
24918 %2:
24919 \newline
24920 } if labelInRange
24921 \layout Standard
24922
24923 The optimizer does a look-up of a function name table defined in function
24924
24925 \emph on
24926 callFuncByName
24927 \emph default
24928  in the source file SDCCpeeph.c, with the name
24929 \emph on
24930 labelInRange
24931 \emph default
24932 .
24933  If it finds a corresponding entry the function is called.
24934  Note there can be no parameters specified for these functions, in this
24935  case the use of
24936 \emph on
24937 %5
24938 \emph default
24939  is crucial, since the function
24940 \emph on
24941 labelInRange
24942 \emph default
24943  expects to find the label in that particular variable (the hash table containin
24944 g the variable bindings is passed as a parameter).
24945  If you want to code more such functions, take a close look at the function
24946  labelInRange and the calling mechanism in source file SDCCpeeph.c.
24947  Currently implemented are
24948 \emph on
24949 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
24950  24bitMode, portIsDS390, 24bitModeAndPortDS390
24951 \emph default
24952 and
24953 \emph on
24954  notVolatile
24955 \emph default
24956 .
24957 \layout Standard
24958
24959 I know this whole thing is a little kludgey, but maybe some day we will
24960  have some better means.
24961  If you are looking at this file, you will see the default rules that are
24962  compiled into the compiler, you can add your own rules in the default set
24963  there if you get tired of specifying the -
24964 \begin_inset ERT
24965 status Collapsed
24966
24967 \layout Standard
24968
24969 \backslash
24970 /
24971 \end_inset
24972
24973 -peep-file option.
24974 \layout Section
24975
24976 ANSI-Compliance
24977 \begin_inset LatexCommand \index{ANSI-compliance}
24978
24979 \end_inset
24980
24981
24982 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
24983
24984 \end_inset
24985
24986
24987 \layout Standard
24988
24989 Deviations from the compliance:
24990 \layout Itemize
24991
24992 functions are not reentrant
24993 \begin_inset LatexCommand \index{reentrant}
24994
24995 \end_inset
24996
24997  unless explicitly declared as such or the
24998 \series bold
24999 -
25000 \begin_inset ERT
25001 status Collapsed
25002
25003 \layout Standard
25004
25005 \backslash
25006 /
25007 \end_inset
25008
25009 -stack-auto
25010 \begin_inset LatexCommand \index{-\/-stack-auto}
25011
25012 \end_inset
25013
25014
25015 \series default
25016  command line option is specified.
25017 \layout Itemize
25018
25019 structures and unions cannot be assigned values directly, cannot be passed
25020  as function parameters or assigned to each other and cannot be a return
25021  value from a function, e.g.:
25022 \begin_deeper
25023 \layout Verse
25024
25025
25026 \family typewriter
25027 struct s { ...
25028  };
25029 \newline
25030 struct s s1, s2;
25031 \newline
25032 foo()
25033 \newline
25034 {
25035 \newline
25036 \SpecialChar ~
25037 \SpecialChar ~
25038 \SpecialChar ~
25039 \SpecialChar ~
25040 ...
25041
25042 \newline
25043 \SpecialChar ~
25044 \SpecialChar ~
25045 \SpecialChar ~
25046 \SpecialChar ~
25047 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
25048 \newline
25049 \SpecialChar ~
25050 \SpecialChar ~
25051 \SpecialChar ~
25052 \SpecialChar ~
25053 ...
25054
25055 \newline
25056 }
25057 \newline
25058 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
25059  */
25060 \newline
25061 {
25062 \newline
25063 \SpecialChar ~
25064 \SpecialChar ~
25065 \SpecialChar ~
25066 \SpecialChar ~
25067 struct s rets;
25068 \newline
25069 \SpecialChar ~
25070 \SpecialChar ~
25071 \SpecialChar ~
25072 \SpecialChar ~
25073 ...
25074
25075 \newline
25076 \SpecialChar ~
25077 \SpecialChar ~
25078 \SpecialChar ~
25079 \SpecialChar ~
25080 return rets;/* is invalid in SDCC although allowed in ANSI */
25081 \newline
25082 }
25083 \end_deeper
25084 \layout Itemize
25085
25086 'long long
25087 \begin_inset LatexCommand \index{long long (not supported)}
25088
25089 \end_inset
25090
25091 ' (64 bit integers
25092 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
25093
25094 \end_inset
25095
25096 ) not supported.
25097 \layout Itemize
25098
25099 'double
25100 \begin_inset LatexCommand \index{double (not supported)}
25101
25102 \end_inset
25103
25104 ' precision floating point
25105 \begin_inset LatexCommand \index{Floating point support}
25106
25107 \end_inset
25108
25109 not supported.
25110 \layout Itemize
25111
25112 No support for setjmp
25113 \begin_inset LatexCommand \index{setjmp (not supported)}
25114
25115 \end_inset
25116
25117  and longjmp
25118 \begin_inset LatexCommand \index{longjmp (not supported)}
25119
25120 \end_inset
25121
25122  (for now).
25123 \layout Itemize
25124
25125 Old K&R style
25126 \begin_inset LatexCommand \index{K\&R style}
25127
25128 \end_inset
25129
25130  function declarations are NOT allowed.
25131 \begin_deeper
25132 \layout Verse
25133
25134
25135 \family typewriter
25136 foo(i,j) /* this old style of function declarations */
25137 \newline
25138 int i,j; /* are valid in ANSI but not valid in SDCC */
25139 \newline
25140 {
25141 \newline
25142 \SpecialChar ~
25143 \SpecialChar ~
25144 \SpecialChar ~
25145 \SpecialChar ~
25146 ...
25147
25148 \newline
25149 }
25150 \end_deeper
25151 \layout Itemize
25152
25153 Certain words that are valid identifiers in the standard may be reserved
25154  words in SDCC unless the
25155 \series bold
25156 -
25157 \begin_inset ERT
25158 status Collapsed
25159
25160 \layout Standard
25161
25162 \backslash
25163 /
25164 \end_inset
25165
25166 -std-c89
25167 \begin_inset LatexCommand \index{-\/-std-c89}
25168
25169 \end_inset
25170
25171  or -
25172 \begin_inset ERT
25173 status Collapsed
25174
25175 \layout Standard
25176
25177 \backslash
25178 /
25179 \end_inset
25180
25181 -std-c99
25182 \begin_inset LatexCommand \index{-\/-std-c99}
25183
25184 \end_inset
25185
25186
25187 \series default
25188  command line options are used.
25189  These may include (depending on the selected processor): 'at', 'banked',
25190  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
25191 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
25192  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
25193  '_naked'.
25194  Compliant equivalents of these keywords are always available in a form
25195  that begin with two underscores
25196 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
25197
25198 \end_inset
25199
25200 , f.e.
25201  '__data' instead of 'data'.
25202 \layout Section
25203
25204 Cyclomatic Complexity
25205 \begin_inset LatexCommand \index{Cyclomatic complexity}
25206
25207 \end_inset
25208
25209
25210 \layout Standard
25211
25212 Cyclomatic complexity of a function is defined as the number of independent
25213  paths the program can take during execution of the function.
25214  This is an important number since it defines the number test cases you
25215  have to generate to validate the function.
25216  The accepted industry standard for complexity number is 10, if the cyclomatic
25217  complexity reported by SDCC exceeds 10 you should think about simplification
25218  of the function logic.
25219  Note that the complexity level is not related to the number of lines of
25220  code in a function.
25221  Large functions can have low complexity, and small functions can have large
25222  complexity levels.
25223
25224 \newline
25225
25226 \newline
25227 SDCC uses the following formula to compute the complexity:
25228 \newline
25229
25230 \layout Standard
25231
25232 complexity = (number of edges in control flow graph) - (number of nodes
25233  in control flow graph) + 2;
25234 \newline
25235
25236 \newline
25237 Having said that the industry standard is 10, you should be aware that in
25238  some cases it be may unavoidable to have a complexity level of less than
25239  10.
25240  For example if you have switch statement with more than 10 case labels,
25241  each case label adds one to the complexity level.
25242  The complexity level is by no means an absolute measure of the algorithmic
25243  complexity of the function, it does however provide a good starting point
25244  for which functions you might look at for further optimization.
25245 \layout Section
25246
25247 Retargetting for other Processors
25248 \layout Standard
25249
25250 The issues for retargetting the compiler are far too numerous to be covered
25251  by this document.
25252  What follows is a brief description of each of the seven phases of the
25253  compiler and its MCU dependency.
25254 \layout Itemize
25255
25256 Parsing the source and building the annotated parse tree.
25257  This phase is largely MCU independent (except for the language extensions).
25258  Syntax & semantic checks are also done in this phase, along with some initial
25259  optimizations like back patching labels and the pattern matching optimizations
25260  like bit-rotation etc.
25261 \layout Itemize
25262
25263 The second phase involves generating an intermediate code which can be easy
25264  manipulated during the later phases.
25265  This phase is entirely MCU independent.
25266  The intermediate code generation assumes the target machine has unlimited
25267  number of registers, and designates them with the name iTemp.
25268  The compiler can be made to dump a human readable form of the code generated
25269  by using the -
25270 \begin_inset ERT
25271 status Collapsed
25272
25273 \layout Standard
25274
25275 \backslash
25276 /
25277 \end_inset
25278
25279 -dumpraw option.
25280 \layout Itemize
25281
25282 This phase does the bulk of the standard optimizations and is also MCU independe
25283 nt.
25284  This phase can be broken down into several sub-phases:
25285 \newline
25286
25287 \newline
25288 Break down intermediate code (iCode) into basic blocks.
25289 \newline
25290 Do control flow & data flow analysis on the basic blocks.
25291 \newline
25292 Do local common subexpression elimination, then global subexpression elimination
25293 \newline
25294 Dead code elimination
25295 \newline
25296 Loop optimizations
25297 \newline
25298 If loop optimizations caused any changes then do 'global subexpression eliminati
25299 on' and 'dead code elimination' again.
25300 \layout Itemize
25301
25302 This phase determines the live-ranges; by live range I mean those iTemp
25303  variables defined by the compiler that still survive after all the optimization
25304 s.
25305  Live range analysis
25306 \begin_inset LatexCommand \index{Live range analysis}
25307
25308 \end_inset
25309
25310  is essential for register allocation, since these computation determines
25311  which of these iTemps will be assigned to registers, and for how long.
25312 \layout Itemize
25313
25314 Phase five is register allocation.
25315  There are two parts to this process.
25316 \newline
25317
25318 \newline
25319 The first part I call 'register packing' (for lack of a better term).
25320  In this case several MCU specific expression folding is done to reduce
25321  register pressure.
25322 \newline
25323
25324 \newline
25325 The second part is more MCU independent and deals with allocating registers
25326  to the remaining live ranges.
25327  A lot of MCU specific code does creep into this phase because of the limited
25328  number of index registers available in the 8051.
25329 \layout Itemize
25330
25331 The Code generation phase is (unhappily), entirely MCU dependent and very
25332  little (if any at all) of this code can be reused for other MCU.
25333  However the scheme for allocating a homogenized assembler operand for each
25334  iCode operand may be reused.
25335 \layout Itemize
25336
25337 As mentioned in the optimization section the peep-hole optimizer is rule
25338  based system, which can reprogrammed for other MCUs.
25339 \layout Chapter
25340
25341 Compiler internals
25342 \begin_inset LatexCommand \index{Compiler internals}
25343
25344 \end_inset
25345
25346
25347 \layout Section
25348
25349 The anatomy of the compiler
25350 \begin_inset LatexCommand \label{sub:The-anatomy-of}
25351
25352 \end_inset
25353
25354
25355 \layout Standard
25356
25357
25358 \shape italic
25359 This is an excerpt from an article published in Circuit Cellar Magazine
25360  in
25361 \series bold
25362 August 2000
25363 \series default
25364 .
25365  It's a little outdated (the compiler is much more efficient now and user/develo
25366 per friendly), but pretty well exposes the guts of it all.
25367 \shape default
25368
25369 \newline
25370
25371 \newline
25372 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
25373  It is fairly easy to retarget for other 8-bit MCU.
25374  Here we take a look at some of the internals of the compiler.
25375
25376 \layout Paragraph*
25377
25378 Parsing
25379 \begin_inset LatexCommand \index{Parsing}
25380
25381 \end_inset
25382
25383
25384 \layout Standard
25385
25386 Parsing the input source file and creating an AST (Annotated Syntax Tree
25387 \begin_inset LatexCommand \index{Annotated syntax tree}
25388
25389 \end_inset
25390
25391 ).
25392  This phase also involves propagating types (annotating each node of the
25393  parse tree with type information) and semantic analysis.
25394  There are some MCU specific parsing rules.
25395  For example the storage classes, the extended storage classes are MCU specific
25396  while there may be a xdata storage class for 8051 there is no such storage
25397  class for z80 or Atmel AVR.
25398  SDCC allows MCU specific storage class extensions, i.e.
25399  xdata will be treated as a storage class specifier when parsing 8051 C
25400  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
25401  C code.
25402 \layout Paragraph*
25403
25404 Generating iCode
25405 \begin_inset LatexCommand \index{iCode}
25406
25407 \end_inset
25408
25409
25410 \layout Standard
25411
25412 Intermediate code generation.
25413  In this phase the AST is broken down into three-operand form (iCode).
25414  These three operand forms are represented as doubly linked lists.
25415  ICode is the term given to the intermediate form generated by the compiler.
25416  ICode example section shows some examples of iCode generated for some simple
25417  C source functions.
25418 \layout Paragraph*
25419
25420 Optimizations
25421 \begin_inset LatexCommand \index{Optimizations}
25422
25423 \end_inset
25424
25425 .
25426 \layout Standard
25427
25428 Bulk of the target independent optimizations is performed in this phase.
25429  The optimizations include constant propagation, common sub-expression eliminati
25430 on, loop invariant code movement, strength reduction of loop induction variables
25431  and dead-code elimination.
25432 \layout Paragraph*
25433
25434 Live range analysis
25435 \begin_inset LatexCommand \index{Live range analysis}
25436
25437 \end_inset
25438
25439
25440 \layout Standard
25441
25442 During intermediate code generation phase, the compiler assumes the target
25443  machine has infinite number of registers and generates a lot of temporary
25444  variables.
25445  The live range computation determines the lifetime of each of these compiler-ge
25446 nerated temporaries.
25447  A picture speaks a thousand words.
25448  ICode example sections show the live range annotations for each of the
25449  operand.
25450  It is important to note here, each iCode is assigned a number in the order
25451  of its execution in the function.
25452  The live ranges are computed in terms of these numbers.
25453  The from number is the number of the iCode which first defines the operand
25454  and the to number signifies the iCode which uses this operand last.
25455 \layout Paragraph*
25456
25457 Register Allocation
25458 \begin_inset LatexCommand \index{Register allocation}
25459
25460 \end_inset
25461
25462
25463 \layout Standard
25464
25465 The register allocation determines the type and number of registers needed
25466  by each operand.
25467  In most MCUs only a few registers can be used for indirect addressing.
25468  In case of 8051 for example the registers R0 & R1 can be used to indirectly
25469  address the internal ram and DPTR to indirectly address the external ram.
25470  The compiler will try to allocate the appropriate register to pointer variables
25471  if it can.
25472  ICode example section shows the operands annotated with the registers assigned
25473  to them.
25474  The compiler will try to keep operands in registers as much as possible;
25475  there are several schemes the compiler uses to do achieve this.
25476  When the compiler runs out of registers the compiler will check to see
25477  if there are any live operands which is not used or defined in the current
25478  basic block being processed, if there are any found then it will push that
25479  operand and use the registers in this block, the operand will then be popped
25480  at the end of the basic block.
25481
25482 \layout Standard
25483
25484 There are other MCU specific considerations in this phase.
25485  Some MCUs have an accumulator; very short-lived operands could be assigned
25486  to the accumulator instead of a general-purpose register.
25487 \layout Paragraph*
25488
25489 Code generation
25490 \layout Standard
25491
25492 Figure II gives a table of iCode operations supported by the compiler.
25493  The code generation involves translating these operations into corresponding
25494  assembly code for the processor.
25495  This sounds overly simple but that is the essence of code generation.
25496  Some of the iCode operations are generated on a MCU specific manner for
25497  example, the z80 port does not use registers to pass parameters so the
25498  SEND and RECV iCode operations will not be generated, and it also does
25499  not support JUMPTABLES.
25500
25501 \newline
25502
25503 \series bold
25504 \shape italic
25505 \color red
25506 <Where is Figure II?>
25507 \layout Comment
25508
25509 In the original article Figure II was announced to be downloadable on
25510 \shape italic
25511 Circuit Cellar
25512 \shape default
25513 's web site.
25514  Unfortunately it never seemed to have shown up there, so: where is Figure
25515  II?
25516 \layout Paragraph*
25517
25518 ICode Example
25519 \begin_inset LatexCommand \index{iCode}
25520
25521 \end_inset
25522
25523
25524 \layout Standard
25525
25526 This section shows some details of iCode.
25527  The example C code does not do anything useful; it is used as an example
25528  to illustrate the intermediate code generated by the compiler.
25529 \layout Verse
25530
25531
25532 \family typewriter
25533 1.\SpecialChar ~
25534 xdata int * p;
25535 \newline
25536 2.\SpecialChar ~
25537 int gint;
25538 \newline
25539 3.\SpecialChar ~
25540 /* This function does nothing useful.
25541  It is used
25542 \newline
25543 4.\SpecialChar ~
25544 \SpecialChar ~
25545 \SpecialChar ~
25546 \SpecialChar ~
25547 for the purpose of explaining iCode */
25548 \newline
25549 5.\SpecialChar ~
25550 short function (data int *x)
25551 \newline
25552 6.\SpecialChar ~
25553 {
25554 \newline
25555 7.\SpecialChar ~
25556 \SpecialChar ~
25557 \SpecialChar ~
25558 short i=10; \SpecialChar ~
25559 \SpecialChar ~
25560 /* dead initialization eliminated */
25561 \newline
25562 8.\SpecialChar ~
25563 \SpecialChar ~
25564 \SpecialChar ~
25565 short sum=10; /* dead initialization eliminated */
25566 \newline
25567 9.\SpecialChar ~
25568 \SpecialChar ~
25569 \SpecialChar ~
25570 short mul;
25571 \newline
25572 10.\SpecialChar ~
25573 \SpecialChar ~
25574 int j ;
25575 \newline
25576 11.\SpecialChar ~
25577 \SpecialChar ~
25578 while (*x) *x++ = *p++;
25579 \newline
25580 12.\SpecialChar ~
25581 \SpecialChar ~
25582 \SpecialChar ~
25583 \SpecialChar ~
25584 sum = 0 ;
25585 \newline
25586 13.\SpecialChar ~
25587 \SpecialChar ~
25588 mul = 0;
25589 \newline
25590 14.\SpecialChar ~
25591 \SpecialChar ~
25592 /* compiler detects i,j to be induction variables */
25593 \newline
25594 15.\SpecialChar ~
25595 \SpecialChar ~
25596 for (i = 0, j = 10 ; i < 10 ; i++, j
25597 \family default
25598 -
25599 \begin_inset ERT
25600 status Collapsed
25601
25602 \layout Standard
25603
25604 \backslash
25605 /
25606 \end_inset
25607
25608 -
25609 \family typewriter
25610 ) {
25611 \newline
25612 16.\SpecialChar ~
25613 \SpecialChar ~
25614 \SpecialChar ~
25615 \SpecialChar ~
25616 sum += i;
25617 \newline
25618 17.\SpecialChar ~
25619 \SpecialChar ~
25620 \SpecialChar ~
25621 \SpecialChar ~
25622 mul += i * 3; \SpecialChar ~
25623 \SpecialChar ~
25624 /* this multiplication remains */
25625 \newline
25626 18.\SpecialChar ~
25627 \SpecialChar ~
25628 \SpecialChar ~
25629 \SpecialChar ~
25630 gint += j * 3;\SpecialChar ~
25631 \SpecialChar ~
25632 /* this multiplication changed to addition */
25633 \newline
25634 19.\SpecialChar ~
25635 \SpecialChar ~
25636 }
25637 \newline
25638 20.\SpecialChar ~
25639 \SpecialChar ~
25640 return sum+mul;
25641 \newline
25642 21.\SpecialChar ~
25643 }
25644 \layout Standard
25645
25646 In addition to the operands each iCode contains information about the filename
25647  and line it corresponds to in the source file.
25648  The first field in the listing should be interpreted as follows:
25649 \newline
25650
25651 \shape italic
25652 \size footnotesize
25653 Filename(linenumber: iCode Execution sequence number : ICode hash table
25654  key : loop depth of the iCode).
25655 \shape default
25656 \size default
25657
25658 \newline
25659 Then follows the human readable form of the ICode operation.
25660  Each operand of this triplet form can be of three basic types a) compiler
25661  generated temporary b) user defined variable c) a constant value.
25662  Note that local variables and parameters are replaced by compiler generated
25663  temporaries.
25664  Live ranges
25665 \begin_inset LatexCommand \index{Live range analysis}
25666
25667 \end_inset
25668
25669  are computed only for temporaries (i.e.
25670  live ranges are not computed for global variables).
25671  Registers
25672 \begin_inset LatexCommand \index{Register allocation}
25673
25674 \end_inset
25675
25676  are allocated for temporaries only.
25677  Operands are formatted in the following manner:
25678 \newline
25679
25680 \shape italic
25681 \size footnotesize
25682 Operand Name [lr live-from : live-to ] { type information } [ registers
25683  allocated ].
25684 \shape default
25685 \size default
25686
25687 \newline
25688 As mentioned earlier the live ranges are computed in terms of the execution
25689  sequence number of the iCodes, for example
25690 \newline
25691 the iTemp0 is live from (i.e.
25692  first defined in iCode with execution sequence number 3, and is last used
25693  in the iCode with sequence number 5).
25694  For induction variables such as iTemp21 the live range computation extends
25695  the lifetime from the start to the end of the loop.
25696 \newline
25697 The register allocator used the live range information to allocate registers,
25698  the same registers may be used for different temporaries if their live
25699  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
25700  iTemp17 since their live ranges do not overlap.
25701  In addition the allocator also takes into consideration the type and usage
25702  of a temporary, for example itemp6 is a pointer to near space and is used
25703  as to fetch data from (i.e.
25704  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
25705  Some short lived temporaries are allocated to special registers which have
25706  meaning to the code generator e.g.
25707  iTemp13 is allocated to a pseudo register CC which tells the back end that
25708  the temporary is used only for a conditional jump the code generation makes
25709  use of this information to optimize a compare and jump ICode.
25710 \newline
25711 There are several loop optimizations
25712 \begin_inset LatexCommand \index{Loop optimization}
25713
25714 \end_inset
25715
25716  performed by the compiler.
25717  It can detect induction variables iTemp21(i) and iTemp23(j).
25718  Also note the compiler does selective strength reduction
25719 \begin_inset LatexCommand \index{Strength reduction}
25720
25721 \end_inset
25722
25723 , i.e.
25724  the multiplication of an induction variable in line 18 (gint = j * 3) is
25725  changed to addition, a new temporary iTemp17 is allocated and assigned
25726  a initial value, a constant 3 is then added for each iteration of the loop.
25727  The compiler does not change the multiplication
25728 \begin_inset LatexCommand \index{Multiplication}
25729
25730 \end_inset
25731
25732  in line 17 however since the processor does support an 8 * 8 bit multiplication.
25733 \newline
25734 Note the dead code elimination
25735 \begin_inset LatexCommand \index{Dead-code elimination}
25736
25737 \end_inset
25738
25739  optimization eliminated the dead assignments in line 7 & 8 to I and sum
25740  respectively.
25741 \newline
25742
25743 \layout Standard
25744
25745
25746 \size footnotesize
25747 Sample.c (5:1:0:0) _entry($9) :
25748 \layout Standard
25749
25750
25751 \size footnotesize
25752 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
25753 \layout Standard
25754
25755
25756 \size footnotesize
25757 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
25758 \layout Standard
25759
25760
25761 \size footnotesize
25762 Sample.c(11:4:53:0) preHeaderLbl0($11) :
25763 \layout Standard
25764
25765
25766 \size footnotesize
25767 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
25768  * int}[r2]
25769 \layout Standard
25770
25771
25772 \size footnotesize
25773 Sample.c(11:6:5:1) _whilecontinue_0($1) :
25774 \layout Standard
25775
25776
25777 \size footnotesize
25778 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
25779  int}[r0]]
25780 \layout Standard
25781
25782
25783 \size footnotesize
25784 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
25785 \layout Standard
25786
25787
25788 \size footnotesize
25789 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
25790  * int}
25791 \layout Standard
25792
25793
25794 \size footnotesize
25795 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
25796  {short}
25797 \layout Standard
25798
25799
25800 \size footnotesize
25801 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
25802  * int}[DPTR]]
25803 \layout Standard
25804
25805
25806 \size footnotesize
25807 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
25808 }[r2 r3]
25809 \layout Standard
25810
25811
25812 \size footnotesize
25813 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
25814  * int}[r0] + 0x2 {short}
25815 \layout Standard
25816
25817
25818 \size footnotesize
25819 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
25820 \layout Standard
25821
25822
25823 \size footnotesize
25824 Sample.c(11:17:21:0)_whilebreak_0($3) :
25825 \layout Standard
25826
25827
25828 \size footnotesize
25829 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
25830 \layout Standard
25831
25832
25833 \size footnotesize
25834 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
25835 \layout Standard
25836
25837
25838 \size footnotesize
25839 Sample.c(15:20:54:0)preHeaderLbl1($13) :
25840 \layout Standard
25841
25842
25843 \size footnotesize
25844 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
25845 \layout Standard
25846
25847
25848 \size footnotesize
25849 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
25850 \layout Standard
25851
25852
25853 \size footnotesize
25854 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
25855 \layout Standard
25856
25857
25858 \size footnotesize
25859 Sample.c(15:24:26:1)_forcond_0($4) :
25860 \layout Standard
25861
25862
25863 \size footnotesize
25864 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
25865  < 0xa {short}
25866 \layout Standard
25867
25868
25869 \size footnotesize
25870 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
25871 \layout Standard
25872
25873
25874 \size footnotesize
25875 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
25876  + ITemp21 [lr21:38]{short}[r4]
25877 \layout Standard
25878
25879
25880 \size footnotesize
25881 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
25882  * 0x3 {short}
25883 \layout Standard
25884
25885
25886 \size footnotesize
25887 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
25888  + iTemp15 [lr29:30]{short}[r1]
25889 \layout Standard
25890
25891
25892 \size footnotesize
25893 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
25894  r0]- 0x3 {short}
25895 \layout Standard
25896
25897
25898 \size footnotesize
25899 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
25900 int}[r7 r0]
25901 \layout Standard
25902
25903
25904 \size footnotesize
25905 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
25906  + 0x1 {short}
25907 \layout Standard
25908
25909
25910 \size footnotesize
25911 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
25912  r6]- 0x1 {short}
25913 \layout Standard
25914
25915
25916 \size footnotesize
25917 Sample.c(19:38:47:1) goto _forcond_0($4)
25918 \layout Standard
25919
25920
25921 \size footnotesize
25922 Sample.c(19:39:48:0)_forbreak_0($7) :
25923 \layout Standard
25924
25925
25926 \size footnotesize
25927 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
25928  + ITemp11 [lr19:40]{short}[r3]
25929 \layout Standard
25930
25931
25932 \size footnotesize
25933 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
25934 \layout Standard
25935
25936
25937 \size footnotesize
25938 Sample.c(20:42:51:0)_return($8) :
25939 \layout Standard
25940
25941
25942 \size footnotesize
25943 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
25944 \size default
25945
25946 \newline
25947
25948 \newline
25949 Finally the code generated for this function:
25950 \newline
25951
25952 \layout Standard
25953
25954
25955 \size footnotesize
25956 .area DSEG (DATA)
25957 \layout Standard
25958
25959
25960 \size footnotesize
25961 _p::
25962 \layout Standard
25963
25964
25965 \size footnotesize
25966 \SpecialChar ~
25967 \SpecialChar ~
25968 .ds 2
25969 \layout Standard
25970
25971
25972 \size footnotesize
25973 _gint::
25974 \layout Standard
25975
25976
25977 \size footnotesize
25978 \SpecialChar ~
25979 \SpecialChar ~
25980 .ds 2
25981 \layout Standard
25982
25983
25984 \size footnotesize
25985 ; sample.c 5
25986 \layout Standard
25987
25988
25989 \size footnotesize
25990 ; ----------------------------------------------
25991 \layout Standard
25992
25993
25994 \size footnotesize
25995 ; function function
25996 \layout Standard
25997
25998
25999 \size footnotesize
26000 ; ----------------------------------------------
26001 \layout Standard
26002
26003
26004 \size footnotesize
26005 _function:
26006 \layout Standard
26007
26008
26009 \size footnotesize
26010 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
26011 \layout Standard
26012
26013
26014 \size footnotesize
26015 \SpecialChar ~
26016 \SpecialChar ~
26017 mov r2,dpl
26018 \layout Standard
26019
26020
26021 \size footnotesize
26022 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
26023 \layout Standard
26024
26025
26026 \size footnotesize
26027 \SpecialChar ~
26028 \SpecialChar ~
26029 mov ar0,r2
26030 \layout Standard
26031
26032
26033 \size footnotesize
26034 ;_whilecontinue_0($1) :
26035 \layout Standard
26036
26037
26038 \size footnotesize
26039 00101$:
26040 \layout Standard
26041
26042
26043 \size footnotesize
26044 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
26045 \layout Standard
26046
26047
26048 \size footnotesize
26049 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
26050 \layout Standard
26051
26052
26053 \size footnotesize
26054 \SpecialChar ~
26055 \SpecialChar ~
26056 mov ar2,@r0
26057 \layout Standard
26058
26059
26060 \size footnotesize
26061 \SpecialChar ~
26062 \SpecialChar ~
26063 inc r0
26064 \layout Standard
26065
26066
26067 \size footnotesize
26068 \SpecialChar ~
26069 \SpecialChar ~
26070 mov ar3,@r0
26071 \layout Standard
26072
26073
26074 \size footnotesize
26075 \SpecialChar ~
26076 \SpecialChar ~
26077 dec r0
26078 \layout Standard
26079
26080
26081 \size footnotesize
26082 \SpecialChar ~
26083 \SpecialChar ~
26084 mov a,r2
26085 \layout Standard
26086
26087
26088 \size footnotesize
26089 \SpecialChar ~
26090 \SpecialChar ~
26091 orl a,r3
26092 \layout Standard
26093
26094
26095 \size footnotesize
26096 \SpecialChar ~
26097 \SpecialChar ~
26098 jz 00103$
26099 \layout Standard
26100
26101
26102 \size footnotesize
26103 00114$:
26104 \layout Standard
26105
26106
26107 \size footnotesize
26108 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
26109 \layout Standard
26110
26111
26112 \size footnotesize
26113 \SpecialChar ~
26114 \SpecialChar ~
26115 mov dpl,_p
26116 \layout Standard
26117
26118
26119 \size footnotesize
26120 \SpecialChar ~
26121 \SpecialChar ~
26122 mov dph,(_p + 1)
26123 \layout Standard
26124
26125
26126 \size footnotesize
26127 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
26128 \layout Standard
26129
26130
26131 \size footnotesize
26132 \SpecialChar ~
26133 \SpecialChar ~
26134 mov a,#0x02
26135 \layout Standard
26136
26137
26138 \size footnotesize
26139 \SpecialChar ~
26140 \SpecialChar ~
26141 add a,_p
26142 \layout Standard
26143
26144
26145 \size footnotesize
26146 \SpecialChar ~
26147 \SpecialChar ~
26148 mov _p,a
26149 \layout Standard
26150
26151
26152 \size footnotesize
26153 \SpecialChar ~
26154 \SpecialChar ~
26155 clr a
26156 \layout Standard
26157
26158
26159 \size footnotesize
26160 \SpecialChar ~
26161 \SpecialChar ~
26162 addc a,(_p + 1)
26163 \layout Standard
26164
26165
26166 \size footnotesize
26167 \SpecialChar ~
26168 \SpecialChar ~
26169 mov (_p + 1),a
26170 \layout Standard
26171
26172
26173 \size footnotesize
26174 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
26175 \layout Standard
26176
26177
26178 \size footnotesize
26179 \SpecialChar ~
26180 \SpecialChar ~
26181 movx a,@dptr
26182 \layout Standard
26183
26184
26185 \size footnotesize
26186 \SpecialChar ~
26187 \SpecialChar ~
26188 mov r2,a
26189 \layout Standard
26190
26191
26192 \size footnotesize
26193 \SpecialChar ~
26194 \SpecialChar ~
26195 inc dptr
26196 \layout Standard
26197
26198
26199 \size footnotesize
26200 \SpecialChar ~
26201 \SpecialChar ~
26202 movx a,@dptr
26203 \layout Standard
26204
26205
26206 \size footnotesize
26207 \SpecialChar ~
26208 \SpecialChar ~
26209 mov r3,a
26210 \layout Standard
26211
26212
26213 \size footnotesize
26214 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
26215 \layout Standard
26216
26217
26218 \size footnotesize
26219 \SpecialChar ~
26220 \SpecialChar ~
26221 mov @r0,ar2
26222 \layout Standard
26223
26224
26225 \size footnotesize
26226 \SpecialChar ~
26227 \SpecialChar ~
26228 inc r0
26229 \layout Standard
26230
26231
26232 \size footnotesize
26233 \SpecialChar ~
26234 \SpecialChar ~
26235 mov @r0,ar3
26236 \layout Standard
26237
26238
26239 \size footnotesize
26240 ; iTemp6 [lr5:16]{_near * int}[r0] =
26241 \layout Standard
26242
26243
26244 \size footnotesize
26245 ; iTemp6 [lr5:16]{_near * int}[r0] +
26246 \layout Standard
26247
26248
26249 \size footnotesize
26250 ; 0x2 {short}
26251 \layout Standard
26252
26253
26254 \size footnotesize
26255 \SpecialChar ~
26256 \SpecialChar ~
26257 inc r0
26258 \layout Standard
26259
26260
26261 \size footnotesize
26262 ; goto _whilecontinue_0($1)
26263 \layout Standard
26264
26265
26266 \size footnotesize
26267 \SpecialChar ~
26268 \SpecialChar ~
26269 sjmp 00101$
26270 \layout Standard
26271
26272
26273 \size footnotesize
26274 ; _whilebreak_0($3) :
26275 \layout Standard
26276
26277
26278 \size footnotesize
26279 00103$:
26280 \layout Standard
26281
26282
26283 \size footnotesize
26284 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
26285 \layout Standard
26286
26287
26288 \size footnotesize
26289 \SpecialChar ~
26290 \SpecialChar ~
26291 mov r2,#0x00
26292 \layout Standard
26293
26294
26295 \size footnotesize
26296 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
26297 \layout Standard
26298
26299
26300 \size footnotesize
26301 \SpecialChar ~
26302 \SpecialChar ~
26303 mov r3,#0x00
26304 \layout Standard
26305
26306
26307 \size footnotesize
26308 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
26309 \layout Standard
26310
26311
26312 \size footnotesize
26313 \SpecialChar ~
26314 \SpecialChar ~
26315 mov r4,#0x00
26316 \layout Standard
26317
26318
26319 \size footnotesize
26320 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
26321 \layout Standard
26322
26323
26324 \size footnotesize
26325 \SpecialChar ~
26326 \SpecialChar ~
26327 mov r5,#0x0A
26328 \layout Standard
26329
26330
26331 \size footnotesize
26332 \SpecialChar ~
26333 \SpecialChar ~
26334 mov r6,#0x00
26335 \layout Standard
26336
26337
26338 \size footnotesize
26339 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
26340 \layout Standard
26341
26342
26343 \size footnotesize
26344 \SpecialChar ~
26345 \SpecialChar ~
26346 mov r7,#0x1E
26347 \layout Standard
26348
26349
26350 \size footnotesize
26351 \SpecialChar ~
26352 \SpecialChar ~
26353 mov r0,#0x00
26354 \layout Standard
26355
26356
26357 \size footnotesize
26358 ; _forcond_0($4) :
26359 \layout Standard
26360
26361
26362 \size footnotesize
26363 00104$:
26364 \layout Standard
26365
26366
26367 \size footnotesize
26368 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
26369 \layout Standard
26370
26371
26372 \size footnotesize
26373 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
26374 \layout Standard
26375
26376
26377 \size footnotesize
26378 \SpecialChar ~
26379 \SpecialChar ~
26380 clr c
26381 \layout Standard
26382
26383
26384 \size footnotesize
26385 \SpecialChar ~
26386 \SpecialChar ~
26387 mov a,r4
26388 \layout Standard
26389
26390
26391 \size footnotesize
26392 \SpecialChar ~
26393 \SpecialChar ~
26394 xrl a,#0x80
26395 \layout Standard
26396
26397
26398 \size footnotesize
26399 \SpecialChar ~
26400 \SpecialChar ~
26401 subb a,#0x8a
26402 \layout Standard
26403
26404
26405 \size footnotesize
26406 \SpecialChar ~
26407 \SpecialChar ~
26408 jnc 00107$
26409 \layout Standard
26410
26411
26412 \size footnotesize
26413 00115$:
26414 \layout Standard
26415
26416
26417 \size footnotesize
26418 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
26419 \layout Standard
26420
26421
26422 \size footnotesize
26423 ; iTemp21 [lr21:38]{short}[r4]
26424 \layout Standard
26425
26426
26427 \size footnotesize
26428 \SpecialChar ~
26429 \SpecialChar ~
26430 mov a,r4
26431 \layout Standard
26432
26433
26434 \size footnotesize
26435 \SpecialChar ~
26436 \SpecialChar ~
26437 add a,r2
26438 \layout Standard
26439
26440
26441 \size footnotesize
26442 \SpecialChar ~
26443 \SpecialChar ~
26444 mov r2,a
26445 \layout Standard
26446
26447
26448 \size footnotesize
26449 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
26450 \layout Standard
26451
26452
26453 \size footnotesize
26454 \SpecialChar ~
26455 \SpecialChar ~
26456 mov b,#0x03
26457 \layout Standard
26458
26459
26460 \size footnotesize
26461 \SpecialChar ~
26462 \SpecialChar ~
26463 mov a,r4
26464 \layout Standard
26465
26466
26467 \size footnotesize
26468 \SpecialChar ~
26469 \SpecialChar ~
26470 mul ab
26471 \layout Standard
26472
26473
26474 \size footnotesize
26475 \SpecialChar ~
26476 \SpecialChar ~
26477 mov r1,a
26478 \layout Standard
26479
26480
26481 \size footnotesize
26482 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
26483 \layout Standard
26484
26485
26486 \size footnotesize
26487 ; iTemp15 [lr29:30]{short}[r1]
26488 \layout Standard
26489
26490
26491 \size footnotesize
26492 \SpecialChar ~
26493 \SpecialChar ~
26494 add a,r3
26495 \layout Standard
26496
26497
26498 \size footnotesize
26499 \SpecialChar ~
26500 \SpecialChar ~
26501 mov r3,a
26502 \layout Standard
26503
26504
26505 \size footnotesize
26506 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
26507 \layout Standard
26508
26509
26510 \size footnotesize
26511 \SpecialChar ~
26512 \SpecialChar ~
26513 mov a,r7
26514 \layout Standard
26515
26516
26517 \size footnotesize
26518 \SpecialChar ~
26519 \SpecialChar ~
26520 add a,#0xfd
26521 \layout Standard
26522
26523
26524 \size footnotesize
26525 \SpecialChar ~
26526 \SpecialChar ~
26527 mov r7,a
26528 \layout Standard
26529
26530
26531 \size footnotesize
26532 \SpecialChar ~
26533 \SpecialChar ~
26534 mov a,r0
26535 \layout Standard
26536
26537
26538 \size footnotesize
26539 \SpecialChar ~
26540 \SpecialChar ~
26541 addc a,#0xff
26542 \layout Standard
26543
26544
26545 \size footnotesize
26546 \SpecialChar ~
26547 \SpecialChar ~
26548 mov r0,a
26549 \layout Standard
26550
26551
26552 \size footnotesize
26553 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
26554 \layout Standard
26555
26556
26557 \size footnotesize
26558 \SpecialChar ~
26559 \SpecialChar ~
26560 mov a,r7
26561 \layout Standard
26562
26563
26564 \size footnotesize
26565 \SpecialChar ~
26566 \SpecialChar ~
26567 add a,_gint
26568 \layout Standard
26569
26570
26571 \size footnotesize
26572 \SpecialChar ~
26573 \SpecialChar ~
26574 mov _gint,a
26575 \layout Standard
26576
26577
26578 \size footnotesize
26579 \SpecialChar ~
26580 \SpecialChar ~
26581 mov a,r0
26582 \layout Standard
26583
26584
26585 \size footnotesize
26586 \SpecialChar ~
26587 \SpecialChar ~
26588 addc a,(_gint + 1)
26589 \layout Standard
26590
26591
26592 \size footnotesize
26593 \SpecialChar ~
26594 \SpecialChar ~
26595 mov (_gint + 1),a
26596 \layout Standard
26597
26598
26599 \size footnotesize
26600 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
26601 \layout Standard
26602
26603
26604 \size footnotesize
26605 \SpecialChar ~
26606 \SpecialChar ~
26607 inc r4
26608 \layout Standard
26609
26610
26611 \size footnotesize
26612 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
26613 \layout Standard
26614
26615
26616 \size footnotesize
26617 \SpecialChar ~
26618 \SpecialChar ~
26619 dec r5
26620 \layout Standard
26621
26622
26623 \size footnotesize
26624 \SpecialChar ~
26625 \SpecialChar ~
26626 cjne r5,#0xff,00104$
26627 \layout Standard
26628
26629
26630 \size footnotesize
26631 \SpecialChar ~
26632 \SpecialChar ~
26633 dec r6
26634 \layout Standard
26635
26636
26637 \size footnotesize
26638 ; goto _forcond_0($4)
26639 \layout Standard
26640
26641
26642 \size footnotesize
26643 \SpecialChar ~
26644 \SpecialChar ~
26645 sjmp 00104$
26646 \layout Standard
26647
26648
26649 \size footnotesize
26650 ; _forbreak_0($7) :
26651 \layout Standard
26652
26653
26654 \size footnotesize
26655 00107$:
26656 \layout Standard
26657
26658
26659 \size footnotesize
26660 ; ret iTemp24 [lr40:41]{short}
26661 \layout Standard
26662
26663
26664 \size footnotesize
26665 \SpecialChar ~
26666 \SpecialChar ~
26667 mov a,r3
26668 \layout Standard
26669
26670
26671 \size footnotesize
26672 \SpecialChar ~
26673 \SpecialChar ~
26674 add a,r2
26675 \layout Standard
26676
26677
26678 \size footnotesize
26679 \SpecialChar ~
26680 \SpecialChar ~
26681 mov dpl,a
26682 \layout Standard
26683
26684
26685 \size footnotesize
26686 ; _return($8) :
26687 \layout Standard
26688
26689
26690 \size footnotesize
26691 00108$:
26692 \layout Standard
26693
26694
26695 \size footnotesize
26696 \SpecialChar ~
26697 \SpecialChar ~
26698 ret
26699 \newline
26700
26701 \layout Section
26702
26703 A few words about basic block successors, predecessors and dominators
26704 \layout Standard
26705
26706 Successors are basic blocks
26707 \begin_inset LatexCommand \index{Basic blocks}
26708
26709 \end_inset
26710
26711  that might execute after this basic block.
26712 \newline
26713 Predecessors are basic blocks that might execute before reaching this basic
26714  block.
26715 \newline
26716 Dominators are basic blocks that WILL execute before reaching this basic
26717  block.
26718 \newline
26719
26720 \layout Standard
26721
26722 [basic block 1]
26723 \layout Standard
26724
26725 if (something)
26726 \layout Standard
26727
26728 \SpecialChar ~
26729 \SpecialChar ~
26730 \SpecialChar ~
26731 \SpecialChar ~
26732 [basic block 2]
26733 \layout Standard
26734
26735 else
26736 \layout Standard
26737
26738 \SpecialChar ~
26739 \SpecialChar ~
26740 \SpecialChar ~
26741 \SpecialChar ~
26742 [basic block 3]
26743 \layout Standard
26744
26745 [basic block 4]
26746 \newline
26747
26748 \layout Standard
26749
26750 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
26751 \layout Standard
26752
26753 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
26754 \layout Standard
26755
26756 c) domVect of [BB4] = BB1 ...
26757  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
26758  was executed.
26759 \layout Chapter
26760
26761 Acknowledgments
26762 \layout Standard
26763
26764
26765 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
26766
26767 \end_inset
26768
26769
26770 \newline
26771
26772 \newline
26773
26774 \emph on
26775 Thanks to all the other volunteer developers who have helped with coding,
26776  testing, web-page creation, distribution sets, etc.
26777  You know who you are :-)
26778 \emph default
26779
26780 \newline
26781
26782 \layout Standard
26783
26784 This document was initially written by Sandeep Dutta
26785 \layout Standard
26786
26787 All product names mentioned herein may be trademarks
26788 \begin_inset LatexCommand \index{Trademarks}
26789
26790 \end_inset
26791
26792  of their respective companies.
26793
26794 \layout Section*
26795
26796 Alphabetical index
26797 \layout Standard
26798
26799 To avoid confusion, the installation and building options for SDCC itself
26800  (chapter 2) are not part of the index.
26801 \layout Standard
26802
26803
26804 \begin_inset LatexCommand \printindex{}
26805
26806 \end_inset
26807
26808
26809 \the_end