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.1
  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  / sbit
8940 \begin_inset LatexCommand \index{\_\_sbit}
8941
8942 \end_inset
8943
8944
8945 \layout Standard
8946
8947 Like the bit keyword,
8948 \emph on
8949 sfr / sbit
8950 \emph default
8951 signifies both a data-type and storage class, they are used to describe
8952  the
8953 \emph on
8954 s
8955 \emph default
8956 pecial
8957 \emph on
8958 f
8959 \emph default
8960 unction
8961 \emph on
8962 r
8963 \emph default
8964 egisters and
8965 \emph on
8966 s
8967 \emph default
8968 pecial
8969 \emph on
8970 bit
8971 \emph default
8972  variables of a 8051, eg:
8973 \layout Verse
8974
8975
8976 \family typewriter
8977 sfr at
8978 \begin_inset LatexCommand \index{at}
8979
8980 \end_inset
8981
8982
8983 \begin_inset LatexCommand \index{\_\_at}
8984
8985 \end_inset
8986
8987  0x80 P0;\SpecialChar ~
8988  /* special function register P0 at location 0x80 */
8989 \newline
8990 sbit at 0xd7 CY; /* CY (Carry Flag
8991 \begin_inset LatexCommand \index{Flags}
8992
8993 \end_inset
8994
8995
8996 \begin_inset LatexCommand \index{Carry flag}
8997
8998 \end_inset
8999
9000 ) */
9001 \layout Standard
9002
9003 Special function registers which are located on an address dividable by
9004  8 are bit-addressable, an
9005 \emph on
9006  sbit
9007 \emph default
9008  addresses a specific bit within these sfr.
9009 \layout Subsubsection
9010
9011 Pointers
9012 \begin_inset LatexCommand \index{Pointer}
9013
9014 \end_inset
9015
9016  to MCS51/DS390 specific memory spaces
9017 \layout Standard
9018
9019 SDCC allows (via language extensions) pointers to explicitly point to any
9020  of the memory spaces
9021 \begin_inset LatexCommand \index{Memory model}
9022
9023 \end_inset
9024
9025  of the 8051.
9026  In addition to the explicit pointers, the compiler uses (by default) generic
9027  pointers which can be used to point to any of the memory spaces.
9028 \newline
9029
9030 \newline
9031 Pointer declaration examples:
9032 \layout Verse
9033
9034
9035 \family typewriter
9036 /* pointer physically in internal ram pointing to object in external ram
9037  */
9038 \newline
9039 xdata unsigned char * data p;
9040 \newline
9041
9042 \newline
9043 /* pointer physically in external ram pointing to object in internal ram
9044  */
9045 \newline
9046 data unsigned char * xdata p;
9047 \newline
9048
9049 \newline
9050 /* pointer physically in code rom pointing to data in xdata space */
9051 \newline
9052 xdata unsigned char * code p;
9053 \newline
9054
9055 \newline
9056 /* pointer physically in code space pointing to data in code space */
9057 \newline
9058 code unsigned char * code p;
9059 \newline
9060
9061 \newline
9062 /* the following is a generic pointer physically located in xdata space
9063  */
9064 \newline
9065 char * xdata p;
9066 \layout Standard
9067
9068 Well you get the idea.
9069
9070 \newline
9071
9072 \newline
9073 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9074 \emph on
9075 generic
9076 \emph default
9077  pointers.
9078
9079 \size small
9080
9081 \newline
9082
9083 \newline
9084
9085 \size default
9086 The highest order byte of the
9087 \emph on
9088 generic
9089 \emph default
9090  pointers contains the data space information.
9091  Assembler support routines are called whenever data is stored or retrieved
9092  using
9093 \emph on
9094 generic
9095 \emph default
9096  pointers.
9097  These are useful for developing reusable library
9098 \begin_inset LatexCommand \index{Libraries}
9099
9100 \end_inset
9101
9102  routines.
9103  Explicitly specifying the pointer type will generate the most efficient
9104  code.
9105 \layout Subsubsection
9106
9107 Notes on MCS51 memory
9108 \begin_inset LatexCommand \index{MCS51 memory}
9109
9110 \end_inset
9111
9112  layout
9113 \layout Standard
9114
9115 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9116  RAM memory which is structured as follows:
9117 \newline
9118
9119 \newline
9120 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9121
9122 \newline
9123 - Bytes 20-2F - 16 bytes to hold 128 bit
9124 \begin_inset LatexCommand \index{bit}
9125
9126 \end_inset
9127
9128  variables and,
9129 \newline
9130 - Bytes 30-7F - 80 bytes for general purpose use.
9131 \newline
9132
9133 \layout Standard
9134
9135 Additionally some members of the MCS51 family may have up to 128 bytes of
9136  additional, indirectly addressable, internal RAM memory (
9137 \emph on
9138 idata
9139 \emph default
9140
9141 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9142
9143 \end_inset
9144
9145
9146 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9147
9148 \end_inset
9149
9150 ).
9151  Furthermore, some chips may have some built in external memory (
9152 \emph on
9153 xdata
9154 \emph default
9155
9156 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9157
9158 \end_inset
9159
9160
9161 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9162
9163 \end_inset
9164
9165 ) which should not be confused with the internal, directly addressable RAM
9166  memory (
9167 \emph on
9168 data
9169 \emph default
9170
9171 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9172
9173 \end_inset
9174
9175
9176 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9177
9178 \end_inset
9179
9180 ).
9181  Sometimes this built in
9182 \emph on
9183 xdata
9184 \emph default
9185  memory has to be activated before using it (you can probably find this
9186  information on the datasheet of the microcontroller your are using, see
9187  also section
9188 \begin_inset LatexCommand \ref{sub:Startup-Code}
9189
9190 \end_inset
9191
9192 \SpecialChar ~
9193 Startup-Code).
9194 \layout Standard
9195
9196 Normally SDCC will only use the first bank
9197 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9198
9199 \end_inset
9200
9201  of registers (register bank 0), but it is possible to specify that other
9202  banks of registers (keyword
9203 \emph on
9204 using
9205 \emph default
9206
9207 \emph on
9208
9209 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9210
9211 \end_inset
9212
9213
9214 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9215
9216 \end_inset
9217
9218
9219 \emph default
9220 ) should be used in interrupt
9221 \begin_inset LatexCommand \index{interrupt}
9222
9223 \end_inset
9224
9225
9226 \begin_inset LatexCommand \index{\_\_interrupt}
9227
9228 \end_inset
9229
9230  routines.
9231  By default, the compiler will place the stack after the last byte of allocated
9232  memory for variables.
9233  For example, if the first 2 banks of registers are used, and only four
9234  bytes are used for
9235 \emph on
9236 data
9237 \emph default
9238  variables, it will position the base of the internal stack at address 20
9239  (0x14).
9240  This implies that as the stack
9241 \begin_inset LatexCommand \index{stack}
9242
9243 \end_inset
9244
9245  grows, it will use up the remaining register banks, and the 16 bytes used
9246  by the 128 bit variables, and 80 bytes for general purpose use.
9247  If any bit variables are used, the data variables will be placed in unused
9248  register banks and after the byte holding the last bit variable.
9249  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9250  (two bytes used),
9251 \emph on
9252 data
9253 \emph default
9254  variables will be placed starting from address 0x10 to 0x20 and continue
9255  at address 0x22.
9256  You can also use -
9257 \begin_inset ERT
9258 status Collapsed
9259
9260 \layout Standard
9261
9262 \backslash
9263 /
9264 \end_inset
9265
9266 -data-loc
9267 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
9268
9269 \end_inset
9270
9271  to specify the start address of the
9272 \emph on
9273 data
9274 \emph default
9275  and -
9276 \begin_inset ERT
9277 status Collapsed
9278
9279 \layout Standard
9280
9281 \backslash
9282 /
9283 \end_inset
9284
9285 -iram-size
9286 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
9287
9288 \end_inset
9289
9290  to specify the size of the total internal RAM (
9291 \emph on
9292 data
9293 \emph default
9294 +
9295 \emph on
9296 idata
9297 \emph default
9298 ).
9299
9300 \layout Standard
9301
9302 By default the 8051 linker will place the stack after the last byte of (i)data
9303  variables.
9304  Option -
9305 \begin_inset ERT
9306 status Collapsed
9307
9308 \layout Standard
9309
9310 \backslash
9311 /
9312 \end_inset
9313
9314 -stack-loc
9315 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
9316
9317 \end_inset
9318
9319  allows you to specify the start of the stack, i.e.
9320  you could start it after any data in the general purpose area.
9321  If your microcontroller has additional indirectly addressable internal
9322  RAM (
9323 \emph on
9324 idata
9325 \emph default
9326 ) you can place the stack on it.
9327  You may also need to use -
9328 \begin_inset ERT
9329 status Collapsed
9330
9331 \layout Standard
9332
9333 \backslash
9334 /
9335 \end_inset
9336
9337 -xdata-loc
9338 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
9339
9340 \end_inset
9341
9342  to set the start address of the external RAM (
9343 \emph on
9344 xdata
9345 \emph default
9346 ) and -
9347 \begin_inset ERT
9348 status Collapsed
9349
9350 \layout Standard
9351
9352 \backslash
9353 /
9354 \end_inset
9355
9356 -xram-size
9357 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
9358
9359 \end_inset
9360
9361  to specify its size.
9362  Same goes for the code memory, using -
9363 \begin_inset ERT
9364 status Collapsed
9365
9366 \layout Standard
9367
9368 \backslash
9369 /
9370 \end_inset
9371
9372 -code-loc
9373 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
9374
9375 \end_inset
9376
9377  and -
9378 \begin_inset ERT
9379 status Collapsed
9380
9381 \layout Standard
9382
9383 \backslash
9384 /
9385 \end_inset
9386
9387 -code-size
9388 \begin_inset LatexCommand \index{-\/-code-size <Value>}
9389
9390 \end_inset
9391
9392 .
9393  If in doubt, don't specify any options and see if the resulting memory
9394  layout is appropriate, then you can adjust it.
9395 \layout Standard
9396
9397 The linker generates two files with memory allocation information.
9398  The first, with extension .map
9399 \begin_inset LatexCommand \index{<file>.map}
9400
9401 \end_inset
9402
9403  shows all the variables and segments.
9404  The second with extension .mem
9405 \begin_inset LatexCommand \index{<file>.mem}
9406
9407 \end_inset
9408
9409  shows the final memory layout.
9410  The linker will complain either if memory segments overlap, there is not
9411  enough memory, or there is not enough space for stack.
9412  If you get any linking warnings and/or errors related to stack or segments
9413  allocation, take a look at either the .map or .mem files to find out what
9414  the problem is.
9415  The .mem file may even suggest a solution to the problem.
9416 \layout Subsection
9417
9418 Z80/Z180 Storage Class
9419 \begin_inset LatexCommand \index{Storage class}
9420
9421 \end_inset
9422
9423  Language Extensions
9424 \layout Subsubsection
9425
9426 sfr
9427 \begin_inset LatexCommand \index{sfr}
9428
9429 \end_inset
9430
9431
9432 \begin_inset LatexCommand \index{\_\_sfr}
9433
9434 \end_inset
9435
9436  (in/out to 8-bit addresses)
9437 \layout Standard
9438
9439 The Z80
9440 \begin_inset LatexCommand \index{Z80}
9441
9442 \end_inset
9443
9444  family has separate address spaces for memory and
9445 \emph on
9446 i
9447 \emph default
9448 nput/
9449 \emph on
9450 o
9451 \emph default
9452 utput memory.
9453  I/O memory
9454 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9455
9456 \end_inset
9457
9458  is accessed with special instructions, e.g.:
9459 \layout Verse
9460
9461
9462 \family typewriter
9463 sfr at 0x78 IoPort;\SpecialChar ~
9464 \SpecialChar ~
9465 /* define a var in I/O space at 78h called IoPort */
9466
9467 \layout Standard
9468
9469 Writing 0x01 to this variable generates the assembly code:
9470 \layout Verse
9471
9472
9473 \family typewriter
9474 3E 01\SpecialChar ~
9475 \SpecialChar ~
9476 \SpecialChar ~
9477 \SpecialChar ~
9478 \SpecialChar ~
9479 \SpecialChar ~
9480 ld a,#0x01
9481 \newline
9482 D3 78\SpecialChar ~
9483 \SpecialChar ~
9484 \SpecialChar ~
9485 \SpecialChar ~
9486 \SpecialChar ~
9487 \SpecialChar ~
9488 out (_IoPort),a
9489 \layout Subsubsection
9490
9491 banked sfr
9492 \begin_inset LatexCommand \index{sfr}
9493
9494 \end_inset
9495
9496
9497 \begin_inset LatexCommand \index{\_\_sfr}
9498
9499 \end_inset
9500
9501  (in/out to 16-bit addresses)
9502 \layout Standard
9503
9504 The keyword
9505 \emph on
9506 banked
9507 \emph default
9508  is used to support 16 bit addresses in I/O memory e.g.:
9509 \layout Verse
9510
9511
9512 \family typewriter
9513 sfr banked at
9514 \begin_inset LatexCommand \index{at}
9515
9516 \end_inset
9517
9518
9519 \begin_inset LatexCommand \index{\_\_at}
9520
9521 \end_inset
9522
9523  0x123 IoPort;
9524 \layout Standard
9525
9526 Writing 0x01 to this variable generates the assembly code:
9527 \layout Verse
9528
9529
9530 \family typewriter
9531 01 23 01\SpecialChar ~
9532 \SpecialChar ~
9533 \SpecialChar ~
9534 ld bc,#_IoPort
9535 \newline
9536 3E 01\SpecialChar ~
9537 \SpecialChar ~
9538 \SpecialChar ~
9539 \SpecialChar ~
9540 \SpecialChar ~
9541 \SpecialChar ~
9542 ld a,#0x01
9543 \newline
9544 ED 79\SpecialChar ~
9545 \SpecialChar ~
9546 \SpecialChar ~
9547 \SpecialChar ~
9548 \SpecialChar ~
9549 \SpecialChar ~
9550 out (c),a
9551 \layout Subsubsection
9552
9553 sfr
9554 \begin_inset LatexCommand \index{sfr}
9555
9556 \end_inset
9557
9558
9559 \begin_inset LatexCommand \index{\_\_sfr}
9560
9561 \end_inset
9562
9563  (in0/out0 to 8 bit addresses on Z180
9564 \begin_inset LatexCommand \index{Z180}
9565
9566 \end_inset
9567
9568 /HD64180
9569 \begin_inset LatexCommand \index{HD64180}
9570
9571 \end_inset
9572
9573 )
9574 \layout Standard
9575
9576 The compiler option -
9577 \begin_inset ERT
9578 status Collapsed
9579
9580 \layout Standard
9581
9582 \backslash
9583 /
9584 \end_inset
9585
9586 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9587 portmode
9588 \begin_inset LatexCommand \index{\#pragma portmode}
9589
9590 \end_inset
9591
9592 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9593 ns
9594 \family typewriter
9595 in0/out0
9596 \family default
9597  instead of
9598 \family typewriter
9599 in/out
9600 \family default
9601 .
9602  If you include the file z180.h this will be set automatically.
9603 \layout Subsection
9604
9605 HC08 Storage Class
9606 \begin_inset LatexCommand \index{Storage class}
9607
9608 \end_inset
9609
9610  Language Extensions
9611 \layout Subsubsection
9612
9613 data
9614 \begin_inset LatexCommand \index{data (hc08 storage class)}
9615
9616 \end_inset
9617
9618
9619 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
9620
9621 \end_inset
9622
9623
9624 \layout Standard
9625
9626 The data storage class declares a variable that resides in the first 256
9627  bytes of memory (the direct page).
9628  The HC08 is most efficient at accessing variables (especially pointers)
9629  stored here.
9630 \layout Subsubsection
9631
9632 xdata
9633 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
9634
9635 \end_inset
9636
9637
9638 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
9639
9640 \end_inset
9641
9642
9643 \layout Standard
9644
9645 The xdata storage class declares a variable that can reside anywhere in
9646  memory.
9647  This is the default if no storage class is specified.
9648
9649 \layout Section
9650
9651 Absolute Addressing
9652 \begin_inset LatexCommand \index{Absolute addressing}
9653
9654 \end_inset
9655
9656
9657 \layout Standard
9658
9659 Data items can be assigned an absolute address with the
9660 \emph on
9661 at
9662 \begin_inset LatexCommand \index{at}
9663
9664 \end_inset
9665
9666
9667 \begin_inset LatexCommand \index{\_\_at}
9668
9669 \end_inset
9670
9671  <address>
9672 \emph default
9673  keyword, in addition to a storage class, e.g.:
9674 \layout Verse
9675
9676
9677 \family typewriter
9678 xdata
9679 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9680
9681 \end_inset
9682
9683
9684 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9685
9686 \end_inset
9687
9688  at
9689 \begin_inset LatexCommand \index{at}
9690
9691 \end_inset
9692
9693
9694 \begin_inset LatexCommand \index{\_\_at}
9695
9696 \end_inset
9697
9698  0x7ffe unsigned int chksum;
9699 \layout Standard
9700
9701 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9702  of the external ram.
9703  The compiler does
9704 \emph on
9705 not
9706 \emph default
9707  reserve any space for variables declared in this way (they are implemented
9708  with an equate in the assembler).
9709  Thus it is left to the programmer to make sure there are no overlaps with
9710  other variables that are declared without the absolute address.
9711  The assembler listing file (.lst
9712 \begin_inset LatexCommand \index{<file>.lst}
9713
9714 \end_inset
9715
9716 ) and the linker output files (.rst
9717 \begin_inset LatexCommand \index{<file>.rst}
9718
9719 \end_inset
9720
9721 ) and (.map
9722 \begin_inset LatexCommand \index{<file>.map}
9723
9724 \end_inset
9725
9726 ) are good places to look for such overlaps.
9727  Variables with an absolute address are
9728 \emph on
9729 not
9730 \emph default
9731  initialized
9732 \begin_inset LatexCommand \index{Variable initialization}
9733
9734 \end_inset
9735
9736 .
9737 \layout Standard
9738
9739 In case of memory mapped I/O devices the keyword
9740 \emph on
9741 volatile
9742 \emph default
9743  has to be used to tell the compiler that accesses might not be removed:
9744 \layout Verse
9745
9746
9747 \family typewriter
9748 volatile
9749 \begin_inset LatexCommand \index{volatile}
9750
9751 \end_inset
9752
9753  xdata
9754 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9755
9756 \end_inset
9757
9758  at
9759 \begin_inset LatexCommand \index{at}
9760
9761 \end_inset
9762
9763  0x8000 unsigned char PORTA_8255;
9764 \layout Standard
9765
9766 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9767 r) array
9768 \family typewriter
9769 \size footnotesize
9770
9771 \begin_inset LatexCommand \index{Aligned array}
9772
9773 \end_inset
9774
9775
9776 \family default
9777 \size default
9778  starts at a block (256 byte) boundary
9779 \begin_inset LatexCommand \index{block boundary}
9780
9781 \end_inset
9782
9783  (section
9784 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9785
9786 \end_inset
9787
9788  has an example).
9789 \newline
9790 Absolute addresses can be specified for variables in all storage classes,
9791  e.g.:
9792 \layout Verse
9793
9794
9795 \family typewriter
9796 bit
9797 \begin_inset LatexCommand \index{bit}
9798
9799 \end_inset
9800
9801  at
9802 \begin_inset LatexCommand \index{at}
9803
9804 \end_inset
9805
9806  0x02 bvar;
9807 \layout Standard
9808
9809 The above example will allocate the variable at offset 0x02 in the bit-addressab
9810 le space.
9811  There is no real advantage to assigning absolute addresses to variables
9812  in this manner, unless you want strict control over all the variables allocated.
9813  One possible use would be to write hardware portable code.
9814  For example, if you have a routine that uses one or more of the microcontroller
9815  I/O pins, and such pins are different for two different hardwares, you
9816  can declare the I/O pins in your routine using:
9817 \layout Verse
9818
9819
9820 \family typewriter
9821 extern volatile
9822 \begin_inset LatexCommand \index{volatile}
9823
9824 \end_inset
9825
9826  bit MOSI;\SpecialChar ~
9827 \SpecialChar ~
9828 \SpecialChar ~
9829 \SpecialChar ~
9830 /* master out, slave in */
9831 \newline
9832 extern volatile bit MISO;\SpecialChar ~
9833 \SpecialChar ~
9834 \SpecialChar ~
9835 \SpecialChar ~
9836 /* master in, slave out */
9837 \newline
9838 extern volatile bit MCLK;\SpecialChar ~
9839 \SpecialChar ~
9840 \SpecialChar ~
9841 \SpecialChar ~
9842 /* master clock */
9843 \newline
9844
9845 \newline
9846 /* Input and Output of a byte on a 3-wire serial bus.
9847 \newline
9848 \SpecialChar ~
9849 \SpecialChar ~
9850 \SpecialChar ~
9851 If needed adapt polarity of clock, polarity of data and bit order
9852 \newline
9853 \SpecialChar ~
9854 */
9855 \newline
9856 unsigned char spi_io(unsigned char out_byte)
9857 \newline
9858 {
9859 \newline
9860 \SpecialChar ~
9861 \SpecialChar ~
9862 \SpecialChar ~
9863 \SpecialChar ~
9864 unsigned char i=8;
9865 \newline
9866 \SpecialChar ~
9867 \SpecialChar ~
9868 \SpecialChar ~
9869 \SpecialChar ~
9870 do {
9871 \newline
9872 \SpecialChar ~
9873 \SpecialChar ~
9874 \SpecialChar ~
9875 \SpecialChar ~
9876 \SpecialChar ~
9877 \SpecialChar ~
9878 \SpecialChar ~
9879 \SpecialChar ~
9880 MOSI = out_byte & 0x80;
9881 \newline
9882 \SpecialChar ~
9883 \SpecialChar ~
9884 \SpecialChar ~
9885 \SpecialChar ~
9886 \SpecialChar ~
9887 \SpecialChar ~
9888 \SpecialChar ~
9889 \SpecialChar ~
9890 out_byte <<= 1;
9891 \newline
9892 \SpecialChar ~
9893 \SpecialChar ~
9894 \SpecialChar ~
9895 \SpecialChar ~
9896 \SpecialChar ~
9897 \SpecialChar ~
9898 \SpecialChar ~
9899 \SpecialChar ~
9900 MCLK = 1;
9901 \newline
9902 \SpecialChar ~
9903 \SpecialChar ~
9904 \SpecialChar ~
9905 \SpecialChar ~
9906 \SpecialChar ~
9907 \SpecialChar ~
9908 \SpecialChar ~
9909 \SpecialChar ~
9910 /* _asm nop _endasm; */\SpecialChar ~
9911 \SpecialChar ~
9912 \SpecialChar ~
9913 \SpecialChar ~
9914 \SpecialChar ~
9915 \SpecialChar ~
9916 \SpecialChar ~
9917 \SpecialChar ~
9918 /* for slow peripherals */
9919 \newline
9920 \SpecialChar ~
9921 \SpecialChar ~
9922 \SpecialChar ~
9923 \SpecialChar ~
9924 \SpecialChar ~
9925 \SpecialChar ~
9926 \SpecialChar ~
9927 \SpecialChar ~
9928 if(MISO)
9929 \newline
9930 \SpecialChar ~
9931 \SpecialChar ~
9932 \SpecialChar ~
9933 \SpecialChar ~
9934 \SpecialChar ~
9935 \SpecialChar ~
9936 \SpecialChar ~
9937 \SpecialChar ~
9938 \SpecialChar ~
9939 \SpecialChar ~
9940 \SpecialChar ~
9941 \SpecialChar ~
9942 out_byte += 1;
9943 \newline
9944 \SpecialChar ~
9945 \SpecialChar ~
9946 \SpecialChar ~
9947 \SpecialChar ~
9948 \SpecialChar ~
9949 \SpecialChar ~
9950 \SpecialChar ~
9951 \SpecialChar ~
9952 MCLK = 0;
9953 \newline
9954 \SpecialChar ~
9955 \SpecialChar ~
9956 \SpecialChar ~
9957 \SpecialChar ~
9958 } while(--i);
9959 \newline
9960 \SpecialChar ~
9961 \SpecialChar ~
9962 \SpecialChar ~
9963 \SpecialChar ~
9964 return out_byte;
9965 \newline
9966 }
9967 \layout Standard
9968
9969 Then, someplace in the code for the first hardware you would use
9970 \layout Verse
9971
9972
9973 \family typewriter
9974 bit at
9975 \begin_inset LatexCommand \index{at}
9976
9977 \end_inset
9978
9979
9980 \begin_inset LatexCommand \index{\_\_at}
9981
9982 \end_inset
9983
9984  0x80 MOSI;\SpecialChar ~
9985 \SpecialChar ~
9986 \SpecialChar ~
9987 \SpecialChar ~
9988 /* I/O port 0, bit 0 */
9989 \newline
9990 bit at 0x81 MISO;\SpecialChar ~
9991 \SpecialChar ~
9992 \SpecialChar ~
9993 \SpecialChar ~
9994 /* I/O port 0, bit 1 */
9995 \newline
9996 bit at 0x82 MCLK;\SpecialChar ~
9997 \SpecialChar ~
9998 \SpecialChar ~
9999 \SpecialChar ~
10000 /* I/O port 0, bit 2 */
10001 \layout Standard
10002
10003 Similarly, for the second hardware you would use
10004 \layout Verse
10005
10006
10007 \family typewriter
10008 bit at 0x83 MOSI;\SpecialChar ~
10009 \SpecialChar ~
10010 \SpecialChar ~
10011 \SpecialChar ~
10012 /* I/O port 0, bit 3 */
10013 \newline
10014 bit at 0x91 MISO;\SpecialChar ~
10015 \SpecialChar ~
10016 \SpecialChar ~
10017 \SpecialChar ~
10018 /* I/O port 1, bit 1 */
10019 \newline
10020 bit
10021 \begin_inset LatexCommand \index{bit}
10022
10023 \end_inset
10024
10025  at 0x92 MCLK;\SpecialChar ~
10026 \SpecialChar ~
10027 \SpecialChar ~
10028 \SpecialChar ~
10029 /* I/O port 1, bit 2 */
10030 \layout Standard
10031
10032 and you can use the same hardware dependent routine without changes, as
10033  for example in a library.
10034  This is somehow similar to sbit, but only one absolute address has to be
10035  specified in the whole project.
10036 \layout Section
10037
10038 Parameters
10039 \begin_inset LatexCommand \index{Parameters}
10040
10041 \end_inset
10042
10043
10044 \begin_inset LatexCommand \index{function parameter}
10045
10046 \end_inset
10047
10048  & Local Variables
10049 \begin_inset LatexCommand \index{local variables}
10050
10051 \end_inset
10052
10053
10054 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10055
10056 \end_inset
10057
10058
10059 \layout Standard
10060
10061 Automatic (local) variables and parameters to functions can either be placed
10062  on the stack or in data-space.
10063  The default action of the compiler is to place these variables in the internal
10064  RAM (for small model) or external RAM (for large model).
10065  This in fact makes them similar to
10066 \emph on
10067 static
10068 \begin_inset LatexCommand \index{static}
10069
10070 \end_inset
10071
10072
10073 \emph default
10074  so by default functions are non-reentrant
10075 \begin_inset LatexCommand \index{reentrant}
10076
10077 \end_inset
10078
10079 .
10080
10081 \newline
10082
10083 \newline
10084 They can be placed on the stack
10085 \begin_inset LatexCommand \index{stack}
10086
10087 \end_inset
10088
10089  by using the
10090 \emph on
10091  -
10092 \begin_inset ERT
10093 status Collapsed
10094
10095 \layout Standard
10096
10097 \backslash
10098 /
10099 \end_inset
10100
10101 -stack-auto
10102 \begin_inset LatexCommand \index{-\/-stack-auto}
10103
10104 \end_inset
10105
10106
10107 \emph default
10108  option, by using
10109 \emph on
10110 #pragma\SpecialChar ~
10111 stackauto
10112 \emph default
10113
10114 \begin_inset LatexCommand \index{\#pragma stackauto}
10115
10116 \end_inset
10117
10118  or by using the
10119 \emph on
10120 reentrant
10121 \begin_inset LatexCommand \index{reentrant}
10122
10123 \end_inset
10124
10125
10126 \emph default
10127  keyword in the function declaration, e.g.:
10128 \layout Verse
10129
10130
10131 \family typewriter
10132 unsigned char foo(char i) reentrant
10133 \newline
10134 {
10135 \newline
10136 \SpecialChar ~
10137 \SpecialChar ~
10138 \SpecialChar ~
10139 \SpecialChar ~
10140 ...
10141
10142 \newline
10143 }
10144 \layout Standard
10145
10146 Since stack space on 8051 is limited, the
10147 \emph on
10148 reentrant
10149 \emph default
10150 keyword or the
10151 \emph on
10152  -
10153 \begin_inset ERT
10154 status Collapsed
10155
10156 \layout Standard
10157
10158 \backslash
10159 /
10160 \end_inset
10161
10162 -stack-auto
10163 \emph default
10164  option should be used sparingly.
10165  Note that the reentrant keyword just means that the parameters & local
10166  variables will be allocated to the stack, it
10167 \emph on
10168 does not
10169 \emph default
10170  mean that the function is register bank
10171 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10172
10173 \end_inset
10174
10175  independent.
10176 \newline
10177
10178 \newline
10179 Local variables
10180 \begin_inset LatexCommand \index{local variables}
10181
10182 \end_inset
10183
10184  can be assigned storage classes and absolute
10185 \begin_inset LatexCommand \index{Absolute addressing}
10186
10187 \end_inset
10188
10189  addresses, e.g.:
10190 \layout Verse
10191
10192
10193 \family typewriter
10194 unsigned char foo()
10195 \newline
10196 {
10197 \newline
10198 \SpecialChar ~
10199 \SpecialChar ~
10200 \SpecialChar ~
10201 \SpecialChar ~
10202 xdata unsigned char i;
10203 \newline
10204 \SpecialChar ~
10205 \SpecialChar ~
10206 \SpecialChar ~
10207 \SpecialChar ~
10208 bit bvar;
10209 \newline
10210 \SpecialChar ~
10211 \SpecialChar ~
10212 \SpecialChar ~
10213 \SpecialChar ~
10214 data at
10215 \begin_inset LatexCommand \index{at}
10216
10217 \end_inset
10218
10219  0x31 unsigned char j;
10220 \newline
10221 \SpecialChar ~
10222 \SpecialChar ~
10223 \SpecialChar ~
10224 \SpecialChar ~
10225 ...
10226
10227 \newline
10228 }
10229 \layout Standard
10230
10231 In the above example the variable
10232 \emph on
10233 i
10234 \emph default
10235  will be allocated in the external ram,
10236 \emph on
10237 bvar
10238 \emph default
10239  in bit addressable space and
10240 \emph on
10241  j
10242 \emph default
10243  in internal ram.
10244  When compiled with
10245 \emph on
10246 -
10247 \begin_inset ERT
10248 status Collapsed
10249
10250 \layout Standard
10251
10252 \backslash
10253 /
10254 \end_inset
10255
10256 -stack-auto
10257 \emph default
10258  or when a function is declared as
10259 \emph on
10260 reentrant
10261 \emph default
10262  this should only be done for static variables.
10263 \layout Standard
10264
10265 Parameters
10266 \begin_inset LatexCommand \index{function parameter}
10267
10268 \end_inset
10269
10270  however are not allowed any storage class
10271 \begin_inset LatexCommand \index{Storage class}
10272
10273 \end_inset
10274
10275 , (storage classes for parameters will be ignored), their allocation is
10276  governed by the memory model in use, and the reentrancy options.
10277 \layout Section
10278
10279 Overlaying
10280 \begin_inset LatexCommand \label{sub:Overlaying}
10281
10282 \end_inset
10283
10284
10285 \begin_inset LatexCommand \index{Overlaying}
10286
10287 \end_inset
10288
10289
10290 \layout Standard
10291
10292 For non-reentrant
10293 \begin_inset LatexCommand \index{reentrant}
10294
10295 \end_inset
10296
10297  functions SDCC will try to reduce internal ram space usage by overlaying
10298  parameters and local variables of a function (if possible).
10299  Parameters and local variables
10300 \begin_inset LatexCommand \index{local variables}
10301
10302 \end_inset
10303
10304  of a function will be allocated to an overlayable segment if the function
10305  has
10306 \emph on
10307 no other function calls and the function is non-reentrant and the memory
10308  model
10309 \begin_inset LatexCommand \index{Memory model}
10310
10311 \end_inset
10312
10313  is small.
10314
10315 \emph default
10316  If an explicit storage class
10317 \begin_inset LatexCommand \index{Storage class}
10318
10319 \end_inset
10320
10321  is specified for a local variable, it will NOT be overlayed.
10322 \layout Standard
10323
10324 Note that the compiler (not the linkage editor) makes the decision for overlayin
10325 g the data items.
10326  Functions that are called from an interrupt service routine should be preceded
10327  by a #pragma\SpecialChar ~
10328 nooverlay
10329 \begin_inset LatexCommand \index{\#pragma nooverlay}
10330
10331 \end_inset
10332
10333  if they are not reentrant.
10334 \layout Standard
10335
10336 Also note that the compiler does not do any processing of inline assembler
10337  code, so the compiler might incorrectly assign local variables and parameters
10338  of a function into the overlay segment if the inline assembler code calls
10339  other c-functions that might use the overlay.
10340  In that case the #pragma\SpecialChar ~
10341 nooverlay should be used.
10342 \layout Standard
10343
10344 Parameters and local variables of functions that contain 16 or 32 bit multiplica
10345 tion
10346 \begin_inset LatexCommand \index{Multiplication}
10347
10348 \end_inset
10349
10350  or division
10351 \begin_inset LatexCommand \index{Division}
10352
10353 \end_inset
10354
10355  will NOT be overlayed since these are implemented using external functions,
10356  e.g.:
10357 \layout Verse
10358
10359
10360 \family typewriter
10361 #pragma save
10362 \newline
10363 #pragma nooverlay
10364 \begin_inset LatexCommand \index{\#pragma nooverlay}
10365
10366 \end_inset
10367
10368
10369 \newline
10370 void set_error(unsigned char errcd)
10371 \newline
10372 {
10373 \newline
10374 \SpecialChar ~
10375 \SpecialChar ~
10376 \SpecialChar ~
10377 \SpecialChar ~
10378 P3 = errcd;
10379 \newline
10380 }
10381 \newline
10382 #pragma restore
10383 \newline
10384
10385 \newline
10386 void some_isr () interrupt
10387 \begin_inset LatexCommand \index{interrupt}
10388
10389 \end_inset
10390
10391  2
10392 \newline
10393 {
10394 \newline
10395 \SpecialChar ~
10396 \SpecialChar ~
10397 \SpecialChar ~
10398 \SpecialChar ~
10399 ...
10400 \newline
10401 \SpecialChar ~
10402 \SpecialChar ~
10403 \SpecialChar ~
10404 \SpecialChar ~
10405 set_error(10);
10406 \newline
10407 \SpecialChar ~
10408 \SpecialChar ~
10409 \SpecialChar ~
10410 \SpecialChar ~
10411 ...
10412
10413 \newline
10414 }
10415 \layout Standard
10416
10417 In the above example the parameter
10418 \emph on
10419 errcd
10420 \emph default
10421  for the function
10422 \emph on
10423 set_error
10424 \emph default
10425  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
10426 nooverlay was
10427  not present, this could cause unpredictable runtime behavior when called
10428  from an interrupt service routine.
10429  The #pragma\SpecialChar ~
10430 nooverlay ensures that the parameters and local variables for
10431  the function are NOT overlayed.
10432 \layout Section
10433
10434 Interrupt Service Routines
10435 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
10436
10437 \end_inset
10438
10439
10440 \layout Subsection
10441
10442 General Information
10443 \layout Standard
10444
10445 SDCC allows
10446 \emph on
10447 i
10448 \emph default
10449 nterrupt
10450 \emph on
10451 s
10452 \emph default
10453 ervice
10454 \emph on
10455 r
10456 \emph default
10457 outines to be coded in C, with some extended keywords.
10458 \layout Verse
10459
10460
10461 \family typewriter
10462 void timer_isr (void) interrupt 1 using 1
10463 \newline
10464 {
10465 \newline
10466 \SpecialChar ~
10467 \SpecialChar ~
10468 \SpecialChar ~
10469 \SpecialChar ~
10470 ...
10471
10472 \newline
10473 }
10474 \layout Standard
10475
10476 The optional number following the
10477 \emph on
10478 interrupt
10479 \begin_inset LatexCommand \index{interrupt}
10480
10481 \end_inset
10482
10483
10484 \begin_inset LatexCommand \index{\_\_interrupt}
10485
10486 \end_inset
10487
10488
10489 \emph default
10490  keyword is the interrupt number this routine will service.
10491  When present, the compiler will insert a call to this routine in the interrupt
10492  vector table for the interrupt number specified.
10493  If you have multiple source files in your project, interrupt service routines
10494  can be present in any of them, but a prototype of the isr MUST be present
10495  or included in the file that contains the function
10496 \emph on
10497 main
10498 \emph default
10499 .
10500  The optional
10501 \emph on
10502 using
10503 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10504
10505 \end_inset
10506
10507
10508 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10509
10510 \end_inset
10511
10512
10513 \emph default
10514  keyword can be used to tell the compiler to use the specified register
10515  bank (8051 specific) when generating code for this function.
10516
10517 \newline
10518
10519 \layout Standard
10520
10521 Interrupt service routines open the door for some very interesting bugs:
10522 \newline
10523 If an interrupt service routine changes variables which are accessed by
10524  other functions these variables have to be declared
10525 \emph on
10526 volatile
10527 \emph default
10528
10529 \begin_inset LatexCommand \index{volatile}
10530
10531 \end_inset
10532
10533 .
10534
10535 \layout Standard
10536
10537 If the access to these variables is not
10538 \emph on
10539 atomic
10540 \begin_inset LatexCommand \index{atomic}
10541
10542 \end_inset
10543
10544
10545 \emph default
10546  (i.e.
10547  the processor needs more than one instruction for the access and could
10548  be interrupted while accessing the variable) the interrupt must be disabled
10549  during the access to avoid inconsistent data.
10550  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10551  and should be protected by disabling interrupts.
10552  You're not automatically on the safe side if you use 8 bit variables though.
10553  We need an example here: f.e.
10554  on the 8051 the harmless looking
10555 \begin_inset Quotes srd
10556 \end_inset
10557
10558
10559 \family typewriter
10560 flags\SpecialChar ~
10561 |=\SpecialChar ~
10562 0x80;
10563 \family default
10564
10565 \begin_inset Quotes sld
10566 \end_inset
10567
10568  is not atomic if
10569 \family typewriter
10570 flags
10571 \family default
10572  resides in xdata.
10573  Setting
10574 \begin_inset Quotes srd
10575 \end_inset
10576
10577
10578 \family typewriter
10579 flags\SpecialChar ~
10580 |=\SpecialChar ~
10581 0x40;
10582 \family default
10583
10584 \begin_inset Quotes sld
10585 \end_inset
10586
10587  from within an interrupt routine might get lost if the interrupt occurs
10588  at the wrong time.
10589
10590 \begin_inset Quotes sld
10591 \end_inset
10592
10593
10594 \family typewriter
10595 counter\SpecialChar ~
10596 +=\SpecialChar ~
10597 8;
10598 \family default
10599
10600 \begin_inset Quotes srd
10601 \end_inset
10602
10603  is not atomic on the 8051 even if
10604 \family typewriter
10605 counter
10606 \family default
10607  is located in data memory.
10608  Bugs like these are hard to reproduce and can cause a lot of trouble.
10609
10610 \layout Standard
10611
10612 The return address and the registers used in the interrupt service routine
10613  are saved on the stack
10614 \begin_inset LatexCommand \index{stack}
10615
10616 \end_inset
10617
10618  so there must be sufficient stack space.
10619  If there isn't variables or registers (or even the return address itself)
10620  will be corrupted.
10621  This
10622 \emph on
10623 stack overflow
10624 \emph default
10625
10626 \begin_inset LatexCommand \index{stack overflow}
10627
10628 \end_inset
10629
10630  is most likely to happen if the interrupt occurs during the
10631 \begin_inset Quotes sld
10632 \end_inset
10633
10634 deepest
10635 \begin_inset Quotes srd
10636 \end_inset
10637
10638  subroutine when the stack is already in use for f.e.
10639  many return addresses.
10640 \layout Standard
10641
10642 A special note here, int (16 bit) and long (32 bit) integer division
10643 \begin_inset LatexCommand \index{Division}
10644
10645 \end_inset
10646
10647 , multiplication
10648 \begin_inset LatexCommand \index{Multiplication}
10649
10650 \end_inset
10651
10652  & modulus
10653 \begin_inset LatexCommand \index{Modulus}
10654
10655 \end_inset
10656
10657  and floating-point
10658 \begin_inset LatexCommand \index{Floating point support}
10659
10660 \end_inset
10661
10662  operations are implemented using external support routines developed in
10663  ANSI-C.
10664  If an interrupt service routine needs to do any of these operations then
10665  the support routines (as mentioned in a following section) will have to
10666  be recompiled using the
10667 \emph on
10668  -
10669 \begin_inset ERT
10670 status Collapsed
10671
10672 \layout Standard
10673
10674 \backslash
10675 /
10676 \end_inset
10677
10678 -stack-auto
10679 \begin_inset LatexCommand \index{-\/-stack-auto}
10680
10681 \end_inset
10682
10683
10684 \emph default
10685  option and the source file will need to be compiled using the
10686 \emph on
10687 -
10688 \begin_inset ERT
10689 status Collapsed
10690
10691 \layout Standard
10692
10693 \backslash
10694 /
10695 \end_inset
10696
10697 -int-long-reent
10698 \emph default
10699
10700 \begin_inset LatexCommand \index{-\/-int-long-reent}
10701
10702 \end_inset
10703
10704  compiler option.
10705 \layout Standard
10706
10707 Calling other functions from an interrupt service routine is not recommended,
10708  avoid it if possible.
10709  Note that when some function is called from an interrupt service routine
10710  it should be preceded by a #pragma\SpecialChar ~
10711 nooverlay
10712 \begin_inset LatexCommand \index{\#pragma nooverlay}
10713
10714 \end_inset
10715
10716  if it is not reentrant.
10717  Furthermore nonreentrant functions should not be called from the main program
10718  while the interrupt service routine might be active.
10719
10720 \newline
10721
10722 \newline
10723 Also see section
10724 \begin_inset LatexCommand \ref{sub:Overlaying}
10725
10726 \end_inset
10727
10728 \SpecialChar ~
10729 about Overlaying and section
10730 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10731
10732 \end_inset
10733
10734 \SpecialChar ~
10735 about Functions using private register banks.
10736 \layout Subsection
10737
10738 MCS51/DS390 Interrupt Service Routines
10739 \layout Standard
10740
10741 Interrupt numbers and the corresponding address & descriptions for the Standard
10742  8051/8052 are listed below.
10743  SDCC will automatically adjust the interrupt vector table to the maximum
10744  interrupt number specified.
10745 \newline
10746
10747 \layout Standard
10748 \align center
10749
10750 \begin_inset  Tabular
10751 <lyxtabular version="3" rows="7" columns="3">
10752 <features>
10753 <column alignment="center" valignment="top" leftline="true" width="0in">
10754 <column alignment="center" valignment="top" leftline="true" width="0in">
10755 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10756 <row topline="true" bottomline="true">
10757 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10758 \begin_inset Text
10759
10760 \layout Standard
10761
10762 Interrupt #
10763 \end_inset
10764 </cell>
10765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10766 \begin_inset Text
10767
10768 \layout Standard
10769
10770 Description
10771 \end_inset
10772 </cell>
10773 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10774 \begin_inset Text
10775
10776 \layout Standard
10777
10778 Vector Address
10779 \end_inset
10780 </cell>
10781 </row>
10782 <row topline="true">
10783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10784 \begin_inset Text
10785
10786 \layout Standard
10787
10788 0
10789 \end_inset
10790 </cell>
10791 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10792 \begin_inset Text
10793
10794 \layout Standard
10795
10796 External 0
10797 \end_inset
10798 </cell>
10799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10800 \begin_inset Text
10801
10802 \layout Standard
10803
10804 0x0003
10805 \end_inset
10806 </cell>
10807 </row>
10808 <row topline="true">
10809 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10810 \begin_inset Text
10811
10812 \layout Standard
10813
10814 1
10815 \end_inset
10816 </cell>
10817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10818 \begin_inset Text
10819
10820 \layout Standard
10821
10822 Timer 0
10823 \end_inset
10824 </cell>
10825 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10826 \begin_inset Text
10827
10828 \layout Standard
10829
10830 0x000B
10831 \end_inset
10832 </cell>
10833 </row>
10834 <row topline="true">
10835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10836 \begin_inset Text
10837
10838 \layout Standard
10839
10840 2
10841 \end_inset
10842 </cell>
10843 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10844 \begin_inset Text
10845
10846 \layout Standard
10847
10848 External 1
10849 \end_inset
10850 </cell>
10851 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10852 \begin_inset Text
10853
10854 \layout Standard
10855
10856 0x0013
10857 \end_inset
10858 </cell>
10859 </row>
10860 <row topline="true">
10861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10862 \begin_inset Text
10863
10864 \layout Standard
10865
10866 3
10867 \end_inset
10868 </cell>
10869 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10870 \begin_inset Text
10871
10872 \layout Standard
10873
10874 Timer 1
10875 \end_inset
10876 </cell>
10877 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10878 \begin_inset Text
10879
10880 \layout Standard
10881
10882 0x001B
10883 \end_inset
10884 </cell>
10885 </row>
10886 <row topline="true">
10887 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10888 \begin_inset Text
10889
10890 \layout Standard
10891
10892 4
10893 \end_inset
10894 </cell>
10895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10896 \begin_inset Text
10897
10898 \layout Standard
10899
10900 Serial
10901 \end_inset
10902 </cell>
10903 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10904 \begin_inset Text
10905
10906 \layout Standard
10907
10908 0x0023
10909 \end_inset
10910 </cell>
10911 </row>
10912 <row topline="true" bottomline="true">
10913 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10914 \begin_inset Text
10915
10916 \layout Standard
10917
10918 5
10919 \end_inset
10920 </cell>
10921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10922 \begin_inset Text
10923
10924 \layout Standard
10925
10926 Timer 2 (8052)
10927 \end_inset
10928 </cell>
10929 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10930 \begin_inset Text
10931
10932 \layout Standard
10933
10934 0x002B
10935 \end_inset
10936 </cell>
10937 </row>
10938 </lyxtabular>
10939
10940 \end_inset
10941
10942
10943 \newline
10944
10945 \layout Standard
10946
10947 If the interrupt service routine is defined without
10948 \emph on
10949 using
10950 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10951
10952 \end_inset
10953
10954
10955 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10956
10957 \end_inset
10958
10959
10960 \emph default
10961  a register bank or with register bank 0 (
10962 \emph on
10963 using
10964 \emph default
10965  0), the compiler will save the registers used by itself on the stack upon
10966  entry and restore them at exit, however if such an interrupt service routine
10967  calls another function then the entire register bank will be saved on the
10968  stack.
10969  This scheme may be advantageous for small interrupt service routines which
10970  have low register usage.
10971 \layout Standard
10972
10973 If the interrupt service routine is defined to be using a specific register
10974  bank then only
10975 \emph on
10976 a, b, dptr
10977 \emph default
10978  & psw are saved and restored, if such an interrupt service routine calls
10979  another function (using another register bank) then the entire register
10980  bank of the called function will be saved on the stack.
10981  This scheme is recommended for larger interrupt service routines.
10982 \layout Subsection
10983
10984 HC08 Interrupt Service Routines
10985 \layout Standard
10986
10987 Since the number of interrupts available is chip specific and the interrupt
10988  vector table always ends at the last byte of memory, the interrupt numbers
10989  corresponds to the interrupt vectors in reverse order of address.
10990  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
10991  2 will use the interrupt vector at 0xfffa, and so on.
10992  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
10993  this way; instead see section
10994 \begin_inset LatexCommand \ref{sub:Startup-Code}
10995
10996 \end_inset
10997
10998  for details on customizing startup.
10999 \layout Subsection
11000
11001 Z80 Interrupt Service Routines
11002 \layout Standard
11003
11004 The Z80 uses several different methods for determining the correct interrupt
11005  vector depending on the hardware implementation.
11006  Therefore, SDCC ignores the optional interrupt number and does not attempt
11007  to generate an interrupt vector table.
11008 \layout Standard
11009
11010 By default, SDCC generates code for a maskable interrupt, which uses an
11011  RETI instruction to return from the interrupt.
11012  To write an interrupt handler for the non-maskable interrupt, which needs
11013  an RETN instruction instead, add the
11014 \emph on
11015 critical
11016 \emph default
11017  keyword:
11018 \layout Verse
11019
11020
11021 \family typewriter
11022 void nmi_isr (void) critical interrupt
11023 \newline
11024 {
11025 \newline
11026 \SpecialChar ~
11027 \SpecialChar ~
11028 \SpecialChar ~
11029 \SpecialChar ~
11030 ...
11031
11032 \newline
11033 }
11034 \layout Section
11035
11036 Enabling and Disabling Interrupts
11037 \layout Subsection
11038
11039 Critical Functions and Critical Statements
11040 \layout Standard
11041
11042 A special keyword may be associated with a block or a function declaring
11043  it as
11044 \emph on
11045 critical
11046 \emph default
11047 .
11048  SDCC will generate code to disable all interrupts
11049 \begin_inset LatexCommand \index{interrupt}
11050
11051 \end_inset
11052
11053  upon entry to a critical function and restore the interrupt enable to the
11054  previous state before returning.
11055  Nesting critical functions will need one additional byte on the stack
11056 \begin_inset LatexCommand \index{stack}
11057
11058 \end_inset
11059
11060  for each call.
11061 \layout Verse
11062
11063
11064 \family typewriter
11065 int foo () critical
11066 \begin_inset LatexCommand \index{critical}
11067
11068 \end_inset
11069
11070
11071 \begin_inset LatexCommand \index{\_\_critical}
11072
11073 \end_inset
11074
11075
11076 \newline
11077 {
11078 \newline
11079 \SpecialChar ~
11080 \SpecialChar ~
11081 \SpecialChar ~
11082 \SpecialChar ~
11083 ...
11084
11085 \newline
11086 \SpecialChar ~
11087 \SpecialChar ~
11088 \SpecialChar ~
11089 \SpecialChar ~
11090 ...
11091
11092 \newline
11093 }
11094 \layout Standard
11095
11096 The critical attribute maybe used with other attributes like
11097 \emph on
11098 reentrant.
11099 \emph default
11100
11101 \newline
11102 The keyword
11103 \emph on
11104 critical
11105 \emph default
11106  may also be used to disable interrupts more locally:
11107 \layout Verse
11108
11109
11110 \family typewriter
11111 critical{ i++; }
11112 \layout Standard
11113
11114 More than one statement could have been included in the block.
11115 \layout Subsection
11116
11117 Enabling and Disabling Interrupts directly
11118 \layout Standard
11119
11120 Interrupts
11121 \begin_inset LatexCommand \index{interrupt}
11122
11123 \end_inset
11124
11125  can also be disabled and enabled directly (8051):
11126 \layout Verse
11127
11128
11129 \family typewriter
11130 EA = 0;\SpecialChar ~
11131 \SpecialChar ~
11132 \SpecialChar ~
11133 \SpecialChar ~
11134 \SpecialChar ~
11135 \SpecialChar ~
11136 \SpecialChar ~
11137 \SpecialChar ~
11138 \SpecialChar ~
11139 \SpecialChar ~
11140 \SpecialChar ~
11141 \SpecialChar ~
11142 or:\SpecialChar ~
11143 \SpecialChar ~
11144 \SpecialChar ~
11145 \SpecialChar ~
11146 \SpecialChar ~
11147 \SpecialChar ~
11148 \SpecialChar ~
11149 \SpecialChar ~
11150 \SpecialChar ~
11151 \SpecialChar ~
11152 \SpecialChar ~
11153 EA_SAVE = EA;
11154 \layout Verse
11155
11156
11157 \family typewriter
11158 ...\SpecialChar ~
11159 \SpecialChar ~
11160 \SpecialChar ~
11161 \SpecialChar ~
11162 \SpecialChar ~
11163 \SpecialChar ~
11164 \SpecialChar ~
11165 \SpecialChar ~
11166 \SpecialChar ~
11167 \SpecialChar ~
11168 \SpecialChar ~
11169 \SpecialChar ~
11170 \SpecialChar ~
11171 \SpecialChar ~
11172 \SpecialChar ~
11173 \SpecialChar ~
11174 \SpecialChar ~
11175 \SpecialChar ~
11176 \SpecialChar ~
11177 \SpecialChar ~
11178 \SpecialChar ~
11179 \SpecialChar ~
11180 \SpecialChar ~
11181 \SpecialChar ~
11182 \SpecialChar ~
11183 \SpecialChar ~
11184 \SpecialChar ~
11185 \SpecialChar ~
11186 \SpecialChar ~
11187 \SpecialChar ~
11188 EA = 0;
11189 \layout Verse
11190
11191
11192 \family typewriter
11193 EA = 1;\SpecialChar ~
11194 \SpecialChar ~
11195 \SpecialChar ~
11196 \SpecialChar ~
11197 \SpecialChar ~
11198 \SpecialChar ~
11199 \SpecialChar ~
11200 \SpecialChar ~
11201 \SpecialChar ~
11202 \SpecialChar ~
11203 \SpecialChar ~
11204 \SpecialChar ~
11205 \SpecialChar ~
11206 \SpecialChar ~
11207 \SpecialChar ~
11208 \SpecialChar ~
11209 \SpecialChar ~
11210 \SpecialChar ~
11211 \SpecialChar ~
11212 \SpecialChar ~
11213 \SpecialChar ~
11214 \SpecialChar ~
11215 \SpecialChar ~
11216 \SpecialChar ~
11217 \SpecialChar ~
11218 \SpecialChar ~
11219 ...
11220 \layout Verse
11221
11222
11223 \family typewriter
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 \SpecialChar ~
11246 \SpecialChar ~
11247 \SpecialChar ~
11248 \SpecialChar ~
11249 \SpecialChar ~
11250 \SpecialChar ~
11251 \SpecialChar ~
11252 \SpecialChar ~
11253 \SpecialChar ~
11254 \SpecialChar ~
11255 \SpecialChar ~
11256 \SpecialChar ~
11257 EA = EA_SAVE;
11258 \layout Standard
11259
11260 On other architectures which have seperate opcodes for enabling and disabling
11261  interrupts you might want to make use of defines with inline assembly
11262 \begin_inset LatexCommand \index{Assembler routines}
11263
11264 \end_inset
11265
11266  (HC08):
11267 \layout Verse
11268
11269
11270 \family typewriter
11271 #define CLI _asm
11272 \begin_inset LatexCommand \index{\_asm}
11273
11274 \end_inset
11275
11276 \SpecialChar ~
11277 \SpecialChar ~
11278 cli\SpecialChar ~
11279 \SpecialChar ~
11280 _endasm
11281 \begin_inset LatexCommand \index{\_endasm}
11282
11283 \end_inset
11284
11285 ;
11286 \layout Verse
11287
11288
11289 \family typewriter
11290 #define SEI _asm\SpecialChar ~
11291 \SpecialChar ~
11292 sei\SpecialChar ~
11293 \SpecialChar ~
11294 _endasm;
11295 \layout Verse
11296
11297
11298 \family typewriter
11299 ...
11300 \layout Standard
11301
11302 Note: it is sometimes sufficient to disable only a specific interrupt source
11303  like f.e.
11304  a timer or serial interrupt by manipulating an
11305 \emph on
11306 interrupt mask
11307 \begin_inset LatexCommand \index{interrupt mask}
11308
11309 \end_inset
11310
11311
11312 \emph default
11313  register.
11314
11315 \layout Standard
11316
11317 Usually the time during which interrupts are disabled should be kept as
11318  short as possible.
11319  This minimizes both
11320 \emph on
11321 interrupt latency
11322 \emph default
11323
11324 \begin_inset LatexCommand \index{interrupt latency}
11325
11326 \end_inset
11327
11328  (the time between the occurrence of the interrupt and the execution of
11329  the first code in the interrupt routine) and
11330 \emph on
11331 interrupt jitter
11332 \emph default
11333
11334 \begin_inset LatexCommand \index{interrupt jitter}
11335
11336 \end_inset
11337
11338  (the difference between the shortest and the longest interrupt latency).
11339  These really are something different, f.e.
11340  a serial interrupt has to be served before its buffer overruns so it cares
11341  for the maximum interrupt latency, whereas it does not care about jitter.
11342  On a loudspeaker driven via a digital to analog converter which is fed
11343  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11344  a much smaller jitter will be very audible.
11345 \layout Standard
11346
11347 You can reenable interrupts within an interrupt routine and on some architecture
11348 s you can make use of two (or more) levels of
11349 \emph on
11350 interrupt priorities
11351 \emph default
11352
11353 \begin_inset LatexCommand \index{interrupt priority}
11354
11355 \end_inset
11356
11357 .
11358  On some architectures which don't support interrupt priorities these can
11359  be implemented by manipulating the interrupt mask and reenabling interrupts
11360  within the interrupt routine.
11361  Check there is sufficient space on the stack
11362 \begin_inset LatexCommand \index{stack}
11363
11364 \end_inset
11365
11366  and don't add complexity unless you have to.
11367
11368 \layout Subsection
11369
11370 Semaphore
11371 \begin_inset LatexCommand \index{semaphore}
11372
11373 \end_inset
11374
11375  locking (mcs51/ds390)
11376 \layout Standard
11377
11378 Some architectures (mcs51/ds390) have an atomic
11379 \begin_inset LatexCommand \index{atomic}
11380
11381 \end_inset
11382
11383  bit test and
11384 \emph on
11385
11386 \emph default
11387 clear
11388 \emph on
11389
11390 \emph default
11391 instruction.
11392  These type of instructions are typically used in preemptive multitasking
11393  systems, where a routine f.e.
11394  claims the use of a data structure ('acquires a lock
11395 \begin_inset LatexCommand \index{lock}
11396
11397 \end_inset
11398
11399  on it'), makes some modifications and then releases the lock when the data
11400  structure is consistent again.
11401  The instruction may also be used if interrupt and non-interrupt code have
11402  to compete for a resource.
11403  With the atomic bit test and clear instruction interrupts
11404 \begin_inset LatexCommand \index{interrupt}
11405
11406 \end_inset
11407
11408  don't have to be disabled for the locking operation.
11409
11410 \layout Standard
11411
11412 SDCC generates this instruction if the source follows this pattern:
11413 \layout Verse
11414
11415
11416 \family typewriter
11417 volatile
11418 \begin_inset LatexCommand \index{volatile}
11419
11420 \end_inset
11421
11422  bit resource_is_free;
11423 \newline
11424
11425 \newline
11426 if (resource_is_free)
11427 \newline
11428 \SpecialChar ~
11429 \SpecialChar ~
11430 {
11431 \newline
11432 \SpecialChar ~
11433 \SpecialChar ~
11434 \SpecialChar ~
11435 \SpecialChar ~
11436 resource_is_free=0;
11437 \newline
11438 \SpecialChar ~
11439 \SpecialChar ~
11440 \SpecialChar ~
11441 \SpecialChar ~
11442 ...
11443
11444 \newline
11445 \SpecialChar ~
11446 \SpecialChar ~
11447 \SpecialChar ~
11448 \SpecialChar ~
11449 resource_is_free=1;
11450 \newline
11451 \SpecialChar ~
11452 \SpecialChar ~
11453 }
11454 \layout Standard
11455
11456 Note, mcs51 and ds390 support only an atomic
11457 \begin_inset LatexCommand \index{atomic}
11458
11459 \end_inset
11460
11461  bit test and
11462 \emph on
11463 clear
11464 \emph default
11465  instruction (as opposed to atomic bit test and
11466 \emph on
11467 set).
11468 \layout Section
11469
11470 Functions using private register banks
11471 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11472
11473 \end_inset
11474
11475  (mcs51/ds390)
11476 \layout Standard
11477
11478 Some architectures have support for quickly changing register sets.
11479  SDCC supports this feature with the
11480 \emph on
11481 using
11482 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11483
11484 \end_inset
11485
11486
11487 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11488
11489 \end_inset
11490
11491
11492 \emph default
11493  attribute (which tells the compiler to use a register bank
11494 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11495
11496 \end_inset
11497
11498  other than the default bank zero).
11499  It should only be applied to
11500 \emph on
11501 interrupt
11502 \begin_inset LatexCommand \index{interrupt}
11503
11504 \end_inset
11505
11506
11507 \emph default
11508  functions (see footnote below).
11509  This will in most circumstances make the generated ISR code more efficient
11510  since it will not have to save registers on the stack.
11511 \layout Standard
11512
11513 The
11514 \emph on
11515 using
11516 \emph default
11517  attribute will have no effect on the generated code for a
11518 \emph on
11519 non-interrupt
11520 \emph default
11521  function (but may occasionally be useful anyway
11522 \begin_inset Foot
11523 collapsed false
11524
11525 \layout Standard
11526
11527 possible exception: if a function is called ONLY from 'interrupt' functions
11528  using a particular bank, it can be declared with the same 'using' attribute
11529  as the calling 'interrupt' functions.
11530  For instance, if you have several ISRs using bank one, and all of them
11531  call memcpy(), it might make sense to create a specialized version of memcpy()
11532  'using 1', since this would prevent the ISR from having to save bank zero
11533  to the stack on entry and switch to bank zero before calling the function
11534 \end_inset
11535
11536 ).
11537 \newline
11538
11539 \emph on
11540 (pending: I don't think this has been done yet)
11541 \layout Standard
11542
11543 An
11544 \emph on
11545 interrupt
11546 \emph default
11547  function using a non-zero bank will assume that it can trash that register
11548  bank, and will not save it.
11549  Since high-priority interrupts
11550 \begin_inset LatexCommand \index{interrupts}
11551
11552 \end_inset
11553
11554
11555 \begin_inset LatexCommand \index{interrupt priority}
11556
11557 \end_inset
11558
11559  can interrupt low-priority ones on the 8051 and friends, this means that
11560  if a high-priority ISR
11561 \emph on
11562 using
11563 \emph default
11564  a particular bank occurs while processing a low-priority ISR
11565 \emph on
11566 using
11567 \emph default
11568  the same bank, terrible and bad things can happen.
11569  To prevent this, no single register bank should be
11570 \emph on
11571 used
11572 \emph default
11573  by both a high priority and a low priority ISR.
11574  This is probably most easily done by having all high priority ISRs use
11575  one bank and all low priority ISRs use another.
11576  If you have an ISR which can change priority at runtime, you're on your
11577  own: I suggest using the default bank zero and taking the small performance
11578  hit.
11579 \layout Standard
11580
11581 It is most efficient if your ISR calls no other functions.
11582  If your ISR must call other functions, it is most efficient if those functions
11583  use the same bank as the ISR (see note 1 below); the next best is if the
11584  called functions use bank zero.
11585  It is very inefficient to call a function using a different, non-zero bank
11586  from an ISR.
11587
11588 \layout Section
11589
11590 Startup Code
11591 \begin_inset LatexCommand \label{sub:Startup-Code}
11592
11593 \end_inset
11594
11595
11596 \begin_inset LatexCommand \index{Startup code}
11597
11598 \end_inset
11599
11600
11601 \layout Subsection
11602
11603 MCS51/DS390 Startup Code
11604 \layout Standard
11605
11606 The compiler inserts a call to the C routine
11607 \emph on
11608 _sdcc_external_startup()
11609 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11610
11611 \end_inset
11612
11613
11614 \series bold
11615 \emph default
11616
11617 \series default
11618 at the start of the CODE area.
11619  This routine is in the runtime library
11620 \begin_inset LatexCommand \index{Runtime library}
11621
11622 \end_inset
11623
11624 .
11625  By default this routine returns 0, if this routine returns a non-zero value,
11626  the static & global variable initialization will be skipped and the function
11627  main will be invoked.
11628  Otherwise static & global variables will be initialized before the function
11629  main is invoked.
11630  You could add a
11631 \emph on
11632 _sdcc_external_startup()
11633 \emph default
11634  routine to your program to override the default if you need to setup hardware
11635  or perform some other critical operation prior to static & global variable
11636  initialization
11637 \begin_inset LatexCommand \index{Variable initialization}
11638
11639 \end_inset
11640
11641 .
11642  On some mcs51 variants xdata
11643 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11644
11645 \end_inset
11646
11647  memory has to be explicitly enabled before it can be accessed or if the
11648  watchdog needs to be disabled, this is the place to do it.
11649  The startup code clears all internal data memory, 256 bytes by default,
11650  but from 0 to n-1 if
11651 \emph on
11652 -
11653 \begin_inset ERT
11654 status Collapsed
11655
11656 \layout Standard
11657
11658 \backslash
11659 /
11660 \end_inset
11661
11662 -iram-size
11663 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
11664
11665 \end_inset
11666
11667 n
11668 \emph default
11669  is used.
11670  (recommended for Chipcon CC1010).
11671 \layout Standard
11672
11673 See also the compiler option
11674 \emph on
11675 -
11676 \begin_inset ERT
11677 status Collapsed
11678
11679 \layout Standard
11680
11681 \backslash
11682 /
11683 \end_inset
11684
11685 -no-xinit
11686 \emph default
11687 -
11688 \emph on
11689 opt
11690 \emph default
11691
11692 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11693
11694 \end_inset
11695
11696  and section
11697 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11698
11699 \end_inset
11700
11701 \SpecialChar ~
11702 about MCS51-variants.
11703 \layout Subsection
11704
11705 HC08 Startup Code
11706 \layout Standard
11707
11708 The HC08 startup code follows the same scheme as the MCS51 startup code.
11709 \layout Subsection
11710
11711 Z80 Startup Code
11712 \layout Standard
11713
11714 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11715  from sdcc/device/lib/z80/crt0.s.
11716  If you need a different startup code you can use the compiler option
11717 \emph on
11718 -
11719 \series bold
11720 \emph default
11721
11722 \begin_inset ERT
11723 status Collapsed
11724
11725 \layout Standard
11726
11727 \backslash
11728 /
11729 \end_inset
11730
11731
11732 \series default
11733 \emph on
11734 -no-std-crt0
11735 \emph default
11736
11737 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11738
11739 \end_inset
11740
11741  and provide your own crt0.o.
11742
11743 \layout Section
11744
11745 Inline Assembler Code
11746 \begin_inset LatexCommand \index{Assembler routines}
11747
11748 \end_inset
11749
11750
11751 \layout Subsection
11752
11753 A Step by Step Introduction
11754 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11755
11756 \end_inset
11757
11758
11759 \layout Standard
11760
11761 Starting from a small snippet of c-code this example shows for the MCS51
11762  how to use inline assembly, access variables, a function parameter and
11763  an array in xdata memory.
11764  The example uses an MCS51 here but is easily adapted for other architectures.
11765  This is a buffer routine which should be optimized:
11766 \layout Verse
11767
11768
11769 \family typewriter
11770 \size footnotesize
11771 unsigned char far
11772 \begin_inset LatexCommand \index{far (storage class)}
11773
11774 \end_inset
11775
11776
11777 \begin_inset LatexCommand \index{\_\_far (storage class)}
11778
11779 \end_inset
11780
11781  at
11782 \begin_inset LatexCommand \index{at}
11783
11784 \end_inset
11785
11786
11787 \begin_inset LatexCommand \index{\_\_at}
11788
11789 \end_inset
11790
11791  0x7f00 buf[0x100];
11792 \begin_inset LatexCommand \index{Aligned array}
11793
11794 \end_inset
11795
11796
11797 \newline
11798 unsigned char head,tail;
11799 \newline
11800
11801 \newline
11802 void to_buffer( unsigned char c )
11803 \newline
11804 {
11805 \newline
11806 \SpecialChar ~
11807 \SpecialChar ~
11808 \SpecialChar ~
11809 \SpecialChar ~
11810 if( head != tail-1 )
11811 \newline
11812 \SpecialChar ~
11813 \SpecialChar ~
11814 \SpecialChar ~
11815 \SpecialChar ~
11816 \SpecialChar ~
11817 \SpecialChar ~
11818 \SpecialChar ~
11819 \SpecialChar ~
11820 buf[ head++ ] = c;\SpecialChar ~
11821 \SpecialChar ~
11822 \SpecialChar ~
11823 \SpecialChar ~
11824 /* access to a 256 byte aligned array */
11825 \newline
11826 }
11827 \layout Standard
11828
11829 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
11830  then a corresponding buffer.asm file is generated.
11831  We define a new function
11832 \family typewriter
11833 to_buffer_asm()
11834 \family default
11835  in file buffer.c in which we cut and paste the generated code, removing
11836  unwanted comments and some ':'.
11837  Then add
11838 \begin_inset Quotes sld
11839 \end_inset
11840
11841 _asm
11842 \begin_inset Quotes srd
11843 \end_inset
11844
11845  and
11846 \begin_inset Quotes sld
11847 \end_inset
11848
11849 _endasm;
11850 \begin_inset Quotes srd
11851 \end_inset
11852
11853  to the beginning and the end of the function body:
11854 \layout Verse
11855
11856
11857 \family typewriter
11858 \size footnotesize
11859 /* With a cut and paste from the .asm file, we have something to start with.
11860 \newline
11861 \SpecialChar ~
11862 \SpecialChar ~
11863 \SpecialChar ~
11864 The function is not yet OK! (registers aren't saved) */
11865 \newline
11866 void to_buffer_asm( unsigned char c )
11867 \newline
11868 {
11869 \newline
11870 \SpecialChar ~
11871 \SpecialChar ~
11872 \SpecialChar ~
11873 \SpecialChar ~
11874 _asm
11875 \begin_inset LatexCommand \index{\_asm}
11876
11877 \end_inset
11878
11879
11880 \begin_inset LatexCommand \index{\_\_asm}
11881
11882 \end_inset
11883
11884
11885 \newline
11886 \SpecialChar ~
11887 \SpecialChar ~
11888 \SpecialChar ~
11889 \SpecialChar ~
11890 mov\SpecialChar ~
11891 \SpecialChar ~
11892 r2,dpl
11893 \newline
11894 ;buffer.c if( head != tail-1 )
11895 \newline
11896 \SpecialChar ~
11897 \SpecialChar ~
11898 \SpecialChar ~
11899 \SpecialChar ~
11900 mov\SpecialChar ~
11901 \SpecialChar ~
11902 a,_tail
11903 \newline
11904 \SpecialChar ~
11905 \SpecialChar ~
11906 \SpecialChar ~
11907 \SpecialChar ~
11908 dec\SpecialChar ~
11909 \SpecialChar ~
11910 a
11911 \newline
11912 \SpecialChar ~
11913 \SpecialChar ~
11914 \SpecialChar ~
11915 \SpecialChar ~
11916 mov\SpecialChar ~
11917 \SpecialChar ~
11918 r3,a
11919 \newline
11920 \SpecialChar ~
11921 \SpecialChar ~
11922 \SpecialChar ~
11923 \SpecialChar ~
11924 mov\SpecialChar ~
11925 \SpecialChar ~
11926 a,_head
11927 \newline
11928 \SpecialChar ~
11929 \SpecialChar ~
11930 \SpecialChar ~
11931 \SpecialChar ~
11932 cjne a,ar3,00106$
11933 \newline
11934 \SpecialChar ~
11935 \SpecialChar ~
11936 \SpecialChar ~
11937 \SpecialChar ~
11938 ret
11939 \newline
11940 00106$:
11941 \newline
11942 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
11943 \begin_inset LatexCommand \index{Aligned array}
11944
11945 \end_inset
11946
11947
11948 \newline
11949 \SpecialChar ~
11950 \SpecialChar ~
11951 \SpecialChar ~
11952 \SpecialChar ~
11953 mov\SpecialChar ~
11954 \SpecialChar ~
11955 r3,_head
11956 \newline
11957 \SpecialChar ~
11958 \SpecialChar ~
11959 \SpecialChar ~
11960 \SpecialChar ~
11961 inc\SpecialChar ~
11962 \SpecialChar ~
11963 _head
11964 \newline
11965 \SpecialChar ~
11966 \SpecialChar ~
11967 \SpecialChar ~
11968 \SpecialChar ~
11969 mov\SpecialChar ~
11970 \SpecialChar ~
11971 dpl,r3
11972 \newline
11973 \SpecialChar ~
11974 \SpecialChar ~
11975 \SpecialChar ~
11976 \SpecialChar ~
11977 mov\SpecialChar ~
11978 \SpecialChar ~
11979 dph,#(_buf >> 8)
11980 \newline
11981 \SpecialChar ~
11982 \SpecialChar ~
11983 \SpecialChar ~
11984 \SpecialChar ~
11985 mov\SpecialChar ~
11986 \SpecialChar ~
11987 a,r2
11988 \newline
11989 \SpecialChar ~
11990 \SpecialChar ~
11991 \SpecialChar ~
11992 \SpecialChar ~
11993 movx @dptr,a
11994 \newline
11995 00103$:
11996 \newline
11997 \SpecialChar ~
11998 \SpecialChar ~
11999 \SpecialChar ~
12000 \SpecialChar ~
12001 ret
12002 \newline
12003 \SpecialChar ~
12004 \SpecialChar ~
12005 \SpecialChar ~
12006 \SpecialChar ~
12007 _endasm
12008 \begin_inset LatexCommand \index{\_endasm}
12009
12010 \end_inset
12011
12012
12013 \begin_inset LatexCommand \index{\_\_endasm}
12014
12015 \end_inset
12016
12017 ;
12018 \newline
12019 }
12020 \layout Standard
12021
12022 The new file buffer.c should compile with only one warning about the unreferenced
12023  function argument 'c'.
12024  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12025  (1) and finally have:
12026 \layout Verse
12027
12028
12029 \family typewriter
12030 \size footnotesize
12031 unsigned char far at 0x7f00 buf[0x100];
12032 \newline
12033 unsigned char head,tail;
12034 \newline
12035 #define USE_ASSEMBLY (1)
12036 \newline
12037
12038 \newline
12039 #if !USE_ASSEMBLY
12040 \newline
12041
12042 \newline
12043 void to_buffer( unsigned char c )
12044 \newline
12045 {
12046 \newline
12047 \SpecialChar ~
12048 \SpecialChar ~
12049 \SpecialChar ~
12050 \SpecialChar ~
12051 if( head != tail-1 )
12052 \newline
12053 \SpecialChar ~
12054 \SpecialChar ~
12055 \SpecialChar ~
12056 \SpecialChar ~
12057 \SpecialChar ~
12058 \SpecialChar ~
12059 \SpecialChar ~
12060 \SpecialChar ~
12061 buf[ head++ ] = c;
12062 \newline
12063 }
12064 \newline
12065
12066 \newline
12067 #else
12068 \newline
12069
12070 \newline
12071 void to_buffer( unsigned char c )
12072 \newline
12073 {
12074 \newline
12075 \SpecialChar ~
12076 \SpecialChar ~
12077 \SpecialChar ~
12078 \SpecialChar ~
12079 c; // to avoid warning: unreferenced function argument
12080 \newline
12081 \SpecialChar ~
12082 \SpecialChar ~
12083 \SpecialChar ~
12084 \SpecialChar ~
12085 _asm
12086 \begin_inset LatexCommand \index{\_asm}
12087
12088 \end_inset
12089
12090
12091 \begin_inset LatexCommand \index{\_\_asm}
12092
12093 \end_inset
12094
12095
12096 \newline
12097 \SpecialChar ~
12098 \SpecialChar ~
12099 \SpecialChar ~
12100 \SpecialChar ~
12101 \SpecialChar ~
12102 \SpecialChar ~
12103 \SpecialChar ~
12104 \SpecialChar ~
12105 ; save used registers here.
12106
12107 \newline
12108 \SpecialChar ~
12109 \SpecialChar ~
12110 \SpecialChar ~
12111 \SpecialChar ~
12112 \SpecialChar ~
12113 \SpecialChar ~
12114 \SpecialChar ~
12115 \SpecialChar ~
12116 ; If we were still using r2,r3 we would have to push them here.
12117
12118 \newline
12119 ; if( head != tail-1 )
12120 \newline
12121 \SpecialChar ~
12122 \SpecialChar ~
12123 \SpecialChar ~
12124 \SpecialChar ~
12125 \SpecialChar ~
12126 \SpecialChar ~
12127 \SpecialChar ~
12128 \SpecialChar ~
12129 mov\SpecialChar ~
12130  a,_tail
12131 \newline
12132 \SpecialChar ~
12133 \SpecialChar ~
12134 \SpecialChar ~
12135 \SpecialChar ~
12136 \SpecialChar ~
12137 \SpecialChar ~
12138 \SpecialChar ~
12139 \SpecialChar ~
12140 dec\SpecialChar ~
12141  a
12142 \newline
12143 \SpecialChar ~
12144 \SpecialChar ~
12145 \SpecialChar ~
12146 \SpecialChar ~
12147 \SpecialChar ~
12148 \SpecialChar ~
12149 \SpecialChar ~
12150 \SpecialChar ~
12151 xrl\SpecialChar ~
12152  a,_head
12153 \newline
12154 \SpecialChar ~
12155 \SpecialChar ~
12156 \SpecialChar ~
12157 \SpecialChar ~
12158 \SpecialChar ~
12159 \SpecialChar ~
12160 \SpecialChar ~
12161 \SpecialChar ~
12162 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
12163 \newline
12164 \SpecialChar ~
12165 \SpecialChar ~
12166 \SpecialChar ~
12167 \SpecialChar ~
12168 \SpecialChar ~
12169 \SpecialChar ~
12170 \SpecialChar ~
12171 \SpecialChar ~
12172 jz\SpecialChar ~
12173 \SpecialChar ~
12174  t_b_end$
12175 \newline
12176 \SpecialChar ~
12177 \SpecialChar ~
12178 \SpecialChar ~
12179 \SpecialChar ~
12180 \SpecialChar ~
12181 \SpecialChar ~
12182 \SpecialChar ~
12183 \SpecialChar ~
12184 ;
12185 \newline
12186 ; buf[ head++ ] = c;
12187 \newline
12188 \SpecialChar ~
12189 \SpecialChar ~
12190 \SpecialChar ~
12191 \SpecialChar ~
12192 \SpecialChar ~
12193 \SpecialChar ~
12194 \SpecialChar ~
12195 \SpecialChar ~
12196 mov\SpecialChar ~
12197  a,dpl \SpecialChar ~
12198 \SpecialChar ~
12199 \SpecialChar ~
12200 \SpecialChar ~
12201 \SpecialChar ~
12202 \SpecialChar ~
12203 \SpecialChar ~
12204 ; dpl holds lower byte of function argument
12205 \newline
12206 \SpecialChar ~
12207 \SpecialChar ~
12208 \SpecialChar ~
12209 \SpecialChar ~
12210 \SpecialChar ~
12211 \SpecialChar ~
12212 \SpecialChar ~
12213 \SpecialChar ~
12214 mov\SpecialChar ~
12215  dpl,_head \SpecialChar ~
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 ; buf is 0x100 byte aligned so head can be used directly
12219 \newline
12220 \SpecialChar ~
12221 \SpecialChar ~
12222 \SpecialChar ~
12223 \SpecialChar ~
12224 \SpecialChar ~
12225 \SpecialChar ~
12226 \SpecialChar ~
12227 \SpecialChar ~
12228 mov\SpecialChar ~
12229  dph,#(_buf>>8)
12230 \newline
12231 \SpecialChar ~
12232 \SpecialChar ~
12233 \SpecialChar ~
12234 \SpecialChar ~
12235 \SpecialChar ~
12236 \SpecialChar ~
12237 \SpecialChar ~
12238 \SpecialChar ~
12239 movx @dptr,a
12240 \newline
12241 \SpecialChar ~
12242 \SpecialChar ~
12243 \SpecialChar ~
12244 \SpecialChar ~
12245 \SpecialChar ~
12246 \SpecialChar ~
12247 \SpecialChar ~
12248 \SpecialChar ~
12249 inc \SpecialChar ~
12250 _head
12251 \newline
12252 \SpecialChar ~
12253 \SpecialChar ~
12254 \SpecialChar ~
12255 \SpecialChar ~
12256 \SpecialChar ~
12257 \SpecialChar ~
12258 \SpecialChar ~
12259 \SpecialChar ~
12260 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
12261 \newline
12262 t_b_end$:
12263 \newline
12264 \SpecialChar ~
12265 \SpecialChar ~
12266 \SpecialChar ~
12267 \SpecialChar ~
12268 \SpecialChar ~
12269 \SpecialChar ~
12270 \SpecialChar ~
12271 \SpecialChar ~
12272 ; restore used registers here
12273 \newline
12274 \SpecialChar ~
12275 \SpecialChar ~
12276 \SpecialChar ~
12277 \SpecialChar ~
12278 _endasm
12279 \begin_inset LatexCommand \index{\_endasm}
12280
12281 \end_inset
12282
12283
12284 \begin_inset LatexCommand \index{\_\_endasm}
12285
12286 \end_inset
12287
12288 ;
12289 \newline
12290 }
12291 \newline
12292 #endif
12293 \layout Standard
12294
12295 The inline assembler code can contain any valid code understood by the assembler
12296 , this includes any assembler directives and comment lines
12297 \begin_inset Foot
12298 collapsed false
12299
12300 \layout Standard
12301
12302 The assembler does not like some characters like ':' or ''' in comments.
12303  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
12304 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
12305
12306 \end_inset
12307
12308
12309 \begin_inset LatexCommand \index{Assembler documentation}
12310
12311 \end_inset
12312
12313
12314 \end_inset
12315
12316 .
12317  The compiler does not do any validation of the code within the
12318 \family typewriter
12319 _asm
12320 \begin_inset LatexCommand \index{\_asm}
12321
12322 \end_inset
12323
12324
12325 \begin_inset LatexCommand \index{\_\_asm}
12326
12327 \end_inset
12328
12329  ...
12330  _endasm
12331 \size footnotesize
12332
12333 \begin_inset LatexCommand \index{\_endasm}
12334
12335 \end_inset
12336
12337
12338 \begin_inset LatexCommand \index{\_\_endasm}
12339
12340 \end_inset
12341
12342
12343 \size default
12344 ;
12345 \family default
12346  keyword pair.
12347  Specifically it will not know which registers are used and thus register
12348  pushing/popping
12349 \begin_inset LatexCommand \index{push/pop}
12350
12351 \end_inset
12352
12353  has to be done manually.
12354
12355 \layout Standard
12356
12357 It is recommended that each assembly instruction (including labels) be placed
12358  in a separate line (as the example shows).
12359  When the -
12360 \begin_inset ERT
12361 status Collapsed
12362
12363 \layout Standard
12364
12365 \backslash
12366 /
12367 \end_inset
12368
12369 -
12370 \emph on
12371 peep-asm
12372 \begin_inset LatexCommand \index{-\/-peep-asm}
12373
12374 \end_inset
12375
12376
12377 \emph default
12378  command line option is used, the inline assembler code will be passed through
12379  the peephole optimizer
12380 \begin_inset LatexCommand \index{Peephole optimizer}
12381
12382 \end_inset
12383
12384 .
12385  There are only a few (if any) cases where this option makes sense, it might
12386  cause some unexpected changes in the inline assembler code.
12387  Please go through the peephole optimizer rules defined in file
12388 \emph on
12389 SDCCpeeph.def
12390 \emph default
12391  before using this option.
12392 \layout Subsection
12393
12394 Naked Functions
12395 \begin_inset LatexCommand \label{sub:Naked-Functions}
12396
12397 \end_inset
12398
12399
12400 \begin_inset LatexCommand \index{Naked functions}
12401
12402 \end_inset
12403
12404
12405 \layout Standard
12406
12407 A special keyword may be associated with a function declaring it as
12408 \emph on
12409 _naked
12410 \begin_inset LatexCommand \index{\_naked}
12411
12412 \end_inset
12413
12414
12415 \begin_inset LatexCommand \index{\_\_naked}
12416
12417 \end_inset
12418
12419 .
12420
12421 \emph default
12422 The
12423 \emph on
12424 _naked
12425 \emph default
12426  function modifier attribute prevents the compiler from generating prologue
12427 \begin_inset LatexCommand \index{function prologue}
12428
12429 \end_inset
12430
12431  and epilogue
12432 \begin_inset LatexCommand \index{function epilogue}
12433
12434 \end_inset
12435
12436  code for that function.
12437  This means that the user is entirely responsible for such things as saving
12438  any registers that may need to be preserved, selecting the proper register
12439  bank, generating the
12440 \emph on
12441 return
12442 \emph default
12443  instruction at the end, etc.
12444  Practically, this means that the contents of the function must be written
12445  in inline assembler.
12446  This is particularly useful for interrupt functions, which can have a large
12447  (and often unnecessary) prologue/epilogue.
12448  For example, compare the code generated by these two functions:
12449 \layout Verse
12450
12451
12452 \family typewriter
12453 volatile
12454 \begin_inset LatexCommand \index{volatile}
12455
12456 \end_inset
12457
12458  data unsigned char counter;
12459 \newline
12460
12461 \newline
12462 void simpleInterrupt(void) interrupt
12463 \begin_inset LatexCommand \index{interrupt}
12464
12465 \end_inset
12466
12467
12468 \begin_inset LatexCommand \index{\_\_interrupt}
12469
12470 \end_inset
12471
12472  1
12473 \newline
12474 {
12475 \newline
12476 \SpecialChar ~
12477 \SpecialChar ~
12478 \SpecialChar ~
12479 \SpecialChar ~
12480 counter++;
12481 \newline
12482 }
12483 \newline
12484
12485 \newline
12486 void nakedInterrupt(void) interrupt 2 _naked
12487 \newline
12488 {
12489 \newline
12490 \SpecialChar ~
12491 \SpecialChar ~
12492 \SpecialChar ~
12493 \SpecialChar ~
12494 _asm
12495 \begin_inset LatexCommand \index{\_asm}
12496
12497 \end_inset
12498
12499
12500 \begin_inset LatexCommand \index{\_\_asm}
12501
12502 \end_inset
12503
12504
12505 \newline
12506 \SpecialChar ~
12507 \SpecialChar ~
12508 \SpecialChar ~
12509 \SpecialChar ~
12510 \SpecialChar ~
12511 \SpecialChar ~
12512 inc\SpecialChar ~
12513 \SpecialChar ~
12514 \SpecialChar ~
12515 \SpecialChar ~
12516 \SpecialChar ~
12517 _counter ; does not change flags, no need to save psw
12518 \newline
12519 \SpecialChar ~
12520 \SpecialChar ~
12521 \SpecialChar ~
12522 \SpecialChar ~
12523 \SpecialChar ~
12524 \SpecialChar ~
12525 reti\SpecialChar ~
12526 \SpecialChar ~
12527 \SpecialChar ~
12528 \SpecialChar ~
12529 ; MUST explicitly include ret or reti in _naked function.
12530 \newline
12531 \SpecialChar ~
12532 \SpecialChar ~
12533 \SpecialChar ~
12534 \SpecialChar ~
12535 _endasm
12536 \begin_inset LatexCommand \index{\_endasm}
12537
12538 \end_inset
12539
12540
12541 \begin_inset LatexCommand \index{\_\_endasm}
12542
12543 \end_inset
12544
12545 ;
12546 \newline
12547 }
12548 \layout Standard
12549
12550 For an 8051 target, the generated simpleInterrupt looks like:
12551 \layout Verse
12552
12553
12554 \family typewriter
12555 _simpleInterrupt:
12556 \newline
12557 \SpecialChar ~
12558 \SpecialChar ~
12559 \SpecialChar ~
12560 \SpecialChar ~
12561 push\SpecialChar ~
12562 \SpecialChar ~
12563 \SpecialChar ~
12564 \SpecialChar ~
12565 acc
12566 \newline
12567 \SpecialChar ~
12568 \SpecialChar ~
12569 \SpecialChar ~
12570 \SpecialChar ~
12571 push\SpecialChar ~
12572 \SpecialChar ~
12573 \SpecialChar ~
12574 \SpecialChar ~
12575 b
12576 \newline
12577 \SpecialChar ~
12578 \SpecialChar ~
12579 \SpecialChar ~
12580 \SpecialChar ~
12581 push\SpecialChar ~
12582 \SpecialChar ~
12583 \SpecialChar ~
12584 \SpecialChar ~
12585 dpl
12586 \newline
12587 \SpecialChar ~
12588 \SpecialChar ~
12589 \SpecialChar ~
12590 \SpecialChar ~
12591 push\SpecialChar ~
12592 \SpecialChar ~
12593 \SpecialChar ~
12594 \SpecialChar ~
12595 dph
12596 \newline
12597 \SpecialChar ~
12598 \SpecialChar ~
12599 \SpecialChar ~
12600 \SpecialChar ~
12601 push\SpecialChar ~
12602 \SpecialChar ~
12603 \SpecialChar ~
12604 \SpecialChar ~
12605 psw
12606 \newline
12607 \SpecialChar ~
12608 \SpecialChar ~
12609 \SpecialChar ~
12610 \SpecialChar ~
12611 mov\SpecialChar ~
12612 \SpecialChar ~
12613 \SpecialChar ~
12614 \SpecialChar ~
12615 \SpecialChar ~
12616 psw,#0x00
12617 \newline
12618 \SpecialChar ~
12619 \SpecialChar ~
12620 \SpecialChar ~
12621 \SpecialChar ~
12622 inc\SpecialChar ~
12623 \SpecialChar ~
12624 \SpecialChar ~
12625 \SpecialChar ~
12626 \SpecialChar ~
12627 _counter
12628 \newline
12629 \SpecialChar ~
12630 \SpecialChar ~
12631 \SpecialChar ~
12632 \SpecialChar ~
12633 pop\SpecialChar ~
12634 \SpecialChar ~
12635 \SpecialChar ~
12636 \SpecialChar ~
12637 \SpecialChar ~
12638 psw
12639 \newline
12640 \SpecialChar ~
12641 \SpecialChar ~
12642 \SpecialChar ~
12643 \SpecialChar ~
12644 pop\SpecialChar ~
12645 \SpecialChar ~
12646 \SpecialChar ~
12647 \SpecialChar ~
12648 \SpecialChar ~
12649 dph
12650 \newline
12651 \SpecialChar ~
12652 \SpecialChar ~
12653 \SpecialChar ~
12654 \SpecialChar ~
12655 pop\SpecialChar ~
12656 \SpecialChar ~
12657 \SpecialChar ~
12658 \SpecialChar ~
12659 \SpecialChar ~
12660 dpl
12661 \newline
12662 \SpecialChar ~
12663 \SpecialChar ~
12664 \SpecialChar ~
12665 \SpecialChar ~
12666 pop\SpecialChar ~
12667 \SpecialChar ~
12668 \SpecialChar ~
12669 \SpecialChar ~
12670 \SpecialChar ~
12671 b
12672 \newline
12673 \SpecialChar ~
12674 \SpecialChar ~
12675 \SpecialChar ~
12676 \SpecialChar ~
12677 pop\SpecialChar ~
12678 \SpecialChar ~
12679 \SpecialChar ~
12680 \SpecialChar ~
12681 \SpecialChar ~
12682 acc
12683 \newline
12684 \SpecialChar ~
12685 \SpecialChar ~
12686 \SpecialChar ~
12687 \SpecialChar ~
12688 reti
12689 \layout Standard
12690
12691 whereas nakedInterrupt looks like:
12692 \layout Verse
12693
12694
12695 \family typewriter
12696 _nakedInterrupt:
12697 \newline
12698 \SpecialChar ~
12699 \SpecialChar ~
12700 \SpecialChar ~
12701 \SpecialChar ~
12702 inc\SpecialChar ~
12703 \SpecialChar ~
12704 \SpecialChar ~
12705 \SpecialChar ~
12706 _counter ; does not change flags, no need to save psw
12707 \newline
12708 \SpecialChar ~
12709 \SpecialChar ~
12710 \SpecialChar ~
12711 \SpecialChar ~
12712 reti\SpecialChar ~
12713 \SpecialChar ~
12714 \SpecialChar ~
12715 \SpecialChar ~
12716 \SpecialChar ~
12717 \SpecialChar ~
12718 \SpecialChar ~
12719 \SpecialChar ~
12720 \SpecialChar ~
12721 \SpecialChar ~
12722 \SpecialChar ~
12723 \SpecialChar ~
12724 ; MUST explicitly include ret or reti in _naked function
12725 \layout Standard
12726
12727 The related directive #pragma exclude
12728 \begin_inset LatexCommand \index{\#pragma exclude}
12729
12730 \end_inset
12731
12732  allows a more fine grained control over pushing & popping
12733 \begin_inset LatexCommand \index{push/pop}
12734
12735 \end_inset
12736
12737  the registers.
12738 \layout Standard
12739
12740 While there is nothing preventing you from writing C code inside a
12741 \family typewriter
12742 _naked
12743 \family default
12744  function, there are many ways to shoot yourself in the foot doing this,
12745  and it is recommended that you stick to inline assembler.
12746 \layout Subsection
12747
12748 Use of Labels within Inline Assembler
12749 \layout Standard
12750
12751 SDCC allows the use of in-line assembler with a few restrictions regarding
12752  labels.
12753  In older versions of the compiler all labels defined within inline assembler
12754  code
12755 \emph on
12756 had to be
12757 \emph default
12758  of the form
12759 \emph on
12760 nnnnn$
12761 \emph default
12762  where nnnn is a number less than 100 (which implies a limit of utmost 100
12763  inline assembler labels
12764 \emph on
12765 per function
12766 \emph default
12767 \noun on
12768 )
12769 \noun default
12770 .
12771
12772 \layout Verse
12773
12774
12775 \family typewriter
12776 _asm
12777 \begin_inset LatexCommand \index{\_asm}
12778
12779 \end_inset
12780
12781
12782 \begin_inset LatexCommand \index{\_\_asm}
12783
12784 \end_inset
12785
12786
12787 \newline
12788 \SpecialChar ~
12789 \SpecialChar ~
12790 \SpecialChar ~
12791 \SpecialChar ~
12792 mov\SpecialChar ~
12793 \SpecialChar ~
12794 \SpecialChar ~
12795 \SpecialChar ~
12796 \SpecialChar ~
12797 b,#10
12798 \newline
12799 00001$:
12800 \newline
12801 \SpecialChar ~
12802 \SpecialChar ~
12803 \SpecialChar ~
12804 \SpecialChar ~
12805 djnz\SpecialChar ~
12806 \SpecialChar ~
12807 \SpecialChar ~
12808 \SpecialChar ~
12809 b,00001$
12810 \newline
12811 _endasm
12812 \begin_inset LatexCommand \index{\_endasm}
12813
12814 \end_inset
12815
12816
12817 \begin_inset LatexCommand \index{\_\_endasm}
12818
12819 \end_inset
12820
12821  ;
12822 \layout Standard
12823
12824 Inline assembler code cannot reference any C-Labels, however it can reference
12825  labels
12826 \begin_inset LatexCommand \index{Labels}
12827
12828 \end_inset
12829
12830  defined by the inline assembler, e.g.:
12831 \layout Verse
12832
12833
12834 \family typewriter
12835 foo() {
12836 \newline
12837 \SpecialChar ~
12838 \SpecialChar ~
12839 \SpecialChar ~
12840 \SpecialChar ~
12841 /* some c code */
12842 \newline
12843 \SpecialChar ~
12844 \SpecialChar ~
12845 \SpecialChar ~
12846 \SpecialChar ~
12847 _asm
12848 \newline
12849 \SpecialChar ~
12850 \SpecialChar ~
12851 \SpecialChar ~
12852 \SpecialChar ~
12853 \SpecialChar ~
12854 \SpecialChar ~
12855 ; some assembler code
12856 \newline
12857 \SpecialChar ~
12858 \SpecialChar ~
12859 \SpecialChar ~
12860 \SpecialChar ~
12861 \SpecialChar ~
12862 \SpecialChar ~
12863 ljmp $0003
12864 \newline
12865 \SpecialChar ~
12866 \SpecialChar ~
12867 \SpecialChar ~
12868 \SpecialChar ~
12869 _endasm;
12870 \newline
12871 \SpecialChar ~
12872 \SpecialChar ~
12873 \SpecialChar ~
12874 \SpecialChar ~
12875 /* some more c code */
12876 \newline
12877 clabel:\SpecialChar ~
12878 \SpecialChar ~
12879 /* inline assembler cannot reference this label */
12880 \newline
12881 \SpecialChar ~
12882 \SpecialChar ~
12883 \SpecialChar ~
12884 \SpecialChar ~
12885 _asm
12886 \newline
12887 \SpecialChar ~
12888 \SpecialChar ~
12889 \SpecialChar ~
12890 \SpecialChar ~
12891 $0003: ;label (can be referenced by inline assembler only)
12892 \newline
12893 \SpecialChar ~
12894 \SpecialChar ~
12895 \SpecialChar ~
12896 \SpecialChar ~
12897 _endasm
12898 \begin_inset LatexCommand \index{\_endasm}
12899
12900 \end_inset
12901
12902
12903 \begin_inset LatexCommand \index{\_\_endasm}
12904
12905 \end_inset
12906
12907  ;
12908 \newline
12909 \SpecialChar ~
12910 \SpecialChar ~
12911 \SpecialChar ~
12912 \SpecialChar ~
12913 /* some more c code */
12914 \newline
12915 }
12916 \layout Standard
12917
12918 In other words inline assembly code can access labels defined in inline
12919  assembly within the scope of the function.
12920  The same goes the other way, i.e.
12921  labels defines in inline assembly can not be accessed by C statements.
12922 \layout Section
12923
12924 Interfacing with Assembler Code
12925 \begin_inset LatexCommand \index{Assembler routines}
12926
12927 \end_inset
12928
12929
12930 \layout Subsection
12931
12932 Global Registers used for Parameter Passing
12933 \begin_inset LatexCommand \index{Parameter passing}
12934
12935 \end_inset
12936
12937
12938 \layout Standard
12939
12940 The compiler always uses the global registers
12941 \emph on
12942 DPL, DPH
12943 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12944
12945 \end_inset
12946
12947
12948 \begin_inset LatexCommand \index{DPTR}
12949
12950 \end_inset
12951
12952 , B
12953 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
12954
12955 \end_inset
12956
12957
12958 \emph default
12959 and
12960 \emph on
12961  ACC
12962 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
12963
12964 \end_inset
12965
12966
12967 \emph default
12968  to pass the first parameter to a routine.
12969  The second parameter onwards is either allocated on the stack (for reentrant
12970  routines or if -
12971 \begin_inset ERT
12972 status Collapsed
12973
12974 \layout Standard
12975
12976 \backslash
12977 /
12978 \end_inset
12979
12980 -stack-auto is used) or in data / xdata memory (depending on the memory
12981  model).
12982
12983 \layout Subsection
12984
12985 Assembler Routine (non-reentrant)
12986 \layout Standard
12987
12988 In the following example
12989 \begin_inset LatexCommand \index{reentrant}
12990
12991 \end_inset
12992
12993
12994 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
12995
12996 \end_inset
12997
12998  the function c_func calls an assembler routine asm_func, which takes two
12999  parameters
13000 \begin_inset LatexCommand \index{function parameter}
13001
13002 \end_inset
13003
13004 .
13005 \layout Verse
13006
13007
13008 \family typewriter
13009 extern int asm_func(unsigned char, unsigned char);
13010 \newline
13011
13012 \newline
13013 int c_func (unsigned char i, unsigned char j)
13014 \newline
13015 {
13016 \newline
13017 \SpecialChar ~
13018 \SpecialChar ~
13019 \SpecialChar ~
13020 \SpecialChar ~
13021 return asm_func(i,j);
13022 \newline
13023 }
13024 \newline
13025
13026 \newline
13027 int main()
13028 \newline
13029 {
13030 \newline
13031 \SpecialChar ~
13032 \SpecialChar ~
13033 \SpecialChar ~
13034 \SpecialChar ~
13035 return c_func(10,9);
13036 \newline
13037 }
13038 \layout Standard
13039
13040 The corresponding assembler function is:
13041 \layout Verse
13042
13043
13044 \family typewriter
13045 .globl _asm_func_PARM_2
13046 \newline
13047 \SpecialChar ~
13048 \SpecialChar ~
13049 \SpecialChar ~
13050 \SpecialChar ~
13051 \SpecialChar ~
13052 \SpecialChar ~
13053 \SpecialChar ~
13054 \SpecialChar ~
13055 .globl _asm_func
13056 \newline
13057 \SpecialChar ~
13058 \SpecialChar ~
13059 \SpecialChar ~
13060 \SpecialChar ~
13061 \SpecialChar ~
13062 \SpecialChar ~
13063 \SpecialChar ~
13064 \SpecialChar ~
13065 .area OSEG
13066 \newline
13067 _asm_func_PARM_2:
13068 \newline
13069 \SpecialChar ~
13070 \SpecialChar ~
13071 \SpecialChar ~
13072 \SpecialChar ~
13073 \SpecialChar ~
13074 \SpecialChar ~
13075 \SpecialChar ~
13076 \SpecialChar ~
13077 .ds    1
13078 \newline
13079 \SpecialChar ~
13080 \SpecialChar ~
13081 \SpecialChar ~
13082 \SpecialChar ~
13083 \SpecialChar ~
13084 \SpecialChar ~
13085 \SpecialChar ~
13086 \SpecialChar ~
13087 .area CSEG
13088 \newline
13089 _asm_func:
13090 \newline
13091 \SpecialChar ~
13092 \SpecialChar ~
13093 \SpecialChar ~
13094 \SpecialChar ~
13095 \SpecialChar ~
13096 \SpecialChar ~
13097 \SpecialChar ~
13098 \SpecialChar ~
13099 mov\SpecialChar ~
13100 \SpecialChar ~
13101 \SpecialChar ~
13102 \SpecialChar ~
13103 a,dpl
13104 \newline
13105 \SpecialChar ~
13106 \SpecialChar ~
13107 \SpecialChar ~
13108 \SpecialChar ~
13109 \SpecialChar ~
13110 \SpecialChar ~
13111 \SpecialChar ~
13112 \SpecialChar ~
13113 add\SpecialChar ~
13114 \SpecialChar ~
13115 \SpecialChar ~
13116 \SpecialChar ~
13117 a,_asm_func_PARM_2
13118 \newline
13119 \SpecialChar ~
13120 \SpecialChar ~
13121 \SpecialChar ~
13122 \SpecialChar ~
13123 \SpecialChar ~
13124 \SpecialChar ~
13125 \SpecialChar ~
13126 \SpecialChar ~
13127 mov\SpecialChar ~
13128 \SpecialChar ~
13129 \SpecialChar ~
13130 \SpecialChar ~
13131 dpl,a
13132 \newline
13133 \SpecialChar ~
13134 \SpecialChar ~
13135 \SpecialChar ~
13136 \SpecialChar ~
13137 \SpecialChar ~
13138 \SpecialChar ~
13139 \SpecialChar ~
13140 \SpecialChar ~
13141 mov\SpecialChar ~
13142 \SpecialChar ~
13143 \SpecialChar ~
13144 \SpecialChar ~
13145 dph
13146 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13147
13148 \end_inset
13149
13150 ,#0x00
13151 \newline
13152 \SpecialChar ~
13153 \SpecialChar ~
13154 \SpecialChar ~
13155 \SpecialChar ~
13156 \SpecialChar ~
13157 \SpecialChar ~
13158 \SpecialChar ~
13159 \SpecialChar ~
13160 ret
13161 \layout Standard
13162
13163 Note here that the return values
13164 \begin_inset LatexCommand \index{return value}
13165
13166 \end_inset
13167
13168  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
13169  two byte values.
13170  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
13171 b' & 'acc' for four byte values.
13172 \layout Standard
13173
13174 The parameter naming convention is _<function_name>_PARM_<n>, where n is
13175  the parameter number starting from 1, and counting from the left.
13176  The first parameter is passed in
13177 \begin_inset Quotes eld
13178 \end_inset
13179
13180 dpl
13181 \begin_inset Quotes erd
13182 \end_inset
13183
13184  for a one byte parameter,
13185 \begin_inset Quotes eld
13186 \end_inset
13187
13188 dptr
13189 \begin_inset Quotes erd
13190 \end_inset
13191
13192  for two bytes,
13193 \begin_inset Quotes eld
13194 \end_inset
13195
13196 b,dptr
13197 \begin_inset Quotes erd
13198 \end_inset
13199
13200  for three bytes and
13201 \begin_inset Quotes eld
13202 \end_inset
13203
13204 acc,b,dptr
13205 \begin_inset Quotes erd
13206 \end_inset
13207
13208  for a four bytes parameter.
13209  The variable name for the second parameter will be _<function_name>_PARM_2.
13210 \newline
13211
13212 \newline
13213 Assemble the assembler routine with the following command:
13214 \newline
13215
13216 \newline
13217
13218 \family sans
13219 \series bold
13220 asx8051 -losg asmfunc.asm
13221 \newline
13222
13223 \newline
13224
13225 \family default
13226 \series default
13227 Then compile and link the assembler routine to the C source file with the
13228  following command:
13229 \newline
13230
13231 \newline
13232
13233 \family sans
13234 \series bold
13235 sdcc cfunc.c asmfunc.rel
13236 \layout Subsection
13237
13238 Assembler Routine (reentrant)
13239 \layout Standard
13240
13241 In this case
13242 \begin_inset LatexCommand \index{reentrant}
13243
13244 \end_inset
13245
13246
13247 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
13248
13249 \end_inset
13250
13251  the second parameter
13252 \begin_inset LatexCommand \index{function parameter}
13253
13254 \end_inset
13255
13256  onwards will be passed on the stack, the parameters are pushed from right
13257  to left i.e.
13258  after the call the leftmost parameter will be on the top of the stack.
13259  Here is an example:
13260 \layout Verse
13261
13262
13263 \family typewriter
13264 extern int asm_func(unsigned char, unsigned char);
13265 \newline
13266
13267 \newline
13268 int c_func (unsigned char i, unsigned char j) reentrant
13269 \newline
13270 {
13271 \newline
13272 \SpecialChar ~
13273 \SpecialChar ~
13274 \SpecialChar ~
13275 \SpecialChar ~
13276 return asm_func(i,j);
13277 \newline
13278 }
13279 \newline
13280
13281 \newline
13282 int main()
13283 \newline
13284 {
13285 \newline
13286 \SpecialChar ~
13287 \SpecialChar ~
13288 \SpecialChar ~
13289 \SpecialChar ~
13290 return c_func(10,9);
13291 \newline
13292 }
13293 \layout Standard
13294
13295 The corresponding assembler routine is:
13296 \layout Verse
13297
13298
13299 \family typewriter
13300 .globl _asm_func
13301 \newline
13302 _asm_func:
13303 \newline
13304 \SpecialChar ~
13305 \SpecialChar ~
13306 \SpecialChar ~
13307 \SpecialChar ~
13308 push  _bp
13309 \newline
13310 \SpecialChar ~
13311 \SpecialChar ~
13312 \SpecialChar ~
13313 \SpecialChar ~
13314 mov _bp,sp
13315 \newline
13316 \SpecialChar ~
13317 \SpecialChar ~
13318 \SpecialChar ~
13319 \SpecialChar ~
13320 mov r2,dpl
13321 \newline
13322 \SpecialChar ~
13323 \SpecialChar ~
13324 \SpecialChar ~
13325 \SpecialChar ~
13326 mov a,_bp
13327 \newline
13328 \SpecialChar ~
13329 \SpecialChar ~
13330 \SpecialChar ~
13331 \SpecialChar ~
13332 add a,#0xfd
13333 \newline
13334 \SpecialChar ~
13335 \SpecialChar ~
13336 \SpecialChar ~
13337 \SpecialChar ~
13338 mov r0,a
13339 \newline
13340 \SpecialChar ~
13341 \SpecialChar ~
13342 \SpecialChar ~
13343 \SpecialChar ~
13344 add  a,#0xfc ;?
13345 \newline
13346 \SpecialChar ~
13347 \SpecialChar ~
13348 \SpecialChar ~
13349 \SpecialChar ~
13350 mov  r1,a
13351 \newline
13352 \SpecialChar ~
13353 \SpecialChar ~
13354 \SpecialChar ~
13355 \SpecialChar ~
13356 mov  a,@r0
13357 \newline
13358 \SpecialChar ~
13359 \SpecialChar ~
13360 \SpecialChar ~
13361 \SpecialChar ~
13362 add  a,r2 ;?
13363 \newline
13364 \SpecialChar ~
13365 \SpecialChar ~
13366 \SpecialChar ~
13367 \SpecialChar ~
13368 mov  dpl,a
13369 \newline
13370 \SpecialChar ~
13371 \SpecialChar ~
13372 \SpecialChar ~
13373 \SpecialChar ~
13374 mov  dph,#0x00
13375 \newline
13376 \SpecialChar ~
13377 \SpecialChar ~
13378 \SpecialChar ~
13379 \SpecialChar ~
13380 mov  sp,_bp
13381 \newline
13382 \SpecialChar ~
13383 \SpecialChar ~
13384 \SpecialChar ~
13385 \SpecialChar ~
13386 pop  _bp
13387 \newline
13388 \SpecialChar ~
13389 \SpecialChar ~
13390 \SpecialChar ~
13391 \SpecialChar ~
13392 ret
13393 \layout Standard
13394
13395 The compiling and linking procedure remains the same, however note the extra
13396  entry & exit linkage required for the assembler code, _bp is the stack
13397  frame pointer and is used to compute the offset into the stack for parameters
13398  and local variables.
13399 \layout Section
13400
13401 int (16 bit)
13402 \begin_inset LatexCommand \index{int (16 bit)}
13403
13404 \end_inset
13405
13406  and long (32 bit)
13407 \begin_inset LatexCommand \index{long (32 bit)}
13408
13409 \end_inset
13410
13411  Support
13412 \layout Standard
13413
13414 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
13415  multiplication and modulus operations are implemented by support routines.
13416  These support routines are all developed in ANSI-C to facilitate porting
13417  to other MCUs, although some model specific assembler optimizations are
13418  used.
13419  The following files contain the described routines, all of them can be
13420  found in <installdir>/share/sdcc/lib.
13421 \newline
13422
13423 \layout Standard
13424 \align center
13425
13426 \begin_inset  Tabular
13427 <lyxtabular version="3" rows="11" columns="2">
13428 <features>
13429 <column alignment="center" valignment="top" leftline="true" width="0">
13430 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13431 <row topline="true" bottomline="true">
13432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13433 \begin_inset Text
13434
13435 \layout Standard
13436
13437
13438 \series bold
13439 Function
13440 \end_inset
13441 </cell>
13442 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13443 \begin_inset Text
13444
13445 \layout Standard
13446
13447
13448 \series bold
13449 Description
13450 \end_inset
13451 </cell>
13452 </row>
13453 <row topline="true">
13454 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13455 \begin_inset Text
13456
13457 \layout Standard
13458
13459 _mulint.c
13460 \end_inset
13461 </cell>
13462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13463 \begin_inset Text
13464
13465 \layout Standard
13466
13467 16 bit multiplication
13468 \end_inset
13469 </cell>
13470 </row>
13471 <row topline="true">
13472 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13473 \begin_inset Text
13474
13475 \layout Standard
13476
13477 _divsint.c
13478 \end_inset
13479 </cell>
13480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13481 \begin_inset Text
13482
13483 \layout Standard
13484
13485  signed 16 bit division (calls _divuint)
13486 \end_inset
13487 </cell>
13488 </row>
13489 <row topline="true">
13490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13491 \begin_inset Text
13492
13493 \layout Standard
13494
13495 _divuint.c
13496 \end_inset
13497 </cell>
13498 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13499 \begin_inset Text
13500
13501 \layout Standard
13502
13503  unsigned 16 bit division
13504 \end_inset
13505 </cell>
13506 </row>
13507 <row topline="true">
13508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13509 \begin_inset Text
13510
13511 \layout Standard
13512
13513 _modsint.c
13514 \end_inset
13515 </cell>
13516 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13517 \begin_inset Text
13518
13519 \layout Standard
13520
13521 signed 16 bit modulus (calls _moduint)
13522 \end_inset
13523 </cell>
13524 </row>
13525 <row topline="true">
13526 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13527 \begin_inset Text
13528
13529 \layout Standard
13530
13531 _moduint.c
13532 \end_inset
13533 </cell>
13534 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13535 \begin_inset Text
13536
13537 \layout Standard
13538
13539 unsigned 16 bit modulus
13540 \end_inset
13541 </cell>
13542 </row>
13543 <row topline="true">
13544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13545 \begin_inset Text
13546
13547 \layout Standard
13548
13549 _mullong.c
13550 \end_inset
13551 </cell>
13552 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13553 \begin_inset Text
13554
13555 \layout Standard
13556
13557 32 bit multiplication
13558 \end_inset
13559 </cell>
13560 </row>
13561 <row topline="true">
13562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13563 \begin_inset Text
13564
13565 \layout Standard
13566
13567 _divslong.c
13568 \end_inset
13569 </cell>
13570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13571 \begin_inset Text
13572
13573 \layout Standard
13574
13575  signed 32 division (calls _divulong)
13576 \end_inset
13577 </cell>
13578 </row>
13579 <row topline="true">
13580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13581 \begin_inset Text
13582
13583 \layout Standard
13584
13585 _divulong.c
13586 \end_inset
13587 </cell>
13588 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13589 \begin_inset Text
13590
13591 \layout Standard
13592
13593 unsigned 32 division
13594 \end_inset
13595 </cell>
13596 </row>
13597 <row topline="true">
13598 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13599 \begin_inset Text
13600
13601 \layout Standard
13602
13603 _modslong.c
13604 \end_inset
13605 </cell>
13606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13607 \begin_inset Text
13608
13609 \layout Standard
13610
13611  signed 32 bit modulus (calls _modulong)
13612 \end_inset
13613 </cell>
13614 </row>
13615 <row topline="true" bottomline="true">
13616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13617 \begin_inset Text
13618
13619 \layout Standard
13620
13621 _modulong.c
13622 \end_inset
13623 </cell>
13624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13625 \begin_inset Text
13626
13627 \layout Standard
13628
13629 unsigned 32 bit modulus
13630 \end_inset
13631 </cell>
13632 </row>
13633 </lyxtabular>
13634
13635 \end_inset
13636
13637
13638 \newline
13639
13640 \layout Standard
13641
13642 Since they are compiled as
13643 \emph on
13644 non-reentrant
13645 \emph default
13646
13647 \begin_inset LatexCommand \index{reentrant}
13648
13649 \end_inset
13650
13651 , interrupt
13652 \begin_inset LatexCommand \index{interrupt}
13653
13654 \end_inset
13655
13656  service routines should not do any of the above operations.
13657  If this is unavoidable then the above routines will need to be compiled
13658  with the
13659 \emph on
13660 -
13661 \begin_inset ERT
13662 status Collapsed
13663
13664 \layout Standard
13665
13666 \backslash
13667 /
13668 \end_inset
13669
13670 -stack-auto
13671 \begin_inset LatexCommand \index{-\/-stack-auto}
13672
13673 \end_inset
13674
13675
13676 \emph default
13677  option, after which the source program will have to be compiled with
13678 \emph on
13679 -
13680 \begin_inset ERT
13681 status Collapsed
13682
13683 \layout Standard
13684
13685 \backslash
13686 /
13687 \end_inset
13688
13689 -int-long-reent
13690 \begin_inset LatexCommand \index{-\/-int-long-reent}
13691
13692 \end_inset
13693
13694
13695 \emph default
13696  option.
13697  Notice that you don't have to call these routines directly.
13698  The compiler will use them automatically every time an integer operation
13699  is required.
13700 \layout Section
13701
13702 Floating Point Support
13703 \begin_inset LatexCommand \index{Floating point support}
13704
13705 \end_inset
13706
13707
13708 \layout Standard
13709
13710 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13711  floating point support routines are derived from gcc's floatlib.c and consist
13712  of the following routines:
13713 \newline
13714
13715 \layout Standard
13716 \align center
13717
13718 \size footnotesize
13719
13720 \begin_inset  Tabular
13721 <lyxtabular version="3" rows="17" columns="2">
13722 <features>
13723 <column alignment="center" valignment="top" leftline="true" width="0">
13724 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13725 <row topline="true" bottomline="true">
13726 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13727 \begin_inset Text
13728
13729 \layout Standard
13730
13731
13732 \family roman
13733 \series medium
13734 \shape up
13735 \size normal
13736 \emph off
13737 \bar no
13738 \noun off
13739 \color none
13740 Function
13741 \end_inset
13742 </cell>
13743 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13744 \begin_inset Text
13745
13746 \layout Standard
13747
13748 Description
13749 \end_inset
13750 </cell>
13751 </row>
13752 <row topline="true">
13753 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13754 \begin_inset Text
13755
13756 \layout Standard
13757
13758
13759 \family roman
13760 \series medium
13761 \shape up
13762 \size normal
13763 \emph off
13764 \bar no
13765 \noun off
13766 \color none
13767 _fsadd.c
13768 \end_inset
13769 </cell>
13770 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13771 \begin_inset Text
13772
13773 \layout Standard
13774
13775
13776 \family roman
13777 \series medium
13778 \shape up
13779 \size normal
13780 \emph off
13781 \bar no
13782 \noun off
13783 \color none
13784 add floating point numbers
13785 \end_inset
13786 </cell>
13787 </row>
13788 <row topline="true">
13789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13790 \begin_inset Text
13791
13792 \layout Standard
13793
13794
13795 \family roman
13796 \series medium
13797 \shape up
13798 \size normal
13799 \emph off
13800 \bar no
13801 \noun off
13802 \color none
13803 _fssub.c
13804 \end_inset
13805 </cell>
13806 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13807 \begin_inset Text
13808
13809 \layout Standard
13810
13811
13812 \family roman
13813 \series medium
13814 \shape up
13815 \size normal
13816 \emph off
13817 \bar no
13818 \noun off
13819 \color none
13820 subtract floating point numbers
13821 \end_inset
13822 </cell>
13823 </row>
13824 <row topline="true">
13825 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13826 \begin_inset Text
13827
13828 \layout Standard
13829
13830
13831 \family roman
13832 \series medium
13833 \shape up
13834 \size normal
13835 \emph off
13836 \bar no
13837 \noun off
13838 \color none
13839 _fsdiv.c
13840 \end_inset
13841 </cell>
13842 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13843 \begin_inset Text
13844
13845 \layout Standard
13846
13847
13848 \family roman
13849 \series medium
13850 \shape up
13851 \size normal
13852 \emph off
13853 \bar no
13854 \noun off
13855 \color none
13856 divide floating point numbers
13857 \end_inset
13858 </cell>
13859 </row>
13860 <row topline="true">
13861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13862 \begin_inset Text
13863
13864 \layout Standard
13865
13866
13867 \family roman
13868 \series medium
13869 \shape up
13870 \size normal
13871 \emph off
13872 \bar no
13873 \noun off
13874 \color none
13875 _fsmul.c
13876 \end_inset
13877 </cell>
13878 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13879 \begin_inset Text
13880
13881 \layout Standard
13882
13883
13884 \family roman
13885 \series medium
13886 \shape up
13887 \size normal
13888 \emph off
13889 \bar no
13890 \noun off
13891 \color none
13892 multiply floating point numbers
13893 \end_inset
13894 </cell>
13895 </row>
13896 <row topline="true">
13897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13898 \begin_inset Text
13899
13900 \layout Standard
13901
13902
13903 \family roman
13904 \series medium
13905 \shape up
13906 \size normal
13907 \emph off
13908 \bar no
13909 \noun off
13910 \color none
13911 _fs2uchar.c
13912 \end_inset
13913 </cell>
13914 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13915 \begin_inset Text
13916
13917 \layout Standard
13918
13919
13920 \family roman
13921 \series medium
13922 \shape up
13923 \size normal
13924 \emph off
13925 \bar no
13926 \noun off
13927 \color none
13928 convert floating point to unsigned char
13929 \end_inset
13930 </cell>
13931 </row>
13932 <row topline="true">
13933 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13934 \begin_inset Text
13935
13936 \layout Standard
13937
13938
13939 \family roman
13940 \series medium
13941 \shape up
13942 \size normal
13943 \emph off
13944 \bar no
13945 \noun off
13946 \color none
13947 _fs2char.c
13948 \end_inset
13949 </cell>
13950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13951 \begin_inset Text
13952
13953 \layout Standard
13954
13955
13956 \family roman
13957 \series medium
13958 \shape up
13959 \size normal
13960 \emph off
13961 \bar no
13962 \noun off
13963 \color none
13964 convert floating point to signed char
13965 \end_inset
13966 </cell>
13967 </row>
13968 <row topline="true">
13969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13970 \begin_inset Text
13971
13972 \layout Standard
13973
13974
13975 \family roman
13976 \series medium
13977 \shape up
13978 \size normal
13979 \emph off
13980 \bar no
13981 \noun off
13982 \color none
13983 _fs2uint.c
13984 \end_inset
13985 </cell>
13986 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13987 \begin_inset Text
13988
13989 \layout Standard
13990
13991
13992 \family roman
13993 \series medium
13994 \shape up
13995 \size normal
13996 \emph off
13997 \bar no
13998 \noun off
13999 \color none
14000 convert floating point to unsigned int
14001 \end_inset
14002 </cell>
14003 </row>
14004 <row topline="true">
14005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14006 \begin_inset Text
14007
14008 \layout Standard
14009
14010
14011 \family roman
14012 \series medium
14013 \shape up
14014 \size normal
14015 \emph off
14016 \bar no
14017 \noun off
14018 \color none
14019 _fs2int.c
14020 \end_inset
14021 </cell>
14022 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14023 \begin_inset Text
14024
14025 \layout Standard
14026
14027
14028 \family roman
14029 \series medium
14030 \shape up
14031 \size normal
14032 \emph off
14033 \bar no
14034 \noun off
14035 \color none
14036 convert floating point to signed int
14037 \end_inset
14038 </cell>
14039 </row>
14040 <row topline="true">
14041 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14042 \begin_inset Text
14043
14044 \layout Standard
14045
14046
14047 \family roman
14048 \series medium
14049 \shape up
14050 \size normal
14051 \emph off
14052 \bar no
14053 \noun off
14054 \color none
14055 _fs2ulong.
14056 \family default
14057 \series default
14058 \shape default
14059 \size default
14060 \emph default
14061 \bar default
14062 \noun default
14063 \color default
14064 c
14065 \end_inset
14066 </cell>
14067 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14068 \begin_inset Text
14069
14070 \layout Standard
14071
14072
14073 \family roman
14074 \series medium
14075 \shape up
14076 \size normal
14077 \emph off
14078 \bar no
14079 \noun off
14080 \color none
14081 convert floating point to unsigned long
14082 \end_inset
14083 </cell>
14084 </row>
14085 <row topline="true">
14086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14087 \begin_inset Text
14088
14089 \layout Standard
14090
14091
14092 \family roman
14093 \series medium
14094 \shape up
14095 \size normal
14096 \emph off
14097 \bar no
14098 \noun off
14099 \color none
14100 _fs2long.c
14101 \end_inset
14102 </cell>
14103 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14104 \begin_inset Text
14105
14106 \layout Standard
14107
14108
14109 \family roman
14110 \series medium
14111 \shape up
14112 \size normal
14113 \emph off
14114 \bar no
14115 \noun off
14116 \color none
14117 convert floating point to signed long
14118 \end_inset
14119 </cell>
14120 </row>
14121 <row topline="true">
14122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14123 \begin_inset Text
14124
14125 \layout Standard
14126
14127
14128 \family roman
14129 \series medium
14130 \shape up
14131 \size normal
14132 \emph off
14133 \bar no
14134 \noun off
14135 \color none
14136 _uchar2fs.c
14137 \end_inset
14138 </cell>
14139 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14140 \begin_inset Text
14141
14142 \layout Standard
14143
14144
14145 \family roman
14146 \series medium
14147 \shape up
14148 \size normal
14149 \emph off
14150 \bar no
14151 \noun off
14152 \color none
14153 convert unsigned char to floating point
14154 \end_inset
14155 </cell>
14156 </row>
14157 <row topline="true">
14158 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14159 \begin_inset Text
14160
14161 \layout Standard
14162
14163
14164 \family roman
14165 \series medium
14166 \shape up
14167 \size normal
14168 \emph off
14169 \bar no
14170 \noun off
14171 \color none
14172 _char2fs.c
14173 \end_inset
14174 </cell>
14175 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14176 \begin_inset Text
14177
14178 \layout Standard
14179
14180
14181 \family roman
14182 \series medium
14183 \shape up
14184 \size normal
14185 \emph off
14186 \bar no
14187 \noun off
14188 \color none
14189 convert char to floating point number
14190 \end_inset
14191 </cell>
14192 </row>
14193 <row topline="true">
14194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14195 \begin_inset Text
14196
14197 \layout Standard
14198
14199
14200 \family roman
14201 \series medium
14202 \shape up
14203 \size normal
14204 \emph off
14205 \bar no
14206 \noun off
14207 \color none
14208 _uint2fs.c
14209 \end_inset
14210 </cell>
14211 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14212 \begin_inset Text
14213
14214 \layout Standard
14215
14216
14217 \family roman
14218 \series medium
14219 \shape up
14220 \size normal
14221 \emph off
14222 \bar no
14223 \noun off
14224 \color none
14225 convert unsigned int to floating point
14226 \end_inset
14227 </cell>
14228 </row>
14229 <row topline="true">
14230 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14231 \begin_inset Text
14232
14233 \layout Standard
14234
14235
14236 \family roman
14237 \series medium
14238 \shape up
14239 \size normal
14240 \emph off
14241 \bar no
14242 \noun off
14243 \color none
14244 _int2fs.c
14245 \end_inset
14246 </cell>
14247 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14248 \begin_inset Text
14249
14250 \layout Standard
14251
14252
14253 \family roman
14254 \series medium
14255 \shape up
14256 \size normal
14257 \emph off
14258 \bar no
14259 \noun off
14260 \color none
14261 convert int to floating point numbers
14262 \end_inset
14263 </cell>
14264 </row>
14265 <row topline="true">
14266 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14267 \begin_inset Text
14268
14269 \layout Standard
14270
14271
14272 \family roman
14273 \series medium
14274 \shape up
14275 \size normal
14276 \emph off
14277 \bar no
14278 \noun off
14279 \color none
14280 _ulong2fs.c
14281 \end_inset
14282 </cell>
14283 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14284 \begin_inset Text
14285
14286 \layout Standard
14287
14288
14289 \family roman
14290 \series medium
14291 \shape up
14292 \size normal
14293 \emph off
14294 \bar no
14295 \noun off
14296 \color none
14297 convert unsigned long to floating point number
14298 \end_inset
14299 </cell>
14300 </row>
14301 <row topline="true" bottomline="true">
14302 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14303 \begin_inset Text
14304
14305 \layout Standard
14306
14307
14308 \family roman
14309 \series medium
14310 \shape up
14311 \size normal
14312 \emph off
14313 \bar no
14314 \noun off
14315 \color none
14316 _long2fs.c
14317 \end_inset
14318 </cell>
14319 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14320 \begin_inset Text
14321
14322 \layout Standard
14323
14324
14325 \family roman
14326 \series medium
14327 \shape up
14328 \size normal
14329 \emph off
14330 \bar no
14331 \noun off
14332 \color none
14333 convert long to floating point number
14334 \end_inset
14335 </cell>
14336 </row>
14337 </lyxtabular>
14338
14339 \end_inset
14340
14341
14342 \newline
14343
14344 \layout Standard
14345
14346 These support routines are developed in ANSI-C so there is room for space
14347  and speed improvement
14348 \begin_inset Foot
14349 collapsed false
14350
14351 \layout Standard
14352
14353 The floating point routines for the mcs51 are implemented in assembler
14354 \end_inset
14355
14356 .
14357  Note if all these routines are used simultaneously the data space might
14358  overflow.
14359  For serious floating point usage the large model might be needed.
14360  Also notice that you don't have to call this routines directly.
14361  The compiler will use them automatically every time a floating point operation
14362  is required.
14363 \layout Section
14364
14365 Library Routines
14366 \begin_inset LatexCommand \index{Libraries}
14367
14368 \end_inset
14369
14370
14371 \layout Standard
14372
14373
14374 \emph on
14375 <pending: this is messy and incomplete - a little more information is in
14376  sdcc/doc/libdoc.txt
14377 \emph default
14378  >
14379 \layout Subsection
14380
14381 Compiler support routines (_gptrget, _mulint etc.)
14382 \layout Subsection
14383
14384 Stdclib functions (puts, printf, strcat etc.)
14385 \layout Subsubsection
14386
14387 <stdio.h>
14388 \layout Standard
14389
14390
14391 \begin_inset LatexCommand \index{<stdio.h>}
14392
14393 \end_inset
14394
14395 As usual on embedded systems you have to provide your own
14396 \family typewriter
14397 getchar()
14398 \begin_inset LatexCommand \index{getchar()}
14399
14400 \end_inset
14401
14402
14403 \family default
14404 and
14405 \family typewriter
14406 putchar()
14407 \begin_inset LatexCommand \index{putchar()}
14408
14409 \end_inset
14410
14411
14412 \family default
14413  routines.
14414  SDCC does not know whether the system connects to a serial line with or
14415  without handshake, LCD, keyboard or other device.
14416  You'll find examples for serial routines f.e.
14417  in sdcc/device/lib.
14418 \layout Standard
14419
14420 The default
14421 \family typewriter
14422  printf()
14423 \begin_inset LatexCommand \index{printf()}
14424
14425 \end_inset
14426
14427
14428 \family default
14429 implementation in
14430 \family typewriter
14431  printf_large.c
14432 \family default
14433  does not support float (except on ds390).
14434  To enable this recompile it with the option
14435 \emph on
14436 -
14437 \begin_inset ERT
14438 status Collapsed
14439
14440 \layout Standard
14441
14442 \backslash
14443 /
14444 \end_inset
14445
14446 DUSE_FLOATS=1
14447 \begin_inset LatexCommand \index{USE\_FLOATS}
14448
14449 \end_inset
14450
14451
14452 \emph default
14453  on the command line.
14454  Use
14455 \emph on
14456 -
14457 \begin_inset ERT
14458 status Collapsed
14459
14460 \layout Standard
14461
14462 \backslash
14463 /
14464 \end_inset
14465
14466 -model-large
14467 \begin_inset LatexCommand \index{-\/-model-large}
14468
14469 \end_inset
14470
14471
14472 \emph default
14473  for the mcs51 port, since this uses a lot of memory.
14474 \layout Standard
14475
14476 If you're short on memory you might want to use
14477 \family typewriter
14478 printf_small()
14479 \begin_inset LatexCommand \index{printf\_small()}
14480
14481 \end_inset
14482
14483
14484 \family default
14485
14486 \emph on
14487 instead
14488 \emph default
14489  of
14490 \family typewriter
14491  printf().
14492
14493 \family default
14494  For the mcs51 there additionally are assembly versions
14495 \family typewriter
14496 printf_tiny()
14497 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
14498
14499 \end_inset
14500
14501
14502 \family default
14503  and
14504 \family typewriter
14505 printf_fast()
14506 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
14507
14508 \end_inset
14509
14510
14511 \family default
14512 and
14513 \family typewriter
14514  printf_fast_f()
14515 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
14516
14517 \end_inset
14518
14519
14520 \family default
14521  which should fit the requirements of many embedded systems (printf_fast()
14522  can be customized by unsetting #defines to
14523 \emph on
14524 not
14525 \emph default
14526  support long variables and field widths).
14527 \layout Subsection
14528
14529 Math functions (sin, pow, sqrt etc.)
14530 \layout Subsection
14531
14532 Other libraries
14533 \layout Standard
14534
14535 Libraries
14536 \begin_inset LatexCommand \index{Libraries}
14537
14538 \end_inset
14539
14540  included in SDCC should have a license at least as liberal as the GNU Lesser
14541  General Public License
14542 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14543
14544 \end_inset
14545
14546
14547 \emph on
14548 LGPL
14549 \emph default
14550 .
14551 \layout Comment
14552
14553 license statements for the libraries are missing.
14554  sdcc/device/lib/ser_ir.c
14555 \layout Comment
14556
14557 or _decdptr f.e.
14558  come with a GPL (as opposed to LGPL) License - this will not be liberal
14559  enough for many embedded programmers.
14560 \layout Standard
14561
14562 If you have ported some library or want to share experience about some code
14563  which f.e.
14564  falls into any of these categories Busses (I
14565 \begin_inset Formula $^{\textrm{2}}$
14566 \end_inset
14567
14568 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14569  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14570  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14571 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14572
14573 \end_inset
14574
14575 \SpecialChar ~
14576 would certainly like to hear about it.
14577  Programmers coding for embedded systems are not especially famous for being
14578  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14579 e these references are very valuable.
14580  Let's help to create a climate where information is shared.
14581 \layout Section
14582
14583 Memory Models
14584 \layout Subsection
14585
14586 MCS51 Memory Models
14587 \begin_inset LatexCommand \index{Memory model}
14588
14589 \end_inset
14590
14591
14592 \begin_inset LatexCommand \index{MCS51 memory model}
14593
14594 \end_inset
14595
14596
14597 \layout Subsubsection
14598
14599 Small and Large
14600 \layout Standard
14601
14602 SDCC allows two memory models for MCS51 code,
14603 \shape slanted
14604 small
14605 \shape default
14606  and
14607 \shape slanted
14608 large
14609 \shape default
14610 .
14611  Modules compiled with different memory models should
14612 \emph on
14613 never
14614 \emph default
14615  be combined together or the results would be unpredictable.
14616  The library routines supplied with the compiler are compiled as both small
14617  and large.
14618  The compiled library modules are contained in separate directories as small
14619  and large so that you can link to either set.
14620
14621 \layout Standard
14622
14623 When the large model is used all variables declared without a storage class
14624  will be allocated into the external ram, this includes all parameters and
14625  local variables (for non-reentrant
14626 \begin_inset LatexCommand \index{reentrant}
14627
14628 \end_inset
14629
14630  functions).
14631  When the small model is used variables without storage class are allocated
14632  in the internal ram.
14633 \layout Standard
14634
14635 Judicious usage of the processor specific storage classes
14636 \begin_inset LatexCommand \index{Storage class}
14637
14638 \end_inset
14639
14640  and the 'reentrant' function type will yield much more efficient code,
14641  than using the large model.
14642  Several optimizations are disabled when the program is compiled using the
14643  large model, it is therefore recommended that the small model be used unless
14644  absolutely required.
14645 \layout Subsubsection
14646
14647 External Stack
14648 \begin_inset LatexCommand \label{sub:External-Stack}
14649
14650 \end_inset
14651
14652
14653 \begin_inset LatexCommand \index{stack}
14654
14655 \end_inset
14656
14657
14658 \begin_inset LatexCommand \index{External stack (mcs51)}
14659
14660 \end_inset
14661
14662
14663 \layout Standard
14664
14665 The external stack (-
14666 \begin_inset ERT
14667 status Collapsed
14668
14669 \layout Standard
14670
14671 \backslash
14672 /
14673 \end_inset
14674
14675 -xstack option
14676 \begin_inset LatexCommand \index{-\/-xstack}
14677
14678 \end_inset
14679
14680 ) is located in pdata
14681 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14682
14683 \end_inset
14684
14685  memory (usually at the start of the external ram segment) and uses all
14686  unused space in pdata (max.
14687  256 bytes).
14688  When -
14689 \begin_inset ERT
14690 status Collapsed
14691
14692 \layout Standard
14693
14694 \backslash
14695 /
14696 \end_inset
14697
14698 -xstack option is used to compile the program, the parameters and local
14699  variables
14700 \begin_inset LatexCommand \index{local variables}
14701
14702 \end_inset
14703
14704  of all reentrant functions are allocated in this area.
14705  This option is provided for programs with large stack space requirements.
14706  When used with the -
14707 \begin_inset ERT
14708 status Collapsed
14709
14710 \layout Standard
14711
14712 \backslash
14713 /
14714 \end_inset
14715
14716 -stack-auto
14717 \begin_inset LatexCommand \index{-\/-stack-auto}
14718
14719 \end_inset
14720
14721  option, all parameters and local variables are allocated on the external
14722  stack (note: support libraries will need to be recompiled with the same
14723  options.
14724  There is a predefined target in the library makefile).
14725 \layout Standard
14726
14727 The compiler outputs the higher order address byte of the external ram segment
14728  into port P2
14729 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14730
14731 \end_inset
14732
14733  (see also section
14734 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14735
14736 \end_inset
14737
14738 ), therefore when using the External Stack option, this port
14739 \emph on
14740 may not
14741 \emph default
14742  be used by the application program.
14743 \layout Subsection
14744
14745 DS390 Memory Model
14746 \begin_inset LatexCommand \index{Memory model}
14747
14748 \end_inset
14749
14750
14751 \begin_inset LatexCommand \index{DS390 memory model}
14752
14753 \end_inset
14754
14755
14756 \layout Standard
14757
14758 The only model supported is Flat 24
14759 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
14760
14761 \end_inset
14762
14763 .
14764  This generates code for the 24 bit contiguous addressing mode of the Dallas
14765  DS80C390 part.
14766  In this mode, up to four meg of external RAM or code space can be directly
14767  addressed.
14768  See the data sheets at www.dalsemi.com for further information on this part.
14769 \newline
14770
14771 \newline
14772 Note that the compiler does not generate any code to place the processor
14773  into 24 bitmode (although
14774 \emph on
14775 tinibios
14776 \emph default
14777  in the ds390 libraries will do that for you).
14778  If you don't use
14779 \emph on
14780 tinibios
14781 \emph default
14782
14783 \begin_inset LatexCommand \index{Tinibios (DS390)}
14784
14785 \end_inset
14786
14787 , the boot loader or similar code must ensure that the processor is in 24
14788  bit contiguous addressing mode before calling the SDCC startup code.
14789 \newline
14790
14791 \newline
14792 Like the
14793 \emph on
14794 -
14795 \begin_inset ERT
14796 status Collapsed
14797
14798 \layout Standard
14799
14800 \backslash
14801 /
14802 \end_inset
14803
14804 -model-large
14805 \emph default
14806  option, variables will by default be placed into the XDATA segment.
14807
14808 \newline
14809
14810 \newline
14811 Segments may be placed anywhere in the 4 meg address space using the usual
14812  -
14813 \begin_inset ERT
14814 status Collapsed
14815
14816 \layout Standard
14817
14818 \backslash
14819 /
14820 \end_inset
14821
14822 -*-loc options.
14823  Note that if any segments are located above 64K, the -r flag must be passed
14824  to the linker to generate the proper segment relocations, and the Intel
14825  HEX output format must be used.
14826  The -r flag can be passed to the linker by using the option
14827 \emph on
14828 -Wl-r
14829 \emph default
14830  on the SDCC command line.
14831  However, currently the linker can not handle code segments > 64k.
14832 \layout Section
14833
14834 Pragmas
14835 \begin_inset LatexCommand \index{Pragmas}
14836
14837 \end_inset
14838
14839
14840 \layout Standard
14841
14842 SDCC supports the following #pragma directives:
14843 \layout Itemize
14844
14845 save
14846 \begin_inset LatexCommand \index{\#pragma save}
14847
14848 \end_inset
14849
14850  - this will save all current options to the save/restore stack.
14851  See #pragma\SpecialChar ~
14852 restore.
14853 \layout Itemize
14854
14855 restore
14856 \begin_inset LatexCommand \index{\#pragma restore}
14857
14858 \end_inset
14859
14860  - will restore saved options from the last save.
14861  saves & restores can be nested.
14862  SDCC uses a save/restore stack: save pushes current options to the stack,
14863  restore pulls current options from the stack.
14864  See #pragma\SpecialChar ~
14865 save.
14866 \newline
14867
14868 \layout Itemize
14869
14870 callee_saves
14871 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14872
14873 \end_inset
14874
14875
14876 \begin_inset LatexCommand \index{function prologue}
14877
14878 \end_inset
14879
14880  function1[,function2[,function3...]] - The compiler by default uses a caller
14881  saves convention for register saving across function calls, however this
14882  can cause unnecessary register pushing & popping
14883 \begin_inset LatexCommand \index{push/pop}
14884
14885 \end_inset
14886
14887  when calling small functions from larger functions.
14888  This option can be used to switch off the register saving convention for
14889  the function names specified.
14890  The compiler will not save registers when calling these functions, extra
14891  code need to be manually inserted at the entry & exit for these functions
14892  to save & restore the registers used by these functions, this can SUBSTANTIALLY
14893  reduce code & improve run time performance of the generated code.
14894  In the future the compiler (with inter procedural analysis) may be able
14895  to determine the appropriate scheme to use for each function call.
14896  If -
14897 \begin_inset ERT
14898 status Collapsed
14899
14900 \layout Standard
14901
14902 \backslash
14903 /
14904 \end_inset
14905
14906 -callee-saves command line option is used, the function names specified
14907  in #pragma\SpecialChar ~
14908 callee_saves
14909 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14910
14911 \end_inset
14912
14913  is appended to the list of functions specified in the command line.
14914 \layout Itemize
14915
14916 exclude
14917 \begin_inset LatexCommand \index{\#pragma exclude}
14918
14919 \end_inset
14920
14921  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
14922  of pairs of push/pop
14923 \begin_inset LatexCommand \index{push/pop}
14924
14925 \end_inset
14926
14927  instructions in
14928 \emph on
14929 I
14930 \emph default
14931 nterrupt
14932 \begin_inset LatexCommand \index{interrupt}
14933
14934 \end_inset
14935
14936
14937 \emph on
14938 S
14939 \emph default
14940 ervice
14941 \emph on
14942 R
14943 \emph default
14944 outines.
14945  The directive should be placed immediately before the ISR function definition
14946  and it affects ALL ISR functions following it.
14947  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
14948 exclude\SpecialChar ~
14949 none
14950 \begin_inset LatexCommand \index{\#pragma exclude}
14951
14952 \end_inset
14953
14954 .
14955  See also the related keyword _naked
14956 \begin_inset LatexCommand \index{\_naked}
14957
14958 \end_inset
14959
14960
14961 \begin_inset LatexCommand \index{\_\_naked}
14962
14963 \end_inset
14964
14965 .
14966 \layout Itemize
14967
14968 less_pedantic
14969 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
14970
14971 \end_inset
14972
14973  - the compiler will not warn you anymore for obvious mistakes, you'r on
14974  your own now ;-(
14975 \layout Itemize
14976
14977 disable_warning <nnnn>
14978 \begin_inset LatexCommand \index{\#pragma disable\_warning}
14979
14980 \end_inset
14981
14982  - the compiler will not warn you anymore about warning number <nnnn>.
14983 \layout Itemize
14984
14985 nogcse
14986 \begin_inset LatexCommand \index{\#pragma nogcse}
14987
14988 \end_inset
14989
14990  - will stop global common subexpression elimination.
14991 \layout Itemize
14992
14993 noinduction
14994 \begin_inset LatexCommand \index{\#pragma noinduction}
14995
14996 \end_inset
14997
14998  - will stop loop induction optimizations.
14999 \layout Itemize
15000
15001 noinvariant
15002 \begin_inset LatexCommand \index{\#pragma noinvariant}
15003
15004 \end_inset
15005
15006  - will not do loop invariant optimizations.
15007  For more details see Loop Invariants in section
15008 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15009
15010 \end_inset
15011
15012 .
15013 \layout Itemize
15014
15015 noiv
15016 \begin_inset LatexCommand \index{\#pragma noiv}
15017
15018 \end_inset
15019
15020  - Do not generate interrupt
15021 \begin_inset LatexCommand \index{interrupt}
15022
15023 \end_inset
15024
15025  vector table entries for all ISR functions defined after the pragma.
15026  This is useful in cases where the interrupt vector table must be defined
15027  manually, or when there is a secondary, manually defined interrupt vector
15028  table (e.g.
15029  for the autovector feature of the Cypress EZ-USB FX2).
15030  More elegantly this can be achieved by obmitting the optional interrupt
15031  number after the interrupt keyword, see section
15032 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15033
15034 \end_inset
15035
15036 \SpecialChar ~
15037 about interrupts.
15038 \layout Itemize
15039
15040 nojtbound
15041 \begin_inset LatexCommand \index{\#pragma nojtbound}
15042
15043 \end_inset
15044
15045  - will not generate code for boundary value checking, when switch statements
15046  are turned into jump-tables (dangerous).
15047  For more details see section
15048 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15049
15050 \end_inset
15051
15052 .
15053 \layout Itemize
15054
15055 noloopreverse
15056 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15057
15058 \end_inset
15059
15060  - Will not do loop reversal optimization
15061 \layout Itemize
15062
15063 nooverlay
15064 \begin_inset LatexCommand \index{\#pragma nooverlay}
15065
15066 \end_inset
15067
15068  - the compiler will not overlay the parameters and local variables of a
15069  function.
15070 \layout Itemize
15071
15072 stackauto
15073 \begin_inset LatexCommand \index{\#pragma stackauto}
15074
15075 \end_inset
15076
15077 - See option -
15078 \begin_inset ERT
15079 status Collapsed
15080
15081 \layout Standard
15082
15083 \backslash
15084 /
15085 \end_inset
15086
15087 -stack-auto
15088 \begin_inset LatexCommand \index{-\/-stack-auto}
15089
15090 \end_inset
15091
15092  and section
15093 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
15094
15095 \end_inset
15096
15097  Parameters and Local Variables.
15098 \layout Itemize
15099
15100 opt_code_speed
15101 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
15102
15103 \end_inset
15104
15105 - The compiler will optimize code generation towards fast code, possibly
15106  at the expense of code size.
15107 \layout Itemize
15108
15109 opt_code_size
15110 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
15111
15112 \end_inset
15113
15114 - The compiler will optimize code generation towards compact code, possibly
15115  at the expense of code speed.
15116 \layout Itemize
15117
15118 opt_code_balanced
15119 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
15120
15121 \end_inset
15122
15123 - The compiler will attempt to generate code that is both compact and fast,
15124  as long as meeting one goal is not a detriment to the other (this is the
15125  default).
15126
15127 \layout Itemize
15128
15129 std_sdcc89
15130 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
15131
15132 \end_inset
15133
15134 - Generally follow the C89 standard, but allow SDCC features that conflict
15135  with the standard (default).
15136 \layout Itemize
15137
15138 std_c89
15139 \begin_inset LatexCommand \index{\#pragma std\_c89}
15140
15141 \end_inset
15142
15143 - Follow the C89 standard and disable SDCC features that conflict with the
15144  standard.
15145 \layout Itemize
15146
15147 std_sdcc99
15148 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
15149
15150 \end_inset
15151
15152 - Generally follow the C99 standard, but allow SDCC features that conflict
15153  with the standard (incomplete support).
15154 \layout Itemize
15155
15156 std_c99
15157 \begin_inset LatexCommand \index{\#pragma std\_c99}
15158
15159 \end_inset
15160
15161 - Follow the C99 standard and disable SDCC features that conflict with the
15162  standard (incomplete support).
15163 \layout Standard
15164
15165 SDCPP supports the following #pragma directives:
15166 \layout Itemize
15167
15168 preproc_asm
15169 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
15170
15171 \end_inset
15172
15173  (+ | -) - switch _asm _endasm block preprocessing on / off.
15174  Default is on.
15175 \layout Standard
15176
15177 The pragma's are intended to be used to turn-on or off certain optimizations
15178  which might cause the compiler to generate extra stack / data space to
15179  store compiler generated temporary variables.
15180  This usually happens in large functions.
15181  Pragma directives should be used as shown in the following example, they
15182  are used to control options & optimizations for a given function; pragmas
15183  should be placed before and/or after a function, placing pragma's inside
15184  a function body could have unpredictable results.
15185 \layout Verse
15186
15187
15188 \family typewriter
15189 #pragma save
15190 \begin_inset LatexCommand \index{\#pragma save}
15191
15192 \end_inset
15193
15194  \SpecialChar ~
15195 \SpecialChar ~
15196 \SpecialChar ~
15197 \SpecialChar ~
15198 \SpecialChar ~
15199 \SpecialChar ~
15200 \SpecialChar ~
15201 /* save the current settings */
15202 \newline
15203 #pragma nogcse
15204 \begin_inset LatexCommand \index{\#pragma nogcse}
15205
15206 \end_inset
15207
15208  \SpecialChar ~
15209 \SpecialChar ~
15210 \SpecialChar ~
15211 \SpecialChar ~
15212 \SpecialChar ~
15213 /* turnoff global subexpression elimination */
15214 \newline
15215 #pragma noinduction
15216 \begin_inset LatexCommand \index{\#pragma noinduction}
15217
15218 \end_inset
15219
15220  /* turn off induction optimizations */
15221 \newline
15222 int foo ()
15223 \newline
15224 {
15225 \newline
15226 \SpecialChar ~
15227  \SpecialChar ~
15228  ...
15229
15230 \newline
15231 \SpecialChar ~
15232  \SpecialChar ~
15233  /* large code */
15234 \newline
15235 \SpecialChar ~
15236  \SpecialChar ~
15237  ...
15238
15239 \newline
15240 }
15241 \newline
15242 #pragma restore
15243 \begin_inset LatexCommand \index{\#pragma restore}
15244
15245 \end_inset
15246
15247  /* turn the optimizations back on */
15248 \layout Standard
15249
15250 The compiler will generate a warning message when extra space is allocated.
15251  It is strongly recommended that the save and restore pragma's be used when
15252  changing options for a function.
15253 \layout Section
15254
15255 Defines Created by the Compiler
15256 \layout Standard
15257
15258 The compiler creates the following #defines
15259 \begin_inset LatexCommand \index{\#defines}
15260
15261 \end_inset
15262
15263
15264 \begin_inset LatexCommand \index{Defines created by the compiler}
15265
15266 \end_inset
15267
15268 :
15269 \newline
15270
15271 \layout Standard
15272
15273
15274 \begin_inset  Tabular
15275 <lyxtabular version="3" rows="10" columns="2">
15276 <features>
15277 <column alignment="center" valignment="top" leftline="true" width="0">
15278 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15279 <row topline="true" bottomline="true">
15280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15281 \begin_inset Text
15282
15283 \layout Standard
15284
15285
15286 \series bold
15287 #define
15288 \end_inset
15289 </cell>
15290 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15291 \begin_inset Text
15292
15293 \layout Standard
15294
15295
15296 \series bold
15297 Description
15298 \end_inset
15299 </cell>
15300 </row>
15301 <row topline="true">
15302 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15303 \begin_inset Text
15304
15305 \layout Standard
15306
15307 SDCC
15308 \begin_inset LatexCommand \index{SDCC}
15309
15310 \end_inset
15311
15312
15313 \end_inset
15314 </cell>
15315 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15316 \begin_inset Text
15317
15318 \layout Standard
15319
15320 this Symbol is always defined
15321 \end_inset
15322 </cell>
15323 </row>
15324 <row topline="true">
15325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15326 \begin_inset Text
15327
15328 \layout Standard
15329
15330 SDCC_mcs51
15331 \begin_inset LatexCommand \index{SDCC\_mcs51}
15332
15333 \end_inset
15334
15335  or SDCC_ds390
15336 \begin_inset LatexCommand \index{SDCC\_ds390}
15337
15338 \end_inset
15339
15340  or SDCC_z80
15341 \begin_inset LatexCommand \index{SDCC\_z80}
15342
15343 \end_inset
15344
15345 , etc
15346 \end_inset
15347 </cell>
15348 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15349 \begin_inset Text
15350
15351 \layout Standard
15352
15353 depending on the model used (e.g.: -mds390
15354 \end_inset
15355 </cell>
15356 </row>
15357 <row topline="true">
15358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15359 \begin_inset Text
15360
15361 \layout Standard
15362
15363 __mcs51
15364 \begin_inset LatexCommand \index{\_\_mcs51}
15365
15366 \end_inset
15367
15368 , __ds390
15369 \begin_inset LatexCommand \index{\_\_ds390}
15370
15371 \end_inset
15372
15373 , __hc08
15374 \begin_inset LatexCommand \index{\_\_hc08}
15375
15376 \end_inset
15377
15378 , __z80
15379 \begin_inset LatexCommand \index{\_\_z80}
15380
15381 \end_inset
15382
15383 , etc
15384 \end_inset
15385 </cell>
15386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15387 \begin_inset Text
15388
15389 \layout Standard
15390
15391 depending on the model used (e.g.
15392  -mz80)
15393 \end_inset
15394 </cell>
15395 </row>
15396 <row topline="true">
15397 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15398 \begin_inset Text
15399
15400 \layout Standard
15401
15402 SDCC_STACK_AUTO
15403 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
15404
15405 \end_inset
15406
15407
15408 \end_inset
15409 </cell>
15410 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15411 \begin_inset Text
15412
15413 \layout Standard
15414
15415 when
15416 \emph on
15417 -
15418 \begin_inset ERT
15419 status Collapsed
15420
15421 \layout Standard
15422
15423 \backslash
15424 /
15425 \end_inset
15426
15427 -stack-auto
15428 \emph default
15429  option is used
15430 \end_inset
15431 </cell>
15432 </row>
15433 <row topline="true">
15434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15435 \begin_inset Text
15436
15437 \layout Standard
15438
15439 SDCC_MODEL_SMALL
15440 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
15441
15442 \end_inset
15443
15444
15445 \end_inset
15446 </cell>
15447 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15448 \begin_inset Text
15449
15450 \layout Standard
15451
15452 when
15453 \emph on
15454 -
15455 \begin_inset ERT
15456 status Collapsed
15457
15458 \layout Standard
15459
15460 \backslash
15461 /
15462 \end_inset
15463
15464 -model-small
15465 \emph default
15466  is used
15467 \end_inset
15468 </cell>
15469 </row>
15470 <row topline="true">
15471 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15472 \begin_inset Text
15473
15474 \layout Standard
15475
15476 SDCC_MODEL_LARGE
15477 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
15478
15479 \end_inset
15480
15481
15482 \end_inset
15483 </cell>
15484 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15485 \begin_inset Text
15486
15487 \layout Standard
15488
15489 when
15490 \emph on
15491 -
15492 \begin_inset ERT
15493 status Collapsed
15494
15495 \layout Standard
15496
15497 \backslash
15498 /
15499 \end_inset
15500
15501 -model-large
15502 \emph default
15503  is used
15504 \end_inset
15505 </cell>
15506 </row>
15507 <row topline="true">
15508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15509 \begin_inset Text
15510
15511 \layout Standard
15512
15513 SDCC_USE_XSTACK
15514 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15515
15516 \end_inset
15517
15518
15519 \end_inset
15520 </cell>
15521 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15522 \begin_inset Text
15523
15524 \layout Standard
15525
15526 when
15527 \emph on
15528 -
15529 \begin_inset ERT
15530 status Collapsed
15531
15532 \layout Standard
15533
15534 \backslash
15535 /
15536 \end_inset
15537
15538 -xstack
15539 \emph default
15540  option is used
15541 \end_inset
15542 </cell>
15543 </row>
15544 <row topline="true">
15545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15546 \begin_inset Text
15547
15548 \layout Standard
15549
15550 SDCC_STACK_TENBIT
15551 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
15552
15553 \end_inset
15554
15555
15556 \end_inset
15557 </cell>
15558 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15559 \begin_inset Text
15560
15561 \layout Standard
15562
15563 when
15564 \emph on
15565 -mds390
15566 \emph default
15567  is used
15568 \end_inset
15569 </cell>
15570 </row>
15571 <row topline="true" bottomline="true">
15572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15573 \begin_inset Text
15574
15575 \layout Standard
15576
15577 SDCC_MODEL_FLAT24
15578 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
15579
15580 \end_inset
15581
15582
15583 \end_inset
15584 </cell>
15585 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15586 \begin_inset Text
15587
15588 \layout Standard
15589
15590 when
15591 \emph on
15592 -mds390
15593 \emph default
15594  is used
15595 \end_inset
15596 </cell>
15597 </row>
15598 </lyxtabular>
15599
15600 \end_inset
15601
15602
15603 \layout Chapter
15604
15605 Notes on supported Processors
15606 \layout Section
15607
15608 MCS51 variants
15609 \begin_inset LatexCommand \label{sub:MCS51-variants}
15610
15611 \end_inset
15612
15613
15614 \begin_inset LatexCommand \index{MCS51 variants}
15615
15616 \end_inset
15617
15618
15619 \layout Standard
15620
15621 MCS51 processors are available from many vendors and come in many different
15622  flavours.
15623  While they might differ considerably in respect to Special Function Registers
15624  the core MCS51 is usually not modified or is kept compatible.
15625
15626 \layout Subsection
15627
15628 pdata access by SFR
15629 \layout Standard
15630
15631 With the upcome of devices with internal xdata and flash memory devices
15632  using port P2
15633 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15634
15635 \end_inset
15636
15637  as dedicated I/O port is becoming more popular.
15638  Switching the high byte for pdata
15639 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15640
15641 \end_inset
15642
15643  access which was formerly done by port P2 is then achieved by a Special
15644  Function Register
15645 \begin_inset LatexCommand \index{sfr}
15646
15647 \end_inset
15648
15649 .
15650  In well-established MCS51 tradition the address of this
15651 \emph on
15652 sfr
15653 \emph default
15654  is where the chip designers decided to put it.
15655  Needless to say that they didn't agree on a common name either.
15656  So that the startup code can correctly initialize xdata variables, you
15657  should define an sfr with the name _XPAGE
15658 \family typewriter
15659
15660 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
15661
15662 \end_inset
15663
15664
15665 \family default
15666  at the appropriate location if the default, port P2, is not used for this.
15667  Some examples are:
15668 \layout Verse
15669
15670
15671 \family typewriter
15672 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
15673 \layout Verse
15674
15675
15676 \family typewriter
15677 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
15678 \layout Verse
15679
15680
15681 \family typewriter
15682 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
15683 \layout Standard
15684
15685 For more exotic implementations further customizations may be needed.
15686  See section
15687 \begin_inset LatexCommand \ref{sub:Startup-Code}
15688
15689 \end_inset
15690
15691  for other possibilities.
15692 \layout Subsection
15693
15694 Other Features available by SFR
15695 \layout Standard
15696
15697 Some MCS51 variants offer features like Double DPTR
15698 \begin_inset LatexCommand \index{DPTR}
15699
15700 \end_inset
15701
15702 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
15703  These are currently not used for the MCS51 port.
15704  If you absolutely need them you can fall back to inline assembly or submit
15705  a patch to SDCC.
15706 \layout Section
15707
15708 DS400 port
15709 \layout Standard
15710
15711 The DS80C400 microcontroller has a rich set of peripherals.
15712  In its built-in ROM library it includes functions to access some of the
15713  features, among them is a TCP stack with IP4 and IP6 support.
15714  Library headers (currently in beta status) and other files are provided
15715  at
15716 \size footnotesize
15717
15718 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
15719
15720 \end_inset
15721
15722 .
15723
15724 \layout Section
15725
15726 The Z80 and gbz80 port
15727 \layout Standard
15728
15729 SDCC can target both the Zilog
15730 \begin_inset LatexCommand \index{Z80}
15731
15732 \end_inset
15733
15734  and the Nintendo Gameboy's Z80-like gbz80
15735 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
15736
15737 \end_inset
15738
15739 .
15740  The Z80 port is passed through the same
15741 \emph on
15742 regressions tests
15743 \begin_inset LatexCommand \index{Regression test}
15744
15745 \end_inset
15746
15747
15748 \emph default
15749  as the MCS51 and DS390 ports, so floating point support, support for long
15750  variables and bitfield support is fine.
15751  See mailing lists and forums about interrupt routines.
15752 \layout Standard
15753
15754 As always, the code is the authoritative reference - see z80/ralloc.c and
15755  z80/gen.c.
15756  The stack
15757 \begin_inset LatexCommand \index{stack}
15758
15759 \end_inset
15760
15761  frame is similar to that generated by the IAR Z80 compiler.
15762  IX is used as the base pointer, HL and IY are used as a temporary registers,
15763  and BC and DE are available for holding variables.
15764  Return values
15765 \begin_inset LatexCommand \index{return value}
15766
15767 \end_inset
15768
15769  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
15770  bytes).
15771  The gbz80 port use the same set of registers for the return values, but
15772  in a different order of significance: E (one byte), DE (two bytes), or
15773  HLDE (four bytes).
15774 \layout Section
15775
15776 The HC08 port
15777 \layout Standard
15778
15779 The port to the Motorola HC08
15780 \begin_inset LatexCommand \index{HC08}
15781
15782 \end_inset
15783
15784  family has been added in October 2003, and is still undergoing some basic
15785  development.
15786  The code generator is complete, but the register allocation is still quite
15787  unoptimized.
15788  Some of the SDCC's standard C library functions have embedded non-HC08
15789  inline assembly and so are not yet usable.
15790 \newline
15791
15792 \newline
15793
15794 \layout Section
15795
15796 The PIC14 port
15797 \layout Standard
15798
15799 The 14bit PIC
15800 \begin_inset LatexCommand \index{PIC14}
15801
15802 \end_inset
15803
15804  port still requires a major effort from the development community.
15805  However it can work for very simple code.
15806 \layout Subsection
15807
15808 C code and 14bit PIC code page
15809 \begin_inset LatexCommand \index{code page (pic14)}
15810
15811 \end_inset
15812
15813  and RAM banks
15814 \begin_inset LatexCommand \index{RAM bank (pic14)}
15815
15816 \end_inset
15817
15818
15819 \layout Standard
15820
15821 The linker organizes allocation for the code page and RAM banks.
15822  It does not have intimate knowledge of the code flow.
15823  It will put all the code section of a single asm file into a single code
15824  page.
15825  In order to make use of multiple code pages, separate asm files must be
15826  used.
15827  The compiler treats all functions of a single C file as being in the same
15828  code page unless it is non static.
15829  The compiler treats all local variables of a single C file as being in
15830  the same RAM bank unless it is an extern.
15831 \newline
15832
15833 \newline
15834 To get the best follow these guide lines:
15835 \layout Enumerate
15836
15837 make local functions static, as non static functions require code page selection
15838  overhead.
15839 \layout Enumerate
15840
15841 Make local variables static as extern variables require RAM bank selection
15842  overhead.
15843 \layout Enumerate
15844
15845 For devices that have multiple code pages it is more efficient to use the
15846  same number of files as pages, i.e.
15847  for the 16F877 use 4 separate files and i.e.
15848  for the 16F874 use 2 separate files.
15849  This way the linker can put the code for each file into different code
15850  pages and the compiler can allocate reusable variables more efficiently
15851  and there's less page selection overhead.
15852  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
15853  instruction set) use 'unsigned char' whereever possible instead of 'int'.
15854 \layout Subsection
15855
15856 Creating a device include file
15857 \layout Standard
15858
15859 For generating a device include file use the support perl script inc2h.pl
15860  kept in directory support/script.
15861 \layout Subsection
15862
15863 Interrupt code
15864 \layout Standard
15865
15866 For the interrupt function, use the keyword 'interrupt'
15867 \begin_inset LatexCommand \index{interrupt}
15868
15869 \end_inset
15870
15871  with level number of 0 (PIC14 only has 1 interrupt so this number is only
15872  there to avoid a syntax error - it ought to be fixed).
15873  E.g.:
15874 \layout Verse
15875
15876
15877 \family typewriter
15878 void Intr(void) interrupt 0
15879 \newline
15880 {
15881 \newline
15882 \SpecialChar ~
15883 \SpecialChar ~
15884 T0IF = 0; /* Clear timer interrupt */
15885 \newline
15886 }
15887 \layout Subsection
15888
15889 Linking and assembling
15890 \layout Standard
15891
15892 For assembling you can use either GPUTILS'
15893 \begin_inset LatexCommand \index{gputils (pic tools)}
15894
15895 \end_inset
15896
15897  gpasm.exe or MPLAB's mpasmwin.exe.
15898  GPUTILS is available from
15899 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
15900
15901 \end_inset
15902
15903 .
15904  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
15905  If you use MPLAB and an interrupt function then the linker script file
15906  vectors section will need to be enlarged to link with mplink.
15907 \newline
15908
15909 \newline
15910 Here is a
15911 \family typewriter
15912 Makefile
15913 \family default
15914  using GPUTILS:
15915 \layout Verse
15916
15917
15918 \family typewriter
15919 .c.o:
15920 \newline
15921 \SpecialChar ~
15922 \SpecialChar ~
15923 \SpecialChar ~
15924 \SpecialChar ~
15925 \SpecialChar ~
15926 \SpecialChar ~
15927 \SpecialChar ~
15928 \SpecialChar ~
15929 sdcc -S -V -mpic14 -p16F877 $<
15930 \newline
15931 \SpecialChar ~
15932 \SpecialChar ~
15933 \SpecialChar ~
15934 \SpecialChar ~
15935 \SpecialChar ~
15936 \SpecialChar ~
15937 \SpecialChar ~
15938 \SpecialChar ~
15939 gpasm -c $*.asm
15940 \newline
15941
15942 \newline
15943 $(PRJ).hex: $(OBJS)
15944 \newline
15945 \SpecialChar ~
15946 \SpecialChar ~
15947 \SpecialChar ~
15948 \SpecialChar ~
15949 \SpecialChar ~
15950 \SpecialChar ~
15951 \SpecialChar ~
15952 \SpecialChar ~
15953 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
15954 \layout Standard
15955
15956 Here is a
15957 \family typewriter
15958 Makefile
15959 \family default
15960  using MPLAB:
15961 \layout Verse
15962
15963
15964 \family typewriter
15965 .c.o:
15966 \newline
15967 \SpecialChar ~
15968 \SpecialChar ~
15969 \SpecialChar ~
15970 \SpecialChar ~
15971 \SpecialChar ~
15972 \SpecialChar ~
15973 \SpecialChar ~
15974 \SpecialChar ~
15975 sdcc -S -V -mpic14 -p16F877 $<
15976 \newline
15977 \SpecialChar ~
15978 \SpecialChar ~
15979 \SpecialChar ~
15980 \SpecialChar ~
15981 \SpecialChar ~
15982 \SpecialChar ~
15983 \SpecialChar ~
15984 \SpecialChar ~
15985 mpasmwin /q /o $*.asm
15986 \newline
15987
15988 \newline
15989 $(PRJ).hex: $(OBJS)
15990 \newline
15991 \SpecialChar ~
15992 \SpecialChar ~
15993 \SpecialChar ~
15994 \SpecialChar ~
15995 \SpecialChar ~
15996 \SpecialChar ~
15997 \SpecialChar ~
15998 \SpecialChar ~
15999 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
16000 \layout Standard
16001
16002 Please note that indentations within a
16003 \family typewriter
16004  Makefile
16005 \family default
16006  have to be done with a tabulator character.
16007 \layout Section
16008
16009 The PIC16
16010 \begin_inset LatexCommand \index{PIC16}
16011
16012 \end_inset
16013
16014  port
16015 \layout Standard
16016
16017 The PIC16
16018 \begin_inset LatexCommand \index{PIC16}
16019
16020 \end_inset
16021
16022  port is the portion of SDCC that is responsible to produce code for the
16023  Microchip
16024 \begin_inset LatexCommand \index{Microchip}
16025
16026 \end_inset
16027
16028 (TM) microcontrollers with 16 bit core.
16029  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
16030  Currently supported devices are:
16031 \layout Standard
16032 \align center
16033
16034 \begin_inset  Tabular
16035 <lyxtabular version="3" rows="4" columns="6">
16036 <features>
16037 <column alignment="center" valignment="top" leftline="true" width="0">
16038 <column alignment="center" valignment="top" leftline="true" width="0">
16039 <column alignment="center" valignment="top" leftline="true" width="0">
16040 <column alignment="center" valignment="top" leftline="true" width="0">
16041 <column alignment="center" valignment="top" leftline="true" width="0">
16042 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16043 <row topline="true">
16044 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16045 \begin_inset Text
16046
16047 \layout Standard
16048
16049 18F242
16050 \end_inset
16051 </cell>
16052 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16053 \begin_inset Text
16054
16055 \layout Standard
16056
16057 18F248
16058 \end_inset
16059 </cell>
16060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16061 \begin_inset Text
16062
16063 \layout Standard
16064
16065 18F252
16066 \end_inset
16067 </cell>
16068 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16069 \begin_inset Text
16070
16071 \layout Standard
16072
16073 18F258
16074 \end_inset
16075 </cell>
16076 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16077 \begin_inset Text
16078
16079 \layout Standard
16080
16081 18F442
16082 \end_inset
16083 </cell>
16084 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16085 \begin_inset Text
16086
16087 \layout Standard
16088
16089 18F448
16090 \end_inset
16091 </cell>
16092 </row>
16093 <row topline="true">
16094 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16095 \begin_inset Text
16096
16097 \layout Standard
16098
16099 18F452
16100 \end_inset
16101 </cell>
16102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16103 \begin_inset Text
16104
16105 \layout Standard
16106
16107 18F458
16108 \end_inset
16109 </cell>
16110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16111 \begin_inset Text
16112
16113 \layout Standard
16114
16115 18F1220
16116 \end_inset
16117 </cell>
16118 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16119 \begin_inset Text
16120
16121 \layout Standard
16122
16123 18F2220
16124 \end_inset
16125 </cell>
16126 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16127 \begin_inset Text
16128
16129 \layout Standard
16130
16131 18F2550
16132 \end_inset
16133 </cell>
16134 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16135 \begin_inset Text
16136
16137 \layout Standard
16138
16139 18F4331
16140 \end_inset
16141 </cell>
16142 </row>
16143 <row topline="true">
16144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16145 \begin_inset Text
16146
16147 \layout Standard
16148
16149 18F4455
16150 \end_inset
16151 </cell>
16152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16153 \begin_inset Text
16154
16155 \layout Standard
16156
16157 18F6520
16158 \end_inset
16159 </cell>
16160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16161 \begin_inset Text
16162
16163 \layout Standard
16164
16165 18F6620
16166 \end_inset
16167 </cell>
16168 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16169 \begin_inset Text
16170
16171 \layout Standard
16172
16173 18F6680
16174 \end_inset
16175 </cell>
16176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16177 \begin_inset Text
16178
16179 \layout Standard
16180
16181 18F6720
16182 \end_inset
16183 </cell>
16184 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16185 \begin_inset Text
16186
16187 \layout Standard
16188
16189 18F8520
16190 \end_inset
16191 </cell>
16192 </row>
16193 <row topline="true" bottomline="true">
16194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16195 \begin_inset Text
16196
16197 \layout Standard
16198
16199 18F8620
16200 \end_inset
16201 </cell>
16202 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16203 \begin_inset Text
16204
16205 \layout Standard
16206
16207 18F8680
16208 \end_inset
16209 </cell>
16210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16211 \begin_inset Text
16212
16213 \layout Standard
16214
16215 18F8720
16216 \end_inset
16217 </cell>
16218 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16219 \begin_inset Text
16220
16221 \layout Standard
16222
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 \end_inset
16231 </cell>
16232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16233 \begin_inset Text
16234
16235 \layout Standard
16236
16237 \end_inset
16238 </cell>
16239 </row>
16240 </lyxtabular>
16241
16242 \end_inset
16243
16244
16245 \layout Subsection
16246
16247 Global Options
16248 \layout Standard
16249
16250 PIC16 port supports the standard command line arguments as supposed, with
16251  the exception of certain cases that will be mentioned in the following
16252  list:
16253 \layout List
16254 \labelwidthstring 00.00.0000
16255
16256 -
16257 \begin_inset ERT
16258 status Collapsed
16259
16260 \layout Standard
16261
16262 \backslash
16263 /
16264 \end_inset
16265
16266 -callee-saves See -
16267 \begin_inset ERT
16268 status Collapsed
16269
16270 \layout Standard
16271
16272 \backslash
16273 /
16274 \end_inset
16275
16276 -all-callee-saves
16277 \layout List
16278 \labelwidthstring 00.00.0000
16279
16280 -
16281 \begin_inset ERT
16282 status Collapsed
16283
16284 \layout Standard
16285
16286 \backslash
16287 /
16288 \end_inset
16289
16290 -all-callee-saves All function arguments are passed on stack by default.
16291
16292 \emph on
16293 There is no need to specify this in the command line.
16294 \layout List
16295 \labelwidthstring 00.00.0000
16296
16297 -
16298 \begin_inset ERT
16299 status Collapsed
16300
16301 \layout Standard
16302
16303 \backslash
16304 /
16305 \end_inset
16306
16307 -fommit-frame-pointer Frame pointer will be omitted when the function uses
16308  no local variables.
16309 \layout Subsection
16310
16311 Port Specific Options
16312 \begin_inset LatexCommand \index{Options PIC16}
16313
16314 \end_inset
16315
16316
16317 \layout Standard
16318
16319 The port specific options appear after the global options in the sdcc --help
16320  output.
16321 \layout Subsubsection
16322
16323 General Options
16324 \layout Standard
16325
16326 General options enable certain port features and optimizations.
16327 \layout List
16328 \labelwidthstring 00.00.0000
16329
16330 -
16331 \begin_inset ERT
16332 status Collapsed
16333
16334 \layout Standard
16335
16336 \backslash
16337 /
16338 \end_inset
16339
16340 -stack-model=[model] Used in conjuction with the command above.
16341  Defines the stack model to be used, valid stack models are :
16342 \begin_deeper
16343 \layout List
16344 \labelwidthstring 00.00.0000
16345
16346
16347 \emph on
16348 small
16349 \emph default
16350  Selects small stack model.
16351  8 bit stack and frame pointers.
16352  Supports 256 bytes stack size.
16353 \layout List
16354 \labelwidthstring 00.00.0000
16355
16356
16357 \emph on
16358 large
16359 \emph default
16360  Selects large stack model.
16361  16 bit stack and frame pointers.
16362  Supports 65536 bytes stack size.
16363 \end_deeper
16364 \layout List
16365 \labelwidthstring 00.00.0000
16366
16367 -
16368 \begin_inset ERT
16369 status Collapsed
16370
16371 \layout Standard
16372
16373 \backslash
16374 /
16375 \end_inset
16376
16377 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
16378  unitialized data variables with [kword].
16379  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
16380 \layout List
16381 \labelwidthstring 00.00.0000
16382
16383 -
16384 \begin_inset ERT
16385 status Collapsed
16386
16387 \layout Standard
16388
16389 \backslash
16390 /
16391 \end_inset
16392
16393 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
16394  Useful for bootloaders.
16395 \layout List
16396 \labelwidthstring 00.00.0000
16397
16398 -
16399 \begin_inset ERT
16400 status Collapsed
16401
16402 \layout Standard
16403
16404 \backslash
16405 /
16406 \end_inset
16407
16408 -asm= sets the full path and name of an external assembler to call.
16409 \layout List
16410 \labelwidthstring 00.00.0000
16411
16412 -
16413 \begin_inset ERT
16414 status Collapsed
16415
16416 \layout Standard
16417
16418 \backslash
16419 /
16420 \end_inset
16421
16422 -link= sets the full path and name of an external linker to call.
16423 \layout List
16424 \labelwidthstring 00.00.0000
16425
16426 -
16427 \begin_inset ERT
16428 status Collapsed
16429
16430 \layout Standard
16431
16432 \backslash
16433 /
16434 \end_inset
16435
16436 -mplab-comp MPLAB compatibility option.
16437  Currently only suppresses special gpasm directives.
16438 \layout Subsubsection
16439
16440 Optimization Options
16441 \layout List
16442 \labelwidthstring 00.00.0000
16443
16444 -
16445 \begin_inset ERT
16446 status Collapsed
16447
16448 \layout Standard
16449
16450 \backslash
16451 /
16452 \end_inset
16453
16454 -optimize-goto Try to use (conditional) BRA instead of GOTO
16455 \layout List
16456 \labelwidthstring 00.00.0000
16457
16458 -
16459 \begin_inset ERT
16460 status Collapsed
16461
16462 \layout Standard
16463
16464 \backslash
16465 /
16466 \end_inset
16467
16468 -optimize-cmp Try to optimize some compares.
16469 \layout List
16470 \labelwidthstring 00.00.0000
16471
16472 -
16473 \begin_inset ERT
16474 status Collapsed
16475
16476 \layout Standard
16477
16478 \backslash
16479 /
16480 \end_inset
16481
16482 -obanksel=nn Set optimization level for inserting BANKSELs.
16483 \newline
16484
16485 \begin_deeper
16486 \layout List
16487 \labelwidthstring 00.00.0000
16488
16489 0 no optimization
16490 \layout List
16491 \labelwidthstring 00.00.0000
16492
16493 1 checks previous used register and if it is the same then does not emit
16494  BANKSEL, accounts only for labels.
16495 \layout List
16496 \labelwidthstring 00.00.0000
16497
16498 2 tries to check the location of (even different) symbols and removes BANKSELs
16499  if they are in the same bank.
16500
16501 \newline
16502
16503 \emph on
16504 Important: There might be problems if the linker script has data sections
16505  across bank borders!
16506 \end_deeper
16507 \layout Subsubsection
16508
16509 Linking Options
16510 \layout List
16511 \labelwidthstring 00.00.0000
16512
16513 -
16514 \begin_inset ERT
16515 status Collapsed
16516
16517 \layout Standard
16518
16519 \backslash
16520 /
16521 \end_inset
16522
16523 -nodefaultlibs do not link default libraries when linking
16524 \layout List
16525 \labelwidthstring 00.00.0000
16526
16527 -
16528 \begin_inset ERT
16529 status Collapsed
16530
16531 \layout Standard
16532
16533 \backslash
16534 /
16535 \end_inset
16536
16537 -no-crt Don't link the default run-time modules
16538 \layout List
16539 \labelwidthstring 00.00.0000
16540
16541 -
16542 \begin_inset ERT
16543 status Collapsed
16544
16545 \layout Standard
16546
16547 \backslash
16548 /
16549 \end_inset
16550
16551 -use-crt= Use a custom run-time module instead of the defaults.
16552 \layout Subsubsection
16553
16554 Debugging Options
16555 \layout Standard
16556
16557 Debugging options enable extra debugging information in the output files.
16558 \layout List
16559 \labelwidthstring 00.00.0000
16560
16561 -
16562 \begin_inset ERT
16563 status Collapsed
16564
16565 \layout Standard
16566
16567 \backslash
16568 /
16569 \end_inset
16570
16571 -debug-xtra Similar to -
16572 \begin_inset ERT
16573 status Collapsed
16574
16575 \layout Standard
16576
16577 \backslash
16578 /
16579 \end_inset
16580
16581 -debug
16582 \begin_inset LatexCommand \index{-\/-debug}
16583
16584 \end_inset
16585
16586 , but dumps more information.
16587 \layout List
16588 \labelwidthstring 00.00.0000
16589
16590 -
16591 \begin_inset ERT
16592 status Collapsed
16593
16594 \layout Standard
16595
16596 \backslash
16597 /
16598 \end_inset
16599
16600 -debug-ralloc Force register allocator to dump <source>.d file with debugging
16601  information.
16602  <source> is the name of the file compiled.
16603 \layout List
16604 \labelwidthstring 00.00.0000
16605
16606 -
16607 \begin_inset ERT
16608 status Collapsed
16609
16610 \layout Standard
16611
16612 \backslash
16613 /
16614 \end_inset
16615
16616 -pcode-verbose Enable pcode debugging information in translation.
16617 \layout List
16618 \labelwidthstring 00.00.0000
16619
16620 -
16621 \begin_inset ERT
16622 status Collapsed
16623
16624 \layout Standard
16625
16626 \backslash
16627 /
16628 \end_inset
16629
16630 -denable-peeps Force the usage of peepholes.
16631  Use with care.
16632 \layout List
16633 \labelwidthstring 00.00.0000
16634
16635 -
16636 \begin_inset ERT
16637 status Collapsed
16638
16639 \layout Standard
16640
16641 \backslash
16642 /
16643 \end_inset
16644
16645 -gstack Trace push/pops for stack pointer overflow
16646 \layout List
16647 \labelwidthstring 00.00.0000
16648
16649 -
16650 \begin_inset ERT
16651 status Collapsed
16652
16653 \layout Standard
16654
16655 \backslash
16656 /
16657 \end_inset
16658
16659 -call-tree dump call tree in .calltree file
16660 \layout Subsection
16661
16662 Enviromental Variables
16663 \layout Standard
16664
16665 There is a number of enviromental variables that can be used when running
16666  SDCC to enable certain optimizations or force a specific program behaviour.
16667  these variables are primarily for debugging purposes so they can be enabled/dis
16668 abled at will.
16669 \layout Standard
16670
16671 Currently there is only two such variables available:
16672 \layout List
16673 \labelwidthstring 00.00.0000
16674
16675 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
16676  bitfields is optimized by directly loading FSR0 with the address of the
16677  bitfield structure.
16678  Normally SDCC will cast the bitfield structure to a bitfield pointer and
16679  then load FSR0.
16680  This step saves data ram and code space for functions that perform heavy
16681  use of bitfields.
16682  (ie.
16683  80 bytes of code space are saved when compiling malloc.c with this option).
16684
16685 \layout List
16686 \labelwidthstring 00.00.0000
16687
16688 NO_REG_OPT do not perform pCode registers optimization.
16689  This should be used for debugging purposes.
16690  In some where bugs in the pcode optimizer are found, users can benefit
16691  from temporarily disabling the optimizer until the bug is fixed.
16692 \layout Subsection
16693
16694 Preprocessor Macros
16695 \layout Standard
16696
16697 PIC16 port defines the following preprocessor macros while translating a
16698  source.
16699 \layout Standard
16700 \align center
16701
16702 \begin_inset  Tabular
16703 <lyxtabular version="3" rows="6" columns="2">
16704 <features>
16705 <column alignment="center" valignment="top" leftline="true" width="0">
16706 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16707 <row topline="true" bottomline="true">
16708 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16709 \begin_inset Text
16710
16711 \layout Standard
16712
16713 Macro
16714 \end_inset
16715 </cell>
16716 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16717 \begin_inset Text
16718
16719 \layout Standard
16720
16721 Description
16722 \end_inset
16723 </cell>
16724 </row>
16725 <row topline="true">
16726 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16727 \begin_inset Text
16728
16729 \layout Standard
16730
16731 SDCC_pic16
16732 \end_inset
16733 </cell>
16734 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16735 \begin_inset Text
16736
16737 \layout Standard
16738
16739 Port identification
16740 \end_inset
16741 </cell>
16742 </row>
16743 <row topline="true">
16744 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16745 \begin_inset Text
16746
16747 \layout Standard
16748
16749 _
16750 \begin_inset ERT
16751 status Collapsed
16752
16753 \layout Standard
16754
16755 \backslash
16756 /
16757 \end_inset
16758
16759 _pic16
16760 \end_inset
16761 </cell>
16762 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16763 \begin_inset Text
16764
16765 \layout Standard
16766
16767 Port identification (same as above)
16768 \end_inset
16769 </cell>
16770 </row>
16771 <row topline="true">
16772 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16773 \begin_inset Text
16774
16775 \layout Standard
16776
16777 pic18fxxxx
16778 \end_inset
16779 </cell>
16780 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16781 \begin_inset Text
16782
16783 \layout Standard
16784
16785 MCU Identification.
16786
16787 \emph on
16788 xxxx
16789 \emph default
16790  is the microcontrol identification number, i.e.
16791  452, 6620, etc
16792 \end_inset
16793 </cell>
16794 </row>
16795 <row topline="true">
16796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16797 \begin_inset Text
16798
16799 \layout Standard
16800
16801 _
16802 \begin_inset ERT
16803 status Collapsed
16804
16805 \layout Standard
16806
16807 \backslash
16808 /
16809 \end_inset
16810
16811 _18Fxxxx
16812 \end_inset
16813 </cell>
16814 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16815 \begin_inset Text
16816
16817 \layout Standard
16818
16819 MCU Identification (same as above)
16820 \end_inset
16821 </cell>
16822 </row>
16823 <row topline="true" bottomline="true">
16824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16825 \begin_inset Text
16826
16827 \layout Standard
16828
16829 STACK_MODEL_nnn
16830 \end_inset
16831 </cell>
16832 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16833 \begin_inset Text
16834
16835 \layout Standard
16836
16837 nnn = SMALL or LARGE respectively according to the stack model used
16838 \end_inset
16839 </cell>
16840 </row>
16841 </lyxtabular>
16842
16843 \end_inset
16844
16845
16846 \layout Standard
16847
16848 In addition the following macros are defined when calling assembler:
16849 \layout Standard
16850 \align center
16851
16852 \begin_inset  Tabular
16853 <lyxtabular version="3" rows="4" columns="2">
16854 <features>
16855 <column alignment="center" valignment="top" leftline="true" width="0">
16856 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16857 <row topline="true" bottomline="true">
16858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16859 \begin_inset Text
16860
16861 \layout Standard
16862
16863 Macro
16864 \end_inset
16865 </cell>
16866 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16867 \begin_inset Text
16868
16869 \layout Standard
16870
16871 Description
16872 \end_inset
16873 </cell>
16874 </row>
16875 <row topline="true">
16876 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16877 \begin_inset Text
16878
16879 \layout Standard
16880
16881 __18Fxxxx
16882 \end_inset
16883 </cell>
16884 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16885 \begin_inset Text
16886
16887 \layout Standard
16888
16889 MCU Identification.
16890
16891 \emph on
16892 xxxx
16893 \emph default
16894  is the microcontrol identification number, i.e.
16895  452, 6620, etc
16896 \end_inset
16897 </cell>
16898 </row>
16899 <row topline="true">
16900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16901 \begin_inset Text
16902
16903 \layout Standard
16904
16905 SDCC_MODEL_nnn
16906 \end_inset
16907 </cell>
16908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16909 \begin_inset Text
16910
16911 \layout Standard
16912
16913 nnn = SMALL or LARGE respectively according to the memory model used for
16914  SDCC
16915 \end_inset
16916 </cell>
16917 </row>
16918 <row topline="true" bottomline="true">
16919 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16920 \begin_inset Text
16921
16922 \layout Standard
16923
16924 STACK_MODEL_nnn
16925 \end_inset
16926 </cell>
16927 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16928 \begin_inset Text
16929
16930 \layout Standard
16931
16932 nnn = SMALL or LARGE respectively according to the stack model used
16933 \end_inset
16934 </cell>
16935 </row>
16936 </lyxtabular>
16937
16938 \end_inset
16939
16940
16941 \layout Subsection
16942
16943 Directories
16944 \layout Standard
16945
16946 PIC16
16947 \begin_inset LatexCommand \index{PIC16}
16948
16949 \end_inset
16950
16951  port uses the following directories for searching header files and libraries.
16952 \layout Standard
16953 \align center
16954
16955 \begin_inset  Tabular
16956 <lyxtabular version="3" rows="3" columns="4">
16957 <features>
16958 <column alignment="center" valignment="top" leftline="true" width="0">
16959 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16960 <column alignment="center" valignment="top" width="0">
16961 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16962 <row topline="true" bottomline="true">
16963 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16964 \begin_inset Text
16965
16966 \layout Standard
16967
16968 Directory
16969 \end_inset
16970 </cell>
16971 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16972 \begin_inset Text
16973
16974 \layout Standard
16975
16976 Description
16977 \end_inset
16978 </cell>
16979 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16980 \begin_inset Text
16981
16982 \layout Standard
16983
16984 Target
16985 \end_inset
16986 </cell>
16987 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16988 \begin_inset Text
16989
16990 \layout Standard
16991
16992 Command prefix
16993 \end_inset
16994 </cell>
16995 </row>
16996 <row topline="true">
16997 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16998 \begin_inset Text
16999
17000 \layout Standard
17001
17002 PREFIX/sdcc/include/pic16
17003 \end_inset
17004 </cell>
17005 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17006 \begin_inset Text
17007
17008 \layout Standard
17009
17010 PIC16 specific headers
17011 \end_inset
17012 </cell>
17013 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17014 \begin_inset Text
17015
17016 \layout Standard
17017
17018 Compiler
17019 \end_inset
17020 </cell>
17021 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17022 \begin_inset Text
17023
17024 \layout Standard
17025
17026 -I
17027 \end_inset
17028 </cell>
17029 </row>
17030 <row topline="true" bottomline="true">
17031 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17032 \begin_inset Text
17033
17034 \layout Standard
17035
17036 PREFIX/sdcc/lib/pic16
17037 \end_inset
17038 </cell>
17039 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17040 \begin_inset Text
17041
17042 \layout Standard
17043
17044 PIC16 specific libraries
17045 \end_inset
17046 </cell>
17047 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17048 \begin_inset Text
17049
17050 \layout Standard
17051
17052 Linker
17053 \end_inset
17054 </cell>
17055 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17056 \begin_inset Text
17057
17058 \layout Standard
17059
17060 -L
17061 \end_inset
17062 </cell>
17063 </row>
17064 </lyxtabular>
17065
17066 \end_inset
17067
17068
17069 \layout Subsection
17070
17071 Pragmas
17072 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
17073
17074 \end_inset
17075
17076
17077 \layout Standard
17078
17079 PIC16 port currently supports the following pragmas:
17080 \layout List
17081 \labelwidthstring 00.00.0000
17082
17083 stack pragma stack forces the code generator to initialize the stack & frame
17084  pointers at a specific address.
17085  This is an adhoc solution for cases where no STACK directive is available
17086  in the linker script or gplink is not instructed to create a stack section.
17087 \newline
17088 The stack pragma should be used only once in a project.
17089  Multiple pragmas may result in indeterminate behaviour of the program.
17090 \begin_inset Foot
17091 collapsed false
17092
17093 \layout Standard
17094
17095 The old format (ie.
17096  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
17097  cross page boundaries (or even exceed the available data RAM) and crash
17098  the program.
17099  Make sure that stack does not cross page boundaries when using the SMALL
17100  stack model.
17101 \end_inset
17102
17103
17104 \newline
17105 The format is as follows:
17106 \layout LyX-Code
17107
17108 #pragma stack bottom_address [stack_size]
17109 \layout Standard
17110
17111
17112 \emph on
17113 bottom_address
17114 \emph default
17115  is the lower bound of the stack section.
17116  The stack pointer initially will point at address (bottom_address+stack_size-1).
17117 \layout LyX-Code
17118
17119 Example:
17120 \layout LyX-Code
17121
17122 \layout LyX-Code
17123
17124 /* initializes stack of 100 bytes at RAM address 0x200 */
17125 \layout LyX-Code
17126
17127 #pragma stack 0x200 100
17128 \layout Standard
17129
17130 If the stack_size field is omitted then a stack is created with the default
17131  size of 64.
17132  This size might be enough for most programs, but its not enough for operations
17133  with deep function nesting or excessive stack usage.
17134 \layout List
17135 \labelwidthstring 00.00.0000
17136
17137 wparam
17138 \emph on
17139 This pragma is deprecated.
17140  Its use will cause a warning message to be issued.
17141 \emph default
17142
17143 \newline
17144
17145 \layout List
17146 \labelwidthstring 00.00.0000
17147
17148 code place a function symbol at static FLASH address
17149 \layout LyX-Code
17150
17151 Example:
17152 \layout LyX-Code
17153
17154 \layout LyX-Code
17155
17156 /* place function test_func at 0x4000 */
17157 \layout LyX-Code
17158
17159 #pragma code test_func 0x4000
17160 \layout LyX-Code
17161
17162 \layout List
17163 \labelwidthstring 00.00.0000
17164
17165 library instructs the linker to use a library module.
17166 \newline
17167 Usage:
17168 \layout LyX-Code
17169
17170 #pragma library module_name
17171 \layout Standard
17172
17173
17174 \emph on
17175 module_name
17176 \emph default
17177  can be any library or object file (including its path).
17178  Note that there are four reserved keywords which have special meaning.
17179  These are:
17180 \layout Standard
17181 \align center
17182
17183 \begin_inset  Tabular
17184 <lyxtabular version="3" rows="6" columns="3">
17185 <features>
17186 <column alignment="center" valignment="top" leftline="true" width="0">
17187 <column alignment="block" valignment="top" leftline="true" width="20page%">
17188 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
17189 <row topline="true" bottomline="true">
17190 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17191 \begin_inset Text
17192
17193 \layout Standard
17194
17195 Keyword
17196 \end_inset
17197 </cell>
17198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17199 \begin_inset Text
17200
17201 \layout Standard
17202
17203 Description
17204 \end_inset
17205 </cell>
17206 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17207 \begin_inset Text
17208
17209 \layout Standard
17210
17211 Module to link
17212 \end_inset
17213 </cell>
17214 </row>
17215 <row topline="true">
17216 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17217 \begin_inset Text
17218
17219 \layout Standard
17220
17221
17222 \series bold
17223 ignore
17224 \end_inset
17225 </cell>
17226 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17227 \begin_inset Text
17228
17229 \layout Standard
17230
17231 ignore all library pragmas
17232 \end_inset
17233 </cell>
17234 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17235 \begin_inset Text
17236
17237 \layout Standard
17238
17239
17240 \emph on
17241 (none)
17242 \end_inset
17243 </cell>
17244 </row>
17245 <row topline="true">
17246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17247 \begin_inset Text
17248
17249 \layout Standard
17250
17251
17252 \series bold
17253 c
17254 \end_inset
17255 </cell>
17256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17257 \begin_inset Text
17258
17259 \layout Standard
17260
17261 link the C library
17262 \end_inset
17263 </cell>
17264 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17265 \begin_inset Text
17266
17267 \layout Standard
17268
17269
17270 \emph on
17271 libc18f
17272 \emph default
17273 .lib
17274 \end_inset
17275 </cell>
17276 </row>
17277 <row topline="true">
17278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17279 \begin_inset Text
17280
17281 \layout Standard
17282
17283
17284 \series bold
17285 math
17286 \end_inset
17287 </cell>
17288 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17289 \begin_inset Text
17290
17291 \layout Standard
17292
17293 link the Math libarary
17294 \end_inset
17295 </cell>
17296 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17297 \begin_inset Text
17298
17299 \layout Standard
17300
17301
17302 \emph on
17303 libm18f
17304 \emph default
17305 .lib
17306 \end_inset
17307 </cell>
17308 </row>
17309 <row topline="true">
17310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17311 \begin_inset Text
17312
17313 \layout Standard
17314
17315
17316 \series bold
17317 io
17318 \end_inset
17319 </cell>
17320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17321 \begin_inset Text
17322
17323 \layout Standard
17324
17325 link the I/O library
17326 \end_inset
17327 </cell>
17328 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17329 \begin_inset Text
17330
17331 \layout Standard
17332
17333
17334 \emph on
17335 libio18f*
17336 \emph default
17337 .lib
17338 \end_inset
17339 </cell>
17340 </row>
17341 <row topline="true" bottomline="true">
17342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17343 \begin_inset Text
17344
17345 \layout Standard
17346
17347
17348 \series bold
17349 debug
17350 \end_inset
17351 </cell>
17352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17353 \begin_inset Text
17354
17355 \layout Standard
17356
17357 link the debug library
17358 \end_inset
17359 </cell>
17360 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17361 \begin_inset Text
17362
17363 \layout Standard
17364
17365
17366 \emph on
17367 libdebug
17368 \emph default
17369 .lib
17370 \end_inset
17371 </cell>
17372 </row>
17373 </lyxtabular>
17374
17375 \end_inset
17376
17377
17378 \newline
17379 * is the device number, i.e.
17380  452 for PIC18F452 MCU.
17381 \layout Standard
17382
17383 This feature allows for linking with specific libraries withoug having to
17384  explicit name them in the command line.
17385  Note that the
17386 \noun on
17387 ignore
17388 \noun default
17389  keyword will reject all modules specified by the library pragma.
17390 \layout List
17391 \labelwidthstring 00.00.0000
17392
17393 udata pragma udata instructs the compiler to emit code so that linker will
17394  place a variable at a specific memory bank
17395 \layout LyX-Code
17396
17397 Example:
17398 \layout LyX-Code
17399
17400 \layout LyX-Code
17401
17402 /* places variable foo at bank2 */
17403 \layout LyX-Code
17404
17405 #pragma udata bank2 foo
17406 \layout LyX-Code
17407
17408 char foo;
17409 \layout Standard
17410
17411 In order for this pragma to work extra SECTION directives should be added
17412  in the .lkr script.
17413  In the following example a sample .lkr file is shown:
17414 \layout LyX-Code
17415
17416 \layout LyX-Code
17417
17418 // Sample linker script for the PIC18F452 processor
17419 \layout LyX-Code
17420
17421 LIBPATH .
17422 \layout LyX-Code
17423
17424 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
17425 \layout LyX-Code
17426
17427 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
17428 \layout LyX-Code
17429
17430 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
17431 \layout LyX-Code
17432
17433 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
17434 \layout LyX-Code
17435
17436 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
17437 \layout LyX-Code
17438
17439 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
17440 \layout LyX-Code
17441
17442 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
17443 \layout LyX-Code
17444
17445 \layout LyX-Code
17446
17447 DATABANK   NAME=gpr0       START=0x80           END=0xFF
17448 \layout LyX-Code
17449
17450 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
17451 \layout LyX-Code
17452
17453 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
17454 \layout LyX-Code
17455
17456 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
17457 \layout LyX-Code
17458
17459 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
17460 \layout LyX-Code
17461
17462 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
17463 \layout LyX-Code
17464
17465 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
17466 \layout LyX-Code
17467
17468 \layout LyX-Code
17469
17470 SECTION    NAME=CONFIG     ROM=config
17471 \layout LyX-Code
17472
17473 \layout LyX-Code
17474
17475 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
17476 \layout LyX-Code
17477
17478 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
17479 \layout LyX-Code
17480
17481 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
17482 \layout LyX-Code
17483
17484 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
17485 \layout LyX-Code
17486
17487 SECTION    NAME=bank4      RAM=gpr4
17488 \layout LyX-Code
17489
17490 SECTION    NAME=bank5      RAM=gpr5
17491 \layout Standard
17492
17493 The linker will recognise the section name set in the pragma statement and
17494  will position the variable at the memory bank set with the RAM field at
17495  the SECTION line in the linker script file.
17496 \layout Subsection
17497
17498 Header Files
17499 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
17500
17501 \end_inset
17502
17503
17504 \layout Standard
17505
17506 There is one main header file that can be included to the source files using
17507  the pic16 port.
17508  That file is the
17509 \series bold
17510 pic18fregs.h
17511 \series default
17512 .
17513  This header file contains the definitions for the processor special registers,
17514  so it is necessary if the source accesses them.
17515  It can be included by adding the following line in the beginning of the
17516  file:
17517 \layout LyX-Code
17518
17519 #include <pic18fregs.h>
17520 \layout Standard
17521
17522 The specific microcontroller is selected within the pic18fregs.h automatically,
17523  so the same source can be used with a variety of devices.
17524 \layout Subsection
17525
17526 Libraries
17527 \layout Standard
17528
17529 The libraries that PIC16
17530 \begin_inset LatexCommand \index{PIC16}
17531
17532 \end_inset
17533
17534  port depends on are the microcontroller device libraries which contain
17535  the symbol definitions for the microcontroller special function registers.
17536  These libraries have the format pic18fxxxx.lib, where
17537 \emph on
17538 xxxx
17539 \emph default
17540  is the microcontroller identification number.
17541  The specific library is selected automatically by the compiler at link
17542  stage according to the selected device.
17543 \layout Standard
17544
17545 Libraries are created with gplib which is part of the gputils package
17546 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17547
17548 \end_inset
17549
17550 .
17551 \layout Subsubsection*
17552
17553 Building the libraries
17554 \layout Standard
17555
17556 Before using SDCC/pic16 there are some libraries that need to be compiled.
17557  This process is not done automatically by SDCC since not all users use
17558  SDCC for pic16 projects.
17559  So each user should compile the libraries separately.
17560 \layout Standard
17561
17562 The steps to compile the pic16 libraries under Linux are:
17563 \layout LyX-Code
17564
17565 cd device/lib/pic16
17566 \layout LyX-Code
17567
17568 ./configure
17569 \layout LyX-Code
17570
17571 make
17572 \layout LyX-Code
17573
17574 cd ..
17575 \layout LyX-Code
17576
17577 make model-pic16
17578 \layout LyX-Code
17579
17580 su -c 'make install'     # install the libraries, you need the root password
17581 \layout Standard
17582
17583 If you need to install the headers too, do:
17584 \layout LyX-Code
17585
17586 cd device/include
17587 \layout LyX-Code
17588
17589 su -c 'make install'     # install the headers, you need the root password
17590 \layout Standard
17591
17592 There exist a special target to build the I/O libraries.
17593  This target is not automatically build because it will build the I/O library
17594  for
17595 \emph on
17596 every
17597 \emph default
17598  supported device.
17599  This way building will take quite a lot of time.
17600  Users are advised to edit the
17601 \series bold
17602 device/lib/pic16/pics.build
17603 \series default
17604  file and then execute:
17605 \layout LyX-Code
17606
17607 make lib-io
17608 \layout Subsection
17609
17610 Memory Models
17611 \layout Standard
17612
17613 The following memory models are supported by the PIC16 port:
17614 \layout Itemize
17615
17616 small model
17617 \layout Itemize
17618
17619 large model
17620 \layout Standard
17621
17622 Memory model affects the default size of pointers within the source.
17623  The sizes are shown in the next table:
17624 \layout Standard
17625 \align center
17626
17627 \begin_inset  Tabular
17628 <lyxtabular version="3" rows="3" columns="3">
17629 <features>
17630 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17631 <column alignment="center" valignment="top" leftline="true" width="0">
17632 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17633 <row topline="true" bottomline="true">
17634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17635 \begin_inset Text
17636
17637 \layout Standard
17638
17639 Pointer sizes according to memory model
17640 \end_inset
17641 </cell>
17642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17643 \begin_inset Text
17644
17645 \layout Standard
17646
17647 small model
17648 \end_inset
17649 </cell>
17650 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17651 \begin_inset Text
17652
17653 \layout Standard
17654
17655 large model
17656 \end_inset
17657 </cell>
17658 </row>
17659 <row topline="true" bottomline="true">
17660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17661 \begin_inset Text
17662
17663 \layout Standard
17664
17665 code pointers
17666 \end_inset
17667 </cell>
17668 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17669 \begin_inset Text
17670
17671 \layout Standard
17672
17673 16-bits
17674 \end_inset
17675 </cell>
17676 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17677 \begin_inset Text
17678
17679 \layout Standard
17680
17681 24-bits
17682 \end_inset
17683 </cell>
17684 </row>
17685 <row topline="true" bottomline="true">
17686 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17687 \begin_inset Text
17688
17689 \layout Standard
17690
17691 data pointers
17692 \end_inset
17693 </cell>
17694 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
17695 \begin_inset Text
17696
17697 \layout Standard
17698
17699 16-bits
17700 \end_inset
17701 </cell>
17702 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17703 \begin_inset Text
17704
17705 \layout Standard
17706
17707 16-bits
17708 \end_inset
17709 </cell>
17710 </row>
17711 </lyxtabular>
17712
17713 \end_inset
17714
17715
17716 \layout Standard
17717
17718 It is advisable that all sources within a project are compiled with the
17719  same memory model.
17720  If one wants to override the default memory model, this can be done by
17721  declaring a pointer as
17722 \series bold
17723 far
17724 \series default
17725  or
17726 \series bold
17727 near
17728 \series default
17729 .
17730  Far selects large memory model's pointers, while near selects small memory
17731  model's pointers.
17732 \layout Standard
17733
17734 The standard device libraries (see
17735 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
17736
17737 \end_inset
17738
17739 ) contain no reference to pointers, so they can be used with both memory
17740  models.
17741 \layout Subsection
17742
17743 Stack
17744 \layout Standard
17745
17746 The stack implementation for the PIC16 port uses two indirect registers,
17747  FSR1 and FSR2.
17748 \layout List
17749 \labelwidthstring 00.00.0000
17750
17751 FSR1 is assigned as stack pointer
17752 \layout List
17753 \labelwidthstring 00.00.0000
17754
17755 FSR2 is assigned as frame pointer
17756 \layout Standard
17757
17758 The following stack models are supported by the PIC16 port
17759 \layout Itemize
17760
17761
17762 \noun on
17763 small
17764 \noun default
17765  model
17766 \layout Itemize
17767
17768
17769 \noun on
17770 large
17771 \noun default
17772  model
17773 \layout Standard
17774
17775
17776 \noun on
17777 Small
17778 \noun default
17779  model means that only the FSRxL byte is used to access stack and frame,
17780  while
17781 \emph on
17782 \noun on
17783 large
17784 \emph default
17785 \noun default
17786  uses both FSRxL and FSRxH registers.
17787  The following table shows the stack/frame pointers sizes according to stack
17788  model and the maximum space they can address:
17789 \layout Standard
17790 \align center
17791
17792 \begin_inset  Tabular
17793 <lyxtabular version="3" rows="3" columns="3">
17794 <features>
17795 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17796 <column alignment="center" valignment="top" leftline="true" width="0">
17797 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17798 <row topline="true" bottomline="true">
17799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17800 \begin_inset Text
17801
17802 \layout Standard
17803
17804 Stack & Frame pointer sizes according to stack model
17805 \end_inset
17806 </cell>
17807 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17808 \begin_inset Text
17809
17810 \layout Standard
17811
17812 small
17813 \end_inset
17814 </cell>
17815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17816 \begin_inset Text
17817
17818 \layout Standard
17819
17820 large
17821 \end_inset
17822 </cell>
17823 </row>
17824 <row topline="true">
17825 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17826 \begin_inset Text
17827
17828 \layout Standard
17829
17830 Stack pointer FSR1
17831 \end_inset
17832 </cell>
17833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17834 \begin_inset Text
17835
17836 \layout Standard
17837
17838 8-bits
17839 \end_inset
17840 </cell>
17841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17842 \begin_inset Text
17843
17844 \layout Standard
17845
17846 16-bits
17847 \end_inset
17848 </cell>
17849 </row>
17850 <row topline="true" bottomline="true">
17851 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17852 \begin_inset Text
17853
17854 \layout Standard
17855
17856 Frame pointer FSR2
17857 \end_inset
17858 </cell>
17859 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17860 \begin_inset Text
17861
17862 \layout Standard
17863
17864 8-bits
17865 \end_inset
17866 </cell>
17867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17868 \begin_inset Text
17869
17870 \layout Standard
17871
17872 16-bits
17873 \end_inset
17874 </cell>
17875 </row>
17876 </lyxtabular>
17877
17878 \end_inset
17879
17880
17881 \layout Standard
17882
17883
17884 \noun on
17885 Large
17886 \noun default
17887 stack model is currently not working properly throughout the code generator.
17888  So its use is not advised.
17889  Also there are some other points that need special care:
17890 \newline
17891
17892 \layout Enumerate
17893
17894 Do not create stack sections with size more than one physical bank (that
17895  is 256 bytes)
17896 \layout Enumerate
17897
17898 Stack sections should no cross physical bank limits (i.e.
17899  #pragma stack 0x50 0x100)
17900 \layout Standard
17901
17902 These limitations are caused by the fact that only FSRxL is modified when
17903  using SMALL stack model, so no more than 256 bytes of stack can be used.
17904  This problem will disappear after LARGE model is fully implemented.
17905 \layout Subsection
17906
17907 Functions
17908 \layout Standard
17909
17910 In addition to the standard SDCC function keywords, PIC16 port makes available
17911  two more:
17912 \layout List
17913 \labelwidthstring 00.00.0000
17914
17915 wparam Use the WREG to pass one byte of the first function argument.
17916  This improves speed but you may not use this for functions with arguments
17917  that are called via function pointers, otherwise the first byte of the
17918  first parameter will get lost.
17919  Usage:
17920 \layout LyX-Code
17921
17922 void func_wparam(int a) wparam
17923 \layout LyX-Code
17924
17925 {
17926 \layout LyX-Code
17927
17928     /* WREG hold the lower part of a */
17929 \layout LyX-Code
17930
17931     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
17932  */
17933 \layout LyX-Code
17934
17935 ...
17936 \layout LyX-Code
17937
17938 }
17939 \layout Standard
17940
17941 This keyword replaces the deprecated wparam pragma.
17942 \layout List
17943 \labelwidthstring 00.00.0000
17944
17945 shadowregs When entering/exiting an ISR, it is possible to take advantage
17946  of the PIC18F hardware shadow registers which hold the values of WREG,
17947  STATUS and BSR registers.
17948  This can be done by adding the keyword
17949 \emph on
17950 shadowregs
17951 \emph default
17952  before the
17953 \emph on
17954 interrupt
17955 \emph default
17956  keyword in the function's header.
17957 \layout LyX-Code
17958
17959 void isr_shadow(void) shadowregs interrupt 1
17960 \layout LyX-Code
17961
17962 {
17963 \layout LyX-Code
17964
17965 ...
17966 \layout LyX-Code
17967
17968 }
17969 \layout Standard
17970
17971
17972 \emph on
17973 shadowregs
17974 \emph default
17975  instructs the code generator not to store/restore WREG, STATUS, BSR when
17976  entering/exiting the ISR.
17977 \layout Subsection
17978
17979 Function return values
17980 \layout Standard
17981
17982 Return values from functions are placed to the appropriate registers following
17983  a modified Microchip policy optimized for SDCC.
17984  The following table shows these registers:
17985 \layout Standard
17986 \align center
17987
17988 \begin_inset  Tabular
17989 <lyxtabular version="3" rows="6" columns="2">
17990 <features>
17991 <column alignment="center" valignment="top" leftline="true" width="0">
17992 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17993 <row topline="true" bottomline="true">
17994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17995 \begin_inset Text
17996
17997 \layout Standard
17998
17999 size
18000 \end_inset
18001 </cell>
18002 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18003 \begin_inset Text
18004
18005 \layout Standard
18006
18007 destination register
18008 \end_inset
18009 </cell>
18010 </row>
18011 <row topline="true">
18012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18013 \begin_inset Text
18014
18015 \layout Standard
18016
18017 8 bits
18018 \end_inset
18019 </cell>
18020 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18021 \begin_inset Text
18022
18023 \layout Standard
18024
18025 WREG
18026 \end_inset
18027 </cell>
18028 </row>
18029 <row topline="true">
18030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18031 \begin_inset Text
18032
18033 \layout Standard
18034
18035 16 bits
18036 \end_inset
18037 </cell>
18038 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18039 \begin_inset Text
18040
18041 \layout Standard
18042
18043 PRODL:WREG
18044 \end_inset
18045 </cell>
18046 </row>
18047 <row topline="true">
18048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18049 \begin_inset Text
18050
18051 \layout Standard
18052
18053 24 bits
18054 \end_inset
18055 </cell>
18056 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18057 \begin_inset Text
18058
18059 \layout Standard
18060
18061 PRODH:PRODL:WREG
18062 \end_inset
18063 </cell>
18064 </row>
18065 <row topline="true">
18066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18067 \begin_inset Text
18068
18069 \layout Standard
18070
18071 32 bits
18072 \end_inset
18073 </cell>
18074 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18075 \begin_inset Text
18076
18077 \layout Standard
18078
18079 FSR0L:PRODH:PRODL:WREG
18080 \end_inset
18081 </cell>
18082 </row>
18083 <row topline="true" bottomline="true">
18084 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18085 \begin_inset Text
18086
18087 \layout Standard
18088
18089 >32 bits
18090 \end_inset
18091 </cell>
18092 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18093 \begin_inset Text
18094
18095 \layout Standard
18096
18097 on stack, FSR0 points to the beginning
18098 \end_inset
18099 </cell>
18100 </row>
18101 </lyxtabular>
18102
18103 \end_inset
18104
18105
18106 \layout Subsection
18107
18108 Interrupts
18109 \layout Standard
18110
18111 An interrupt servive routine (ISR) is declared using the
18112 \emph on
18113 interrupt
18114 \emph default
18115  keyword.
18116 \layout LyX-Code
18117
18118 void isr(void) interrupt
18119 \emph on
18120 n
18121 \layout LyX-Code
18122
18123 {
18124 \layout LyX-Code
18125
18126 ...
18127 \layout LyX-Code
18128
18129 }
18130 \layout Standard
18131
18132
18133 \emph on
18134 n
18135 \emph default
18136  is the interrupt number, which for PIC18F devices can be:
18137 \layout Standard
18138 \align center
18139
18140 \begin_inset  Tabular
18141 <lyxtabular version="3" rows="4" columns="3">
18142 <features>
18143 <column alignment="center" valignment="top" leftline="true" width="0">
18144 <column alignment="center" valignment="top" leftline="true" width="0">
18145 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18146 <row topline="true" bottomline="true">
18147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18148 \begin_inset Text
18149
18150 \layout Standard
18151
18152
18153 \emph on
18154 n
18155 \end_inset
18156 </cell>
18157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18158 \begin_inset Text
18159
18160 \layout Standard
18161
18162 Interrupt Vector
18163 \end_inset
18164 </cell>
18165 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18166 \begin_inset Text
18167
18168 \layout Standard
18169
18170 Interrupt Vector Address
18171 \end_inset
18172 </cell>
18173 </row>
18174 <row topline="true">
18175 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18176 \begin_inset Text
18177
18178 \layout Standard
18179
18180 0
18181 \end_inset
18182 </cell>
18183 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18184 \begin_inset Text
18185
18186 \layout Standard
18187
18188 RESET vector
18189 \end_inset
18190 </cell>
18191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18192 \begin_inset Text
18193
18194 \layout Standard
18195
18196 0x000000
18197 \end_inset
18198 </cell>
18199 </row>
18200 <row topline="true">
18201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18202 \begin_inset Text
18203
18204 \layout Standard
18205
18206
18207 \family roman
18208 \series medium
18209 \shape up
18210 \size normal
18211 \emph off
18212 \bar no
18213 \noun off
18214 \color none
18215 1
18216 \end_inset
18217 </cell>
18218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18219 \begin_inset Text
18220
18221 \layout Standard
18222
18223
18224 \family roman
18225 \series medium
18226 \shape up
18227 \size normal
18228 \emph off
18229 \bar no
18230 \noun off
18231 \color none
18232 HIGH priority interrupts
18233 \end_inset
18234 </cell>
18235 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18236 \begin_inset Text
18237
18238 \layout Standard
18239
18240 0x000008
18241 \end_inset
18242 </cell>
18243 </row>
18244 <row topline="true" bottomline="true">
18245 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18246 \begin_inset Text
18247
18248 \layout Standard
18249
18250 2
18251 \end_inset
18252 </cell>
18253 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18254 \begin_inset Text
18255
18256 \layout Standard
18257
18258 LOW priority interrupts
18259 \end_inset
18260 </cell>
18261 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18262 \begin_inset Text
18263
18264 \layout Standard
18265
18266 0x000018
18267 \end_inset
18268 </cell>
18269 </row>
18270 </lyxtabular>
18271
18272 \end_inset
18273
18274
18275 \layout Standard
18276
18277 When generating assembly code for ISR the code generator places a
18278 \noun on
18279 goto
18280 \noun default
18281 instruction at the
18282 \emph on
18283 Interrupt Vector Address
18284 \emph default
18285  which points at the genetated ISR.
18286  This single GOTO instruction is part of an automatically generated
18287 \emph on
18288 interrupt entry point
18289 \emph default
18290  function.
18291  The actuall ISR code is placed as normally would in the code space.
18292  Upon interrupt request, the GOTO instruction is executed which jumps to
18293  the ISR code.
18294  When declaring interrupt functions as _naked this GOTO instruction is
18295 \series bold
18296 not
18297 \series default
18298  generated.
18299  The whole interrupt functions is therefore placed at the Interrupt Vector
18300  Address of the specific interrupt.
18301  This is not a problem for the LOW priority interrupts, but it is a problem
18302  for the RESET and the HIGH priority interrupts because code may be written
18303  at the next interrupt´s vector address and cause undeterminate program
18304  behaviour if that interrupt is raised.
18305 \begin_inset Foot
18306 collapsed false
18307
18308 \layout Standard
18309
18310 This is not a problem when
18311 \layout Enumerate
18312
18313 this is a HIGH interrupt ISR and LOW interrupts are
18314 \emph on
18315 disabled
18316 \emph default
18317  or not used.
18318 \layout Enumerate
18319
18320 when the ISR is small enough not to reach the next interrupt´s vector address.
18321 \end_inset
18322
18323
18324 \layout Standard
18325
18326
18327 \emph on
18328 n
18329 \emph default
18330  is possible to be omitted.
18331  This way a function is generated similar to an ISR, but it is not assigned
18332  to any interrupt.
18333 \layout Standard
18334
18335 When entering an interrupt, currently the PIC16
18336 \begin_inset LatexCommand \index{PIC16}
18337
18338 \end_inset
18339
18340  port automatically saves the following registers:
18341 \layout Itemize
18342
18343 WREG
18344 \layout Itemize
18345
18346 STATUS
18347 \layout Itemize
18348
18349 BSR
18350 \layout Itemize
18351
18352 PROD (PRODL and PRODH)
18353 \layout Itemize
18354
18355 FSR0 (FSR0L and FSR0H)
18356 \layout Standard
18357
18358 These registers are restored upon return from the interrupt routine.
18359 \begin_inset Foot
18360 collapsed false
18361
18362 \layout Standard
18363
18364 NOTE that when the _naked attribute is specified for an interrupt routine,
18365  then NO registers are stored or restored.
18366 \end_inset
18367
18368
18369 \layout Subsection
18370
18371 Generic Pointers
18372 \layout Standard
18373
18374 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
18375  There are 3 types of generic pointers currently implemented data, code
18376  and eeprom pointers.
18377  They are differentiated by the value of the 7th and 6th bits of the upper
18378  byte:
18379 \layout Standard
18380 \align center
18381
18382 \begin_inset  Tabular
18383 <lyxtabular version="3" rows="5" columns="5">
18384 <features>
18385 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18386 <column alignment="center" valignment="top" width="0">
18387 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18388 <column alignment="center" valignment="top" width="0">
18389 <column alignment="left" valignment="top" rightline="true" width="0">
18390 <row topline="true" bottomline="true">
18391 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18392 \begin_inset Text
18393
18394 \layout Standard
18395
18396 pointer type
18397 \end_inset
18398 </cell>
18399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18400 \begin_inset Text
18401
18402 \layout Standard
18403
18404 7th bit
18405 \end_inset
18406 </cell>
18407 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18408 \begin_inset Text
18409
18410 \layout Standard
18411
18412 6th bit
18413 \end_inset
18414 </cell>
18415 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18416 \begin_inset Text
18417
18418 \layout Standard
18419
18420 rest of the pointer
18421 \end_inset
18422 </cell>
18423 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18424 \begin_inset Text
18425
18426 \layout Standard
18427
18428 descrption
18429 \end_inset
18430 </cell>
18431 </row>
18432 <row topline="true" bottomline="true">
18433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18434 \begin_inset Text
18435
18436 \layout Standard
18437
18438 data
18439 \end_inset
18440 </cell>
18441 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18442 \begin_inset Text
18443
18444 \layout Standard
18445
18446 1
18447 \end_inset
18448 </cell>
18449 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18450 \begin_inset Text
18451
18452 \layout Standard
18453
18454 0
18455 \end_inset
18456 </cell>
18457 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18458 \begin_inset Text
18459
18460 \layout Standard
18461
18462
18463 \family typewriter
18464 \shape slanted
18465 \emph on
18466 uuuuuu uuuuxxxx xxxxxxxx
18467 \end_inset
18468 </cell>
18469 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18470 \begin_inset Text
18471
18472 \layout Standard
18473
18474 a 12-bit data pointer in data RAM memory
18475 \end_inset
18476 </cell>
18477 </row>
18478 <row bottomline="true">
18479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18480 \begin_inset Text
18481
18482 \layout Standard
18483
18484 code
18485 \end_inset
18486 </cell>
18487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18488 \begin_inset Text
18489
18490 \layout Standard
18491
18492 0
18493 \end_inset
18494 </cell>
18495 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18496 \begin_inset Text
18497
18498 \layout Standard
18499
18500 0
18501 \end_inset
18502 </cell>
18503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18504 \begin_inset Text
18505
18506 \layout Standard
18507
18508
18509 \family typewriter
18510 \shape slanted
18511 \emph on
18512 uxxxxx xxxxxxxx xxxxxxxx
18513 \end_inset
18514 </cell>
18515 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18516 \begin_inset Text
18517
18518 \layout Standard
18519
18520 a 21-bit code pointer in FLASH memory
18521 \end_inset
18522 </cell>
18523 </row>
18524 <row bottomline="true">
18525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18526 \begin_inset Text
18527
18528 \layout Standard
18529
18530 eeprom
18531 \end_inset
18532 </cell>
18533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18534 \begin_inset Text
18535
18536 \layout Standard
18537
18538 0
18539 \end_inset
18540 </cell>
18541 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18542 \begin_inset Text
18543
18544 \layout Standard
18545
18546 1
18547 \end_inset
18548 </cell>
18549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18550 \begin_inset Text
18551
18552 \layout Standard
18553
18554
18555 \family typewriter
18556 \shape slanted
18557 \emph on
18558 uuuuuu uuuuuuxx xxxxxxxx
18559 \end_inset
18560 </cell>
18561 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18562 \begin_inset Text
18563
18564 \layout Standard
18565
18566 a 10-bit eeprom pointer in EEPROM memory
18567 \end_inset
18568 </cell>
18569 </row>
18570 <row bottomline="true">
18571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18572 \begin_inset Text
18573
18574 \layout Standard
18575
18576 (unimplemented)
18577 \end_inset
18578 </cell>
18579 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18580 \begin_inset Text
18581
18582 \layout Standard
18583
18584 1
18585 \end_inset
18586 </cell>
18587 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18588 \begin_inset Text
18589
18590 \layout Standard
18591
18592 1
18593 \end_inset
18594 </cell>
18595 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18596 \begin_inset Text
18597
18598 \layout Standard
18599
18600
18601 \family typewriter
18602 \shape slanted
18603 \emph on
18604 xxxxxx xxxxxxxx xxxxxxxx
18605 \end_inset
18606 </cell>
18607 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18608 \begin_inset Text
18609
18610 \layout Standard
18611
18612 unimplemented pointer type
18613 \end_inset
18614 </cell>
18615 </row>
18616 </lyxtabular>
18617
18618 \end_inset
18619
18620
18621 \layout Standard
18622
18623 Generic pointer are read and written with a set of library functions which
18624  read/write 1, 2, 3, 4 bytes.
18625 \layout Subsection
18626
18627 PIC16 C Libraries
18628 \layout Subsubsection
18629
18630 Standard I/O Streams
18631 \layout Standard
18632
18633 In the
18634 \emph on
18635 stdio.h
18636 \emph default
18637  the type FILE is defined as:
18638 \layout LyX-Code
18639
18640 typedef char * FILE;
18641 \layout Standard
18642
18643 This type is the stream type implemented I/O in the PIC18F devices.
18644  Also the standard input and output streams are declared in stdio.h:
18645 \layout LyX-Code
18646
18647 extern FILE * stdin;
18648 \layout LyX-Code
18649
18650 extern FILE * stdout;
18651 \layout Standard
18652
18653 The FILE type is actually a generic pointer which defines one more type
18654  of generic pointers, the
18655 \emph on
18656 stream
18657 \emph default
18658 pointer.
18659  This new type has the format:
18660 \layout Standard
18661 \align center
18662
18663 \begin_inset  Tabular
18664 <lyxtabular version="3" rows="2" columns="7">
18665 <features>
18666 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18667 <column alignment="center" valignment="top" width="0">
18668 <column alignment="center" valignment="top" leftline="true" width="0">
18669 <column alignment="center" valignment="top" leftline="true" width="0">
18670 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18671 <column alignment="center" valignment="top" width="0">
18672 <column alignment="left" valignment="top" rightline="true" width="0">
18673 <row topline="true" bottomline="true">
18674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18675 \begin_inset Text
18676
18677 \layout Standard
18678
18679 pointer type
18680 \end_inset
18681 </cell>
18682 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18683 \begin_inset Text
18684
18685 \layout Standard
18686
18687 <7:6>
18688 \end_inset
18689 </cell>
18690 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18691 \begin_inset Text
18692
18693 \layout Standard
18694
18695 <5>
18696 \end_inset
18697 </cell>
18698 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18699 \begin_inset Text
18700
18701 \layout Standard
18702
18703 <4>
18704 \end_inset
18705 </cell>
18706 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18707 \begin_inset Text
18708
18709 \layout Standard
18710
18711 <3:0>
18712 \end_inset
18713 </cell>
18714 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18715 \begin_inset Text
18716
18717 \layout Standard
18718
18719 rest of the pointer
18720 \end_inset
18721 </cell>
18722 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18723 \begin_inset Text
18724
18725 \layout Standard
18726
18727 descrption
18728 \end_inset
18729 </cell>
18730 </row>
18731 <row topline="true" bottomline="true">
18732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18733 \begin_inset Text
18734
18735 \layout Standard
18736
18737 stream
18738 \end_inset
18739 </cell>
18740 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18741 \begin_inset Text
18742
18743 \layout Standard
18744
18745 00
18746 \end_inset
18747 </cell>
18748 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18749 \begin_inset Text
18750
18751 \layout Standard
18752
18753 1
18754 \end_inset
18755 </cell>
18756 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18757 \begin_inset Text
18758
18759 \layout Standard
18760
18761 0
18762 \end_inset
18763 </cell>
18764 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18765 \begin_inset Text
18766
18767 \layout Standard
18768
18769 nnnn
18770 \end_inset
18771 </cell>
18772 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18773 \begin_inset Text
18774
18775 \layout Standard
18776
18777
18778 \family typewriter
18779 \shape slanted
18780 \emph on
18781 uuuuuuuu uuuuuuuu
18782 \end_inset
18783 </cell>
18784 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18785 \begin_inset Text
18786
18787 \layout Standard
18788
18789 upper byte high nubble is 0x2n, the rest are zeroes
18790 \end_inset
18791 </cell>
18792 </row>
18793 </lyxtabular>
18794
18795 \end_inset
18796
18797
18798 \layout Standard
18799
18800 Currently implemented there are 3 types of streams defined:
18801 \layout Standard
18802 \align center
18803
18804 \begin_inset  Tabular
18805 <lyxtabular version="3" rows="4" columns="4">
18806 <features>
18807 <column alignment="center" valignment="top" leftline="true" width="0">
18808 <column alignment="center" valignment="top" leftline="true" width="0">
18809 <column alignment="center" valignment="top" leftline="true" width="0">
18810 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18811 <row topline="true" bottomline="true">
18812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18813 \begin_inset Text
18814
18815 \layout Standard
18816
18817 stream type
18818 \end_inset
18819 </cell>
18820 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18821 \begin_inset Text
18822
18823 \layout Standard
18824
18825 value
18826 \end_inset
18827 </cell>
18828 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18829 \begin_inset Text
18830
18831 \layout Standard
18832
18833 module
18834 \end_inset
18835 </cell>
18836 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18837 \begin_inset Text
18838
18839 \layout Standard
18840
18841 description
18842 \end_inset
18843 </cell>
18844 </row>
18845 <row topline="true">
18846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18847 \begin_inset Text
18848
18849 \layout Standard
18850
18851 STREAM_USART
18852 \end_inset
18853 </cell>
18854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18855 \begin_inset Text
18856
18857 \layout Standard
18858
18859
18860 \family typewriter
18861 0x200000UL
18862 \end_inset
18863 </cell>
18864 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18865 \begin_inset Text
18866
18867 \layout Standard
18868
18869 USART
18870 \end_inset
18871 </cell>
18872 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18873 \begin_inset Text
18874
18875 \layout Standard
18876
18877 Writes/Reads characters via the USART peripheral
18878 \end_inset
18879 </cell>
18880 </row>
18881 <row topline="true">
18882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18883 \begin_inset Text
18884
18885 \layout Standard
18886
18887 STREAM_MSSP
18888 \end_inset
18889 </cell>
18890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18891 \begin_inset Text
18892
18893 \layout Standard
18894
18895
18896 \family typewriter
18897 0x210000UL
18898 \end_inset
18899 </cell>
18900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18901 \begin_inset Text
18902
18903 \layout Standard
18904
18905 MSSP
18906 \end_inset
18907 </cell>
18908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18909 \begin_inset Text
18910
18911 \layout Standard
18912
18913 Writes/Reads characters via the MSSP peripheral
18914 \end_inset
18915 </cell>
18916 </row>
18917 <row topline="true" bottomline="true">
18918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18919 \begin_inset Text
18920
18921 \layout Standard
18922
18923 STREAM_USER
18924 \end_inset
18925 </cell>
18926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18927 \begin_inset Text
18928
18929 \layout Standard
18930
18931
18932 \family typewriter
18933 0x2f0000UL
18934 \end_inset
18935 </cell>
18936 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18937 \begin_inset Text
18938
18939 \layout Standard
18940
18941 (none)
18942 \end_inset
18943 </cell>
18944 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18945 \begin_inset Text
18946
18947 \layout Standard
18948
18949 Writes/Reads characters via used defined functions
18950 \end_inset
18951 </cell>
18952 </row>
18953 </lyxtabular>
18954
18955 \end_inset
18956
18957
18958 \layout Standard
18959
18960 The stream identifiers are declared as macros in the stdio.h header.
18961 \layout Standard
18962
18963 In the libc library there exist the functions that are used to write to
18964  each of the above streams.
18965  These are
18966 \layout List
18967 \labelwidthstring 00.00.0000
18968
18969 _
18970 \begin_inset ERT
18971 status Collapsed
18972
18973 \layout Standard
18974
18975 \backslash
18976 /
18977 \end_inset
18978
18979 _stream_usart_putchar writes a character at the USART stream
18980 \layout List
18981 \labelwidthstring 00.00.0000
18982
18983 _
18984 \begin_inset ERT
18985 status Collapsed
18986
18987 \layout Standard
18988
18989 \backslash
18990 /
18991 \end_inset
18992
18993 _stream_mssp_putchar writes a character at the MSSP stream
18994 \layout List
18995 \labelwidthstring 00.00.0000
18996
18997 putchar dummy function.
18998  This writes a character to a user specified manner.
18999 \layout Standard
19000
19001 In order to increase performance
19002 \emph on
19003 putchar
19004 \emph default
19005 is declared in stdio.h as having its parameter in WREG (it has the wparam
19006  keyword).
19007  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
19008  in a user-friendly way.
19009
19010 \emph on
19011 arg
19012 \emph default
19013  is the name of the variable that holds the character to print.
19014  An example follows:
19015 \layout LyX-Code
19016
19017 #include <pic18fregs.h>
19018 \newline
19019 #include <stdio.h>
19020 \newline
19021
19022 \newline
19023 PUTCHAR( c )
19024 \layout LyX-Code
19025
19026 {
19027 \layout LyX-Code
19028
19029     PORTA = c;    /* dump character c to PORTA */
19030 \layout LyX-Code
19031
19032 }
19033 \newline
19034
19035 \newline
19036 void main(void)
19037 \layout LyX-Code
19038
19039 {
19040 \layout LyX-Code
19041
19042     stdout = STREAM_USER;    /* this is not necessery, since stdout points
19043 \layout LyX-Code
19044
19045                               * by default to STREAM_USER */
19046 \layout LyX-Code
19047
19048     printf (¨This is a printf test
19049 \backslash
19050 n¨);
19051 \layout LyX-Code
19052
19053 }
19054 \layout LyX-Code
19055
19056 \layout Subsubsection
19057
19058 Printing functions
19059 \layout Standard
19060
19061 PIC16 contains an implementation of the printf-family of functions.
19062  There exist the following functions:
19063 \layout LyX-Code
19064
19065 extern unsigned int sprintf(char *buf, char *fmt, ...);
19066 \layout LyX-Code
19067
19068 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
19069 \layout LyX-Code
19070
19071 \layout LyX-Code
19072
19073 extern unsigned int printf(char *fmt, ...);
19074 \layout LyX-Code
19075
19076 extern unsigned int vprintf(char *fmt, va_lista ap);
19077 \layout LyX-Code
19078
19079 \layout LyX-Code
19080
19081 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
19082 \layout LyX-Code
19083
19084 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
19085 \layout Standard
19086
19087 For sprintf and vsprintf
19088 \emph on
19089 buf
19090 \emph default
19091 should normally be a data pointer where the resulting string will be placed.
19092  No range checking is done so the user should allocate the necessery buffer.
19093  For fprintf and vfprintf
19094 \emph on
19095 fp
19096 \emph default
19097  should be a stream pointer (i.e.
19098  stdout, STREAM_MSSP, etc...).
19099 \layout Subsubsection
19100
19101 Signals
19102 \layout Standard
19103
19104 The PIC18F family of microcontrollers supports a number of interrupt sources.
19105  A list of these interrupts is shown in the following table:
19106 \layout Standard
19107 \align center
19108
19109 \begin_inset  Tabular
19110 <lyxtabular version="3" rows="11" columns="4">
19111 <features>
19112 <column alignment="left" valignment="top" leftline="true" width="0">
19113 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19114 <column alignment="left" valignment="top" leftline="true" width="0">
19115 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19116 <row topline="true" bottomline="true">
19117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19118 \begin_inset Text
19119
19120 \layout Standard
19121
19122 signal name
19123 \end_inset
19124 </cell>
19125 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19126 \begin_inset Text
19127
19128 \layout Standard
19129
19130 description
19131 \end_inset
19132 </cell>
19133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19134 \begin_inset Text
19135
19136 \layout Standard
19137
19138 signal name
19139 \end_inset
19140 </cell>
19141 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19142 \begin_inset Text
19143
19144 \layout Standard
19145
19146 descritpion
19147 \end_inset
19148 </cell>
19149 </row>
19150 <row topline="true">
19151 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19152 \begin_inset Text
19153
19154 \layout Standard
19155
19156 SIG_RB
19157 \end_inset
19158 </cell>
19159 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19160 \begin_inset Text
19161
19162 \layout Standard
19163
19164 PORTB change interrupt
19165 \end_inset
19166 </cell>
19167 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19168 \begin_inset Text
19169
19170 \layout Standard
19171
19172 SIG_EE
19173 \end_inset
19174 </cell>
19175 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19176 \begin_inset Text
19177
19178 \layout Standard
19179
19180 EEPROM/FLASH write complete interrupt
19181 \end_inset
19182 </cell>
19183 </row>
19184 <row topline="true">
19185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19186 \begin_inset Text
19187
19188 \layout Standard
19189
19190 SIG_INT0
19191 \end_inset
19192 </cell>
19193 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19194 \begin_inset Text
19195
19196 \layout Standard
19197
19198 INT0 external interrupt
19199 \end_inset
19200 </cell>
19201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19202 \begin_inset Text
19203
19204 \layout Standard
19205
19206 SIG_BCOL
19207 \end_inset
19208 </cell>
19209 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19210 \begin_inset Text
19211
19212 \layout Standard
19213
19214 Bus collision interrupt
19215 \end_inset
19216 </cell>
19217 </row>
19218 <row topline="true">
19219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19220 \begin_inset Text
19221
19222 \layout Standard
19223
19224 SIG_INT1
19225 \end_inset
19226 </cell>
19227 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19228 \begin_inset Text
19229
19230 \layout Standard
19231
19232 INT1 external interrupt
19233 \end_inset
19234 </cell>
19235 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19236 \begin_inset Text
19237
19238 \layout Standard
19239
19240 SIG_LVD
19241 \end_inset
19242 </cell>
19243 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19244 \begin_inset Text
19245
19246 \layout Standard
19247
19248 Low voltage detect interrupt
19249 \end_inset
19250 </cell>
19251 </row>
19252 <row topline="true">
19253 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19254 \begin_inset Text
19255
19256 \layout Standard
19257
19258 SIG_INT2
19259 \end_inset
19260 </cell>
19261 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19262 \begin_inset Text
19263
19264 \layout Standard
19265
19266 INT2 external interrupt
19267 \end_inset
19268 </cell>
19269 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19270 \begin_inset Text
19271
19272 \layout Standard
19273
19274 SIG_PSP
19275 \end_inset
19276 </cell>
19277 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19278 \begin_inset Text
19279
19280 \layout Standard
19281
19282 Parallel slave port interrupt
19283 \end_inset
19284 </cell>
19285 </row>
19286 <row topline="true">
19287 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19288 \begin_inset Text
19289
19290 \layout Standard
19291
19292 SIG_CCP1
19293 \end_inset
19294 </cell>
19295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19296 \begin_inset Text
19297
19298 \layout Standard
19299
19300 CCP1 module interrupt
19301 \end_inset
19302 </cell>
19303 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19304 \begin_inset Text
19305
19306 \layout Standard
19307
19308 SIG_AD
19309 \end_inset
19310 </cell>
19311 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19312 \begin_inset Text
19313
19314 \layout Standard
19315
19316 AD convertion complete interrupt
19317 \end_inset
19318 </cell>
19319 </row>
19320 <row topline="true">
19321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19322 \begin_inset Text
19323
19324 \layout Standard
19325
19326 SIG_CCP2
19327 \end_inset
19328 </cell>
19329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19330 \begin_inset Text
19331
19332 \layout Standard
19333
19334 CCP2 module interrupt
19335 \end_inset
19336 </cell>
19337 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19338 \begin_inset Text
19339
19340 \layout Standard
19341
19342 SIG_RC
19343 \end_inset
19344 </cell>
19345 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19346 \begin_inset Text
19347
19348 \layout Standard
19349
19350 USART receive interrupt
19351 \end_inset
19352 </cell>
19353 </row>
19354 <row topline="true">
19355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19356 \begin_inset Text
19357
19358 \layout Standard
19359
19360 SIG_TMR0
19361 \end_inset
19362 </cell>
19363 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19364 \begin_inset Text
19365
19366 \layout Standard
19367
19368 TMR0 overflow interrupt
19369 \end_inset
19370 </cell>
19371 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19372 \begin_inset Text
19373
19374 \layout Standard
19375
19376 SIG_TX
19377 \end_inset
19378 </cell>
19379 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19380 \begin_inset Text
19381
19382 \layout Standard
19383
19384 USART transmit interrupt
19385 \end_inset
19386 </cell>
19387 </row>
19388 <row topline="true">
19389 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19390 \begin_inset Text
19391
19392 \layout Standard
19393
19394 SIG_TMR1
19395 \end_inset
19396 </cell>
19397 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19398 \begin_inset Text
19399
19400 \layout Standard
19401
19402 TMR1 overflow interrupt
19403 \end_inset
19404 </cell>
19405 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19406 \begin_inset Text
19407
19408 \layout Standard
19409
19410 SIG_MSSP
19411 \end_inset
19412 </cell>
19413 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19414 \begin_inset Text
19415
19416 \layout Standard
19417
19418 SSP receive/transmit interrupt
19419 \end_inset
19420 </cell>
19421 </row>
19422 <row topline="true">
19423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19424 \begin_inset Text
19425
19426 \layout Standard
19427
19428 SIG_TMR2
19429 \end_inset
19430 </cell>
19431 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19432 \begin_inset Text
19433
19434 \layout Standard
19435
19436 TMR2 matches PR2 interrupt
19437 \end_inset
19438 </cell>
19439 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19440 \begin_inset Text
19441
19442 \layout Standard
19443
19444 \end_inset
19445 </cell>
19446 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19447 \begin_inset Text
19448
19449 \layout Standard
19450
19451 \end_inset
19452 </cell>
19453 </row>
19454 <row topline="true" bottomline="true">
19455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19456 \begin_inset Text
19457
19458 \layout Standard
19459
19460 SIG_TMR3
19461 \end_inset
19462 </cell>
19463 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19464 \begin_inset Text
19465
19466 \layout Standard
19467
19468 TMR3 overflow interrupt
19469 \end_inset
19470 </cell>
19471 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19472 \begin_inset Text
19473
19474 \layout Standard
19475
19476 \end_inset
19477 </cell>
19478 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19479 \begin_inset Text
19480
19481 \layout Standard
19482
19483 \end_inset
19484 </cell>
19485 </row>
19486 </lyxtabular>
19487
19488 \end_inset
19489
19490
19491 \layout Standard
19492
19493 The prototypes for these names are defined in the header file
19494 \emph on
19495 signal.h
19496 \emph default
19497  .
19498 \layout Standard
19499
19500 In order to simplify signal handling, a number of macros is provided:
19501 \layout List
19502 \labelwidthstring 00.00.0000
19503
19504 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
19505  high priority interrupts.
19506
19507 \emph on
19508 name
19509 \emph default
19510  is the function name to use.
19511 \layout List
19512 \labelwidthstring 00.00.0000
19513
19514 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
19515  low priority interrupt.
19516
19517 \emph on
19518 name
19519 \emph default
19520  is the function name to use.
19521 \layout List
19522 \labelwidthstring 00.00.0000
19523
19524 DEF_HANDLER(sig,handler) define a handler for signal
19525 \emph on
19526 sig.
19527 \layout List
19528 \labelwidthstring 00.00.0000
19529
19530 END_DEF end the declaration of the dispatch table.
19531 \layout Standard
19532
19533 Additionally there are two more macros to simplify the declaration of the
19534  signal handler:
19535 \layout List
19536 \labelwidthstring 00.00.0000
19537
19538
19539 \series medium
19540 SIGHANDLER(handler)
19541 \series default
19542 this declares the function prototype for the
19543 \emph on
19544 handler
19545 \emph default
19546  function.
19547 \layout List
19548 \labelwidthstring 00.00.0000
19549
19550 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
19551 \layout Standard
19552
19553 An example of using the macros above is shown below:
19554 \layout LyX-Code
19555
19556 #include <pic18fregs.h>
19557 \layout LyX-Code
19558
19559 #include <signal.h>
19560 \newline
19561
19562 \newline
19563 DEF_INTHIGH(high_int)
19564 \layout LyX-Code
19565
19566 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
19567 \layout LyX-Code
19568
19569 DEF_HANDLER(SIG_BCOL, _bcol_handler)
19570 \layout LyX-Code
19571
19572 END_DEF
19573 \newline
19574
19575 \newline
19576 SIGHANDLER(_tmr0_handler)
19577 \layout LyX-Code
19578
19579 {
19580 \layout LyX-Code
19581
19582   /* action to be taken when timer 0 overflows */
19583 \layout LyX-Code
19584
19585 }
19586 \newline
19587
19588 \newline
19589 SIGHANDLERNAKED(_bcol_handler)
19590 \layout LyX-Code
19591
19592 {
19593 \layout LyX-Code
19594
19595   _asm
19596 \layout LyX-Code
19597
19598     /* action to be taken when bus collision occurs */
19599 \layout LyX-Code
19600
19601     retfie
19602 \layout LyX-Code
19603
19604  _endasm;
19605 \layout LyX-Code
19606
19607 }
19608 \layout Standard
19609
19610
19611 \series bold
19612 NOTES:
19613 \series default
19614  Special care should be taken when using the above scheme:
19615 \layout Itemize
19616
19617 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
19618 \layout Itemize
19619
19620 when declaring SIGHANDLERNAKED handler never forget to use
19621 \emph on
19622 retfie
19623 \emph default
19624  for proper returning.
19625 \layout Subsection
19626
19627 PIC16 Port -- Tips
19628 \layout Standard
19629
19630 Here you can find some general tips for compiling programs with SDCC/pic16.
19631 \layout Subsubsection
19632
19633 Stack size
19634 \layout Standard
19635
19636 The default stack size (that is 64 bytes) probably is enough for many programs.
19637  One must take care that when there are many levels of function nesting,
19638  or there is excessive usage of stack, its size should be extended.
19639  An example of such a case is the printf/sprintf family of functions.
19640  If you encounter problems like not being able to print integers, then you
19641  need to set the stack size around the maximum (256 for small stack model).
19642  The following diagram shows what happens when calling printf to print an
19643  integer:
19644 \layout LyX-Code
19645
19646 printf () --> ltoa () --> ultoa () --> divschar ()
19647 \layout Standard
19648
19649 It is should be understood that stack is easily consumed when calling complicate
19650 d functions.
19651  Using command line arguments like -
19652 \begin_inset ERT
19653 status Collapsed
19654
19655 \layout Standard
19656
19657 \backslash
19658 /
19659 \end_inset
19660
19661 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
19662  stack frames.
19663  Other ways to reduce stack usage may exist.
19664 \layout Chapter
19665
19666 Debugging with SDCDB
19667 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
19668
19669 \end_inset
19670
19671
19672 \begin_inset LatexCommand \index{sdcdb (debugger)}
19673
19674 \end_inset
19675
19676
19677 \layout Standard
19678
19679 SDCC is distributed with a source level debugger
19680 \begin_inset LatexCommand \index{Debugger}
19681
19682 \end_inset
19683
19684 .
19685  The debugger uses a command line interface, the command repertoire of the
19686  debugger has been kept as close to gdb
19687 \begin_inset LatexCommand \index{gdb}
19688
19689 \end_inset
19690
19691  (the GNU debugger) as possible.
19692  The configuration and build process is part of the standard compiler installati
19693 on, which also builds and installs the debugger in the target directory
19694  specified during configuration.
19695  The debugger allows you debug BOTH at the C source and at the ASM source
19696  level.
19697  Sdcdb is available on Unix platforms only.
19698 \layout Section
19699
19700 Compiling for Debugging
19701 \layout Standard
19702
19703 The -
19704 \begin_inset ERT
19705 status Collapsed
19706
19707 \layout Standard
19708
19709 \backslash
19710 /
19711 \end_inset
19712
19713 -debug
19714 \begin_inset LatexCommand \index{-\/-debug}
19715
19716 \end_inset
19717
19718  option must be specified for all files for which debug information is to
19719  be generated.
19720  The complier generates a .adb file for each of these files.
19721  The linker creates the .cdb
19722 \begin_inset LatexCommand \index{<file>.cdb}
19723
19724 \end_inset
19725
19726  file from the .adb
19727 \begin_inset LatexCommand \index{<file>.adb}
19728
19729 \end_inset
19730
19731  files and the address information.
19732  This .cdb is used by the debugger.
19733 \layout Section
19734
19735 How the Debugger Works
19736 \layout Standard
19737
19738 When the -
19739 \begin_inset ERT
19740 status Collapsed
19741
19742 \layout Standard
19743
19744 \backslash
19745 /
19746 \end_inset
19747
19748 -debug option is specified the compiler generates extra symbol information
19749  some of which are put into the assembler source and some are put into the
19750  .adb file.
19751   Then the linker creates the .cdb file from the individual .adb files with
19752  the address information for the symbols.
19753  The debugger reads the symbolic information generated by the compiler &
19754  the address information generated by the linker.
19755  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
19756  execution is controlled by the debugger.
19757  When a command is issued for the debugger, it translates it into appropriate
19758  commands for the simulator.
19759 \layout Section
19760
19761 Starting the Debugger
19762 \layout Standard
19763
19764 The debugger can be started using the following command line.
19765  (Assume the file you are debugging has the file name foo).
19766 \newline
19767
19768 \newline
19769
19770 \family sans
19771 \series bold
19772 sdcdb foo
19773 \newline
19774
19775 \family default
19776 \series default
19777
19778 \newline
19779 The debugger will look for the following files.
19780 \layout Itemize
19781
19782 foo.c - the source file.
19783 \layout Itemize
19784
19785 foo.cdb - the debugger symbol information file.
19786 \layout Itemize
19787
19788 foo.ihx - the Intel hex format
19789 \begin_inset LatexCommand \index{Intel hex format}
19790
19791 \end_inset
19792
19793  object file.
19794 \layout Section
19795
19796 Command Line Options.
19797 \layout Itemize
19798
19799 -
19800 \begin_inset ERT
19801 status Collapsed
19802
19803 \layout Standard
19804
19805 \backslash
19806 /
19807 \end_inset
19808
19809 -directory=<source file directory> this option can used to specify the directory
19810  search list.
19811  The debugger will look into the directory list specified for source, cdb
19812  & ihx files.
19813  The items in the directory list must be separated by ':', e.g.
19814  if the source files can be in the directories /home/src1 and /home/src2,
19815  the -
19816 \begin_inset ERT
19817 status Collapsed
19818
19819 \layout Standard
19820
19821 \backslash
19822 /
19823 \end_inset
19824
19825 -directory option should be -
19826 \begin_inset ERT
19827 status Collapsed
19828
19829 \layout Standard
19830
19831 \backslash
19832 /
19833 \end_inset
19834
19835 -directory=/home/src1:/home/src2.
19836  Note there can be no spaces in the option.
19837
19838 \layout Itemize
19839
19840 -cd <directory> - change to the <directory>.
19841 \layout Itemize
19842
19843 -fullname - used by GUI front ends.
19844 \layout Itemize
19845
19846 -cpu <cpu-type> - this argument is passed to the simulator please see the
19847  simulator docs for details.
19848 \layout Itemize
19849
19850 -X <Clock frequency > this options is passed to the simulator please see
19851  the simulator docs for details.
19852 \layout Itemize
19853
19854 -s <serial port file> passed to simulator see the simulator docs for details.
19855 \layout Itemize
19856
19857 -S <serial in,out> passed to simulator see the simulator docs for details.
19858 \layout Itemize
19859
19860 -k <port number> passed to simulator see the simulator docs for details.
19861 \layout Section
19862
19863 Debugger Commands.
19864 \layout Standard
19865
19866 As mentioned earlier the command interface for the debugger has been deliberatel
19867 y kept as close the GNU debugger gdb, as possible.
19868  This will help the integration with existing graphical user interfaces
19869  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
19870  If you use a graphical user interface for the debugger you can skip the
19871  next sections.
19872 \layout Subsubsection*
19873
19874 break [line | file:line | function | file:function]
19875 \layout Standard
19876
19877 Set breakpoint at specified line or function:
19878 \newline
19879
19880 \newline
19881
19882 \family sans
19883 \series bold
19884 sdcdb>break 100
19885 \newline
19886 sdcdb>break foo.c:100
19887 \newline
19888 sdcdb>break funcfoo
19889 \newline
19890 sdcdb>break foo.c:funcfoo
19891 \layout Subsubsection*
19892
19893 clear [line | file:line | function | file:function ]
19894 \layout Standard
19895
19896 Clear breakpoint at specified line or function:
19897 \newline
19898
19899 \newline
19900
19901 \family sans
19902 \series bold
19903 sdcdb>clear 100
19904 \newline
19905 sdcdb>clear foo.c:100
19906 \newline
19907 sdcdb>clear funcfoo
19908 \newline
19909 sdcdb>clear foo.c:funcfoo
19910 \layout Subsubsection*
19911
19912 continue
19913 \layout Standard
19914
19915 Continue program being debugged, after breakpoint.
19916 \layout Subsubsection*
19917
19918 finish
19919 \layout Standard
19920
19921 Execute till the end of the current function.
19922 \layout Subsubsection*
19923
19924 delete [n]
19925 \layout Standard
19926
19927 Delete breakpoint number 'n'.
19928  If used without any option clear ALL user defined break points.
19929 \layout Subsubsection*
19930
19931 info [break | stack | frame | registers ]
19932 \layout Itemize
19933
19934 info break - list all breakpoints
19935 \layout Itemize
19936
19937 info stack - show the function call stack.
19938 \layout Itemize
19939
19940 info frame - show information about the current execution frame.
19941 \layout Itemize
19942
19943 info registers - show content of all registers.
19944 \layout Subsubsection*
19945
19946 step
19947 \layout Standard
19948
19949 Step program until it reaches a different source line.
19950  Note: pressing <return> repeats the last command.
19951 \layout Subsubsection*
19952
19953 next
19954 \layout Standard
19955
19956 Step program, proceeding through subroutine calls.
19957 \layout Subsubsection*
19958
19959 run
19960 \layout Standard
19961
19962 Start debugged program.
19963 \layout Subsubsection*
19964
19965 ptype variable
19966 \layout Standard
19967
19968 Print type information of the variable.
19969 \layout Subsubsection*
19970
19971 print variable
19972 \layout Standard
19973
19974 print value of variable.
19975 \layout Subsubsection*
19976
19977 file filename
19978 \layout Standard
19979
19980 load the given file name.
19981  Note this is an alternate method of loading file for debugging.
19982 \layout Subsubsection*
19983
19984 frame
19985 \layout Standard
19986
19987 print information about current frame.
19988 \layout Subsubsection*
19989
19990 set srcmode
19991 \layout Standard
19992
19993 Toggle between C source & assembly source.
19994 \layout Subsubsection*
19995
19996 ! simulator command
19997 \layout Standard
19998
19999 Send the string following '!' to the simulator, the simulator response is
20000  displayed.
20001  Note the debugger does not interpret the command being sent to the simulator,
20002  so if a command like 'go' is sent the debugger can loose its execution
20003  context and may display incorrect values.
20004 \layout Subsubsection*
20005
20006 quit
20007 \layout Standard
20008
20009 "Watch me now.
20010  Iam going Down.
20011  My name is Bobby Brown"
20012 \layout Section
20013
20014 Interfacing with XEmacs
20015 \begin_inset LatexCommand \index{XEmacs}
20016
20017 \end_inset
20018
20019
20020 \begin_inset LatexCommand \index{Emacs}
20021
20022 \end_inset
20023
20024 .
20025 \layout Standard
20026
20027 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
20028  sdcdb.el and sdcdbsrc.el.
20029  These two files can be found in the $(prefix)/bin directory after the installat
20030 ion is complete.
20031  These files need to be loaded into XEmacs for the interface to work.
20032  This can be done at XEmacs startup time by inserting the following into
20033  your '.xemacs' file (which can be found in your HOME directory):
20034 \newline
20035
20036 \newline
20037
20038 \family typewriter
20039 (load-file sdcdbsrc.el)
20040 \family default
20041
20042 \newline
20043
20044 \newline
20045 .xemacs is a lisp file so the () around the command is REQUIRED.
20046  The files can also be loaded dynamically while XEmacs is running, set the
20047  environment variable 'EMACSLOADPATH' to the installation bin directory
20048  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
20049  To start the interface enter the following command:
20050 \newline
20051
20052 \newline
20053
20054 \family sans
20055 \series bold
20056 ESC-x sdcdbsrc
20057 \family default
20058 \series default
20059
20060 \newline
20061
20062 \newline
20063 You will prompted to enter the file name to be debugged.
20064
20065 \newline
20066
20067 \newline
20068 The command line options that are passed to the simulator directly are bound
20069  to default values in the file sdcdbsrc.el.
20070  The variables are listed below, these values maybe changed as required.
20071 \layout Itemize
20072
20073 sdcdbsrc-cpu-type '51
20074 \layout Itemize
20075
20076 sdcdbsrc-frequency '11059200
20077 \layout Itemize
20078
20079 sdcdbsrc-serial nil
20080 \layout Standard
20081
20082 The following is a list of key mapping for the debugger interface.
20083 \layout Standard
20084
20085 \SpecialChar ~
20086
20087 \family typewriter
20088
20089 \newline
20090 ;;\SpecialChar ~
20091 Current Listing ::
20092 \newline
20093 ;;key\SpecialChar ~
20094 \SpecialChar ~
20095 \SpecialChar ~
20096 \SpecialChar ~
20097 \SpecialChar ~
20098 \SpecialChar ~
20099 \SpecialChar ~
20100 \SpecialChar ~
20101 \SpecialChar ~
20102 \SpecialChar ~
20103 \SpecialChar ~
20104 \SpecialChar ~
20105 \SpecialChar ~
20106 \SpecialChar ~
20107 binding\SpecialChar ~
20108 \SpecialChar ~
20109 \SpecialChar ~
20110 \SpecialChar ~
20111 \SpecialChar ~
20112 \SpecialChar ~
20113 \SpecialChar ~
20114 \SpecialChar ~
20115 \SpecialChar ~
20116 \SpecialChar ~
20117 \SpecialChar ~
20118 \SpecialChar ~
20119 \SpecialChar ~
20120 \SpecialChar ~
20121 \SpecialChar ~
20122 \SpecialChar ~
20123 \SpecialChar ~
20124 \SpecialChar ~
20125 \SpecialChar ~
20126 \SpecialChar ~
20127 \SpecialChar ~
20128 \SpecialChar ~
20129 Comment
20130 \newline
20131 ;;---\SpecialChar ~
20132 \SpecialChar ~
20133 \SpecialChar ~
20134 \SpecialChar ~
20135 \SpecialChar ~
20136 \SpecialChar ~
20137 \SpecialChar ~
20138 \SpecialChar ~
20139 \SpecialChar ~
20140 \SpecialChar ~
20141 \SpecialChar ~
20142 \SpecialChar ~
20143 \SpecialChar ~
20144 \SpecialChar ~
20145 -------\SpecialChar ~
20146 \SpecialChar ~
20147 \SpecialChar ~
20148 \SpecialChar ~
20149 \SpecialChar ~
20150 \SpecialChar ~
20151 \SpecialChar ~
20152 \SpecialChar ~
20153 \SpecialChar ~
20154 \SpecialChar ~
20155 \SpecialChar ~
20156 \SpecialChar ~
20157 \SpecialChar ~
20158 \SpecialChar ~
20159 \SpecialChar ~
20160 \SpecialChar ~
20161 \SpecialChar ~
20162 \SpecialChar ~
20163 \SpecialChar ~
20164 \SpecialChar ~
20165 \SpecialChar ~
20166 \SpecialChar ~
20167 -------
20168 \newline
20169 ;;
20170 \newline
20171 ;;\SpecialChar ~
20172 n\SpecialChar ~
20173 \SpecialChar ~
20174 \SpecialChar ~
20175 \SpecialChar ~
20176 \SpecialChar ~
20177 \SpecialChar ~
20178 \SpecialChar ~
20179 \SpecialChar ~
20180 \SpecialChar ~
20181 \SpecialChar ~
20182 \SpecialChar ~
20183 \SpecialChar ~
20184 \SpecialChar ~
20185 \SpecialChar ~
20186 \SpecialChar ~
20187 sdcdb-next-from-src\SpecialChar ~
20188 \SpecialChar ~
20189 \SpecialChar ~
20190 \SpecialChar ~
20191 \SpecialChar ~
20192 \SpecialChar ~
20193 \SpecialChar ~
20194 \SpecialChar ~
20195 \SpecialChar ~
20196 \SpecialChar ~
20197 SDCDB next command
20198 \newline
20199 ;;\SpecialChar ~
20200 b\SpecialChar ~
20201 \SpecialChar ~
20202 \SpecialChar ~
20203 \SpecialChar ~
20204 \SpecialChar ~
20205 \SpecialChar ~
20206 \SpecialChar ~
20207 \SpecialChar ~
20208 \SpecialChar ~
20209 \SpecialChar ~
20210 \SpecialChar ~
20211 \SpecialChar ~
20212 \SpecialChar ~
20213 \SpecialChar ~
20214 \SpecialChar ~
20215 sdcdb-back-from-src\SpecialChar ~
20216 \SpecialChar ~
20217 \SpecialChar ~
20218 \SpecialChar ~
20219 \SpecialChar ~
20220 \SpecialChar ~
20221 \SpecialChar ~
20222 \SpecialChar ~
20223 \SpecialChar ~
20224 \SpecialChar ~
20225 SDCDB back command
20226 \newline
20227 ;;\SpecialChar ~
20228 c\SpecialChar ~
20229 \SpecialChar ~
20230 \SpecialChar ~
20231 \SpecialChar ~
20232 \SpecialChar ~
20233 \SpecialChar ~
20234 \SpecialChar ~
20235 \SpecialChar ~
20236 \SpecialChar ~
20237 \SpecialChar ~
20238 \SpecialChar ~
20239 \SpecialChar ~
20240 \SpecialChar ~
20241 \SpecialChar ~
20242 \SpecialChar ~
20243 sdcdb-cont-from-src\SpecialChar ~
20244 \SpecialChar ~
20245 \SpecialChar ~
20246 \SpecialChar ~
20247 \SpecialChar ~
20248 \SpecialChar ~
20249 \SpecialChar ~
20250 \SpecialChar ~
20251 \SpecialChar ~
20252 \SpecialChar ~
20253 SDCDB continue command
20254 \newline
20255 ;;\SpecialChar ~
20256 s\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 sdcdb-step-from-src\SpecialChar ~
20272 \SpecialChar ~
20273 \SpecialChar ~
20274 \SpecialChar ~
20275 \SpecialChar ~
20276 \SpecialChar ~
20277 \SpecialChar ~
20278 \SpecialChar ~
20279 \SpecialChar ~
20280 \SpecialChar ~
20281 SDCDB step command
20282 \newline
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 sdcdb-whatis-c-sexp\SpecialChar ~
20300 \SpecialChar ~
20301 \SpecialChar ~
20302 \SpecialChar ~
20303 \SpecialChar ~
20304 \SpecialChar ~
20305 \SpecialChar ~
20306 \SpecialChar ~
20307 \SpecialChar ~
20308 \SpecialChar ~
20309 SDCDB ptypecommand for data at
20310 \newline
20311 ;;\SpecialChar ~
20312 \SpecialChar ~
20313 \SpecialChar ~
20314 \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 \SpecialChar ~
20330 \SpecialChar ~
20331 \SpecialChar ~
20332 \SpecialChar ~
20333 \SpecialChar ~
20334 \SpecialChar ~
20335 \SpecialChar ~
20336 \SpecialChar ~
20337 \SpecialChar ~
20338 \SpecialChar ~
20339 \SpecialChar ~
20340 \SpecialChar ~
20341 \SpecialChar ~
20342 \SpecialChar ~
20343 \SpecialChar ~
20344 \SpecialChar ~
20345 \SpecialChar ~
20346 \SpecialChar ~
20347 \SpecialChar ~
20348 \SpecialChar ~
20349 \SpecialChar ~
20350 \SpecialChar ~
20351 \SpecialChar ~
20352 \SpecialChar ~
20353 \SpecialChar ~
20354 \SpecialChar ~
20355 \SpecialChar ~
20356 \SpecialChar ~
20357 \SpecialChar ~
20358 buffer point
20359 \newline
20360 ;;\SpecialChar ~
20361 x\SpecialChar ~
20362 \SpecialChar ~
20363 \SpecialChar ~
20364 \SpecialChar ~
20365 \SpecialChar ~
20366 \SpecialChar ~
20367 \SpecialChar ~
20368 \SpecialChar ~
20369 \SpecialChar ~
20370 \SpecialChar ~
20371 \SpecialChar ~
20372 \SpecialChar ~
20373 \SpecialChar ~
20374 \SpecialChar ~
20375 \SpecialChar ~
20376 sdcdbsrc-delete\SpecialChar ~
20377 \SpecialChar ~
20378 \SpecialChar ~
20379 \SpecialChar ~
20380 \SpecialChar ~
20381 \SpecialChar ~
20382 \SpecialChar ~
20383 \SpecialChar ~
20384 \SpecialChar ~
20385 \SpecialChar ~
20386 \SpecialChar ~
20387 \SpecialChar ~
20388 \SpecialChar ~
20389 \SpecialChar ~
20390 SDCDB Delete all breakpoints if no arg
20391 \newline
20392 ;;\SpecialChar ~
20393 \SpecialChar ~
20394 \SpecialChar ~
20395 \SpecialChar ~
20396 \SpecialChar ~
20397 \SpecialChar ~
20398 \SpecialChar ~
20399 \SpecialChar ~
20400 \SpecialChar ~
20401 \SpecialChar ~
20402 \SpecialChar ~
20403 \SpecialChar ~
20404 \SpecialChar ~
20405 \SpecialChar ~
20406 \SpecialChar ~
20407 \SpecialChar ~
20408 \SpecialChar ~
20409 \SpecialChar ~
20410 \SpecialChar ~
20411 \SpecialChar ~
20412 \SpecialChar ~
20413 \SpecialChar ~
20414 \SpecialChar ~
20415 \SpecialChar ~
20416 \SpecialChar ~
20417 \SpecialChar ~
20418 \SpecialChar ~
20419 \SpecialChar ~
20420 \SpecialChar ~
20421 \SpecialChar ~
20422 \SpecialChar ~
20423 \SpecialChar ~
20424 \SpecialChar ~
20425 \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 given or delete arg (C-u arg x)
20440 \newline
20441 ;;\SpecialChar ~
20442 m\SpecialChar ~
20443 \SpecialChar ~
20444 \SpecialChar ~
20445 \SpecialChar ~
20446 \SpecialChar ~
20447 \SpecialChar ~
20448 \SpecialChar ~
20449 \SpecialChar ~
20450 \SpecialChar ~
20451 \SpecialChar ~
20452 \SpecialChar ~
20453 \SpecialChar ~
20454 \SpecialChar ~
20455 \SpecialChar ~
20456 \SpecialChar ~
20457 sdcdbsrc-frame\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 SDCDB Display current frame if no arg,
20473 \newline
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 \SpecialChar ~
20501 \SpecialChar ~
20502 \SpecialChar ~
20503 \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 \SpecialChar ~
20519 \SpecialChar ~
20520 \SpecialChar ~
20521 given or display frame arg
20522 \newline
20523 ;;\SpecialChar ~
20524 \SpecialChar ~
20525 \SpecialChar ~
20526 \SpecialChar ~
20527 \SpecialChar ~
20528 \SpecialChar ~
20529 \SpecialChar ~
20530 \SpecialChar ~
20531 \SpecialChar ~
20532 \SpecialChar ~
20533 \SpecialChar ~
20534 \SpecialChar ~
20535 \SpecialChar ~
20536 \SpecialChar ~
20537 \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 buffer point
20571 \newline
20572 ;;\SpecialChar ~
20573 !\SpecialChar ~
20574 \SpecialChar ~
20575 \SpecialChar ~
20576 \SpecialChar ~
20577 \SpecialChar ~
20578 \SpecialChar ~
20579 \SpecialChar ~
20580 \SpecialChar ~
20581 \SpecialChar ~
20582 \SpecialChar ~
20583 \SpecialChar ~
20584 \SpecialChar ~
20585 \SpecialChar ~
20586 \SpecialChar ~
20587 \SpecialChar ~
20588 sdcdbsrc-goto-sdcdb\SpecialChar ~
20589 \SpecialChar ~
20590 \SpecialChar ~
20591 \SpecialChar ~
20592 \SpecialChar ~
20593 \SpecialChar ~
20594 \SpecialChar ~
20595 \SpecialChar ~
20596 \SpecialChar ~
20597 \SpecialChar ~
20598 Goto the SDCDB output buffer
20599 \newline
20600 ;;\SpecialChar ~
20601 p\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 \SpecialChar ~
20615 \SpecialChar ~
20616 sdcdb-print-c-sexp\SpecialChar ~
20617 \SpecialChar ~
20618 \SpecialChar ~
20619 \SpecialChar ~
20620 \SpecialChar ~
20621 \SpecialChar ~
20622 \SpecialChar ~
20623 \SpecialChar ~
20624 \SpecialChar ~
20625 \SpecialChar ~
20626 \SpecialChar ~
20627 SDCDB print command for data at
20628 \newline
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 \SpecialChar ~
20664 \SpecialChar ~
20665 \SpecialChar ~
20666 \SpecialChar ~
20667 \SpecialChar ~
20668 \SpecialChar ~
20669 \SpecialChar ~
20670 \SpecialChar ~
20671 \SpecialChar ~
20672 \SpecialChar ~
20673 \SpecialChar ~
20674 \SpecialChar ~
20675 \SpecialChar ~
20676 buffer point
20677 \newline
20678 ;;\SpecialChar ~
20679 g\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 sdcdbsrc-goto-sdcdb\SpecialChar ~
20695 \SpecialChar ~
20696 \SpecialChar ~
20697 \SpecialChar ~
20698 \SpecialChar ~
20699 \SpecialChar ~
20700 \SpecialChar ~
20701 \SpecialChar ~
20702 \SpecialChar ~
20703 \SpecialChar ~
20704 Goto the SDCDB output buffer
20705 \newline
20706 ;;\SpecialChar ~
20707 t\SpecialChar ~
20708 \SpecialChar ~
20709 \SpecialChar ~
20710 \SpecialChar ~
20711 \SpecialChar ~
20712 \SpecialChar ~
20713 \SpecialChar ~
20714 \SpecialChar ~
20715 \SpecialChar ~
20716 \SpecialChar ~
20717 \SpecialChar ~
20718 \SpecialChar ~
20719 \SpecialChar ~
20720 \SpecialChar ~
20721 \SpecialChar ~
20722 sdcdbsrc-mode\SpecialChar ~
20723 \SpecialChar ~
20724 \SpecialChar ~
20725 \SpecialChar ~
20726 \SpecialChar ~
20727 \SpecialChar ~
20728 \SpecialChar ~
20729 \SpecialChar ~
20730 \SpecialChar ~
20731 \SpecialChar ~
20732 \SpecialChar ~
20733 \SpecialChar ~
20734 \SpecialChar ~
20735 \SpecialChar ~
20736 \SpecialChar ~
20737 \SpecialChar ~
20738 Toggles Sdcdbsrc mode (turns it off)
20739 \newline
20740 ;;
20741 \newline
20742 ;;\SpecialChar ~
20743 C-c\SpecialChar ~
20744 C-f\SpecialChar ~
20745 \SpecialChar ~
20746 \SpecialChar ~
20747 \SpecialChar ~
20748 \SpecialChar ~
20749 \SpecialChar ~
20750 \SpecialChar ~
20751 \SpecialChar ~
20752 \SpecialChar ~
20753 sdcdb-finish-from-src\SpecialChar ~
20754 \SpecialChar ~
20755 \SpecialChar ~
20756 \SpecialChar ~
20757 \SpecialChar ~
20758 \SpecialChar ~
20759 \SpecialChar ~
20760 \SpecialChar ~
20761 SDCDB finish command
20762 \newline
20763 ;;
20764 \newline
20765 ;;\SpecialChar ~
20766 C-x\SpecialChar ~
20767 SPC\SpecialChar ~
20768 \SpecialChar ~
20769 \SpecialChar ~
20770 \SpecialChar ~
20771 \SpecialChar ~
20772 \SpecialChar ~
20773 \SpecialChar ~
20774 \SpecialChar ~
20775 \SpecialChar ~
20776 sdcdb-break\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 Set break for line with point
20795 \newline
20796 ;;\SpecialChar ~
20797 ESC\SpecialChar ~
20798 t\SpecialChar ~
20799 \SpecialChar ~
20800 \SpecialChar ~
20801 \SpecialChar ~
20802 \SpecialChar ~
20803 \SpecialChar ~
20804 \SpecialChar ~
20805 \SpecialChar ~
20806 \SpecialChar ~
20807 \SpecialChar ~
20808 \SpecialChar ~
20809 sdcdbsrc-mode\SpecialChar ~
20810 \SpecialChar ~
20811 \SpecialChar ~
20812 \SpecialChar ~
20813 \SpecialChar ~
20814 \SpecialChar ~
20815 \SpecialChar ~
20816 \SpecialChar ~
20817 \SpecialChar ~
20818 \SpecialChar ~
20819 \SpecialChar ~
20820 \SpecialChar ~
20821 \SpecialChar ~
20822 \SpecialChar ~
20823 \SpecialChar ~
20824 \SpecialChar ~
20825 Toggle Sdcdbsrc mode
20826 \newline
20827 ;;\SpecialChar ~
20828 ESC\SpecialChar ~
20829 m\SpecialChar ~
20830 \SpecialChar ~
20831 \SpecialChar ~
20832 \SpecialChar ~
20833 \SpecialChar ~
20834 \SpecialChar ~
20835 \SpecialChar ~
20836 \SpecialChar ~
20837 \SpecialChar ~
20838 \SpecialChar ~
20839 \SpecialChar ~
20840 sdcdbsrc-srcmode\SpecialChar ~
20841 \SpecialChar ~
20842 \SpecialChar ~
20843 \SpecialChar ~
20844 \SpecialChar ~
20845 \SpecialChar ~
20846 \SpecialChar ~
20847 \SpecialChar ~
20848 \SpecialChar ~
20849 \SpecialChar ~
20850 \SpecialChar ~
20851 \SpecialChar ~
20852 \SpecialChar ~
20853 Toggle list mode
20854 \newline
20855 ;;
20856 \newline
20857
20858 \layout Chapter
20859 \pagebreak_top
20860 TIPS
20861 \layout Standard
20862
20863 Here are a few guidelines that will help the compiler generate more efficient
20864  code, some of the tips are specific to this compiler others are generally
20865  good programming practice.
20866 \layout Itemize
20867
20868 Use the smallest data type to represent your data-value.
20869  If it is known in advance that the value is going to be less than 256 then
20870  use an 'unsigned char' instead of a 'short' or 'int'.
20871  Please note, that ANSI C requires both signed and unsigned chars to be
20872  promoted to 'signed int' before doing any operation.
20873  This promotion
20874 \begin_inset LatexCommand \index{type promotion}
20875
20876 \end_inset
20877
20878  can be omitted, if the result is the same.
20879  The effect of the promotion rules together with the sign-extension is often
20880  surprising:
20881 \begin_deeper
20882 \layout Verse
20883
20884
20885 \family typewriter
20886 unsigned char uc = 0xfe;
20887 \newline
20888 if (uc * uc < 0) /* this is true! */
20889 \newline
20890 {
20891 \newline
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895 \SpecialChar ~
20896 ....
20897 \newline
20898 }
20899 \layout Standard
20900
20901
20902 \family typewriter
20903 uc * uc
20904 \family default
20905  is evaluated as
20906 \family typewriter
20907 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
20908 \family default
20909 .
20910
20911 \newline
20912 Another one:
20913 \layout Verse
20914
20915
20916 \family typewriter
20917 (unsigned char) -12 / (signed char) -3 = ...
20918 \layout Standard
20919
20920 No, the result is not 4:
20921 \layout Verse
20922
20923
20924 \family typewriter
20925 (int) (unsigned char) -12 / (int) (signed char) -3 =
20926 \newline
20927 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
20928 \newline
20929 (int) 0x00f4 / (int) 0xfffd =
20930 \newline
20931 (int) 0x00f4 / (int) 0xfffd =
20932 \newline
20933 (int) 244 / (int) -3 =
20934 \newline
20935 (int) -81 = (int) 0xffaf;
20936 \layout Standard
20937
20938 Don't complain, that gcc gives you a different result.
20939  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
20940  Therefore the results are different.
20941 \newline
20942 From
20943 \begin_inset Quotes sld
20944 \end_inset
20945
20946 comp.lang.c FAQ
20947 \begin_inset Quotes srd
20948 \end_inset
20949
20950 :
20951 \layout Quote
20952
20953 If well-defined overflow characteristics are important and negative values
20954  are not, or if you want to steer clear of sign-extension problems when
20955  manipulating bits or bytes, use one of the corresponding unsigned types.
20956  (Beware when mixing signed and unsigned values in expressions, though.)
20957 \newline
20958 Although character types (especially unsigned char) can be used as "tiny"
20959  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
20960 ble sign extension and increased code size.
20961 \end_deeper
20962 \layout Itemize
20963
20964 Use unsigned when it is known in advance that the value is not going to
20965  be negative.
20966  This helps especially if you are doing division or multiplication, bit-shifting
20967  or are using an array index.
20968 \layout Itemize
20969
20970 NEVER jump into a LOOP.
20971 \layout Itemize
20972
20973 Declare the variables to be local
20974 \begin_inset LatexCommand \index{local variables}
20975
20976 \end_inset
20977
20978  whenever possible, especially loop control variables (induction).
20979 \layout Itemize
20980
20981 Since the compiler does not always do implicit integral promotion, the programme
20982 r should do an explicit cast when integral promotion is required.
20983 \layout Itemize
20984
20985 Reducing the size of division, multiplication & modulus operations can reduce
20986  code size substantially.
20987  Take the following code for example.
20988 \begin_deeper
20989 \layout Verse
20990
20991
20992 \family typewriter
20993 foobar(unsigned int p1, unsigned char ch)
20994 \newline
20995 {
20996 \newline
20997 \SpecialChar ~
20998 \SpecialChar ~
20999 \SpecialChar ~
21000 \SpecialChar ~
21001 unsigned char ch1 = p1 % ch ;
21002 \newline
21003 \SpecialChar ~
21004 \SpecialChar ~
21005 \SpecialChar ~
21006 \SpecialChar ~
21007 ....
21008 \newline
21009 }
21010 \layout Standard
21011
21012 For the modulus operation the variable ch will be promoted to unsigned int
21013  first then the modulus operation will be performed (this will lead to a
21014  call to support routine _moduint()), and the result will be casted to a
21015  char.
21016  If the code is changed to
21017 \layout Verse
21018
21019
21020 \family typewriter
21021 foobar(unsigned int p1, unsigned char ch)
21022 \newline
21023 {
21024 \newline
21025 \SpecialChar ~
21026 \SpecialChar ~
21027 \SpecialChar ~
21028 \SpecialChar ~
21029 unsigned char ch1 = (unsigned char)p1 % ch ;
21030 \newline
21031 \SpecialChar ~
21032 \SpecialChar ~
21033 \SpecialChar ~
21034 \SpecialChar ~
21035 ....
21036 \newline
21037 }
21038 \layout Standard
21039
21040 It would substantially reduce the code generated (future versions of the
21041  compiler will be smart enough to detect such optimization opportunities).
21042 \end_deeper
21043 \layout Itemize
21044
21045 Have a look at the assembly listing to get a
21046 \begin_inset Quotes sld
21047 \end_inset
21048
21049 feeling
21050 \begin_inset Quotes srd
21051 \end_inset
21052
21053  for the code generation.
21054 \layout Section
21055
21056 Tools
21057 \begin_inset LatexCommand \index{Tools}
21058
21059 \end_inset
21060
21061  included in the distribution
21062 \layout Standard
21063 \align center
21064
21065 \begin_inset  Tabular
21066 <lyxtabular version="3" rows="12" columns="3">
21067 <features>
21068 <column alignment="center" valignment="top" leftline="true" width="0pt">
21069 <column alignment="center" valignment="top" leftline="true" width="0pt">
21070 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21071 <row topline="true" bottomline="true">
21072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21073 \begin_inset Text
21074
21075 \layout Standard
21076
21077 Name
21078 \end_inset
21079 </cell>
21080 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21081 \begin_inset Text
21082
21083 \layout Standard
21084
21085 Purpose
21086 \end_inset
21087 </cell>
21088 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21089 \begin_inset Text
21090
21091 \layout Standard
21092
21093 Directory
21094 \end_inset
21095 </cell>
21096 </row>
21097 <row topline="true">
21098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21099 \begin_inset Text
21100
21101 \layout Standard
21102
21103 uCsim
21104 \end_inset
21105 </cell>
21106 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21107 \begin_inset Text
21108
21109 \layout Standard
21110
21111 Simulator for various architectures
21112 \end_inset
21113 </cell>
21114 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21115 \begin_inset Text
21116
21117 \layout Standard
21118
21119 sdcc/sim/ucsim
21120 \end_inset
21121 </cell>
21122 </row>
21123 <row topline="true">
21124 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21125 \begin_inset Text
21126
21127 \layout Standard
21128
21129 keil2sdcc.pl
21130 \end_inset
21131 </cell>
21132 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21133 \begin_inset Text
21134
21135 \layout Standard
21136
21137 header file conversion
21138 \end_inset
21139 </cell>
21140 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21141 \begin_inset Text
21142
21143 \layout Standard
21144
21145 sdcc/support/scripts
21146 \end_inset
21147 </cell>
21148 </row>
21149 <row topline="true">
21150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21151 \begin_inset Text
21152
21153 \layout Standard
21154
21155 mh2h.c
21156 \end_inset
21157 </cell>
21158 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21159 \begin_inset Text
21160
21161 \layout Standard
21162
21163 header file conversion
21164 \end_inset
21165 </cell>
21166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21167 \begin_inset Text
21168
21169 \layout Standard
21170
21171 sdcc/support/scripts
21172 \end_inset
21173 </cell>
21174 </row>
21175 <row topline="true">
21176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21177 \begin_inset Text
21178
21179 \layout Standard
21180
21181 as-gbz80
21182 \end_inset
21183 </cell>
21184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21185 \begin_inset Text
21186
21187 \layout Standard
21188
21189 Assembler
21190 \end_inset
21191 </cell>
21192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21193 \begin_inset Text
21194
21195 \layout Standard
21196
21197
21198 \family roman
21199 \series medium
21200 \shape up
21201 \size normal
21202 \emph off
21203 \bar no
21204 \noun off
21205 \color none
21206 sdcc/bin
21207 \end_inset
21208 </cell>
21209 </row>
21210 <row topline="true">
21211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21212 \begin_inset Text
21213
21214 \layout Standard
21215
21216 as-z80
21217 \end_inset
21218 </cell>
21219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21220 \begin_inset Text
21221
21222 \layout Standard
21223
21224 Assembler
21225 \end_inset
21226 </cell>
21227 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21228 \begin_inset Text
21229
21230 \layout Standard
21231
21232
21233 \family roman
21234 \series medium
21235 \shape up
21236 \size normal
21237 \emph off
21238 \bar no
21239 \noun off
21240 \color none
21241 sdcc/bin
21242 \end_inset
21243 </cell>
21244 </row>
21245 <row topline="true">
21246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21247 \begin_inset Text
21248
21249 \layout Standard
21250
21251 asx8051
21252 \end_inset
21253 </cell>
21254 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21255 \begin_inset Text
21256
21257 \layout Standard
21258
21259 Assembler
21260 \end_inset
21261 </cell>
21262 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21263 \begin_inset Text
21264
21265 \layout Standard
21266
21267
21268 \family roman
21269 \series medium
21270 \shape up
21271 \size normal
21272 \emph off
21273 \bar no
21274 \noun off
21275 \color none
21276 sdcc/bin
21277 \end_inset
21278 </cell>
21279 </row>
21280 <row topline="true">
21281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21282 \begin_inset Text
21283
21284 \layout Standard
21285
21286 sdcdb
21287 \end_inset
21288 </cell>
21289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21290 \begin_inset Text
21291
21292 \layout Standard
21293
21294 Simulator
21295 \end_inset
21296 </cell>
21297 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21298 \begin_inset Text
21299
21300 \layout Standard
21301
21302
21303 \family roman
21304 \series medium
21305 \shape up
21306 \size normal
21307 \emph off
21308 \bar no
21309 \noun off
21310 \color none
21311 sdcc/bin
21312 \end_inset
21313 </cell>
21314 </row>
21315 <row topline="true">
21316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21317 \begin_inset Text
21318
21319 \layout Standard
21320
21321 aslink
21322 \end_inset
21323 </cell>
21324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21325 \begin_inset Text
21326
21327 \layout Standard
21328
21329 Linker
21330 \end_inset
21331 </cell>
21332 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21333 \begin_inset Text
21334
21335 \layout Standard
21336
21337
21338 \family roman
21339 \series medium
21340 \shape up
21341 \size normal
21342 \emph off
21343 \bar no
21344 \noun off
21345 \color none
21346 sdcc/bin
21347 \end_inset
21348 </cell>
21349 </row>
21350 <row topline="true">
21351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21352 \begin_inset Text
21353
21354 \layout Standard
21355
21356 link-z80
21357 \end_inset
21358 </cell>
21359 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21360 \begin_inset Text
21361
21362 \layout Standard
21363
21364 Linker
21365 \end_inset
21366 </cell>
21367 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21368 \begin_inset Text
21369
21370 \layout Standard
21371
21372
21373 \family roman
21374 \series medium
21375 \shape up
21376 \size normal
21377 \emph off
21378 \bar no
21379 \noun off
21380 \color none
21381 sdcc/bin
21382 \end_inset
21383 </cell>
21384 </row>
21385 <row topline="true">
21386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21387 \begin_inset Text
21388
21389 \layout Standard
21390
21391 link-gbz80
21392 \end_inset
21393 </cell>
21394 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21395 \begin_inset Text
21396
21397 \layout Standard
21398
21399 Linker
21400 \end_inset
21401 </cell>
21402 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21403 \begin_inset Text
21404
21405 \layout Standard
21406
21407
21408 \family roman
21409 \series medium
21410 \shape up
21411 \size normal
21412 \emph off
21413 \bar no
21414 \noun off
21415 \color none
21416 sdcc/bin
21417 \end_inset
21418 </cell>
21419 </row>
21420 <row topline="true" bottomline="true">
21421 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21422 \begin_inset Text
21423
21424 \layout Standard
21425
21426 packihx
21427 \end_inset
21428 </cell>
21429 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21430 \begin_inset Text
21431
21432 \layout Standard
21433
21434 ihx packer
21435 \end_inset
21436 </cell>
21437 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21438 \begin_inset Text
21439
21440 \layout Standard
21441
21442
21443 \family roman
21444 \series medium
21445 \shape up
21446 \size normal
21447 \emph off
21448 \bar no
21449 \noun off
21450 \color none
21451 sdcc/bin
21452 \end_inset
21453 </cell>
21454 </row>
21455 </lyxtabular>
21456
21457 \end_inset
21458
21459
21460 \newline
21461
21462 \layout Section
21463
21464 Documentation
21465 \begin_inset LatexCommand \index{Documentation}
21466
21467 \end_inset
21468
21469  included in the distribution
21470 \layout Standard
21471 \align center
21472
21473 \begin_inset  Tabular
21474 <lyxtabular version="3" rows="10" columns="2">
21475 <features>
21476 <column alignment="left" valignment="top" leftline="true" width="0">
21477 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21478 <row topline="true" bottomline="true">
21479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21480 \begin_inset Text
21481
21482 \layout Standard
21483
21484 Subject / Title
21485 \end_inset
21486 </cell>
21487 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21488 \begin_inset Text
21489
21490 \layout Standard
21491
21492 Where to get / filename
21493 \end_inset
21494 </cell>
21495 </row>
21496 <row topline="true">
21497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21498 \begin_inset Text
21499
21500 \layout Standard
21501
21502 SDCC Compiler User Guide
21503 \end_inset
21504 </cell>
21505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21506 \begin_inset Text
21507
21508 \layout Standard
21509
21510 You're reading it right now
21511 \end_inset
21512 </cell>
21513 </row>
21514 <row topline="true">
21515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21516 \begin_inset Text
21517
21518 \layout Standard
21519
21520 Changelog of SDCC
21521 \end_inset
21522 </cell>
21523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21524 \begin_inset Text
21525
21526 \layout Standard
21527
21528 sdcc/Changelog
21529 \end_inset
21530 </cell>
21531 </row>
21532 <row topline="true">
21533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21534 \begin_inset Text
21535
21536 \layout Standard
21537
21538 ASXXXX
21539 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
21540
21541 \end_inset
21542
21543
21544 \begin_inset LatexCommand \index{Assembler documentation}
21545
21546 \end_inset
21547
21548  Assemblers and ASLINK
21549 \begin_inset LatexCommand \index{aslink}
21550
21551 \end_inset
21552
21553
21554 \begin_inset LatexCommand \index{Linker documentation}
21555
21556 \end_inset
21557
21558  Relocating Linker
21559 \end_inset
21560 </cell>
21561 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21562 \begin_inset Text
21563
21564 \layout Standard
21565
21566 sdcc/as/doc/asxhtm.html
21567 \end_inset
21568 </cell>
21569 </row>
21570 <row topline="true">
21571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21572 \begin_inset Text
21573
21574 \layout Standard
21575
21576 SDCC regression test
21577 \begin_inset LatexCommand \index{Regression test}
21578
21579 \end_inset
21580
21581
21582 \end_inset
21583 </cell>
21584 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21585 \begin_inset Text
21586
21587 \layout Standard
21588
21589 sdcc/doc/test_suite_spec.pdf
21590 \end_inset
21591 </cell>
21592 </row>
21593 <row topline="true">
21594 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21595 \begin_inset Text
21596
21597 \layout Standard
21598
21599 Various notes
21600 \end_inset
21601 </cell>
21602 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21603 \begin_inset Text
21604
21605 \layout Standard
21606
21607 sdcc/doc/*
21608 \end_inset
21609 </cell>
21610 </row>
21611 <row topline="true">
21612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21613 \begin_inset Text
21614
21615 \layout Standard
21616
21617 Notes on debugging with sdcdb
21618 \begin_inset LatexCommand \index{sdcdb (debugger)}
21619
21620 \end_inset
21621
21622
21623 \end_inset
21624 </cell>
21625 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21626 \begin_inset Text
21627
21628 \layout Standard
21629
21630 sdcc/debugger/README
21631 \end_inset
21632 </cell>
21633 </row>
21634 <row topline="true">
21635 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21636 \begin_inset Text
21637
21638 \layout Standard
21639
21640 Software simulator for microcontrollers
21641 \end_inset
21642 </cell>
21643 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21644 \begin_inset Text
21645
21646 \layout Standard
21647
21648
21649 \family roman
21650 \series medium
21651 \shape up
21652 \size normal
21653 \emph off
21654 \bar no
21655 \noun off
21656 \color none
21657 sdcc/sim/ucsim/doc
21658 \family default
21659 \series default
21660 \shape default
21661 \size default
21662 \emph default
21663 \bar default
21664 \noun default
21665 \color default
21666 /index.html
21667 \end_inset
21668 </cell>
21669 </row>
21670 <row topline="true">
21671 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21672 \begin_inset Text
21673
21674 \layout Standard
21675
21676 Temporary notes on the pic16
21677 \begin_inset LatexCommand \index{PIC16}
21678
21679 \end_inset
21680
21681  port
21682 \end_inset
21683 </cell>
21684 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21685 \begin_inset Text
21686
21687 \layout Standard
21688
21689 sdcc/src/pic16/NOTES
21690 \end_inset
21691 </cell>
21692 </row>
21693 <row topline="true" bottomline="true">
21694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21695 \begin_inset Text
21696
21697 \layout Standard
21698
21699 SDCC internal documentation (debugging file format)
21700 \end_inset
21701 </cell>
21702 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21703 \begin_inset Text
21704
21705 \layout Standard
21706
21707 sdcc/doc/
21708 \family roman
21709 \series medium
21710 \shape up
21711 \size normal
21712 \emph off
21713 \bar no
21714 \noun off
21715 \color none
21716 cdbfileformat.pd
21717 \family default
21718 \series default
21719 \shape default
21720 \size default
21721 \emph default
21722 \bar default
21723 \noun default
21724 \color default
21725 f
21726 \end_inset
21727 </cell>
21728 </row>
21729 </lyxtabular>
21730
21731 \end_inset
21732
21733
21734 \newline
21735
21736 \layout Section
21737
21738 Related open source tools
21739 \begin_inset LatexCommand \index{Related tools}
21740
21741 \end_inset
21742
21743
21744 \layout Standard
21745 \align center
21746
21747 \begin_inset  Tabular
21748 <lyxtabular version="3" rows="11" columns="3">
21749 <features>
21750 <column alignment="center" valignment="top" leftline="true" width="0pt">
21751 <column alignment="block" valignment="top" leftline="true" width="30line%">
21752 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21753 <row topline="true" bottomline="true">
21754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21755 \begin_inset Text
21756
21757 \layout Standard
21758
21759 Name
21760 \end_inset
21761 </cell>
21762 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21763 \begin_inset Text
21764
21765 \layout Standard
21766
21767 Purpose
21768 \end_inset
21769 </cell>
21770 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21771 \begin_inset Text
21772
21773 \layout Standard
21774
21775 Where to get
21776 \end_inset
21777 </cell>
21778 </row>
21779 <row topline="true">
21780 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21781 \begin_inset Text
21782
21783 \layout Standard
21784
21785 gpsim
21786 \begin_inset LatexCommand \index{gpsim (pic simulator)}
21787
21788 \end_inset
21789
21790
21791 \end_inset
21792 </cell>
21793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21794 \begin_inset Text
21795
21796 \layout Standard
21797
21798 PIC simulator
21799 \end_inset
21800 </cell>
21801 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21802 \begin_inset Text
21803
21804 \layout Standard
21805
21806
21807 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
21808
21809 \end_inset
21810
21811
21812 \end_inset
21813 </cell>
21814 </row>
21815 <row topline="true">
21816 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21817 \begin_inset Text
21818
21819 \layout Standard
21820
21821 gputils
21822 \begin_inset LatexCommand \index{gputils (pic tools)}
21823
21824 \end_inset
21825
21826
21827 \end_inset
21828 </cell>
21829 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21830 \begin_inset Text
21831
21832 \layout Standard
21833
21834 GNU PIC utilities
21835 \end_inset
21836 </cell>
21837 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21838 \begin_inset Text
21839
21840 \layout Standard
21841
21842
21843 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
21844
21845 \end_inset
21846
21847
21848 \end_inset
21849 </cell>
21850 </row>
21851 <row topline="true">
21852 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21853 \begin_inset Text
21854
21855 \layout Standard
21856
21857 flP5
21858 \end_inset
21859 </cell>
21860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21861 \begin_inset Text
21862
21863 \layout Standard
21864
21865 PIC programmer
21866 \end_inset
21867 </cell>
21868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21869 \begin_inset Text
21870
21871 \layout Standard
21872
21873
21874 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
21875
21876 \end_inset
21877
21878
21879 \end_inset
21880 </cell>
21881 </row>
21882 <row topline="true">
21883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21884 \begin_inset Text
21885
21886 \layout Standard
21887
21888 indent
21889 \begin_inset LatexCommand \index{indent (source formatting tool)}
21890
21891 \end_inset
21892
21893
21894 \end_inset
21895 </cell>
21896 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21897 \begin_inset Text
21898
21899 \layout Standard
21900
21901 Formats C source - Master of the white spaces
21902 \end_inset
21903 </cell>
21904 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21905 \begin_inset Text
21906
21907 \layout Standard
21908
21909
21910 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
21911
21912 \end_inset
21913
21914
21915 \end_inset
21916 </cell>
21917 </row>
21918 <row topline="true">
21919 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21920 \begin_inset Text
21921
21922 \layout Standard
21923
21924 srecord
21925 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
21926
21927 \end_inset
21928
21929
21930 \end_inset
21931 </cell>
21932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21933 \begin_inset Text
21934
21935 \layout Standard
21936
21937 Object file conversion, checksumming, ...
21938 \end_inset
21939 </cell>
21940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21941 \begin_inset Text
21942
21943 \layout Standard
21944
21945
21946 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
21947
21948 \end_inset
21949
21950
21951 \end_inset
21952 </cell>
21953 </row>
21954 <row topline="true">
21955 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21956 \begin_inset Text
21957
21958 \layout Standard
21959
21960 objdump
21961 \begin_inset LatexCommand \index{objdump (tool)}
21962
21963 \end_inset
21964
21965
21966 \end_inset
21967 </cell>
21968 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21969 \begin_inset Text
21970
21971 \layout Standard
21972
21973 Object file conversion, ...
21974 \end_inset
21975 </cell>
21976 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21977 \begin_inset Text
21978
21979 \layout Standard
21980
21981 Part of binutils (should be there anyway)
21982 \end_inset
21983 </cell>
21984 </row>
21985 <row topline="true">
21986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21987 \begin_inset Text
21988
21989 \layout Standard
21990
21991 doxygen
21992 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
21993
21994 \end_inset
21995
21996
21997 \end_inset
21998 </cell>
21999 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22000 \begin_inset Text
22001
22002 \layout Standard
22003
22004 Source code documentation system
22005 \end_inset
22006 </cell>
22007 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22008 \begin_inset Text
22009
22010 \layout Standard
22011
22012
22013 \begin_inset LatexCommand \url{http://www.doxygen.org}
22014
22015 \end_inset
22016
22017
22018 \end_inset
22019 </cell>
22020 </row>
22021 <row topline="true">
22022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22023 \begin_inset Text
22024
22025 \layout Standard
22026
22027 kdevelop
22028 \end_inset
22029 </cell>
22030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22031 \begin_inset Text
22032
22033 \layout Standard
22034
22035 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
22036 \end_inset
22037 </cell>
22038 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22039 \begin_inset Text
22040
22041 \layout Standard
22042
22043
22044 \begin_inset LatexCommand \url{http://www.kdevelop.org}
22045
22046 \end_inset
22047
22048
22049 \end_inset
22050 </cell>
22051 </row>
22052 <row topline="true">
22053 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22054 \begin_inset Text
22055
22056 \layout Standard
22057
22058 splint
22059 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22060
22061 \end_inset
22062
22063
22064 \end_inset
22065 </cell>
22066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22067 \begin_inset Text
22068
22069 \layout Standard
22070
22071 Statically checks c sources (see
22072 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22073
22074 \end_inset
22075
22076 )
22077 \end_inset
22078 </cell>
22079 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22080 \begin_inset Text
22081
22082 \layout Standard
22083
22084
22085 \begin_inset LatexCommand \url{http://www.splint.org}
22086
22087 \end_inset
22088
22089
22090 \end_inset
22091 </cell>
22092 </row>
22093 <row topline="true" bottomline="true">
22094 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22095 \begin_inset Text
22096
22097 \layout Standard
22098
22099 ddd
22100 \begin_inset LatexCommand \index{ddd (debugger)}
22101
22102 \end_inset
22103
22104
22105 \end_inset
22106 </cell>
22107 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22108 \begin_inset Text
22109
22110 \layout Standard
22111
22112 Debugger, serves nicely as GUI to sdcdb
22113 \begin_inset LatexCommand \index{sdcdb (debugger)}
22114
22115 \end_inset
22116
22117  (Unix only)
22118 \end_inset
22119 </cell>
22120 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22121 \begin_inset Text
22122
22123 \layout Standard
22124
22125
22126 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
22127
22128 \end_inset
22129
22130
22131 \end_inset
22132 </cell>
22133 </row>
22134 </lyxtabular>
22135
22136 \end_inset
22137
22138
22139 \newline
22140
22141 \layout Section
22142
22143 Related documentation / recommended reading
22144 \layout Standard
22145 \align center
22146
22147 \begin_inset  Tabular
22148 <lyxtabular version="3" rows="6" columns="3">
22149 <features>
22150 <column alignment="center" valignment="top" leftline="true" width="0pt">
22151 <column alignment="block" valignment="top" leftline="true" width="30line%">
22152 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
22153 <row topline="true" bottomline="true">
22154 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22155 \begin_inset Text
22156
22157 \layout Standard
22158
22159 Name
22160 \end_inset
22161 </cell>
22162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22163 \begin_inset Text
22164
22165 \layout Standard
22166
22167 Subject / Title
22168 \end_inset
22169 </cell>
22170 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22171 \begin_inset Text
22172
22173 \layout Standard
22174
22175 Where to get
22176 \end_inset
22177 </cell>
22178 </row>
22179 <row topline="true">
22180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22181 \begin_inset Text
22182
22183 \layout Standard
22184
22185
22186 \family roman
22187 \series medium
22188 \shape up
22189 \size normal
22190 \emph off
22191 \bar no
22192 \noun off
22193 \color none
22194 c-refcard.pdf
22195 \end_inset
22196 </cell>
22197 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22198 \begin_inset Text
22199
22200 \layout Standard
22201
22202 C Reference Card
22203 \begin_inset LatexCommand \index{C Reference card}
22204
22205 \end_inset
22206
22207 , 2 pages
22208 \end_inset
22209 </cell>
22210 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22211 \begin_inset Text
22212
22213 \layout Standard
22214
22215
22216 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
22217
22218 \end_inset
22219
22220
22221 \end_inset
22222 </cell>
22223 </row>
22224 <row topline="true">
22225 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22226 \begin_inset Text
22227
22228 \layout Standard
22229
22230 c-faq
22231 \end_inset
22232 </cell>
22233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22234 \begin_inset Text
22235
22236 \layout Standard
22237
22238 C-FAQ-list
22239 \end_inset
22240 </cell>
22241 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22242 \begin_inset Text
22243
22244 \layout Standard
22245
22246
22247 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
22248
22249 \end_inset
22250
22251
22252 \end_inset
22253 </cell>
22254 </row>
22255 <row topline="true">
22256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22257 \begin_inset Text
22258
22259 \layout Standard
22260
22261 \end_inset
22262 </cell>
22263 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22264 \begin_inset Text
22265
22266 \layout Standard
22267
22268 Latest datasheet of the target CPU
22269 \end_inset
22270 </cell>
22271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22272 \begin_inset Text
22273
22274 \layout Standard
22275
22276 vendor
22277 \end_inset
22278 </cell>
22279 </row>
22280 <row topline="true">
22281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22282 \begin_inset Text
22283
22284 \layout Standard
22285
22286 \end_inset
22287 </cell>
22288 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22289 \begin_inset Text
22290
22291 \layout Standard
22292
22293 Revision history of datasheet
22294 \end_inset
22295 </cell>
22296 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22297 \begin_inset Text
22298
22299 \layout Standard
22300
22301 vendor
22302 \end_inset
22303 </cell>
22304 </row>
22305 <row topline="true" bottomline="true">
22306 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22307 \begin_inset Text
22308
22309 \layout Standard
22310
22311 S.
22312  S.
22313  Muchnick
22314 \end_inset
22315 </cell>
22316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22317 \begin_inset Text
22318
22319 \layout Standard
22320
22321 Advanced Compiler Design and Implementation
22322 \end_inset
22323 </cell>
22324 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22325 \begin_inset Text
22326
22327 \layout Standard
22328
22329 bookstore (very dedicated, probably read other books first)
22330 \end_inset
22331 </cell>
22332 </row>
22333 </lyxtabular>
22334
22335 \end_inset
22336
22337
22338 \newline
22339
22340 \layout Section
22341
22342 Some Questions
22343 \layout Standard
22344
22345 Some questions answered, some pointers given - it might be time to in turn
22346  ask
22347 \emph on
22348 you
22349 \emph default
22350  some questions:
22351 \layout Itemize
22352
22353 can you solve your project with the selected microcontroller? Would you
22354  find out early or rather late that your target is too small/slow/whatever?
22355  Can you switch to a slightly better device if it doesn't fit?
22356 \layout Itemize
22357
22358 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
22359  and/or another programming language be more adequate? Would an operating
22360  system on the target device help?
22361 \layout Itemize
22362
22363 if you solved the problem, will the marketing department be happy?
22364 \layout Itemize
22365
22366 if the marketing department is happy, will customers be happy?
22367 \layout Itemize
22368
22369 if you're the project manager, marketing department and maybe even the customer
22370  in one person, have you tried to see the project from the outside?
22371 \layout Itemize
22372
22373 is the project done if you think it is done? Or is just that other interface/pro
22374 tocol/feature/configuration/option missing? How about website, manual(s),
22375  internationali(z|s)ation, packaging, labels, 2nd source for components,
22376  electromagnetic compatability/interference, documentation for production,
22377  production test software, update mechanism, patent issues?
22378 \layout Itemize
22379
22380 is your project adequately positioned in that magic triangle: fame, fortune,
22381  fun?
22382 \layout Standard
22383
22384 Maybe not all answers to these questions are known and some answers may
22385  even be
22386 \emph on
22387 no
22388 \emph default
22389 , nevertheless knowing these questions may help you to avoid burnout
22390 \begin_inset Foot
22391 collapsed false
22392
22393 \layout Standard
22394
22395 burnout is bad for electronic devices, programmers and motorcycle tyres
22396 \end_inset
22397
22398 .
22399  Chances are you didn't want to hear some of them...
22400 \layout Chapter
22401
22402 Support
22403 \begin_inset LatexCommand \index{Support}
22404
22405 \end_inset
22406
22407
22408 \layout Standard
22409
22410 SDCC has grown to be a large project.
22411  The compiler alone (without the preprocessor, assembler and linker) is
22412  well over 100,000 lines of code (blank stripped).
22413  The open source nature of this project is a key to its continued growth
22414  and support.
22415  You gain the benefit and support of many active software developers and
22416  end users.
22417  Is SDCC perfect? No, that's why we need your help.
22418  The developers take pride in fixing reported bugs.
22419  You can help by reporting the bugs and helping other SDCC users.
22420  There are lots of ways to contribute, and we encourage you to take part
22421  in making SDCC a great software package.
22422
22423 \layout Standard
22424
22425 The SDCC project is hosted on the SDCC sourceforge site at
22426 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
22427
22428 \end_inset
22429
22430 .
22431  You'll find the complete set of mailing lists
22432 \begin_inset LatexCommand \index{Mailing list(s)}
22433
22434 \end_inset
22435
22436 , forums, bug reporting system, patch submission
22437 \begin_inset LatexCommand \index{Patch submission}
22438
22439 \end_inset
22440
22441  system, download
22442 \begin_inset LatexCommand \index{download}
22443
22444 \end_inset
22445
22446  area and cvs code repository
22447 \begin_inset LatexCommand \index{cvs code repository}
22448
22449 \end_inset
22450
22451  there.
22452 \layout Section
22453
22454 Reporting Bugs
22455 \begin_inset LatexCommand \index{Bug reporting}
22456
22457 \end_inset
22458
22459
22460 \begin_inset LatexCommand \index{Reporting bugs}
22461
22462 \end_inset
22463
22464
22465 \layout Standard
22466
22467 The recommended way of reporting bugs is using the infrastructure of the
22468  sourceforge site.
22469  You can follow the status of bug reports there and have an overview about
22470  the known bugs.
22471 \layout Standard
22472
22473 Bug reports are automatically forwarded to the developer mailing list and
22474  will be fixed ASAP.
22475  When reporting a bug, it is very useful to include a small test program
22476  (the smaller the better) which reproduces the problem.
22477  If you can isolate the problem by looking at the generated assembly code,
22478  this can be very helpful.
22479  Compiling your program with the -
22480 \begin_inset ERT
22481 status Collapsed
22482
22483 \layout Standard
22484
22485 \backslash
22486 /
22487 \end_inset
22488
22489 -dumpall
22490 \begin_inset LatexCommand \index{-\/-dumpall}
22491
22492 \end_inset
22493
22494  option can sometimes be useful in locating optimization problems.
22495  When reporting a bug please maker sure you:
22496 \layout Enumerate
22497
22498 Attach the code you are compiling with SDCC.
22499
22500 \layout Enumerate
22501
22502 Specify the exact command you use to run SDCC, or attach your Makefile.
22503
22504 \layout Enumerate
22505
22506 Specify the SDCC version (type "
22507 \family sans
22508 \series bold
22509 sdcc -v
22510 \family default
22511 \series default
22512 "), your platform, and operating system.
22513
22514 \layout Enumerate
22515
22516 Provide an exact copy of any error message or incorrect output.
22517
22518 \layout Enumerate
22519
22520 Put something meaningful in the subject of your message.
22521 \layout Standard
22522
22523 Please attempt to include these 5 important parts, as applicable, in all
22524  requests for support or when reporting any problems or bugs with SDCC.
22525  Though this will make your message lengthy, it will greatly improve your
22526  chance that SDCC users and developers will be able to help you.
22527  Some SDCC developers are frustrated by bug reports without code provided
22528  that they can use to reproduce and ultimately fix the problem, so please
22529  be sure to provide sample code if you are reporting a bug!
22530 \layout Standard
22531
22532 Please have a short check that you are using a recent version of SDCC and
22533  the bug is not yet known.
22534  This is the link for reporting bugs:
22535 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
22536
22537 \end_inset
22538
22539 .
22540 \layout Section
22541
22542 Requesting Features
22543 \begin_inset LatexCommand \label{sub:Requesting-Features}
22544
22545 \end_inset
22546
22547
22548 \begin_inset LatexCommand \index{Feature request}
22549
22550 \end_inset
22551
22552
22553 \begin_inset LatexCommand \index{Requesting features}
22554
22555 \end_inset
22556
22557
22558 \layout Standard
22559
22560 Like bug reports feature requests are forwarded to the developer mailing
22561  list.
22562  This is the link for requesting features:
22563 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
22564
22565 \end_inset
22566
22567 .
22568 \layout Section
22569
22570 Submitting patches
22571 \layout Standard
22572
22573 Like bug reports contributed patches are forwarded to the developer mailing
22574  list.
22575  This is the link for submitting patches
22576 \begin_inset LatexCommand \index{Patch submission}
22577
22578 \end_inset
22579
22580 :
22581 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
22582
22583 \end_inset
22584
22585 .
22586 \layout Standard
22587
22588 You need to specify some parameters to the
22589 \family typewriter
22590 diff
22591 \family default
22592  command for the patches to be useful.
22593  If you modified more than one file a patch created f.e.
22594  with
22595 \family sans
22596 \series bold
22597
22598 \begin_inset Quotes sld
22599 \end_inset
22600
22601 diff -Naur unmodified_directory modified_directory >my_changes.patch
22602 \begin_inset Quotes srd
22603 \end_inset
22604
22605
22606 \family default
22607 \series default
22608  will be fine, otherwise
22609 \family sans
22610 \series bold
22611
22612 \begin_inset Quotes sld
22613 \end_inset
22614
22615 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
22616 \begin_inset Quotes srd
22617 \end_inset
22618
22619
22620 \series default
22621
22622 \family default
22623 will do.
22624 \layout Section
22625
22626 Getting Help
22627 \layout Standard
22628
22629 These links should take you directly to the
22630 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
22631
22632 \end_inset
22633
22634
22635 \begin_inset Foot
22636 collapsed false
22637
22638 \layout Standard
22639
22640 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
22641  automated messages (mid 2003)
22642 \end_inset
22643
22644  and the
22645 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
22646
22647 \end_inset
22648
22649 , lists
22650 \begin_inset LatexCommand \index{Mailing list(s)}
22651
22652 \end_inset
22653
22654  and forums are archived and searchable so if you are lucky someone already
22655  had a similar problem.
22656  While mails to the lists themselves are delivered promptly their web front
22657  end on sourceforge sometimes shows a severe time lag (up to several weeks),
22658  if you're seriously using SDCC please consider subscribing to the lists.
22659 \layout Section
22660
22661 ChangeLog
22662 \layout Standard
22663
22664 You can follow the status of the cvs version
22665 \begin_inset LatexCommand \index{version}
22666
22667 \end_inset
22668
22669  of SDCC by watching the Changelog
22670 \begin_inset LatexCommand \index{Changelog}
22671
22672 \end_inset
22673
22674  in the cvs-repository
22675 \newline
22676
22677 \size footnotesize
22678
22679 \begin_inset LatexCommand \htmlurl{http://cvs.sf.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
22680
22681 \end_inset
22682
22683 .
22684 \layout Section
22685
22686 Release policy
22687 \begin_inset LatexCommand \index{Release policy}
22688
22689 \end_inset
22690
22691
22692 \layout Standard
22693
22694 Historically there often were long delays between official releases and
22695  the sourceforge download area tends to get not updated at all.
22696  Excuses in the past might have referred to problems with live range analysis,
22697  but as this was fixed a while ago, the current problem is that another
22698  excuse has to be found.
22699  Kidding aside, we have to get better there! On the other hand there are
22700  daily snapshots available at
22701 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
22702
22703 \end_inset
22704
22705 , and you can always build the very last version (hopefully with many bugs
22706  fixed, and features added) from the source code available at
22707 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
22708
22709 \end_inset
22710
22711 .
22712 \layout Section
22713
22714 Examples
22715 \begin_inset LatexCommand \index{Examples}
22716
22717 \end_inset
22718
22719
22720 \layout Standard
22721
22722 You'll find some small examples in the directory
22723 \emph on
22724 sdcc/device/examples/.
22725
22726 \emph default
22727 More examples and libraries are available at
22728 \emph on
22729  The SDCC Open Knowledge Resource
22730 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
22731
22732 \end_inset
22733
22734
22735 \emph default
22736 web site or at
22737 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
22738
22739 \end_inset
22740
22741 .
22742 \layout Comment
22743
22744 I did insert a reference to Paul's web site here although it seems rather
22745  dedicated to a specific 8032 board (I think it's okay because it f.e.
22746  shows LCD/Harddisc interface and has a free 8051 monitor.
22747  Independent 8032 board vendors face hard competition of heavily subsidized
22748  development boards anyway).
22749 \layout Comment
22750
22751 Maybe we should include some links to real world applications.
22752  Preferably pointer to pointers (one for each architecture) so this stays
22753  manageable here?
22754 \layout Section
22755
22756 Quality control
22757 \begin_inset LatexCommand \index{Quality control}
22758
22759 \end_inset
22760
22761
22762 \layout Standard
22763
22764 The compiler is passed through nightly compile and build checks.
22765  The so called
22766 \shape italic
22767 regression tests
22768 \shape default
22769
22770 \begin_inset LatexCommand \index{Regression test}
22771
22772 \end_inset
22773
22774  check that SDCC itself compiles flawlessly on several platforms and checks
22775  the quality of the code generated by SDCC by running the code through simulator
22776 s.
22777  There is a separate document
22778 \shape italic
22779 test_suite.pdf
22780 \begin_inset LatexCommand \index{Test suite}
22781
22782 \end_inset
22783
22784
22785 \shape default
22786  about this.
22787 \layout Standard
22788
22789 You'll find the test code in the directory
22790 \shape italic
22791 sdcc/support/regression
22792 \shape default
22793 .
22794  You can run these tests manually by running
22795 \family sans
22796 make
22797 \family default
22798  in this directory (or f.e.
22799
22800 \family sans
22801 \series bold
22802
22803 \begin_inset Quotes sld
22804 \end_inset
22805
22806 make test-mcs51
22807 \begin_inset Quotes srd
22808 \end_inset
22809
22810
22811 \family default
22812 \series default
22813  if you don't want to run the complete tests).
22814  The test code might also be interesting if you want to look for examples
22815 \begin_inset LatexCommand \index{Examples}
22816
22817 \end_inset
22818
22819  checking corner cases of SDCC or if you plan to submit patches
22820 \begin_inset LatexCommand \index{Patch submission}
22821
22822 \end_inset
22823
22824 .
22825 \layout Standard
22826
22827 The pic port uses a different set of regression tests, you'll find them
22828  in the directory
22829 \shape italic
22830 sdcc/src/regression
22831 \shape default
22832 .
22833 \layout Chapter
22834 \pagebreak_top
22835 SDCC Technical Data
22836 \layout Section
22837
22838 Optimizations
22839 \begin_inset LatexCommand \index{Optimizations}
22840
22841 \end_inset
22842
22843
22844 \layout Standard
22845
22846 SDCC performs a host of standard optimizations in addition to some MCU specific
22847  optimizations.
22848
22849 \layout Subsection
22850
22851 Sub-expression Elimination
22852 \begin_inset LatexCommand \index{Subexpression elimination}
22853
22854 \end_inset
22855
22856
22857 \layout Standard
22858
22859 The compiler does local and
22860 \emph on
22861 g
22862 \emph default
22863 lobal
22864 \emph on
22865 c
22866 \emph default
22867 ommon
22868 \emph on
22869 s
22870 \emph default
22871 ubexpression
22872 \emph on
22873 e
22874 \emph default
22875 limination, e.g.:
22876 \layout Verse
22877
22878
22879 \family typewriter
22880 i = x + y + 1;
22881 \newline
22882 j = x + y;
22883 \layout Standard
22884
22885 will be translated to
22886 \layout Verse
22887
22888
22889 \family typewriter
22890 iTemp = x + y;
22891 \newline
22892 i = iTemp + 1;
22893 \newline
22894 j = iTemp;
22895 \layout Standard
22896
22897 Some subexpressions are not as obvious as the above example, e.g.:
22898 \layout Verse
22899
22900
22901 \family typewriter
22902 a->b[i].c = 10;
22903 \newline
22904 a->b[i].d = 11;
22905 \layout Standard
22906
22907 In this case the address arithmetic a->b[i] will be computed only once;
22908  the equivalent code in C would be.
22909 \layout Verse
22910
22911
22912 \family typewriter
22913 iTemp = a->b[i];
22914 \newline
22915 iTemp.c = 10;
22916 \newline
22917 iTemp.d = 11;
22918 \layout Standard
22919
22920 The compiler will try to keep these temporary variables in registers.
22921 \layout Subsection
22922
22923 Dead-Code Elimination
22924 \begin_inset LatexCommand \index{Dead-code elimination}
22925
22926 \end_inset
22927
22928
22929 \layout Verse
22930
22931
22932 \family typewriter
22933 int global;
22934 \newline
22935
22936 \newline
22937 void f () {
22938 \newline
22939 \SpecialChar ~
22940 \SpecialChar ~
22941 int i;
22942 \newline
22943 \SpecialChar ~
22944 \SpecialChar ~
22945 i = 1; \SpecialChar ~
22946 \SpecialChar ~
22947 \SpecialChar ~
22948 \SpecialChar ~
22949 \SpecialChar ~
22950 /* dead store */
22951 \newline
22952 \SpecialChar ~
22953 \SpecialChar ~
22954 global = 1;\SpecialChar ~
22955 /* dead store */
22956 \newline
22957 \SpecialChar ~
22958 \SpecialChar ~
22959 global = 2;
22960 \newline
22961 \SpecialChar ~
22962 \SpecialChar ~
22963 return;
22964 \newline
22965 \SpecialChar ~
22966 \SpecialChar ~
22967 global = 3;\SpecialChar ~
22968 /* unreachable */
22969 \newline
22970 }
22971 \layout Standard
22972
22973 will be changed to
22974 \layout Verse
22975
22976
22977 \family typewriter
22978 int global;
22979 \newline
22980
22981 \newline
22982 void f () {
22983 \newline
22984 \SpecialChar ~
22985 \SpecialChar ~
22986 global = 2;
22987 \newline
22988 }
22989 \layout Subsection
22990
22991 Copy-Propagation
22992 \begin_inset LatexCommand \index{Copy propagation}
22993
22994 \end_inset
22995
22996
22997 \layout Verse
22998
22999
23000 \family typewriter
23001 int f() {
23002 \newline
23003 \SpecialChar ~
23004 \SpecialChar ~
23005 int i, j;
23006 \newline
23007 \SpecialChar ~
23008 \SpecialChar ~
23009 i = 10;
23010 \newline
23011 \SpecialChar ~
23012 \SpecialChar ~
23013 j = i;
23014 \newline
23015 \SpecialChar ~
23016 \SpecialChar ~
23017 return j;
23018 \newline
23019 }
23020 \layout Standard
23021
23022 will be changed to
23023 \layout Verse
23024
23025
23026 \family typewriter
23027 int f() {
23028 \newline
23029 \SpecialChar ~
23030 \SpecialChar ~
23031 int i, j;
23032 \newline
23033 \SpecialChar ~
23034 \SpecialChar ~
23035 i = 10;
23036 \newline
23037 \SpecialChar ~
23038 \SpecialChar ~
23039 j = 10;
23040 \newline
23041 \SpecialChar ~
23042 \SpecialChar ~
23043 return 10;
23044 \newline
23045 }
23046 \layout Standard
23047
23048 Note: the dead stores created by this copy propagation will be eliminated
23049  by dead-code elimination.
23050 \layout Subsection
23051
23052 Loop Optimizations
23053 \begin_inset LatexCommand \index{Loop optimization}
23054
23055 \end_inset
23056
23057
23058 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
23059
23060 \end_inset
23061
23062
23063 \layout Standard
23064
23065 Two types of loop optimizations are done by SDCC
23066 \emph on
23067 loop invariant
23068 \emph default
23069  lifting and
23070 \emph on
23071  strength reduction
23072 \emph default
23073  of loop induction variables.
23074  In addition to the strength reduction the optimizer marks the induction
23075  variables and the register allocator tries to keep the induction variables
23076  in registers for the duration of the loop.
23077  Because of this preference of the register allocator
23078 \begin_inset LatexCommand \index{Register allocation}
23079
23080 \end_inset
23081
23082 , loop induction optimization causes an increase in register pressure, which
23083  may cause unwanted spilling of other temporary variables into the stack
23084 \begin_inset LatexCommand \index{stack}
23085
23086 \end_inset
23087
23088  / data space.
23089  The compiler will generate a warning message when it is forced to allocate
23090  extra space either on the stack or data space.
23091  If this extra space allocation is undesirable then induction optimization
23092  can be eliminated either for the entire source file (with -
23093 \begin_inset ERT
23094 status Collapsed
23095
23096 \layout Standard
23097
23098 \backslash
23099 /
23100 \end_inset
23101
23102 -noinduction option) or for a given function only using #pragma\SpecialChar ~
23103 noinduction
23104 \begin_inset LatexCommand \index{\#pragma noinduction}
23105
23106 \end_inset
23107
23108 .
23109 \newline
23110
23111 \newline
23112 Loop Invariant:
23113 \layout Verse
23114
23115
23116 \family typewriter
23117 for (i = 0 ; i < 100 ; i ++)
23118 \newline
23119 \SpecialChar ~
23120 \SpecialChar ~
23121 \SpecialChar ~
23122 \SpecialChar ~
23123 f += k + l;
23124 \layout Standard
23125
23126 changed to
23127 \layout Verse
23128
23129
23130 \family typewriter
23131 itemp = k + l;
23132 \newline
23133 for (i = 0; i < 100; i++)
23134 \newline
23135 \SpecialChar ~
23136 \SpecialChar ~
23137 \SpecialChar ~
23138 \SpecialChar ~
23139 f += itemp;
23140 \layout Standard
23141
23142 As mentioned previously some loop invariants are not as apparent, all static
23143  address computations are also moved out of the loop.
23144 \newline
23145
23146 \newline
23147 Strength Reduction
23148 \begin_inset LatexCommand \index{Strength reduction}
23149
23150 \end_inset
23151
23152 , this optimization substitutes an expression by a cheaper expression:
23153 \layout Verse
23154
23155
23156 \family typewriter
23157 for (i=0;i < 100; i++)
23158 \newline
23159 \SpecialChar ~
23160 \SpecialChar ~
23161 \SpecialChar ~
23162 \SpecialChar ~
23163 ar[i*5] = i*3;
23164 \layout Standard
23165
23166 changed to
23167 \layout Verse
23168
23169
23170 \family typewriter
23171 itemp1 = 0;
23172 \newline
23173 itemp2 = 0;
23174 \newline
23175 for (i=0;i< 100;i++) {
23176 \newline
23177 \SpecialChar ~
23178 \SpecialChar ~
23179 \SpecialChar ~
23180 \SpecialChar ~
23181 ar[itemp1] = itemp2;
23182 \newline
23183 \SpecialChar ~
23184 \SpecialChar ~
23185 \SpecialChar ~
23186 \SpecialChar ~
23187 itemp1 += 5;
23188 \newline
23189 \SpecialChar ~
23190 \SpecialChar ~
23191 \SpecialChar ~
23192 \SpecialChar ~
23193 itemp2 += 3;
23194 \newline
23195 }
23196 \layout Standard
23197
23198 The more expensive multiplication
23199 \begin_inset LatexCommand \index{Multiplication}
23200
23201 \end_inset
23202
23203  is changed to a less expensive addition.
23204 \layout Subsection
23205
23206 Loop Reversing
23207 \begin_inset LatexCommand \index{Loop reversing}
23208
23209 \end_inset
23210
23211
23212 \layout Standard
23213
23214 This optimization is done to reduce the overhead of checking loop boundaries
23215  for every iteration.
23216  Some simple loops can be reversed and implemented using a
23217 \begin_inset Quotes eld
23218 \end_inset
23219
23220 decrement and jump if not zero
23221 \begin_inset Quotes erd
23222 \end_inset
23223
23224  instruction.
23225  SDCC checks for the following criterion to determine if a loop is reversible
23226  (note: more sophisticated compilers use data-dependency analysis to make
23227  this determination, SDCC uses a more simple minded analysis).
23228 \layout Itemize
23229
23230 The 'for' loop is of the form
23231 \newline
23232
23233 \newline
23234
23235 \family typewriter
23236 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
23237  += 1])
23238 \newline
23239 \SpecialChar ~
23240 \SpecialChar ~
23241 \SpecialChar ~
23242 \SpecialChar ~
23243 <for body>
23244 \layout Itemize
23245
23246 The <for body> does not contain
23247 \begin_inset Quotes eld
23248 \end_inset
23249
23250 continue
23251 \begin_inset Quotes erd
23252 \end_inset
23253
23254  or 'break
23255 \begin_inset Quotes erd
23256 \end_inset
23257
23258 .
23259 \layout Itemize
23260
23261 All goto's are contained within the loop.
23262 \layout Itemize
23263
23264 No function calls within the loop.
23265 \layout Itemize
23266
23267 The loop control variable <sym> is not assigned any value within the loop
23268 \layout Itemize
23269
23270 The loop control variable does NOT participate in any arithmetic operation
23271  within the loop.
23272 \layout Itemize
23273
23274 There are NO switch statements in the loop.
23275 \layout Subsection
23276
23277 Algebraic Simplifications
23278 \layout Standard
23279
23280 SDCC does numerous algebraic simplifications, the following is a small sub-set
23281  of these optimizations.
23282 \layout Verse
23283
23284
23285 \family typewriter
23286 i = j + 0;\SpecialChar ~
23287 \SpecialChar ~
23288 \SpecialChar ~
23289 \SpecialChar ~
23290  /* changed to: */\SpecialChar ~
23291 \SpecialChar ~
23292 \SpecialChar ~
23293 \SpecialChar ~
23294  i = j;
23295 \newline
23296 i /= 2;\SpecialChar ~
23297 \SpecialChar ~
23298 \SpecialChar ~
23299 \SpecialChar ~
23300 \SpecialChar ~
23301 \SpecialChar ~
23302 \SpecialChar ~
23303  /* changed to: */\SpecialChar ~
23304 \SpecialChar ~
23305 \SpecialChar ~
23306 \SpecialChar ~
23307  i >>= 1;
23308 \newline
23309 i = j - j;\SpecialChar ~
23310 \SpecialChar ~
23311 \SpecialChar ~
23312 \SpecialChar ~
23313  /* changed to: */\SpecialChar ~
23314 \SpecialChar ~
23315 \SpecialChar ~
23316 \SpecialChar ~
23317  i = 0;
23318 \newline
23319 i = j / 1;\SpecialChar ~
23320 \SpecialChar ~
23321 \SpecialChar ~
23322 \SpecialChar ~
23323  /* changed to: */\SpecialChar ~
23324 \SpecialChar ~
23325 \SpecialChar ~
23326 \SpecialChar ~
23327  i = j;
23328 \layout Standard
23329
23330 Note the subexpressions
23331 \begin_inset LatexCommand \index{Subexpression}
23332
23333 \end_inset
23334
23335  given above are generally introduced by macro expansions or as a result
23336  of copy/constant propagation.
23337 \layout Subsection
23338
23339 'switch' Statements
23340 \begin_inset LatexCommand \label{sub:'switch'-Statements}
23341
23342 \end_inset
23343
23344
23345 \begin_inset LatexCommand \index{switch statement}
23346
23347 \end_inset
23348
23349
23350 \layout Standard
23351
23352 SDCC can optimize switch statements to jump tables
23353 \begin_inset LatexCommand \index{jump tables}
23354
23355 \end_inset
23356
23357 .
23358  It makes the decision based on an estimate of the generated code size.
23359  SDCC is quite liberal in the requirements for jump table generation:
23360 \layout Itemize
23361
23362 The labels need not be in order, and the starting number need not be one
23363  or zero, the case labels are in numerical sequence or not too many case
23364  labels are missing.
23365 \begin_deeper
23366 \layout Verse
23367
23368
23369 \family typewriter
23370 switch(i) {\SpecialChar ~
23371 \SpecialChar ~
23372 \SpecialChar ~
23373 \SpecialChar ~
23374 \SpecialChar ~
23375 \SpecialChar ~
23376 \SpecialChar ~
23377 \SpecialChar ~
23378 \SpecialChar ~
23379 \SpecialChar ~
23380 \SpecialChar ~
23381 \SpecialChar ~
23382 \SpecialChar ~
23383 \SpecialChar ~
23384 \SpecialChar ~
23385 \SpecialChar ~
23386 \SpecialChar ~
23387 \SpecialChar ~
23388 \SpecialChar ~
23389 \SpecialChar ~
23390 \SpecialChar ~
23391 \SpecialChar ~
23392 \SpecialChar ~
23393 \SpecialChar ~
23394 \SpecialChar ~
23395 \SpecialChar ~
23396 switch (i) {
23397 \newline
23398 \SpecialChar ~
23399 \SpecialChar ~
23400 \SpecialChar ~
23401 case 4: ...\SpecialChar ~
23402 \SpecialChar ~
23403 \SpecialChar ~
23404 \SpecialChar ~
23405 \SpecialChar ~
23406 \SpecialChar ~
23407 \SpecialChar ~
23408 \SpecialChar ~
23409 \SpecialChar ~
23410 \SpecialChar ~
23411 \SpecialChar ~
23412 \SpecialChar ~
23413 \SpecialChar ~
23414 \SpecialChar ~
23415 \SpecialChar ~
23416 \SpecialChar ~
23417 \SpecialChar ~
23418 \SpecialChar ~
23419 \SpecialChar ~
23420 \SpecialChar ~
23421 \SpecialChar ~
23422 \SpecialChar ~
23423 \SpecialChar ~
23424 \SpecialChar ~
23425 \SpecialChar ~
23426 \SpecialChar ~
23427 case 0: ...
23428
23429 \newline
23430 \SpecialChar ~
23431 \SpecialChar ~
23432 \SpecialChar ~
23433 case 5: ...\SpecialChar ~
23434 \SpecialChar ~
23435 \SpecialChar ~
23436 \SpecialChar ~
23437 \SpecialChar ~
23438 \SpecialChar ~
23439 \SpecialChar ~
23440 \SpecialChar ~
23441 \SpecialChar ~
23442 \SpecialChar ~
23443 \SpecialChar ~
23444 \SpecialChar ~
23445 \SpecialChar ~
23446 \SpecialChar ~
23447 \SpecialChar ~
23448 \SpecialChar ~
23449 \SpecialChar ~
23450 \SpecialChar ~
23451 \SpecialChar ~
23452 \SpecialChar ~
23453 \SpecialChar ~
23454 \SpecialChar ~
23455 \SpecialChar ~
23456 \SpecialChar ~
23457 \SpecialChar ~
23458 \SpecialChar ~
23459 case 1: ...
23460
23461 \newline
23462 \SpecialChar ~
23463 \SpecialChar ~
23464 \SpecialChar ~
23465 case 3: ...\SpecialChar ~
23466 \SpecialChar ~
23467 \SpecialChar ~
23468 \SpecialChar ~
23469 \SpecialChar ~
23470 \SpecialChar ~
23471 \SpecialChar ~
23472 \SpecialChar ~
23473 \SpecialChar ~
23474 \SpecialChar ~
23475 \SpecialChar ~
23476 \SpecialChar ~
23477 \SpecialChar ~
23478 \SpecialChar ~
23479 \SpecialChar ~
23480 \SpecialChar ~
23481 \SpecialChar ~
23482 \SpecialChar ~
23483 \SpecialChar ~
23484 \SpecialChar ~
23485 \SpecialChar ~
23486 \SpecialChar ~
23487 \SpecialChar ~
23488 \SpecialChar ~
23489 \SpecialChar ~
23490 \SpecialChar ~
23491
23492 \newline
23493 \SpecialChar ~
23494 \SpecialChar ~
23495 \SpecialChar ~
23496 case 6: ...\SpecialChar ~
23497 \SpecialChar ~
23498 \SpecialChar ~
23499 \SpecialChar ~
23500 \SpecialChar ~
23501 \SpecialChar ~
23502 \SpecialChar ~
23503 \SpecialChar ~
23504 \SpecialChar ~
23505 \SpecialChar ~
23506 \SpecialChar ~
23507 \SpecialChar ~
23508 \SpecialChar ~
23509 \SpecialChar ~
23510 \SpecialChar ~
23511 \SpecialChar ~
23512 \SpecialChar ~
23513 \SpecialChar ~
23514 \SpecialChar ~
23515 \SpecialChar ~
23516 \SpecialChar ~
23517 \SpecialChar ~
23518 \SpecialChar ~
23519 \SpecialChar ~
23520 \SpecialChar ~
23521 \SpecialChar ~
23522 case 3: ...
23523
23524 \newline
23525 \SpecialChar ~
23526 \SpecialChar ~
23527 \SpecialChar ~
23528 case 7: ...\SpecialChar ~
23529 \SpecialChar ~
23530 \SpecialChar ~
23531 \SpecialChar ~
23532 \SpecialChar ~
23533 \SpecialChar ~
23534 \SpecialChar ~
23535 \SpecialChar ~
23536 \SpecialChar ~
23537 \SpecialChar ~
23538 \SpecialChar ~
23539 \SpecialChar ~
23540 \SpecialChar ~
23541 \SpecialChar ~
23542 \SpecialChar ~
23543 \SpecialChar ~
23544 \SpecialChar ~
23545 \SpecialChar ~
23546 \SpecialChar ~
23547 \SpecialChar ~
23548 \SpecialChar ~
23549 \SpecialChar ~
23550 \SpecialChar ~
23551 \SpecialChar ~
23552 \SpecialChar ~
23553 \SpecialChar ~
23554 case 4: ...
23555
23556 \newline
23557 \SpecialChar ~
23558 \SpecialChar ~
23559 \SpecialChar ~
23560 case 8: ...\SpecialChar ~
23561 \SpecialChar ~
23562 \SpecialChar ~
23563 \SpecialChar ~
23564 \SpecialChar ~
23565 \SpecialChar ~
23566 \SpecialChar ~
23567 \SpecialChar ~
23568 \SpecialChar ~
23569 \SpecialChar ~
23570 \SpecialChar ~
23571 \SpecialChar ~
23572 \SpecialChar ~
23573 \SpecialChar ~
23574 \SpecialChar ~
23575 \SpecialChar ~
23576 \SpecialChar ~
23577 \SpecialChar ~
23578 \SpecialChar ~
23579 \SpecialChar ~
23580 \SpecialChar ~
23581 \SpecialChar ~
23582 \SpecialChar ~
23583 \SpecialChar ~
23584 \SpecialChar ~
23585 \SpecialChar ~
23586 case 5: ...
23587
23588 \newline
23589 \SpecialChar ~
23590 \SpecialChar ~
23591 \SpecialChar ~
23592 case 9: ...\SpecialChar ~
23593 \SpecialChar ~
23594 \SpecialChar ~
23595 \SpecialChar ~
23596 \SpecialChar ~
23597 \SpecialChar ~
23598 \SpecialChar ~
23599 \SpecialChar ~
23600 \SpecialChar ~
23601 \SpecialChar ~
23602 \SpecialChar ~
23603 \SpecialChar ~
23604 \SpecialChar ~
23605 \SpecialChar ~
23606 \SpecialChar ~
23607 \SpecialChar ~
23608 \SpecialChar ~
23609 \SpecialChar ~
23610 \SpecialChar ~
23611 \SpecialChar ~
23612 \SpecialChar ~
23613 \SpecialChar ~
23614 \SpecialChar ~
23615 \SpecialChar ~
23616 \SpecialChar ~
23617 \SpecialChar ~
23618 case 6: ...
23619
23620 \newline
23621 \SpecialChar ~
23622 \SpecialChar ~
23623 \SpecialChar ~
23624 case 10: ...\SpecialChar ~
23625 \SpecialChar ~
23626 \SpecialChar ~
23627 \SpecialChar ~
23628 \SpecialChar ~
23629 \SpecialChar ~
23630 \SpecialChar ~
23631 \SpecialChar ~
23632 \SpecialChar ~
23633 \SpecialChar ~
23634 \SpecialChar ~
23635 \SpecialChar ~
23636 \SpecialChar ~
23637 \SpecialChar ~
23638 \SpecialChar ~
23639 \SpecialChar ~
23640 \SpecialChar ~
23641 \SpecialChar ~
23642 \SpecialChar ~
23643 \SpecialChar ~
23644 \SpecialChar ~
23645 \SpecialChar ~
23646 \SpecialChar ~
23647 \SpecialChar ~
23648 \SpecialChar ~
23649 case 7: ...
23650
23651 \newline
23652 \SpecialChar ~
23653 \SpecialChar ~
23654 \SpecialChar ~
23655 case 11: ...\SpecialChar ~
23656 \SpecialChar ~
23657 \SpecialChar ~
23658 \SpecialChar ~
23659 \SpecialChar ~
23660 \SpecialChar ~
23661 \SpecialChar ~
23662 \SpecialChar ~
23663 \SpecialChar ~
23664 \SpecialChar ~
23665 \SpecialChar ~
23666 \SpecialChar ~
23667 \SpecialChar ~
23668 \SpecialChar ~
23669 \SpecialChar ~
23670 \SpecialChar ~
23671 \SpecialChar ~
23672 \SpecialChar ~
23673 \SpecialChar ~
23674 \SpecialChar ~
23675 \SpecialChar ~
23676 \SpecialChar ~
23677 \SpecialChar ~
23678 \SpecialChar ~
23679 \SpecialChar ~
23680 case 8: ...
23681
23682 \newline
23683 }\SpecialChar ~
23684 \SpecialChar ~
23685 \SpecialChar ~
23686 \SpecialChar ~
23687 \SpecialChar ~
23688 \SpecialChar ~
23689 \SpecialChar ~
23690 \SpecialChar ~
23691 \SpecialChar ~
23692 \SpecialChar ~
23693 \SpecialChar ~
23694 \SpecialChar ~
23695 \SpecialChar ~
23696 \SpecialChar ~
23697 \SpecialChar ~
23698 \SpecialChar ~
23699 \SpecialChar ~
23700 \SpecialChar ~
23701 \SpecialChar ~
23702 \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 }
23720 \layout Standard
23721
23722 Both the above switch statements will be implemented using a jump-table.
23723  The example to the right side is slightly more efficient as the check for
23724  the lower boundary of the jump-table is not needed.
23725 \end_deeper
23726 \layout Itemize
23727
23728 The number of case labels is not larger than supported by the target architectur
23729 e.
23730 \layout Itemize
23731
23732 If the case labels are not in numerical sequence ('gaps' between cases)
23733  SDCC checks whether a jump table with additionally inserted dummy cases
23734  is still attractive.
23735
23736 \layout Itemize
23737
23738 If the starting number is not zero and a check for the lower boundary of
23739  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
23740  ...
23741  .
23742 \layout Standard
23743
23744 Switch statements which have large gaps in the numeric sequence or those
23745  that have too many case labels can be split into more than one switch statement
23746  for efficient code generation, e.g.:
23747 \layout Verse
23748
23749
23750 \family typewriter
23751 switch (i) {
23752 \newline
23753 \SpecialChar ~
23754 \SpecialChar ~
23755 case 1: ...
23756
23757 \newline
23758 \SpecialChar ~
23759 \SpecialChar ~
23760 case 2: ...
23761
23762 \newline
23763 \SpecialChar ~
23764 \SpecialChar ~
23765 case 3: ...
23766
23767 \newline
23768 \SpecialChar ~
23769 \SpecialChar ~
23770 case 4: ...
23771
23772 \newline
23773 \SpecialChar ~
23774 \SpecialChar ~
23775 case 5: ...
23776
23777 \newline
23778 \SpecialChar ~
23779 \SpecialChar ~
23780 case 6: ...
23781
23782 \newline
23783 \SpecialChar ~
23784 \SpecialChar ~
23785 case 7: ...
23786
23787 \newline
23788 \SpecialChar ~
23789 \SpecialChar ~
23790 case 101: ...
23791
23792 \newline
23793 \SpecialChar ~
23794 \SpecialChar ~
23795 case 102: ...
23796
23797 \newline
23798 \SpecialChar ~
23799 \SpecialChar ~
23800 case 103: ...
23801
23802 \newline
23803 \SpecialChar ~
23804 \SpecialChar ~
23805 case 104: ...
23806
23807 \newline
23808 \SpecialChar ~
23809 \SpecialChar ~
23810 case 105: ...
23811
23812 \newline
23813 \SpecialChar ~
23814 \SpecialChar ~
23815 case 106: ...
23816
23817 \newline
23818 \SpecialChar ~
23819 \SpecialChar ~
23820 case 107: ...
23821
23822 \newline
23823 }
23824 \layout Standard
23825
23826 If the above switch statement is broken down into two switch statements
23827 \layout Verse
23828
23829
23830 \family typewriter
23831 switch (i) {
23832 \newline
23833 \SpecialChar ~
23834 \SpecialChar ~
23835 case 1: ...
23836
23837 \newline
23838 \SpecialChar ~
23839 \SpecialChar ~
23840 case 2: ...
23841
23842 \newline
23843 \SpecialChar ~
23844 \SpecialChar ~
23845 case 3: ...
23846
23847 \newline
23848 \SpecialChar ~
23849 \SpecialChar ~
23850 case 4: ...
23851
23852 \newline
23853 \SpecialChar ~
23854 \SpecialChar ~
23855 case 5: ...
23856
23857 \newline
23858 \SpecialChar ~
23859 \SpecialChar ~
23860 case 6: ...
23861
23862 \newline
23863 \SpecialChar ~
23864 \SpecialChar ~
23865 case 7: ...
23866
23867 \newline
23868 }
23869 \layout Standard
23870
23871 and
23872 \layout Verse
23873
23874
23875 \family typewriter
23876 switch (i) {
23877 \newline
23878 \SpecialChar ~
23879 \SpecialChar ~
23880 case 101: ...
23881
23882 \newline
23883 \SpecialChar ~
23884 \SpecialChar ~
23885 case 102: ...
23886
23887 \newline
23888 \SpecialChar ~
23889 \SpecialChar ~
23890 case 103: ...
23891
23892 \newline
23893 \SpecialChar ~
23894 \SpecialChar ~
23895 case 104: ...
23896
23897 \newline
23898 \SpecialChar ~
23899 \SpecialChar ~
23900 case 105: ...
23901
23902 \newline
23903 \SpecialChar ~
23904 \SpecialChar ~
23905 case 106: ...
23906
23907 \newline
23908 \SpecialChar ~
23909 \SpecialChar ~
23910 case 107: ...
23911
23912 \newline
23913 }
23914 \layout Standard
23915
23916 then both the switch statements will be implemented using jump-tables whereas
23917  the unmodified switch statement will not be.
23918 \layout Comment
23919
23920 There might be reasons which SDCC cannot know about to either favour or
23921  not favour jump tables.
23922  If the target system has to be as quick for the last switch case as for
23923  the first (pro jump table), or if the switch argument is known to be zero
23924  in the majority of the cases (contra jump table).
23925 \layout Standard
23926
23927 The pragma nojtbound
23928 \begin_inset LatexCommand \index{\#pragma nojtbound}
23929
23930 \end_inset
23931
23932  can be used to turn off checking the
23933 \emph on
23934 j
23935 \emph default
23936 ump
23937 \emph on
23938 t
23939 \emph default
23940 able
23941 \emph on
23942 bound
23943 \emph default
23944 aries.
23945  It has no effect if a default label is supplied.
23946  Use of this pragma is dangerous: if the switch
23947 \begin_inset LatexCommand \index{switch statement}
23948
23949 \end_inset
23950
23951  argument is not matched by a case statement the processor will happily
23952  jump into Nirvana.
23953 \layout Subsection
23954
23955 Bit-shifting Operations
23956 \begin_inset LatexCommand \index{Bit shifting}
23957
23958 \end_inset
23959
23960 .
23961 \layout Standard
23962
23963 Bit shifting is one of the most frequently used operation in embedded programmin
23964 g.
23965  SDCC tries to implement bit-shift operations in the most efficient way
23966  possible, e.g.:
23967 \layout Verse
23968
23969
23970 \family typewriter
23971 unsigned char i;
23972 \newline
23973 ...
23974
23975 \newline
23976 i >>= 4;
23977 \newline
23978 ...
23979 \layout Standard
23980
23981 generates the following code:
23982 \layout Verse
23983
23984
23985 \family typewriter
23986 mov\SpecialChar ~
23987  a,_i
23988 \newline
23989 swap a
23990 \newline
23991 anl\SpecialChar ~
23992  a,#0x0f
23993 \newline
23994 mov\SpecialChar ~
23995  _i,a
23996 \layout Standard
23997
23998 In general SDCC will never setup a loop if the shift count is known.
23999  Another example:
24000 \layout Verse
24001
24002
24003 \family typewriter
24004 unsigned int i;
24005 \newline
24006 ...
24007
24008 \newline
24009 i >>= 9;
24010 \newline
24011 ...
24012 \layout Standard
24013
24014 will generate:
24015 \layout Verse
24016
24017
24018 \family typewriter
24019 mov\SpecialChar ~
24020 \SpecialChar ~
24021 a,(_i + 1)
24022 \newline
24023 mov\SpecialChar ~
24024 \SpecialChar ~
24025 (_i + 1),#0x00
24026 \newline
24027 clr\SpecialChar ~
24028 \SpecialChar ~
24029 c
24030 \newline
24031 rrc\SpecialChar ~
24032 \SpecialChar ~
24033 a
24034 \newline
24035 mov\SpecialChar ~
24036 \SpecialChar ~
24037 _i,a
24038 \layout Subsection
24039
24040 Bit-rotation
24041 \begin_inset LatexCommand \index{Bit rotation}
24042
24043 \end_inset
24044
24045
24046 \layout Standard
24047
24048 A special case of the bit-shift operation is bit rotation
24049 \begin_inset LatexCommand \index{rotating bits}
24050
24051 \end_inset
24052
24053 , SDCC recognizes the following expression to be a left bit-rotation:
24054 \layout Verse
24055
24056
24057 \family typewriter
24058 \series bold
24059 unsigned
24060 \series default
24061 \SpecialChar ~
24062 \SpecialChar ~
24063 char i;\SpecialChar ~
24064 \SpecialChar ~
24065 \SpecialChar ~
24066 \SpecialChar ~
24067 \SpecialChar ~
24068 \SpecialChar ~
24069 \SpecialChar ~
24070 \SpecialChar ~
24071 \SpecialChar ~
24072 \SpecialChar ~
24073 \SpecialChar ~
24074 /* unsigned is needed for rotation */
24075 \newline
24076 ...
24077
24078 \newline
24079 i = ((i << 1) | (i >> 7));
24080 \family default
24081
24082 \newline
24083
24084 \family typewriter
24085 ...
24086 \layout Standard
24087
24088 will generate the following code:
24089 \layout Verse
24090
24091
24092 \family typewriter
24093 mov\SpecialChar ~
24094 \SpecialChar ~
24095 a,_i
24096 \newline
24097 rl\SpecialChar ~
24098 \SpecialChar ~
24099 \SpecialChar ~
24100 a
24101 \newline
24102 mov\SpecialChar ~
24103 \SpecialChar ~
24104 _i,a
24105 \layout Standard
24106
24107 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
24108 ns of this case will also be recognized as bit-rotation, i.e.:
24109 \layout Verse
24110
24111
24112 \family typewriter
24113 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
24114 \layout Subsection
24115
24116 Nibble and Byte Swapping
24117 \layout Standard
24118
24119 Other special cases of the bit-shift operations are nibble or byte swapping
24120 \begin_inset LatexCommand \index{swapping nibbles/bytes}
24121
24122 \end_inset
24123
24124 , SDCC recognizes the following expressions:
24125 \layout Verse
24126
24127
24128 \family typewriter
24129 \series bold
24130 unsigned
24131 \series default
24132 \SpecialChar ~
24133 \SpecialChar ~
24134 char i;
24135 \newline
24136
24137 \series bold
24138 unsigned
24139 \series default
24140 \SpecialChar ~
24141 \SpecialChar ~
24142 int j;
24143 \newline
24144 ...
24145
24146 \newline
24147 i = ((i << 4) | (i >> 4));
24148 \family default
24149
24150 \newline
24151
24152 \family typewriter
24153 j = ((j << 8) | (j >> 8));
24154 \layout Standard
24155
24156 and generates a swap instruction for the nibble swapping
24157 \begin_inset LatexCommand \index{Nibble swapping}
24158
24159 \end_inset
24160
24161  or move instructions for the byte swapping
24162 \begin_inset LatexCommand \index{Byte swapping}
24163
24164 \end_inset
24165
24166 .
24167  The
24168 \begin_inset Quotes sld
24169 \end_inset
24170
24171 j
24172 \begin_inset Quotes srd
24173 \end_inset
24174
24175  example can be used to convert from little to big-endian or vice versa.
24176  If you want to change the endianness of a
24177 \emph on
24178 signed
24179 \emph default
24180  integer you have to cast to
24181 \family typewriter
24182 (unsigned int)
24183 \family default
24184  first.
24185 \layout Standard
24186
24187 Note that SDCC stores numbers in little-endian
24188 \begin_inset Foot
24189 collapsed false
24190
24191 \layout Standard
24192
24193 Usually 8-bit processors don't care much about endianness.
24194  This is not the case for the standard 8051 which only has an instruction
24195  to increment its
24196 \emph on
24197 dptr
24198 \emph default
24199
24200 \begin_inset LatexCommand \index{DPTR}
24201
24202 \end_inset
24203
24204 -datapointer
24205 \emph on
24206
24207 \emph default
24208 so little-endian is the more efficient byte order.
24209 \end_inset
24210
24211
24212 \begin_inset LatexCommand \index{little-endian}
24213
24214 \end_inset
24215
24216
24217 \begin_inset LatexCommand \index{Endianness}
24218
24219 \end_inset
24220
24221  format (i.e.
24222  lowest order first).
24223 \layout Subsection
24224
24225 Highest Order Bit
24226 \begin_inset LatexCommand \index{Highest Order Bit}
24227
24228 \end_inset
24229
24230
24231 \layout Standard
24232
24233 It is frequently required to obtain the highest order bit of an integral
24234  type (long, int, short or char types).
24235  SDCC recognizes the following expression to yield the highest order bit
24236  and generates optimized code for it, e.g.:
24237 \layout Verse
24238
24239
24240 \family typewriter
24241 unsigned int gint;
24242 \newline
24243
24244 \newline
24245 foo () {
24246 \newline
24247 \SpecialChar ~
24248 \SpecialChar ~
24249 unsigned char hob;
24250 \newline
24251 \SpecialChar ~
24252 \SpecialChar ~
24253 ...
24254
24255 \newline
24256 \SpecialChar ~
24257 \SpecialChar ~
24258 hob = (gint >> 15) & 1;
24259 \newline
24260 \SpecialChar ~
24261 \SpecialChar ~
24262 ..
24263
24264 \newline
24265 }
24266 \layout Standard
24267
24268 will generate the following code:
24269 \layout Verse
24270
24271
24272 \family typewriter
24273 \SpecialChar ~
24274 \SpecialChar ~
24275 \SpecialChar ~
24276 \SpecialChar ~
24277 \SpecialChar ~
24278 \SpecialChar ~
24279 \SpecialChar ~
24280 \SpecialChar ~
24281 \SpecialChar ~
24282 \SpecialChar ~
24283 \SpecialChar ~
24284 \SpecialChar ~
24285 \SpecialChar ~
24286 \SpecialChar ~
24287 \SpecialChar ~
24288 \SpecialChar ~
24289 \SpecialChar ~
24290 \SpecialChar ~
24291 \SpecialChar ~
24292 \SpecialChar ~
24293 \SpecialChar ~
24294 \SpecialChar ~
24295 \SpecialChar ~
24296 \SpecialChar ~
24297 \SpecialChar ~
24298  61 ;\SpecialChar ~
24299  hob.c 7
24300 \newline
24301 000A E5*01\SpecialChar ~
24302 \SpecialChar ~
24303 \SpecialChar ~
24304 \SpecialChar ~
24305 \SpecialChar ~
24306 \SpecialChar ~
24307 \SpecialChar ~
24308 \SpecialChar ~
24309 \SpecialChar ~
24310 \SpecialChar ~
24311 \SpecialChar ~
24312 \SpecialChar ~
24313 \SpecialChar ~
24314 \SpecialChar ~
24315 \SpecialChar ~
24316  62\SpecialChar ~
24317 \SpecialChar ~
24318 \SpecialChar ~
24319 \SpecialChar ~
24320 \SpecialChar ~
24321 \SpecialChar ~
24322 \SpecialChar ~
24323 \SpecialChar ~
24324  mov\SpecialChar ~
24325 \SpecialChar ~
24326  a,(_gint + 1)
24327 \newline
24328 000C 23\SpecialChar ~
24329 \SpecialChar ~
24330 \SpecialChar ~
24331 \SpecialChar ~
24332 \SpecialChar ~
24333 \SpecialChar ~
24334 \SpecialChar ~
24335 \SpecialChar ~
24336 \SpecialChar ~
24337 \SpecialChar ~
24338 \SpecialChar ~
24339 \SpecialChar ~
24340 \SpecialChar ~
24341 \SpecialChar ~
24342 \SpecialChar ~
24343 \SpecialChar ~
24344 \SpecialChar ~
24345 \SpecialChar ~
24346  63\SpecialChar ~
24347 \SpecialChar ~
24348 \SpecialChar ~
24349 \SpecialChar ~
24350 \SpecialChar ~
24351 \SpecialChar ~
24352 \SpecialChar ~
24353 \SpecialChar ~
24354  rl\SpecialChar ~
24355 \SpecialChar ~
24356 \SpecialChar ~
24357  a
24358 \newline
24359 000D 54 01\SpecialChar ~
24360 \SpecialChar ~
24361 \SpecialChar ~
24362 \SpecialChar ~
24363 \SpecialChar ~
24364 \SpecialChar ~
24365 \SpecialChar ~
24366 \SpecialChar ~
24367 \SpecialChar ~
24368 \SpecialChar ~
24369 \SpecialChar ~
24370 \SpecialChar ~
24371 \SpecialChar ~
24372 \SpecialChar ~
24373 \SpecialChar ~
24374  64\SpecialChar ~
24375 \SpecialChar ~
24376 \SpecialChar ~
24377 \SpecialChar ~
24378 \SpecialChar ~
24379 \SpecialChar ~
24380 \SpecialChar ~
24381 \SpecialChar ~
24382  anl\SpecialChar ~
24383 \SpecialChar ~
24384  a,#0x01
24385 \newline
24386 000F F5*02\SpecialChar ~
24387 \SpecialChar ~
24388 \SpecialChar ~
24389 \SpecialChar ~
24390 \SpecialChar ~
24391 \SpecialChar ~
24392 \SpecialChar ~
24393 \SpecialChar ~
24394 \SpecialChar ~
24395 \SpecialChar ~
24396 \SpecialChar ~
24397 \SpecialChar ~
24398 \SpecialChar ~
24399 \SpecialChar ~
24400 \SpecialChar ~
24401  65\SpecialChar ~
24402 \SpecialChar ~
24403 \SpecialChar ~
24404 \SpecialChar ~
24405 \SpecialChar ~
24406 \SpecialChar ~
24407 \SpecialChar ~
24408 \SpecialChar ~
24409  mov\SpecialChar ~
24410 \SpecialChar ~
24411  _foo_hob_1_1,a
24412 \layout Standard
24413
24414 Variations of this case however will
24415 \emph on
24416 not
24417 \emph default
24418  be recognized.
24419  It is a standard C expression, so I heartily recommend this be the only
24420  way to get the highest order bit, (it is portable).
24421  Of course it will be recognized even if it is embedded in other expressions,
24422  e.g.:
24423 \layout Verse
24424
24425
24426 \family typewriter
24427 xyz = gint + ((gint >> 15) & 1);
24428 \layout Standard
24429
24430 will still be recognized.
24431 \layout Subsection
24432
24433 Peephole Optimizer
24434 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
24435
24436 \end_inset
24437
24438
24439 \begin_inset LatexCommand \index{Peephole optimizer}
24440
24441 \end_inset
24442
24443
24444 \layout Standard
24445
24446 The compiler uses a rule based, pattern matching and re-writing mechanism
24447  for peep-hole optimization.
24448  It is inspired by
24449 \emph on
24450 copt
24451 \emph default
24452  a peep-hole optimizer by Christopher W.
24453  Fraser (cwfraser\SpecialChar ~
24454 @\SpecialChar ~
24455 microsoft.com).
24456  A default set of rules are compiled into the compiler, additional rules
24457  may be added with the
24458 \emph on
24459 -
24460 \begin_inset ERT
24461 status Collapsed
24462
24463 \layout Standard
24464
24465 \backslash
24466 /
24467 \end_inset
24468
24469 -peep-file
24470 \begin_inset LatexCommand \index{-\/-peep-file}
24471
24472 \end_inset
24473
24474  <filename>
24475 \emph default
24476  option.
24477  The rule language is best illustrated with examples.
24478 \layout Verse
24479
24480
24481 \family typewriter
24482 replace {
24483 \newline
24484 \SpecialChar ~
24485 \SpecialChar ~
24486 mov %1,a
24487 \newline
24488 \SpecialChar ~
24489 \SpecialChar ~
24490 mov a,%1
24491 \newline
24492 } by {
24493 \newline
24494 \SpecialChar ~
24495 \SpecialChar ~
24496 mov %1,a
24497 \newline
24498 }
24499 \layout Standard
24500
24501 The above rule will change the following assembly
24502 \begin_inset LatexCommand \index{Assembler routines}
24503
24504 \end_inset
24505
24506  sequence:
24507 \layout Verse
24508
24509
24510 \family typewriter
24511 mov r1,a
24512 \newline
24513 mov a,r1
24514 \layout Standard
24515
24516 to
24517 \layout Verse
24518
24519
24520 \family typewriter
24521 mov r1,a
24522 \layout Standard
24523
24524 Note: All occurrences of a
24525 \emph on
24526 %n
24527 \emph default
24528  (pattern variable) must denote the same string.
24529  With the above rule, the assembly sequence:
24530 \layout Verse
24531
24532
24533 \family typewriter
24534 mov r1,a
24535 \newline
24536 mov a,r2
24537 \layout Standard
24538
24539 will remain unmodified.
24540 \newline
24541
24542 \newline
24543 Other special case optimizations may be added by the user (via
24544 \emph on
24545 -
24546 \begin_inset ERT
24547 status Collapsed
24548
24549 \layout Standard
24550
24551 \backslash
24552 /
24553 \end_inset
24554
24555 -peep-file option
24556 \emph default
24557 ).
24558  E.g.
24559  some variants of the 8051 MCU
24560 \begin_inset LatexCommand \index{MCS51 variants}
24561
24562 \end_inset
24563
24564  allow only
24565 \family typewriter
24566 ajmp
24567 \family default
24568  and
24569 \family typewriter
24570 acall
24571 \family default
24572 .
24573  The following two rules will change all
24574 \family typewriter
24575 ljmp
24576 \family default
24577  and
24578 \family typewriter
24579 lcall
24580 \family default
24581  to
24582 \family typewriter
24583 ajmp
24584 \family default
24585  and
24586 \family typewriter
24587 acall
24588 \layout Verse
24589
24590
24591 \family typewriter
24592 replace { lcall %1 } by { acall %1 }
24593 \newline
24594 replace { ljmp %1 } by { ajmp %1 }
24595 \layout Standard
24596
24597 The
24598 \emph on
24599 inline-assembler code
24600 \emph default
24601  is also passed through the peep hole optimizer, thus the peephole optimizer
24602  can also be used as an assembly level macro expander.
24603  The rules themselves are MCU dependent whereas the rule language infra-structur
24604 e is MCU independent.
24605  Peephole optimization rules for other MCU can be easily programmed using
24606  the rule language.
24607 \newline
24608
24609 \newline
24610 The syntax for a rule is as follows:
24611 \layout Verse
24612
24613
24614 \family typewriter
24615 rule := replace [ restart ] '{' <assembly sequence> '
24616 \backslash
24617 n'
24618 \newline
24619 \SpecialChar ~
24620  \SpecialChar ~
24621  \SpecialChar ~
24622  \SpecialChar ~
24623  \SpecialChar ~
24624  \SpecialChar ~
24625  \SpecialChar ~
24626  \SpecialChar ~
24627  \SpecialChar ~
24628  \SpecialChar ~
24629  \SpecialChar ~
24630  \SpecialChar ~
24631  \SpecialChar ~
24632  \SpecialChar ~
24633  '}' by '{' '
24634 \backslash
24635 n'
24636 \newline
24637 \SpecialChar ~
24638  \SpecialChar ~
24639  \SpecialChar ~
24640  \SpecialChar ~
24641  \SpecialChar ~
24642  \SpecialChar ~
24643  \SpecialChar ~
24644  \SpecialChar ~
24645  \SpecialChar ~
24646  \SpecialChar ~
24647  \SpecialChar ~
24648  \SpecialChar ~
24649  \SpecialChar ~
24650  \SpecialChar ~
24651  \SpecialChar ~
24652  \SpecialChar ~
24653  <assembly sequence> '
24654 \backslash
24655 n'
24656 \newline
24657 \SpecialChar ~
24658  \SpecialChar ~
24659  \SpecialChar ~
24660  \SpecialChar ~
24661  \SpecialChar ~
24662  \SpecialChar ~
24663  \SpecialChar ~
24664  \SpecialChar ~
24665  \SpecialChar ~
24666  \SpecialChar ~
24667  \SpecialChar ~
24668  \SpecialChar ~
24669  \SpecialChar ~
24670  \SpecialChar ~
24671  '}' [if <functionName> ] '
24672 \backslash
24673 n'
24674 \layout Standard
24675
24676 <assembly sequence> := assembly instruction (each instruction including
24677  labels must be on a separate line).
24678 \newline
24679
24680 \newline
24681 The optimizer will apply to the rules one by one from the top in the sequence
24682  of their appearance, it will terminate when all rules are exhausted.
24683  If the 'restart' option is specified, then the optimizer will start matching
24684  the rules again from the top, this option for a rule is expensive (performance)
24685 , it is intended to be used in situations where a transformation will trigger
24686  the same rule again.
24687  An example of this (not a good one, it has side effects) is the following
24688  rule:
24689 \layout Verse
24690
24691
24692 \family typewriter
24693 replace restart {
24694 \newline
24695 \SpecialChar ~
24696 \SpecialChar ~
24697 pop %1
24698 \newline
24699 \SpecialChar ~
24700 \SpecialChar ~
24701 push %1 } by {
24702 \newline
24703 \SpecialChar ~
24704 \SpecialChar ~
24705 ; nop
24706 \newline
24707 }
24708 \layout Standard
24709
24710 Note that the replace pattern cannot be a blank, but can be a comment line.
24711  Without the 'restart' option only the innermost 'pop' 'push' pair would
24712  be eliminated, i.e.:
24713 \layout Verse
24714
24715
24716 \family typewriter
24717 pop ar1
24718 \newline
24719 pop ar2
24720 \newline
24721 push ar2
24722 \newline
24723 push ar1
24724 \layout Standard
24725
24726 would result in:
24727 \layout Verse
24728
24729
24730 \family typewriter
24731 pop ar1
24732 \newline
24733 ; nop
24734 \newline
24735 push ar1
24736 \layout Standard
24737
24738
24739 \emph on
24740 with
24741 \emph default
24742  the restart option the rule will be applied again to the resulting code
24743  and then all the pop-push pairs will be eliminated to yield:
24744 \layout Verse
24745
24746
24747 \family typewriter
24748 ; nop
24749 \newline
24750 ; nop
24751 \layout Standard
24752
24753 A conditional function can be attached to a rule.
24754  Attaching rules are somewhat more involved, let me illustrate this with
24755  an example.
24756 \layout Verse
24757
24758
24759 \family typewriter
24760 replace {
24761 \newline
24762 \SpecialChar ~
24763  \SpecialChar ~
24764  \SpecialChar ~
24765 ljmp %5
24766 \newline
24767 %2:
24768 \newline
24769 } by {
24770 \newline
24771 \SpecialChar ~
24772  \SpecialChar ~
24773  \SpecialChar ~
24774 sjmp %5
24775 \newline
24776 %2:
24777 \newline
24778 } if labelInRange
24779 \layout Standard
24780
24781 The optimizer does a look-up of a function name table defined in function
24782
24783 \emph on
24784 callFuncByName
24785 \emph default
24786  in the source file SDCCpeeph.c, with the name
24787 \emph on
24788 labelInRange
24789 \emph default
24790 .
24791  If it finds a corresponding entry the function is called.
24792  Note there can be no parameters specified for these functions, in this
24793  case the use of
24794 \emph on
24795 %5
24796 \emph default
24797  is crucial, since the function
24798 \emph on
24799 labelInRange
24800 \emph default
24801  expects to find the label in that particular variable (the hash table containin
24802 g the variable bindings is passed as a parameter).
24803  If you want to code more such functions, take a close look at the function
24804  labelInRange and the calling mechanism in source file SDCCpeeph.c.
24805  Currently implemented are
24806 \emph on
24807 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
24808  24bitMode, portIsDS390, 24bitModeAndPortDS390
24809 \emph default
24810 and
24811 \emph on
24812  notVolatile
24813 \emph default
24814 .
24815 \layout Standard
24816
24817 I know this whole thing is a little kludgey, but maybe some day we will
24818  have some better means.
24819  If you are looking at this file, you will see the default rules that are
24820  compiled into the compiler, you can add your own rules in the default set
24821  there if you get tired of specifying the -
24822 \begin_inset ERT
24823 status Collapsed
24824
24825 \layout Standard
24826
24827 \backslash
24828 /
24829 \end_inset
24830
24831 -peep-file option.
24832 \layout Section
24833
24834 ANSI-Compliance
24835 \begin_inset LatexCommand \index{ANSI-compliance}
24836
24837 \end_inset
24838
24839
24840 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
24841
24842 \end_inset
24843
24844
24845 \layout Standard
24846
24847 Deviations from the compliance:
24848 \layout Itemize
24849
24850 functions are not reentrant
24851 \begin_inset LatexCommand \index{reentrant}
24852
24853 \end_inset
24854
24855  unless explicitly declared as such or the
24856 \series bold
24857 -
24858 \begin_inset ERT
24859 status Collapsed
24860
24861 \layout Standard
24862
24863 \backslash
24864 /
24865 \end_inset
24866
24867 -stack-auto
24868 \begin_inset LatexCommand \index{-\/-stack-auto}
24869
24870 \end_inset
24871
24872
24873 \series default
24874  command line option is specified.
24875 \layout Itemize
24876
24877 structures and unions cannot be assigned values directly, cannot be passed
24878  as function parameters or assigned to each other and cannot be a return
24879  value from a function, e.g.:
24880 \begin_deeper
24881 \layout Verse
24882
24883
24884 \family typewriter
24885 struct s { ...
24886  };
24887 \newline
24888 struct s s1, s2;
24889 \newline
24890 foo()
24891 \newline
24892 {
24893 \newline
24894 \SpecialChar ~
24895 \SpecialChar ~
24896 \SpecialChar ~
24897 \SpecialChar ~
24898 ...
24899
24900 \newline
24901 \SpecialChar ~
24902 \SpecialChar ~
24903 \SpecialChar ~
24904 \SpecialChar ~
24905 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
24906 \newline
24907 \SpecialChar ~
24908 \SpecialChar ~
24909 \SpecialChar ~
24910 \SpecialChar ~
24911 ...
24912
24913 \newline
24914 }
24915 \newline
24916 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
24917  */
24918 \newline
24919 {
24920 \newline
24921 \SpecialChar ~
24922 \SpecialChar ~
24923 \SpecialChar ~
24924 \SpecialChar ~
24925 struct s rets;
24926 \newline
24927 \SpecialChar ~
24928 \SpecialChar ~
24929 \SpecialChar ~
24930 \SpecialChar ~
24931 ...
24932
24933 \newline
24934 \SpecialChar ~
24935 \SpecialChar ~
24936 \SpecialChar ~
24937 \SpecialChar ~
24938 return rets;/* is invalid in SDCC although allowed in ANSI */
24939 \newline
24940 }
24941 \end_deeper
24942 \layout Itemize
24943
24944 'long long
24945 \begin_inset LatexCommand \index{long long (not supported)}
24946
24947 \end_inset
24948
24949 ' (64 bit integers
24950 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
24951
24952 \end_inset
24953
24954 ) not supported.
24955 \layout Itemize
24956
24957 'double
24958 \begin_inset LatexCommand \index{double (not supported)}
24959
24960 \end_inset
24961
24962 ' precision floating point
24963 \begin_inset LatexCommand \index{Floating point support}
24964
24965 \end_inset
24966
24967 not supported.
24968 \layout Itemize
24969
24970 No support for setjmp
24971 \begin_inset LatexCommand \index{setjmp (not supported)}
24972
24973 \end_inset
24974
24975  and longjmp
24976 \begin_inset LatexCommand \index{longjmp (not supported)}
24977
24978 \end_inset
24979
24980  (for now).
24981 \layout Itemize
24982
24983 Old K&R style
24984 \begin_inset LatexCommand \index{K\&R style}
24985
24986 \end_inset
24987
24988  function declarations are NOT allowed.
24989 \begin_deeper
24990 \layout Verse
24991
24992
24993 \family typewriter
24994 foo(i,j) /* this old style of function declarations */
24995 \newline
24996 int i,j; /* are valid in ANSI but not valid in SDCC */
24997 \newline
24998 {
24999 \newline
25000 \SpecialChar ~
25001 \SpecialChar ~
25002 \SpecialChar ~
25003 \SpecialChar ~
25004 ...
25005
25006 \newline
25007 }
25008 \end_deeper
25009 \layout Itemize
25010
25011 Certain words that are valid identifiers in the standard may be reserved
25012  words in SDCC unless the
25013 \series bold
25014 -
25015 \begin_inset ERT
25016 status Collapsed
25017
25018 \layout Standard
25019
25020 \backslash
25021 /
25022 \end_inset
25023
25024 -std-c89
25025 \begin_inset LatexCommand \index{-\/-std-c89}
25026
25027 \end_inset
25028
25029  or -
25030 \begin_inset ERT
25031 status Collapsed
25032
25033 \layout Standard
25034
25035 \backslash
25036 /
25037 \end_inset
25038
25039 -std-c99
25040 \begin_inset LatexCommand \index{-\/-std-c99}
25041
25042 \end_inset
25043
25044
25045 \series default
25046  command line options are used.
25047  These may include (depending on the selected processor): 'at', 'banked',
25048  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
25049 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
25050  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
25051  '_naked'.
25052  Compliant equivalents of these keywords are always available in a form
25053  that begin with two underscores
25054 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
25055
25056 \end_inset
25057
25058 , f.e.
25059  '__data' instead of 'data'.
25060 \layout Section
25061
25062 Cyclomatic Complexity
25063 \begin_inset LatexCommand \index{Cyclomatic complexity}
25064
25065 \end_inset
25066
25067
25068 \layout Standard
25069
25070 Cyclomatic complexity of a function is defined as the number of independent
25071  paths the program can take during execution of the function.
25072  This is an important number since it defines the number test cases you
25073  have to generate to validate the function.
25074  The accepted industry standard for complexity number is 10, if the cyclomatic
25075  complexity reported by SDCC exceeds 10 you should think about simplification
25076  of the function logic.
25077  Note that the complexity level is not related to the number of lines of
25078  code in a function.
25079  Large functions can have low complexity, and small functions can have large
25080  complexity levels.
25081
25082 \newline
25083
25084 \newline
25085 SDCC uses the following formula to compute the complexity:
25086 \newline
25087
25088 \layout Standard
25089
25090 complexity = (number of edges in control flow graph) - (number of nodes
25091  in control flow graph) + 2;
25092 \newline
25093
25094 \newline
25095 Having said that the industry standard is 10, you should be aware that in
25096  some cases it be may unavoidable to have a complexity level of less than
25097  10.
25098  For example if you have switch statement with more than 10 case labels,
25099  each case label adds one to the complexity level.
25100  The complexity level is by no means an absolute measure of the algorithmic
25101  complexity of the function, it does however provide a good starting point
25102  for which functions you might look at for further optimization.
25103 \layout Section
25104
25105 Retargetting for other Processors
25106 \layout Standard
25107
25108 The issues for retargetting the compiler are far too numerous to be covered
25109  by this document.
25110  What follows is a brief description of each of the seven phases of the
25111  compiler and its MCU dependency.
25112 \layout Itemize
25113
25114 Parsing the source and building the annotated parse tree.
25115  This phase is largely MCU independent (except for the language extensions).
25116  Syntax & semantic checks are also done in this phase, along with some initial
25117  optimizations like back patching labels and the pattern matching optimizations
25118  like bit-rotation etc.
25119 \layout Itemize
25120
25121 The second phase involves generating an intermediate code which can be easy
25122  manipulated during the later phases.
25123  This phase is entirely MCU independent.
25124  The intermediate code generation assumes the target machine has unlimited
25125  number of registers, and designates them with the name iTemp.
25126  The compiler can be made to dump a human readable form of the code generated
25127  by using the -
25128 \begin_inset ERT
25129 status Collapsed
25130
25131 \layout Standard
25132
25133 \backslash
25134 /
25135 \end_inset
25136
25137 -dumpraw option.
25138 \layout Itemize
25139
25140 This phase does the bulk of the standard optimizations and is also MCU independe
25141 nt.
25142  This phase can be broken down into several sub-phases:
25143 \newline
25144
25145 \newline
25146 Break down intermediate code (iCode) into basic blocks.
25147 \newline
25148 Do control flow & data flow analysis on the basic blocks.
25149 \newline
25150 Do local common subexpression elimination, then global subexpression elimination
25151 \newline
25152 Dead code elimination
25153 \newline
25154 Loop optimizations
25155 \newline
25156 If loop optimizations caused any changes then do 'global subexpression eliminati
25157 on' and 'dead code elimination' again.
25158 \layout Itemize
25159
25160 This phase determines the live-ranges; by live range I mean those iTemp
25161  variables defined by the compiler that still survive after all the optimization
25162 s.
25163  Live range analysis
25164 \begin_inset LatexCommand \index{Live range analysis}
25165
25166 \end_inset
25167
25168  is essential for register allocation, since these computation determines
25169  which of these iTemps will be assigned to registers, and for how long.
25170 \layout Itemize
25171
25172 Phase five is register allocation.
25173  There are two parts to this process.
25174 \newline
25175
25176 \newline
25177 The first part I call 'register packing' (for lack of a better term).
25178  In this case several MCU specific expression folding is done to reduce
25179  register pressure.
25180 \newline
25181
25182 \newline
25183 The second part is more MCU independent and deals with allocating registers
25184  to the remaining live ranges.
25185  A lot of MCU specific code does creep into this phase because of the limited
25186  number of index registers available in the 8051.
25187 \layout Itemize
25188
25189 The Code generation phase is (unhappily), entirely MCU dependent and very
25190  little (if any at all) of this code can be reused for other MCU.
25191  However the scheme for allocating a homogenized assembler operand for each
25192  iCode operand may be reused.
25193 \layout Itemize
25194
25195 As mentioned in the optimization section the peep-hole optimizer is rule
25196  based system, which can reprogrammed for other MCUs.
25197 \layout Chapter
25198
25199 Compiler internals
25200 \begin_inset LatexCommand \index{Compiler internals}
25201
25202 \end_inset
25203
25204
25205 \layout Section
25206
25207 The anatomy of the compiler
25208 \begin_inset LatexCommand \label{sub:The-anatomy-of}
25209
25210 \end_inset
25211
25212
25213 \layout Standard
25214
25215
25216 \shape italic
25217 This is an excerpt from an article published in Circuit Cellar Magazine
25218  in
25219 \series bold
25220 August 2000
25221 \series default
25222 .
25223  It's a little outdated (the compiler is much more efficient now and user/develo
25224 per friendly), but pretty well exposes the guts of it all.
25225 \shape default
25226
25227 \newline
25228
25229 \newline
25230 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
25231  It is fairly easy to retarget for other 8-bit MCU.
25232  Here we take a look at some of the internals of the compiler.
25233
25234 \layout Paragraph*
25235
25236 Parsing
25237 \begin_inset LatexCommand \index{Parsing}
25238
25239 \end_inset
25240
25241
25242 \layout Standard
25243
25244 Parsing the input source file and creating an AST (Annotated Syntax Tree
25245 \begin_inset LatexCommand \index{Annotated syntax tree}
25246
25247 \end_inset
25248
25249 ).
25250  This phase also involves propagating types (annotating each node of the
25251  parse tree with type information) and semantic analysis.
25252  There are some MCU specific parsing rules.
25253  For example the storage classes, the extended storage classes are MCU specific
25254  while there may be a xdata storage class for 8051 there is no such storage
25255  class for z80 or Atmel AVR.
25256  SDCC allows MCU specific storage class extensions, i.e.
25257  xdata will be treated as a storage class specifier when parsing 8051 C
25258  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
25259  C code.
25260 \layout Paragraph*
25261
25262 Generating iCode
25263 \begin_inset LatexCommand \index{iCode}
25264
25265 \end_inset
25266
25267
25268 \layout Standard
25269
25270 Intermediate code generation.
25271  In this phase the AST is broken down into three-operand form (iCode).
25272  These three operand forms are represented as doubly linked lists.
25273  ICode is the term given to the intermediate form generated by the compiler.
25274  ICode example section shows some examples of iCode generated for some simple
25275  C source functions.
25276 \layout Paragraph*
25277
25278 Optimizations
25279 \begin_inset LatexCommand \index{Optimizations}
25280
25281 \end_inset
25282
25283 .
25284 \layout Standard
25285
25286 Bulk of the target independent optimizations is performed in this phase.
25287  The optimizations include constant propagation, common sub-expression eliminati
25288 on, loop invariant code movement, strength reduction of loop induction variables
25289  and dead-code elimination.
25290 \layout Paragraph*
25291
25292 Live range analysis
25293 \begin_inset LatexCommand \index{Live range analysis}
25294
25295 \end_inset
25296
25297
25298 \layout Standard
25299
25300 During intermediate code generation phase, the compiler assumes the target
25301  machine has infinite number of registers and generates a lot of temporary
25302  variables.
25303  The live range computation determines the lifetime of each of these compiler-ge
25304 nerated temporaries.
25305  A picture speaks a thousand words.
25306  ICode example sections show the live range annotations for each of the
25307  operand.
25308  It is important to note here, each iCode is assigned a number in the order
25309  of its execution in the function.
25310  The live ranges are computed in terms of these numbers.
25311  The from number is the number of the iCode which first defines the operand
25312  and the to number signifies the iCode which uses this operand last.
25313 \layout Paragraph*
25314
25315 Register Allocation
25316 \begin_inset LatexCommand \index{Register allocation}
25317
25318 \end_inset
25319
25320
25321 \layout Standard
25322
25323 The register allocation determines the type and number of registers needed
25324  by each operand.
25325  In most MCUs only a few registers can be used for indirect addressing.
25326  In case of 8051 for example the registers R0 & R1 can be used to indirectly
25327  address the internal ram and DPTR to indirectly address the external ram.
25328  The compiler will try to allocate the appropriate register to pointer variables
25329  if it can.
25330  ICode example section shows the operands annotated with the registers assigned
25331  to them.
25332  The compiler will try to keep operands in registers as much as possible;
25333  there are several schemes the compiler uses to do achieve this.
25334  When the compiler runs out of registers the compiler will check to see
25335  if there are any live operands which is not used or defined in the current
25336  basic block being processed, if there are any found then it will push that
25337  operand and use the registers in this block, the operand will then be popped
25338  at the end of the basic block.
25339
25340 \layout Standard
25341
25342 There are other MCU specific considerations in this phase.
25343  Some MCUs have an accumulator; very short-lived operands could be assigned
25344  to the accumulator instead of a general-purpose register.
25345 \layout Paragraph*
25346
25347 Code generation
25348 \layout Standard
25349
25350 Figure II gives a table of iCode operations supported by the compiler.
25351  The code generation involves translating these operations into corresponding
25352  assembly code for the processor.
25353  This sounds overly simple but that is the essence of code generation.
25354  Some of the iCode operations are generated on a MCU specific manner for
25355  example, the z80 port does not use registers to pass parameters so the
25356  SEND and RECV iCode operations will not be generated, and it also does
25357  not support JUMPTABLES.
25358
25359 \newline
25360
25361 \series bold
25362 \shape italic
25363 \color red
25364 <Where is Figure II?>
25365 \layout Comment
25366
25367 In the original article Figure II was announced to be downloadable on
25368 \shape italic
25369 Circuit Cellar
25370 \shape default
25371 's web site.
25372  Unfortunately it never seemed to have shown up there, so: where is Figure
25373  II?
25374 \layout Paragraph*
25375
25376 ICode Example
25377 \begin_inset LatexCommand \index{iCode}
25378
25379 \end_inset
25380
25381
25382 \layout Standard
25383
25384 This section shows some details of iCode.
25385  The example C code does not do anything useful; it is used as an example
25386  to illustrate the intermediate code generated by the compiler.
25387 \layout Verse
25388
25389
25390 \family typewriter
25391 1.\SpecialChar ~
25392 xdata int * p;
25393 \newline
25394 2.\SpecialChar ~
25395 int gint;
25396 \newline
25397 3.\SpecialChar ~
25398 /* This function does nothing useful.
25399  It is used
25400 \newline
25401 4.\SpecialChar ~
25402 \SpecialChar ~
25403 \SpecialChar ~
25404 \SpecialChar ~
25405 for the purpose of explaining iCode */
25406 \newline
25407 5.\SpecialChar ~
25408 short function (data int *x)
25409 \newline
25410 6.\SpecialChar ~
25411 {
25412 \newline
25413 7.\SpecialChar ~
25414 \SpecialChar ~
25415 \SpecialChar ~
25416 short i=10; \SpecialChar ~
25417 \SpecialChar ~
25418 /* dead initialization eliminated */
25419 \newline
25420 8.\SpecialChar ~
25421 \SpecialChar ~
25422 \SpecialChar ~
25423 short sum=10; /* dead initialization eliminated */
25424 \newline
25425 9.\SpecialChar ~
25426 \SpecialChar ~
25427 \SpecialChar ~
25428 short mul;
25429 \newline
25430 10.\SpecialChar ~
25431 \SpecialChar ~
25432 int j ;
25433 \newline
25434 11.\SpecialChar ~
25435 \SpecialChar ~
25436 while (*x) *x++ = *p++;
25437 \newline
25438 12.\SpecialChar ~
25439 \SpecialChar ~
25440 \SpecialChar ~
25441 \SpecialChar ~
25442 sum = 0 ;
25443 \newline
25444 13.\SpecialChar ~
25445 \SpecialChar ~
25446 mul = 0;
25447 \newline
25448 14.\SpecialChar ~
25449 \SpecialChar ~
25450 /* compiler detects i,j to be induction variables */
25451 \newline
25452 15.\SpecialChar ~
25453 \SpecialChar ~
25454 for (i = 0, j = 10 ; i < 10 ; i++, j
25455 \family default
25456 -
25457 \begin_inset ERT
25458 status Collapsed
25459
25460 \layout Standard
25461
25462 \backslash
25463 /
25464 \end_inset
25465
25466 -
25467 \family typewriter
25468 ) {
25469 \newline
25470 16.\SpecialChar ~
25471 \SpecialChar ~
25472 \SpecialChar ~
25473 \SpecialChar ~
25474 sum += i;
25475 \newline
25476 17.\SpecialChar ~
25477 \SpecialChar ~
25478 \SpecialChar ~
25479 \SpecialChar ~
25480 mul += i * 3; \SpecialChar ~
25481 \SpecialChar ~
25482 /* this multiplication remains */
25483 \newline
25484 18.\SpecialChar ~
25485 \SpecialChar ~
25486 \SpecialChar ~
25487 \SpecialChar ~
25488 gint += j * 3;\SpecialChar ~
25489 \SpecialChar ~
25490 /* this multiplication changed to addition */
25491 \newline
25492 19.\SpecialChar ~
25493 \SpecialChar ~
25494 }
25495 \newline
25496 20.\SpecialChar ~
25497 \SpecialChar ~
25498 return sum+mul;
25499 \newline
25500 21.\SpecialChar ~
25501 }
25502 \layout Standard
25503
25504 In addition to the operands each iCode contains information about the filename
25505  and line it corresponds to in the source file.
25506  The first field in the listing should be interpreted as follows:
25507 \newline
25508
25509 \shape italic
25510 \size footnotesize
25511 Filename(linenumber: iCode Execution sequence number : ICode hash table
25512  key : loop depth of the iCode).
25513 \shape default
25514 \size default
25515
25516 \newline
25517 Then follows the human readable form of the ICode operation.
25518  Each operand of this triplet form can be of three basic types a) compiler
25519  generated temporary b) user defined variable c) a constant value.
25520  Note that local variables and parameters are replaced by compiler generated
25521  temporaries.
25522  Live ranges
25523 \begin_inset LatexCommand \index{Live range analysis}
25524
25525 \end_inset
25526
25527  are computed only for temporaries (i.e.
25528  live ranges are not computed for global variables).
25529  Registers
25530 \begin_inset LatexCommand \index{Register allocation}
25531
25532 \end_inset
25533
25534  are allocated for temporaries only.
25535  Operands are formatted in the following manner:
25536 \newline
25537
25538 \shape italic
25539 \size footnotesize
25540 Operand Name [lr live-from : live-to ] { type information } [ registers
25541  allocated ].
25542 \shape default
25543 \size default
25544
25545 \newline
25546 As mentioned earlier the live ranges are computed in terms of the execution
25547  sequence number of the iCodes, for example
25548 \newline
25549 the iTemp0 is live from (i.e.
25550  first defined in iCode with execution sequence number 3, and is last used
25551  in the iCode with sequence number 5).
25552  For induction variables such as iTemp21 the live range computation extends
25553  the lifetime from the start to the end of the loop.
25554 \newline
25555 The register allocator used the live range information to allocate registers,
25556  the same registers may be used for different temporaries if their live
25557  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
25558  iTemp17 since their live ranges do not overlap.
25559  In addition the allocator also takes into consideration the type and usage
25560  of a temporary, for example itemp6 is a pointer to near space and is used
25561  as to fetch data from (i.e.
25562  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
25563  Some short lived temporaries are allocated to special registers which have
25564  meaning to the code generator e.g.
25565  iTemp13 is allocated to a pseudo register CC which tells the back end that
25566  the temporary is used only for a conditional jump the code generation makes
25567  use of this information to optimize a compare and jump ICode.
25568 \newline
25569 There are several loop optimizations
25570 \begin_inset LatexCommand \index{Loop optimization}
25571
25572 \end_inset
25573
25574  performed by the compiler.
25575  It can detect induction variables iTemp21(i) and iTemp23(j).
25576  Also note the compiler does selective strength reduction
25577 \begin_inset LatexCommand \index{Strength reduction}
25578
25579 \end_inset
25580
25581 , i.e.
25582  the multiplication of an induction variable in line 18 (gint = j * 3) is
25583  changed to addition, a new temporary iTemp17 is allocated and assigned
25584  a initial value, a constant 3 is then added for each iteration of the loop.
25585  The compiler does not change the multiplication
25586 \begin_inset LatexCommand \index{Multiplication}
25587
25588 \end_inset
25589
25590  in line 17 however since the processor does support an 8 * 8 bit multiplication.
25591 \newline
25592 Note the dead code elimination
25593 \begin_inset LatexCommand \index{Dead-code elimination}
25594
25595 \end_inset
25596
25597  optimization eliminated the dead assignments in line 7 & 8 to I and sum
25598  respectively.
25599 \newline
25600
25601 \layout Standard
25602
25603
25604 \size footnotesize
25605 Sample.c (5:1:0:0) _entry($9) :
25606 \layout Standard
25607
25608
25609 \size footnotesize
25610 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
25611 \layout Standard
25612
25613
25614 \size footnotesize
25615 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
25616 \layout Standard
25617
25618
25619 \size footnotesize
25620 Sample.c(11:4:53:0) preHeaderLbl0($11) :
25621 \layout Standard
25622
25623
25624 \size footnotesize
25625 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
25626  * int}[r2]
25627 \layout Standard
25628
25629
25630 \size footnotesize
25631 Sample.c(11:6:5:1) _whilecontinue_0($1) :
25632 \layout Standard
25633
25634
25635 \size footnotesize
25636 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
25637  int}[r0]]
25638 \layout Standard
25639
25640
25641 \size footnotesize
25642 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
25643 \layout Standard
25644
25645
25646 \size footnotesize
25647 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
25648  * int}
25649 \layout Standard
25650
25651
25652 \size footnotesize
25653 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
25654  {short}
25655 \layout Standard
25656
25657
25658 \size footnotesize
25659 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
25660  * int}[DPTR]]
25661 \layout Standard
25662
25663
25664 \size footnotesize
25665 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
25666 }[r2 r3]
25667 \layout Standard
25668
25669
25670 \size footnotesize
25671 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
25672  * int}[r0] + 0x2 {short}
25673 \layout Standard
25674
25675
25676 \size footnotesize
25677 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
25678 \layout Standard
25679
25680
25681 \size footnotesize
25682 Sample.c(11:17:21:0)_whilebreak_0($3) :
25683 \layout Standard
25684
25685
25686 \size footnotesize
25687 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
25688 \layout Standard
25689
25690
25691 \size footnotesize
25692 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
25693 \layout Standard
25694
25695
25696 \size footnotesize
25697 Sample.c(15:20:54:0)preHeaderLbl1($13) :
25698 \layout Standard
25699
25700
25701 \size footnotesize
25702 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
25703 \layout Standard
25704
25705
25706 \size footnotesize
25707 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
25708 \layout Standard
25709
25710
25711 \size footnotesize
25712 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
25713 \layout Standard
25714
25715
25716 \size footnotesize
25717 Sample.c(15:24:26:1)_forcond_0($4) :
25718 \layout Standard
25719
25720
25721 \size footnotesize
25722 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
25723  < 0xa {short}
25724 \layout Standard
25725
25726
25727 \size footnotesize
25728 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
25729 \layout Standard
25730
25731
25732 \size footnotesize
25733 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
25734  + ITemp21 [lr21:38]{short}[r4]
25735 \layout Standard
25736
25737
25738 \size footnotesize
25739 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
25740  * 0x3 {short}
25741 \layout Standard
25742
25743
25744 \size footnotesize
25745 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
25746  + iTemp15 [lr29:30]{short}[r1]
25747 \layout Standard
25748
25749
25750 \size footnotesize
25751 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
25752  r0]- 0x3 {short}
25753 \layout Standard
25754
25755
25756 \size footnotesize
25757 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
25758 int}[r7 r0]
25759 \layout Standard
25760
25761
25762 \size footnotesize
25763 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
25764  + 0x1 {short}
25765 \layout Standard
25766
25767
25768 \size footnotesize
25769 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
25770  r6]- 0x1 {short}
25771 \layout Standard
25772
25773
25774 \size footnotesize
25775 Sample.c(19:38:47:1) goto _forcond_0($4)
25776 \layout Standard
25777
25778
25779 \size footnotesize
25780 Sample.c(19:39:48:0)_forbreak_0($7) :
25781 \layout Standard
25782
25783
25784 \size footnotesize
25785 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
25786  + ITemp11 [lr19:40]{short}[r3]
25787 \layout Standard
25788
25789
25790 \size footnotesize
25791 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
25792 \layout Standard
25793
25794
25795 \size footnotesize
25796 Sample.c(20:42:51:0)_return($8) :
25797 \layout Standard
25798
25799
25800 \size footnotesize
25801 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
25802 \size default
25803
25804 \newline
25805
25806 \newline
25807 Finally the code generated for this function:
25808 \newline
25809
25810 \layout Standard
25811
25812
25813 \size footnotesize
25814 .area DSEG (DATA)
25815 \layout Standard
25816
25817
25818 \size footnotesize
25819 _p::
25820 \layout Standard
25821
25822
25823 \size footnotesize
25824 \SpecialChar ~
25825 \SpecialChar ~
25826 .ds 2
25827 \layout Standard
25828
25829
25830 \size footnotesize
25831 _gint::
25832 \layout Standard
25833
25834
25835 \size footnotesize
25836 \SpecialChar ~
25837 \SpecialChar ~
25838 .ds 2
25839 \layout Standard
25840
25841
25842 \size footnotesize
25843 ; sample.c 5
25844 \layout Standard
25845
25846
25847 \size footnotesize
25848 ; ----------------------------------------------
25849 \layout Standard
25850
25851
25852 \size footnotesize
25853 ; function function
25854 \layout Standard
25855
25856
25857 \size footnotesize
25858 ; ----------------------------------------------
25859 \layout Standard
25860
25861
25862 \size footnotesize
25863 _function:
25864 \layout Standard
25865
25866
25867 \size footnotesize
25868 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
25869 \layout Standard
25870
25871
25872 \size footnotesize
25873 \SpecialChar ~
25874 \SpecialChar ~
25875 mov r2,dpl
25876 \layout Standard
25877
25878
25879 \size footnotesize
25880 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
25881 \layout Standard
25882
25883
25884 \size footnotesize
25885 \SpecialChar ~
25886 \SpecialChar ~
25887 mov ar0,r2
25888 \layout Standard
25889
25890
25891 \size footnotesize
25892 ;_whilecontinue_0($1) :
25893 \layout Standard
25894
25895
25896 \size footnotesize
25897 00101$:
25898 \layout Standard
25899
25900
25901 \size footnotesize
25902 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
25903 \layout Standard
25904
25905
25906 \size footnotesize
25907 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
25908 \layout Standard
25909
25910
25911 \size footnotesize
25912 \SpecialChar ~
25913 \SpecialChar ~
25914 mov ar2,@r0
25915 \layout Standard
25916
25917
25918 \size footnotesize
25919 \SpecialChar ~
25920 \SpecialChar ~
25921 inc r0
25922 \layout Standard
25923
25924
25925 \size footnotesize
25926 \SpecialChar ~
25927 \SpecialChar ~
25928 mov ar3,@r0
25929 \layout Standard
25930
25931
25932 \size footnotesize
25933 \SpecialChar ~
25934 \SpecialChar ~
25935 dec r0
25936 \layout Standard
25937
25938
25939 \size footnotesize
25940 \SpecialChar ~
25941 \SpecialChar ~
25942 mov a,r2
25943 \layout Standard
25944
25945
25946 \size footnotesize
25947 \SpecialChar ~
25948 \SpecialChar ~
25949 orl a,r3
25950 \layout Standard
25951
25952
25953 \size footnotesize
25954 \SpecialChar ~
25955 \SpecialChar ~
25956 jz 00103$
25957 \layout Standard
25958
25959
25960 \size footnotesize
25961 00114$:
25962 \layout Standard
25963
25964
25965 \size footnotesize
25966 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
25967 \layout Standard
25968
25969
25970 \size footnotesize
25971 \SpecialChar ~
25972 \SpecialChar ~
25973 mov dpl,_p
25974 \layout Standard
25975
25976
25977 \size footnotesize
25978 \SpecialChar ~
25979 \SpecialChar ~
25980 mov dph,(_p + 1)
25981 \layout Standard
25982
25983
25984 \size footnotesize
25985 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
25986 \layout Standard
25987
25988
25989 \size footnotesize
25990 \SpecialChar ~
25991 \SpecialChar ~
25992 mov a,#0x02
25993 \layout Standard
25994
25995
25996 \size footnotesize
25997 \SpecialChar ~
25998 \SpecialChar ~
25999 add a,_p
26000 \layout Standard
26001
26002
26003 \size footnotesize
26004 \SpecialChar ~
26005 \SpecialChar ~
26006 mov _p,a
26007 \layout Standard
26008
26009
26010 \size footnotesize
26011 \SpecialChar ~
26012 \SpecialChar ~
26013 clr a
26014 \layout Standard
26015
26016
26017 \size footnotesize
26018 \SpecialChar ~
26019 \SpecialChar ~
26020 addc a,(_p + 1)
26021 \layout Standard
26022
26023
26024 \size footnotesize
26025 \SpecialChar ~
26026 \SpecialChar ~
26027 mov (_p + 1),a
26028 \layout Standard
26029
26030
26031 \size footnotesize
26032 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
26033 \layout Standard
26034
26035
26036 \size footnotesize
26037 \SpecialChar ~
26038 \SpecialChar ~
26039 movx a,@dptr
26040 \layout Standard
26041
26042
26043 \size footnotesize
26044 \SpecialChar ~
26045 \SpecialChar ~
26046 mov r2,a
26047 \layout Standard
26048
26049
26050 \size footnotesize
26051 \SpecialChar ~
26052 \SpecialChar ~
26053 inc dptr
26054 \layout Standard
26055
26056
26057 \size footnotesize
26058 \SpecialChar ~
26059 \SpecialChar ~
26060 movx a,@dptr
26061 \layout Standard
26062
26063
26064 \size footnotesize
26065 \SpecialChar ~
26066 \SpecialChar ~
26067 mov r3,a
26068 \layout Standard
26069
26070
26071 \size footnotesize
26072 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
26073 \layout Standard
26074
26075
26076 \size footnotesize
26077 \SpecialChar ~
26078 \SpecialChar ~
26079 mov @r0,ar2
26080 \layout Standard
26081
26082
26083 \size footnotesize
26084 \SpecialChar ~
26085 \SpecialChar ~
26086 inc r0
26087 \layout Standard
26088
26089
26090 \size footnotesize
26091 \SpecialChar ~
26092 \SpecialChar ~
26093 mov @r0,ar3
26094 \layout Standard
26095
26096
26097 \size footnotesize
26098 ; iTemp6 [lr5:16]{_near * int}[r0] =
26099 \layout Standard
26100
26101
26102 \size footnotesize
26103 ; iTemp6 [lr5:16]{_near * int}[r0] +
26104 \layout Standard
26105
26106
26107 \size footnotesize
26108 ; 0x2 {short}
26109 \layout Standard
26110
26111
26112 \size footnotesize
26113 \SpecialChar ~
26114 \SpecialChar ~
26115 inc r0
26116 \layout Standard
26117
26118
26119 \size footnotesize
26120 ; goto _whilecontinue_0($1)
26121 \layout Standard
26122
26123
26124 \size footnotesize
26125 \SpecialChar ~
26126 \SpecialChar ~
26127 sjmp 00101$
26128 \layout Standard
26129
26130
26131 \size footnotesize
26132 ; _whilebreak_0($3) :
26133 \layout Standard
26134
26135
26136 \size footnotesize
26137 00103$:
26138 \layout Standard
26139
26140
26141 \size footnotesize
26142 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
26143 \layout Standard
26144
26145
26146 \size footnotesize
26147 \SpecialChar ~
26148 \SpecialChar ~
26149 mov r2,#0x00
26150 \layout Standard
26151
26152
26153 \size footnotesize
26154 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
26155 \layout Standard
26156
26157
26158 \size footnotesize
26159 \SpecialChar ~
26160 \SpecialChar ~
26161 mov r3,#0x00
26162 \layout Standard
26163
26164
26165 \size footnotesize
26166 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
26167 \layout Standard
26168
26169
26170 \size footnotesize
26171 \SpecialChar ~
26172 \SpecialChar ~
26173 mov r4,#0x00
26174 \layout Standard
26175
26176
26177 \size footnotesize
26178 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
26179 \layout Standard
26180
26181
26182 \size footnotesize
26183 \SpecialChar ~
26184 \SpecialChar ~
26185 mov r5,#0x0A
26186 \layout Standard
26187
26188
26189 \size footnotesize
26190 \SpecialChar ~
26191 \SpecialChar ~
26192 mov r6,#0x00
26193 \layout Standard
26194
26195
26196 \size footnotesize
26197 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
26198 \layout Standard
26199
26200
26201 \size footnotesize
26202 \SpecialChar ~
26203 \SpecialChar ~
26204 mov r7,#0x1E
26205 \layout Standard
26206
26207
26208 \size footnotesize
26209 \SpecialChar ~
26210 \SpecialChar ~
26211 mov r0,#0x00
26212 \layout Standard
26213
26214
26215 \size footnotesize
26216 ; _forcond_0($4) :
26217 \layout Standard
26218
26219
26220 \size footnotesize
26221 00104$:
26222 \layout Standard
26223
26224
26225 \size footnotesize
26226 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
26227 \layout Standard
26228
26229
26230 \size footnotesize
26231 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
26232 \layout Standard
26233
26234
26235 \size footnotesize
26236 \SpecialChar ~
26237 \SpecialChar ~
26238 clr c
26239 \layout Standard
26240
26241
26242 \size footnotesize
26243 \SpecialChar ~
26244 \SpecialChar ~
26245 mov a,r4
26246 \layout Standard
26247
26248
26249 \size footnotesize
26250 \SpecialChar ~
26251 \SpecialChar ~
26252 xrl a,#0x80
26253 \layout Standard
26254
26255
26256 \size footnotesize
26257 \SpecialChar ~
26258 \SpecialChar ~
26259 subb a,#0x8a
26260 \layout Standard
26261
26262
26263 \size footnotesize
26264 \SpecialChar ~
26265 \SpecialChar ~
26266 jnc 00107$
26267 \layout Standard
26268
26269
26270 \size footnotesize
26271 00115$:
26272 \layout Standard
26273
26274
26275 \size footnotesize
26276 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
26277 \layout Standard
26278
26279
26280 \size footnotesize
26281 ; iTemp21 [lr21:38]{short}[r4]
26282 \layout Standard
26283
26284
26285 \size footnotesize
26286 \SpecialChar ~
26287 \SpecialChar ~
26288 mov a,r4
26289 \layout Standard
26290
26291
26292 \size footnotesize
26293 \SpecialChar ~
26294 \SpecialChar ~
26295 add a,r2
26296 \layout Standard
26297
26298
26299 \size footnotesize
26300 \SpecialChar ~
26301 \SpecialChar ~
26302 mov r2,a
26303 \layout Standard
26304
26305
26306 \size footnotesize
26307 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
26308 \layout Standard
26309
26310
26311 \size footnotesize
26312 \SpecialChar ~
26313 \SpecialChar ~
26314 mov b,#0x03
26315 \layout Standard
26316
26317
26318 \size footnotesize
26319 \SpecialChar ~
26320 \SpecialChar ~
26321 mov a,r4
26322 \layout Standard
26323
26324
26325 \size footnotesize
26326 \SpecialChar ~
26327 \SpecialChar ~
26328 mul ab
26329 \layout Standard
26330
26331
26332 \size footnotesize
26333 \SpecialChar ~
26334 \SpecialChar ~
26335 mov r1,a
26336 \layout Standard
26337
26338
26339 \size footnotesize
26340 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
26341 \layout Standard
26342
26343
26344 \size footnotesize
26345 ; iTemp15 [lr29:30]{short}[r1]
26346 \layout Standard
26347
26348
26349 \size footnotesize
26350 \SpecialChar ~
26351 \SpecialChar ~
26352 add a,r3
26353 \layout Standard
26354
26355
26356 \size footnotesize
26357 \SpecialChar ~
26358 \SpecialChar ~
26359 mov r3,a
26360 \layout Standard
26361
26362
26363 \size footnotesize
26364 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
26365 \layout Standard
26366
26367
26368 \size footnotesize
26369 \SpecialChar ~
26370 \SpecialChar ~
26371 mov a,r7
26372 \layout Standard
26373
26374
26375 \size footnotesize
26376 \SpecialChar ~
26377 \SpecialChar ~
26378 add a,#0xfd
26379 \layout Standard
26380
26381
26382 \size footnotesize
26383 \SpecialChar ~
26384 \SpecialChar ~
26385 mov r7,a
26386 \layout Standard
26387
26388
26389 \size footnotesize
26390 \SpecialChar ~
26391 \SpecialChar ~
26392 mov a,r0
26393 \layout Standard
26394
26395
26396 \size footnotesize
26397 \SpecialChar ~
26398 \SpecialChar ~
26399 addc a,#0xff
26400 \layout Standard
26401
26402
26403 \size footnotesize
26404 \SpecialChar ~
26405 \SpecialChar ~
26406 mov r0,a
26407 \layout Standard
26408
26409
26410 \size footnotesize
26411 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
26412 \layout Standard
26413
26414
26415 \size footnotesize
26416 \SpecialChar ~
26417 \SpecialChar ~
26418 mov a,r7
26419 \layout Standard
26420
26421
26422 \size footnotesize
26423 \SpecialChar ~
26424 \SpecialChar ~
26425 add a,_gint
26426 \layout Standard
26427
26428
26429 \size footnotesize
26430 \SpecialChar ~
26431 \SpecialChar ~
26432 mov _gint,a
26433 \layout Standard
26434
26435
26436 \size footnotesize
26437 \SpecialChar ~
26438 \SpecialChar ~
26439 mov a,r0
26440 \layout Standard
26441
26442
26443 \size footnotesize
26444 \SpecialChar ~
26445 \SpecialChar ~
26446 addc a,(_gint + 1)
26447 \layout Standard
26448
26449
26450 \size footnotesize
26451 \SpecialChar ~
26452 \SpecialChar ~
26453 mov (_gint + 1),a
26454 \layout Standard
26455
26456
26457 \size footnotesize
26458 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
26459 \layout Standard
26460
26461
26462 \size footnotesize
26463 \SpecialChar ~
26464 \SpecialChar ~
26465 inc r4
26466 \layout Standard
26467
26468
26469 \size footnotesize
26470 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
26471 \layout Standard
26472
26473
26474 \size footnotesize
26475 \SpecialChar ~
26476 \SpecialChar ~
26477 dec r5
26478 \layout Standard
26479
26480
26481 \size footnotesize
26482 \SpecialChar ~
26483 \SpecialChar ~
26484 cjne r5,#0xff,00104$
26485 \layout Standard
26486
26487
26488 \size footnotesize
26489 \SpecialChar ~
26490 \SpecialChar ~
26491 dec r6
26492 \layout Standard
26493
26494
26495 \size footnotesize
26496 ; goto _forcond_0($4)
26497 \layout Standard
26498
26499
26500 \size footnotesize
26501 \SpecialChar ~
26502 \SpecialChar ~
26503 sjmp 00104$
26504 \layout Standard
26505
26506
26507 \size footnotesize
26508 ; _forbreak_0($7) :
26509 \layout Standard
26510
26511
26512 \size footnotesize
26513 00107$:
26514 \layout Standard
26515
26516
26517 \size footnotesize
26518 ; ret iTemp24 [lr40:41]{short}
26519 \layout Standard
26520
26521
26522 \size footnotesize
26523 \SpecialChar ~
26524 \SpecialChar ~
26525 mov a,r3
26526 \layout Standard
26527
26528
26529 \size footnotesize
26530 \SpecialChar ~
26531 \SpecialChar ~
26532 add a,r2
26533 \layout Standard
26534
26535
26536 \size footnotesize
26537 \SpecialChar ~
26538 \SpecialChar ~
26539 mov dpl,a
26540 \layout Standard
26541
26542
26543 \size footnotesize
26544 ; _return($8) :
26545 \layout Standard
26546
26547
26548 \size footnotesize
26549 00108$:
26550 \layout Standard
26551
26552
26553 \size footnotesize
26554 \SpecialChar ~
26555 \SpecialChar ~
26556 ret
26557 \newline
26558
26559 \layout Section
26560
26561 A few words about basic block successors, predecessors and dominators
26562 \layout Standard
26563
26564 Successors are basic blocks
26565 \begin_inset LatexCommand \index{Basic blocks}
26566
26567 \end_inset
26568
26569  that might execute after this basic block.
26570 \newline
26571 Predecessors are basic blocks that might execute before reaching this basic
26572  block.
26573 \newline
26574 Dominators are basic blocks that WILL execute before reaching this basic
26575  block.
26576 \newline
26577
26578 \layout Standard
26579
26580 [basic block 1]
26581 \layout Standard
26582
26583 if (something)
26584 \layout Standard
26585
26586 \SpecialChar ~
26587 \SpecialChar ~
26588 \SpecialChar ~
26589 \SpecialChar ~
26590 [basic block 2]
26591 \layout Standard
26592
26593 else
26594 \layout Standard
26595
26596 \SpecialChar ~
26597 \SpecialChar ~
26598 \SpecialChar ~
26599 \SpecialChar ~
26600 [basic block 3]
26601 \layout Standard
26602
26603 [basic block 4]
26604 \newline
26605
26606 \layout Standard
26607
26608 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
26609 \layout Standard
26610
26611 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
26612 \layout Standard
26613
26614 c) domVect of [BB4] = BB1 ...
26615  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
26616  was executed.
26617 \layout Chapter
26618
26619 Acknowledgments
26620 \layout Standard
26621
26622
26623 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
26624
26625 \end_inset
26626
26627
26628 \newline
26629
26630 \newline
26631
26632 \emph on
26633 Thanks to all the other volunteer developers who have helped with coding,
26634  testing, web-page creation, distribution sets, etc.
26635  You know who you are :-)
26636 \emph default
26637
26638 \newline
26639
26640 \layout Standard
26641
26642 This document was initially written by Sandeep Dutta
26643 \layout Standard
26644
26645 All product names mentioned herein may be trademarks
26646 \begin_inset LatexCommand \index{Trademarks}
26647
26648 \end_inset
26649
26650  of their respective companies.
26651
26652 \layout Section*
26653
26654 Alphabetical index
26655 \layout Standard
26656
26657 To avoid confusion, the installation and building options for SDCC itself
26658  (chapter 2) are not part of the index.
26659 \layout Standard
26660
26661
26662 \begin_inset LatexCommand \printindex{}
26663
26664 \end_inset
26665
26666
26667 \the_end